llm-seam 0.1.0__tar.gz

llm_seam-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m0j0d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llm_seam-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: llm-seam
+Version: 0.1.0
+Summary: Unified LLM abstraction with provider pattern for portfolio projects
+Author-email: Mike Donnelly <82827803+m0j0d@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/m0j0d/libs/tree/main/llm-seam
+Project-URL: Repository, https://github.com/m0j0d/libs
+Project-URL: Issues, https://github.com/m0j0d/libs/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.122.0
+Requires-Dist: openai>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
+Provides-Extra: sdk
+Requires-Dist: claude-agent-sdk>=0.2.139; extra == "sdk"
+Provides-Extra: ollama
+Requires-Dist: litellm>=1.96.2; extra == "ollama"
+Dynamic: license-file
+
+# llm-seam
+
+Unified LLM abstraction with a provider pattern — one interface, five backends,
+automatic fallback and retry.
+
+**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
+
+| Module | What it gives you |
+|---|---|
+| `llm_seam.client` | `LLMClient` — auto-selects a provider from the environment (Anthropic, then OpenAI, then a mock fallback), or accepts an explicit provider name/instance |
+| `llm_seam.providers.base` | `LLMProvider` — the `Protocol` every provider implements (`complete`, `get_name`, `supports_streaming`) |
+| `llm_seam.providers.anthropic` | `AnthropicProvider` — wraps the `anthropic` SDK |
+| `llm_seam.providers.openai` | `OpenAIProvider` — wraps the `openai` SDK |
+| `llm_seam.providers.claude_cli` | `ClaudeCLIProvider` — shells out to the Claude Code CLI |
+| `llm_seam.providers.agent_sdk` | `AgentSDKProvider` — wraps `claude-agent-sdk` (requires the `[sdk]` extra); supports an optional `can_use_tool` security callback (see below) |
+| `llm_seam.providers.ollama` | `OllamaProvider` — local models via `litellm` (requires the `[ollama]` extra) |
+| `llm_seam.providers.mock` | `MockProvider` — fixed-response provider for tests and offline use |
+| `llm_seam.fallback` | `FallbackChain` — tries a list of providers in order, raises `AllProvidersFailed` only if every one of them fails |
+| `llm_seam.retry` | `with_retry` — decorator with exponential backoff, retries on `RateLimitError` by default (configurable) |
+| `llm_seam.tool_guards` | `path_scoped_tool_guard` — ready-made `can_use_tool` callback for `AgentSDKProvider`; confines a tool's path arguments to an allowlist of directories, resists `..` traversal, symlink escapes, and absolute paths outside the allowlist |
+| `llm_seam.exceptions` | `LLMError` (base), `RateLimitError`, `TokenLimitError`, `TimeoutError`, `AllProvidersFailed` |
+
+## 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.
+
+## Install
+
+```bash
+pip install llm-seam
+```
+
+Optional extras:
+
+```bash
+pip install "llm-seam[sdk]"      # AgentSDKProvider (claude-agent-sdk)
+pip install "llm-seam[ollama]"   # OllamaProvider (litellm)
+```
+
+## Usage
+
+```python
+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
+
+```bash
+cd llm-seam
+pytest tests/
+```
+
+## Dependencies
+
+- `anthropic>=0.122.0`
+- `openai>=3.1.0`
+- `claude-agent-sdk>=0.2.139` (optional, `[sdk]` extra)
+- `litellm>=1.96.2` (optional, `[ollama]` extra — pinned floor to avoid a
+  supply-chain attack affecting 1.82.7–1.82.8)
+
+## License
+
+MIT

llm_seam-0.1.0/README.md

@@ -0,0 +1,116 @@
+# llm-seam
+
+Unified LLM abstraction with a provider pattern — one interface, five backends,
+automatic fallback and retry.
+
+**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
+
+| Module | What it gives you |
+|---|---|
+| `llm_seam.client` | `LLMClient` — auto-selects a provider from the environment (Anthropic, then OpenAI, then a mock fallback), or accepts an explicit provider name/instance |
+| `llm_seam.providers.base` | `LLMProvider` — the `Protocol` every provider implements (`complete`, `get_name`, `supports_streaming`) |
+| `llm_seam.providers.anthropic` | `AnthropicProvider` — wraps the `anthropic` SDK |
+| `llm_seam.providers.openai` | `OpenAIProvider` — wraps the `openai` SDK |
+| `llm_seam.providers.claude_cli` | `ClaudeCLIProvider` — shells out to the Claude Code CLI |
+| `llm_seam.providers.agent_sdk` | `AgentSDKProvider` — wraps `claude-agent-sdk` (requires the `[sdk]` extra); supports an optional `can_use_tool` security callback (see below) |
+| `llm_seam.providers.ollama` | `OllamaProvider` — local models via `litellm` (requires the `[ollama]` extra) |
+| `llm_seam.providers.mock` | `MockProvider` — fixed-response provider for tests and offline use |
+| `llm_seam.fallback` | `FallbackChain` — tries a list of providers in order, raises `AllProvidersFailed` only if every one of them fails |
+| `llm_seam.retry` | `with_retry` — decorator with exponential backoff, retries on `RateLimitError` by default (configurable) |
+| `llm_seam.tool_guards` | `path_scoped_tool_guard` — ready-made `can_use_tool` callback for `AgentSDKProvider`; confines a tool's path arguments to an allowlist of directories, resists `..` traversal, symlink escapes, and absolute paths outside the allowlist |
+| `llm_seam.exceptions` | `LLMError` (base), `RateLimitError`, `TokenLimitError`, `TimeoutError`, `AllProvidersFailed` |
+
+## 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.
+
+## Install
+
+```bash
+pip install llm-seam
+```
+
+Optional extras:
+
+```bash
+pip install "llm-seam[sdk]"      # AgentSDKProvider (claude-agent-sdk)
+pip install "llm-seam[ollama]"   # OllamaProvider (litellm)
+```
+
+## Usage
+
+```python
+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
+
+```bash
+cd llm-seam
+pytest tests/
+```
+
+## Dependencies
+
+- `anthropic>=0.122.0`
+- `openai>=3.1.0`
+- `claude-agent-sdk>=0.2.139` (optional, `[sdk]` extra)
+- `litellm>=1.96.2` (optional, `[ollama]` extra — pinned floor to avoid a
+  supply-chain attack affecting 1.82.7–1.82.8)
+
+## License
+
+MIT

