llm-seam

Unified LLM abstraction with a provider pattern — one interface, five backends, automatic fallback and retry.

Source is maintained in a private monorepo. Releases are built and published by GitHub Actions through a PyPI Trusted Publisher; provenance attestations are visible on the PyPI file listing.

Note on the name: this package was llm-base until 2026-08-21. It was renamed to llm-seam because the PyPI name llm-base belongs to an unrelated, older project — no relation to this package.

What's in the box

Design

One interface, provider-agnostic callers. LLMClient and every provider implement the same three-method LLMProvider protocol (complete, get_name, supports_streaming), so a caller can swap Anthropic for a local Ollama model, the Claude CLI, or a mock in tests without touching call sites.

Auto-selection is a convenience, not a requirement. LLMClient() with no arguments picks Anthropic if ANTHROPIC_API_KEY is set, else OpenAI if OPENAI_API_KEY is set, else falls back to MockProvider. Pass an explicit provider= name or instance to bypass auto-selection entirely.

Provider-name convention. When constructing by name string, this portfolio distinguishes two Claude transports: "claude-sdk" selects AgentSDKProvider (the claude-agent-sdk package, preferred for new scheduled work — see libs/CLAUDE.md), and "claude-cli" selects ClaudeCLIProvider (shells out to the installed Claude Code CLI). "claude-sdk" is only registered as a valid name if claude-agent-sdk is installed (the [sdk] extra); otherwise constructing by that name raises ValueError.

AgentSDKProvider's can_use_tool is a security boundary, not a hygiene knob. It threads straight to ClaudeAgentOptions.can_use_tool. If a caller passes a callback and the installed claude-agent-sdk can't accept the field, the call raises LLMError rather than silently proceeding ungated — a caller that believes tool calls are being permission-checked must never find out otherwise the hard way. Use tool_guards.path_scoped_tool_guard(allowed_dirs) rather than hand-rolling path checks.

Fallback and retry compose, they don't replace each other. FallbackChain moves between providers; with_retry retries a single call on a transient error (rate limits by default). Wrap a FallbackChain's .complete in with_retry, or use either alone. Neither treats a refusal as recoverable: LLMRefusalError is not in with_retry's default retryable set, and FallbackChain re-raises it without trying the next provider.

Install

pip install llm-seam

Optional extras:

pip install "llm-seam[sdk]"      # AgentSDKProvider (claude-agent-sdk)

Usage

from llm_seam import LLMClient, FallbackChain, with_retry

# Auto-select a provider from the environment
client = LLMClient()
response = client.complete("Hello, world!")

# Explicit provider by name
client = LLMClient(provider="anthropic")

# Fall back through providers in order
chain = FallbackChain(providers=[
    LLMClient(provider="claude-cli").provider,
    LLMClient(provider="anthropic").provider,
])
response = chain.complete("Hello")

# Retry a call with exponential backoff on rate limits
@with_retry(max_retries=3, initial_delay=1.0)
def call():
    return client.complete("Hello")

Testing

cd llm-seam
pytest tests/

Dependencies

• anthropic>=0.122.0,<2 (1.0.0+ removed temperature/top_p/top_k from Messages.create; AnthropicProvider.complete() drops those three and emits a UserWarning if you pass them — use extra_body={"temperature": ...} if the target model still accepts it)
• openai>=3.1.0 (also used by OllamaProvider, which talks to Ollama's OpenAI-compatible API — no extra required)
• claude-agent-sdk>=0.2.139 (optional, [sdk] extra)

License

MIT