---

name: sdk-core description: "Use for direct LiteLLM Python SDK work: chat/text completions, async calls, streaming, embeddings, structured outputs, tools, token/cost checks, caching, callbacks, import/smoke validation, and shared SDK troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

LiteLLM SDK Core

Use this sub-skill when the task is about calling LiteLLM as a Python library. LiteLLM exposes OpenAI-format SDK calls across providers, with safe local validation available through mock_response and the bundled smoke script.

Route Elsewhere

• Use ../proxy-server/SKILL.md for running or configuring the LiteLLM proxy server and CLI gateway.
• Use ../routing/SKILL.md for Router, model groups, fallbacks, load balancing, and deployment selection.
• Use ../providers-and-endpoints/SKILL.md for provider catalogs, endpoint-specific quirks, and pass-through APIs.
• Use ../agent-tools/SKILL.md for MCP, A2A, and gateway-backed agent tool patterns.

Start Here

1. For API signatures and parameter mapping, read references/api-reference.md.
2. For copy-ready SDK patterns, read references/workflows.md.
3. For failures and diagnostics, read references/troubleshooting.md.
4. For a safe local check, run:

python sub-skills/sdk-core/scripts/sdk_smoke.py --checks import signature mock

Run the command from the generated skill root, or pass the script path directly from any working directory. It imports the installed litellm package and does not contact providers unless --provider-smoke is combined with --model and --api-key-env.

Core Mental Model

• litellm.completion(...) is the main synchronous chat-completion API; litellm.acompletion(...) is the async equivalent.
• litellm.embedding(...) and litellm.aembedding(...) handle embeddings with provider-specific credentials and optional caching.
• litellm.text_completion(...) supports legacy prompt-style text completions when a provider/model still exposes that shape.
• Most provider differences are expressed through model prefixes such as openai/..., anthropic/..., azure/..., bedrock/..., plus per-call api_key, base_url or api_base, api_version, and extra_headers when needed.
• Unknown or provider-specific parameters may be translated, forwarded, or dropped depending on provider support; validate behavior with mock_response, verbose logs, or a targeted live smoke call.

Quick Patterns

import litellm

response = litellm.completion(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
    temperature=0.2,
    timeout=30,
)
print(response.choices[0].message.content)

stream = litellm.completion(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Count to three."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="")

response = litellm.completion(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Return JSON with a color field."}],
    response_format={"type": "json_object"},
    mock_response='{"color":"blue"}',
)

Validation Checklist

• Import check: python sub-skills/sdk-core/scripts/sdk_smoke.py --checks import.
• Signature check: python sub-skills/sdk-core/scripts/sdk_smoke.py --checks signature.
• Mock SDK check: python sub-skills/sdk-core/scripts/sdk_smoke.py --checks mock.
• Optional live check: set the provider key in an environment variable, then run python sub-skills/sdk-core/scripts/sdk_smoke.py --provider-smoke --model openai/gpt-4o-mini --api-key-env OPENAI_API_KEY.

Safety Defaults

• Prefer mock_response for tests and diagnostics that should not spend provider credits.
• Do not hard-code API keys; use provider environment variables or pass api_key from a secret manager.
• Keep timeout explicit on production calls.
• Reset global callbacks/cache in tests that mutate litellm.callbacks, litellm.success_callback, litellm.failure_callback, or litellm.cache.