llm_seam-0.1.0/llm_seam/__init__.py

@@ -0,0 +1,37 @@
+# llm-seam: Unified LLM abstraction with provider pattern
+
+from .client import LLMClient
+from .exceptions import (
+    LLMError,
+    RateLimitError,
+    TokenLimitError,
+    TimeoutError,
+    AllProvidersFailed,
+)
+from .providers.base import LLMProvider
+from .providers.mock import MockProvider
+from .providers.anthropic import AnthropicProvider
+from .providers.openai import OpenAIProvider
+from .providers.claude_cli import ClaudeCLIProvider
+from .providers.ollama import OllamaProvider
+from .fallback import FallbackChain
+from .retry import with_retry
+from .tool_guards import path_scoped_tool_guard
+
+__all__ = [
+    "LLMClient",
+    "LLMProvider",
+    "MockProvider",
+    "AnthropicProvider",
+    "OpenAIProvider",
+    "ClaudeCLIProvider",
+    "OllamaProvider",
+    "FallbackChain",
+    "with_retry",
+    "path_scoped_tool_guard",
+    "LLMError",
+    "RateLimitError",
+    "TokenLimitError",
+    "TimeoutError",
+    "AllProvidersFailed",
+]

llm_seam-0.1.0/llm_seam/client.py

