dd-llm

Shared LLM abstraction layer for Digital Duck projects.

Zero core dependencies. Adapters lazy-import their SDKs only when used.

Install

pip install -e .              # zero deps — claude_cli adapter works out of the box
pip install -e ".[openai]"    # + OpenAI SDK (also covers openrouter, ollama)
pip install -e ".[anthropic]" # + Anthropic SDK
pip install -e ".[gemini]"    # + Google GenAI SDK
pip install -e ".[momagrid]"   # + httpx (Momagrid hub)
pip install -e ".[bedrock]"    # + boto3
pip install -e ".[all]"       # all provider SDKs

Quick Start

from dd_llm import call_llm

# Uses LLM_PROVIDER env var (default: "openai")
response = call_llm("What is 2+2?")

# Specify provider
response = call_llm("Hello", provider="claude_cli")

# With messages
response = call_llm(messages=[
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Hi"},
])

Built-in Adapters

dd_llm.model_compatible(adapter, model) says whether a model name is plausible for an adapter (claude_cli only speaks claude-*, openrouter models contain a slash, ...), so callers can drop a stray model hint instead of making a doomed call.

dd_llm.parse_llm_spec("claude_cli:claude-haiku-5-5") returns ("claude_cli", "claude-haiku-5-5"). It is the parser behind the --llm ADAPTER:MODEL flag of the CLIs built on dd-llm (grafr, spl3): only the first : splits, so ollama:gemma3:12b and openrouter:meta/llama-3 work, and a bare claude_cli gives ("claude_cli", None).

Custom Adapters

from dd_llm import LLMAdapter, LLMResponse, register_adapter, call_llm

class MyAdapter(LLMAdapter):
    def call(self, prompt="", *, messages=None, **kwargs):
        result = my_internal_api(prompt)
        return LLMResponse(content=result, success=True, provider="my_api", model="v1")

register_adapter("my_api", MyAdapter)

# Now usable everywhere
response = call_llm("hello", provider="my_api")

UnifiedLLMProvider

Multi-provider client with retry (exponential backoff + jitter) and automatic fallback to alternative providers.

from dd_llm import UnifiedLLMProvider

provider = UnifiedLLMProvider(
    primary_provider="openai",
    fallback_providers=["anthropic", "ollama"],
    max_retries=3,
)

result = provider.call("Explain quantum computing")
if result.success:
    print(result.content)
    print(f"Provider: {result.provider}, Model: {result.model}")
    print(f"Tokens: {result.input_tokens} in, {result.output_tokens} out")

Environment Variables

License

MIT