@@ -0,0 +1,126 @@
+"""Main LLMClient entry point with auto-provider selection."""
+
+import os
+from typing import Any
+from llm_seam.providers.base import LLMProvider
+from llm_seam.providers.mock import MockProvider
+from llm_seam.providers.anthropic import AnthropicProvider
+from llm_seam.providers.openai import OpenAIProvider
+from llm_seam.providers.claude_cli import ClaudeCLIProvider
+from llm_seam.providers.ollama import OllamaProvider
+
+try:
+    from llm_seam.providers.agent_sdk import AgentSDKProvider
+    HAS_AGENT_SDK = True
+except RuntimeError:
+    HAS_AGENT_SDK = False
+
+
+class LLMClient:
+    """Main LLM client with automatic provider selection.
+
+    Auto-selection priority:
+    1. Anthropic (if ANTHROPIC_API_KEY is set)
+    2. OpenAI (if OPENAI_API_KEY is set)
+    3. MockProvider (fallback when no API keys available)
+
+    Args:
+        provider: Provider instance or name string ('anthropic', 'openai', 'claude-cli', 'ollama', 'mock')
+                 If None, auto-selects based on available API keys
+
+    Example:
+        # Auto-select based on environment
+        client = LLMClient()
+
+        # Explicit provider by name
+        client = LLMClient(provider="anthropic")
+
+        # Explicit provider instance
+        client = LLMClient(provider=AnthropicProvider(api_key="..."))
+    """
+
+    def __init__(self, provider: LLMProvider | str | None = None):
+        if provider is None:
+            self.provider = self._auto_select_provider()
+        elif isinstance(provider, str):
+            self.provider = self._create_provider_from_name(provider)
+        else:
+            self.provider = provider
+
+    def _auto_select_provider(self) -> LLMProvider:
+        """Auto-select provider based on available API keys."""
+        # Check Anthropic first
+        if os.getenv("ANTHROPIC_API_KEY"):
+            try:
+                return AnthropicProvider()
+            except Exception:
+                pass  # Fall through to next option
+
+        # Check OpenAI
+        if os.getenv("OPENAI_API_KEY"):
+            try:
+                return OpenAIProvider()
+            except Exception:
+                pass  # Fall through to next option
+
+        # Default to mock provider
+        return MockProvider(response="Mock LLM response (no API keys configured)")
+
+    def _create_provider_from_name(self, name: str) -> LLMProvider:
+        """Create provider instance from name string."""
+        providers: dict[str, type] = {
+            "anthropic": AnthropicProvider,
+            "openai": OpenAIProvider,
+            "claude-cli": ClaudeCLIProvider,
+            "ollama": OllamaProvider,
+            "mock": MockProvider,
+        }
+
+        if HAS_AGENT_SDK:
+            providers["claude-sdk"] = AgentSDKProvider
+
+        if name not in providers:
+            raise ValueError(
+                f"Unknown provider: {name}. "
+                f"Valid options: {', '.join(providers.keys())}"
+            )
+
+        provider_class = providers[name]
+
+        # MockProvider doesn't need any args
+        if name == "mock":
+            return provider_class()
+
+        # Other providers will use env vars or fail if not available
+        return provider_class()
+
+    def complete(self, prompt: str, **kwargs: Any) -> str:
+        """Generate completion using the configured provider.
+
+        Args:
+            prompt: The input prompt
+            **kwargs: Provider-specific options
+
+        Returns:
+            The completion text
+        """
+        return self.provider.complete(prompt, **kwargs)
+
+    def get_provider_name(self) -> str:
+        """Return the name of the current provider."""
+        return self.provider.get_name()
+
+    def supports_streaming(self) -> bool:
+        """Return whether the current provider supports streaming."""
+        return self.provider.supports_streaming()
+
+    def set_provider(self, provider: LLMProvider | str) -> None:
+        """Switch to a different provider.
+
+        Args:
+            provider: Provider instance or name string
+        """
+        if isinstance(provider, str):
+            self.provider = self._create_provider_from_name(provider)
+        else:
+            self.provider = provider

llm_seam-0.1.0/llm_seam/exceptions.py

@@ -0,0 +1,33 @@
+"""Custom exceptions for llm-seam."""
+
+
+class LLMError(Exception):
+    """Base exception for all LLM errors."""
+    pass
+
+
+class RateLimitError(LLMError):
+    """Raised when API rate limit is exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: float | None = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class TokenLimitError(LLMError):
+    """Raised when token limit is exceeded."""
+    pass
+
+
+class TimeoutError(LLMError):
+    """Raised when request times out."""
+    pass
+
+
+class AllProvidersFailed(LLMError):
+    """Raised when all providers in a fallback chain fail."""
+
+    def __init__(self, errors: list[Exception] | None = None):
+        self.errors = errors or []
+        message = f"All providers failed: {[str(e) for e in self.errors]}"
+        super().__init__(message)

llm_seam-0.1.0/llm_seam/fallback.py

@@ -0,0 +1,70 @@
+"""Fallback chain for trying multiple LLM providers in order.
+
+Based on pepai's llm_gateway.py local-first fallback pattern.
+"""
+
+from typing import Any
+from llm_seam.providers.base import LLMProvider
+from llm_seam.exceptions import AllProvidersFailed
+
+
+class FallbackChain:
+    """Chain of LLM providers tried in order until one succeeds.
+
+    Args:
+        providers: List of LLMProvider instances to try in order
+
+    Example:
+        # Try local Ollama first, fallback to Anthropic
+        chain = FallbackChain(providers=[
+            OllamaProvider(),
+            AnthropicProvider()
+        ])
+        response = chain.complete("Hello")
+    """
+
+    def __init__(self, providers: list[LLMProvider]):
+        if not providers:
+            raise ValueError("At least one provider must be specified")
+
+        self.providers = providers
+        self.last_provider_used: LLMProvider | None = None
+
+    def complete(self, prompt: str, **kwargs: Any) -> str:
+        """Try each provider in order until one succeeds.
+
+        Args:
+            prompt: The input prompt
+            **kwargs: Additional parameters passed to each provider
+
+        Returns:
+            The completion text from the first successful provider
+
+        Raises:
+            AllProvidersFailed: When all providers fail
+        """
+        errors: list[Exception] = []
+
+        for provider in self.providers:
+            try:
+                response = provider.complete(prompt, **kwargs)
+                self.last_provider_used = provider
+                return response
+
+            except Exception as e:
+                errors.append(e)
+                # Continue to next provider
+                continue
+
+        # All providers failed
+        self.last_provider_used = None
+        raise AllProvidersFailed(errors=errors)
+
+    def get_name(self) -> str:
+        """Return fallback chain identifier."""
+        provider_names = [p.get_name() for p in self.providers]
+        return f"fallback({', '.join(provider_names)})"
+
+    def supports_streaming(self) -> bool:
+        """Return whether streaming is supported (always False for chains)."""
+        return False

llm_seam-0.1.0/llm_seam/providers/__init__.py

@@ -0,0 +1,24 @@
+"""LLM provider implementations."""
+
+from .base import LLMProvider
+from .mock import MockProvider
+from .anthropic import AnthropicProvider
+from .openai import OpenAIProvider
+from .claude_cli import ClaudeCLIProvider
+from .ollama import OllamaProvider
+
+# Optional — requires pip install llm-seam[sdk]
+try:
+    from .agent_sdk import AgentSDKProvider
+except RuntimeError:
+    AgentSDKProvider = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "LLMProvider",
+    "MockProvider",
+    "AnthropicProvider",
+    "OpenAIProvider",
+    "ClaudeCLIProvider",
+    "OllamaProvider",
+    "AgentSDKProvider",
+]