agentic-programming 0.4.0__py3-none-any.whl

agentic/providers/__init__.py

@@ -0,0 +1,169 @@
+"""
+agentic.providers — Built-in Runtime implementations for popular LLM providers.
+
+Each provider is an optional dependency. Import will give a clear error
+if the required SDK is not installed.
+
+Available providers:
+    AnthropicRuntime    — Anthropic Claude API (text + image, prompt caching)
+    OpenAIRuntime       — OpenAI GPT API (text + image, response_format)
+    GeminiRuntime       — Google Gemini API (text + image)
+    ClaudeCodeRuntime   — Claude Code CLI (no API key, uses subscription)
+    CodexRuntime        — OpenAI Codex CLI (no API key in harness, uses codex auth)
+    GeminiCLIRuntime    — Gemini CLI (no API key, uses Google account)
+
+Usage:
+    from agentic.providers import AnthropicRuntime
+    rt = AnthropicRuntime(api_key="sk-...", model="claude-sonnet-4-20250514")
+
+    from agentic.providers import OpenAIRuntime
+    rt = OpenAIRuntime(api_key="sk-...", model="gpt-4o")
+
+    from agentic.providers import GeminiRuntime
+    rt = GeminiRuntime(api_key="...", model="gemini-2.5-flash")
+
+    from agentic.providers import CodexRuntime
+    rt = CodexRuntime(model="o4-mini")
+
+Auto-detection:
+    from agentic.providers import detect_provider, create_runtime
+
+    provider, model = detect_provider()     # auto-detect best available
+    rt = create_runtime()                   # create runtime with auto-detection
+    rt = create_runtime(provider="anthropic", model="claude-sonnet-4-20250514")
+"""
+
+import os
+import shutil
+
+
+# -- Provider registry -------------------------------------------------------
+
+# Maps provider name -> (class_name, module_path, default_model)
+PROVIDERS = {
+    "claude-code":  ("ClaudeCodeRuntime",  "agentic.providers.claude_code",  "sonnet"),
+    "codex":        ("CodexRuntime",       "agentic.providers.codex",        "o4-mini"),
+    "gemini-cli":   ("GeminiCLIRuntime",   "agentic.providers.gemini_cli",   "default"),
+    "anthropic":    ("AnthropicRuntime",    "agentic.providers.anthropic",    "claude-sonnet-4-20250514"),
+    "openai":       ("OpenAIRuntime",       "agentic.providers.openai",       "gpt-4o"),
+    "gemini":       ("GeminiRuntime",       "agentic.providers.gemini",       "gemini-2.5-flash"),
+}
+
+
+def detect_provider() -> tuple[str, str]:
+    """Auto-detect the best available LLM provider.
+
+    Detection priority (CLI-first, then API keys):
+      1. Claude Code CLI  (`claude` in PATH)       — subscription, no per-token cost
+      2. Codex CLI         (`codex` in PATH)        — uses codex auth
+      3. Gemini CLI        (`gemini` in PATH)       — uses Google account
+      4. Anthropic API     (ANTHROPIC_API_KEY set)  — pay per token
+      5. OpenAI API        (OPENAI_API_KEY set)     — pay per token
+      6. Gemini API        (GOOGLE_API_KEY set)     — pay per token
+
+    Returns:
+        (provider_name, default_model) — e.g. ("claude-code", "sonnet")
+
+    Raises:
+        RuntimeError if no provider is found.
+    """
+    # CLI providers (no API key needed)
+    if shutil.which("claude"):
+        return "claude-code", "sonnet"
+    if shutil.which("codex"):
+        return "codex", "o4-mini"
+    if shutil.which("gemini"):
+        return "gemini-cli", "default"
+
+    # API providers (need keys)
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return "anthropic", "claude-sonnet-4-20250514"
+    if os.environ.get("OPENAI_API_KEY"):
+        return "openai", "gpt-4o"
+    if os.environ.get("GOOGLE_API_KEY"):
+        return "gemini", "gemini-2.5-flash"
+
+    raise RuntimeError(
+        "No LLM provider found. Set up one of the following:\n"
+        "\n"
+        "  CLI providers (no API key needed):\n"
+        "    1. Claude Code CLI:  npm install -g @anthropic-ai/claude-code && claude login\n"
+        "    2. Codex CLI:        npm install -g @openai/codex && codex auth\n"
+        "    3. Gemini CLI:       npm install -g @anthropic-ai/gemini-cli\n"
+        "\n"
+        "  API providers (set environment variable):\n"
+        "    4. Anthropic:  export ANTHROPIC_API_KEY=sk-ant-...\n"
+        "    5. OpenAI:     export OPENAI_API_KEY=sk-...\n"
+        "    6. Gemini:     export GOOGLE_API_KEY=...\n"
+    )
+
+
+def create_runtime(provider: str = None, model: str = None, **kwargs):
+    """Create a Runtime instance with auto-detection or explicit provider.
+
+    Args:
+        provider:  Provider name (e.g. "anthropic", "claude-code", "openai").
+                   If None, auto-detects the best available provider.
+        model:     Model name override.
+        **kwargs:  Forwarded to the provider Runtime constructor.
+
+    Returns:
+        A Runtime instance ready to use.
+    """
+    import importlib
+
+    if provider:
+        if provider not in PROVIDERS:
+            available = ", ".join(sorted(PROVIDERS.keys()))
+            raise ValueError(
+                f"Unknown provider: {provider!r}. Available: {available}"
+            )
+        class_name, module_path, default_model = PROVIDERS[provider]
+    else:
+        detected, default_model = detect_provider()
+        class_name, module_path, _ = PROVIDERS[detected]
+        provider = detected
+
+    use_model = model or default_model
+
+    mod = importlib.import_module(module_path)
+    cls = getattr(mod, class_name)
+    return cls(model=use_model, **kwargs)
+
+
+# -- Lazy imports for direct class access ------------------------------------
+
+def __getattr__(name):
+    """Lazy imports — only load a provider when accessed."""
+    if name == "AnthropicRuntime":
+        from agentic.providers.anthropic import AnthropicRuntime
+        return AnthropicRuntime
+    if name == "OpenAIRuntime":
+        from agentic.providers.openai import OpenAIRuntime
+        return OpenAIRuntime
+    if name == "GeminiRuntime":
+        from agentic.providers.gemini import GeminiRuntime
+        return GeminiRuntime
+    if name == "ClaudeCodeRuntime":
+        from agentic.providers.claude_code import ClaudeCodeRuntime
+        return ClaudeCodeRuntime
+    if name == "CodexRuntime":
+        from agentic.providers.codex import CodexRuntime
+        return CodexRuntime
+    if name == "GeminiCLIRuntime":
+        from agentic.providers.gemini_cli import GeminiCLIRuntime
+        return GeminiCLIRuntime
+    raise AttributeError(f"module 'agentic.providers' has no attribute {name!r}")
+
+
+__all__ = [
+    "PROVIDERS",
+    "detect_provider",
+    "create_runtime",
+    "AnthropicRuntime",
+    "OpenAIRuntime",
+    "GeminiRuntime",
+    "ClaudeCodeRuntime",
+    "CodexRuntime",
+    "GeminiCLIRuntime",
+]

agentic/providers/anthropic.py

@@ -0,0 +1,234 @@
+"""
+AnthropicRuntime — Runtime subclass for Anthropic Claude API.
+
+Supports:
+    - Text and image content blocks
+    - PDF/document content blocks (Anthropic document type)
+    - Prompt caching via cache_control
+    - System prompts
+    - Max tokens configuration
+
+Requires: pip install anthropic
+
+Usage:
+    from agentic.providers import AnthropicRuntime
+
+    rt = AnthropicRuntime(api_key="sk-...", model="claude-sonnet-4-20250514")
+
+    @agentic_function
+    def analyze(task):
+        '''Analyze the given task.'''
+        return rt.exec(content=[
+            {"type": "text", "text": f"Analyze: {task}"},
+        ])
+"""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+import os
+from typing import Optional
+
+from agentic.runtime import Runtime
+
+try:
+    import anthropic
+except ImportError:
+    raise ImportError(
+        "AnthropicRuntime requires the 'anthropic' package.\n"
+        "Install it with: pip install anthropic"
+    )
+
+
+class AnthropicRuntime(Runtime):
+    """
+    Runtime implementation for Anthropic Claude.
+
+    Args:
+        api_key:        Anthropic API key. If None, reads from ANTHROPIC_API_KEY env var.
+        model:          Default model name (e.g. "claude-sonnet-4-20250514").
+        max_tokens:     Maximum tokens in the response (default: 4096).
+        system:         System prompt. If provided, sent as the system parameter.
+        cache_system:   Whether to cache the system prompt (default: True).
+                        Adds cache_control to the system block for prompt caching.
+        max_retries:    Maximum number of exec() attempts before raising.
+        **client_kwargs: Additional kwargs passed to anthropic.Anthropic().
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "claude-sonnet-4-20250514",
+        max_tokens: int = 4096,
+        system: Optional[str] = None,
+        cache_system: bool = True,
+        max_retries: int = 2,
+        **client_kwargs,
+    ):
+        super().__init__(model=model, max_retries=max_retries)
+        self.max_tokens = max_tokens
+        self.system = system
+        self.cache_system = cache_system
+
+        api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "Anthropic API key is required. Pass api_key= or set ANTHROPIC_API_KEY env var."
+            )
+        self.client = anthropic.Anthropic(api_key=api_key, **client_kwargs)
+
+    def _call(
+        self,
+        content: list[dict],
+        model: str = "default",
+        response_format: Optional[dict] = None,
+    ) -> str:
+        """
+        Call Anthropic Claude API.
+
+        Content blocks are converted to Anthropic's format:
+            {"type": "text", "text": "..."}
+                → {"type": "text", "text": "..."}
+
+            {"type": "image", "path": "screenshot.png"}
+                → {"type": "image", "source": {"type": "base64", ...}}
+
+            {"type": "image", "data": "<base64>", "media_type": "image/png"}
+                → {"type": "image", "source": {"type": "base64", ...}}
+
+        If cache_control is set on a content block, it's passed through.
+        """
+        messages_content = []
+        for block in content:
+            converted = self._convert_block(block)
+            if converted:
+                messages_content.append(converted)
+
+        # Enable prompt caching on the last content block
+        if messages_content:
+            messages_content[-1]["cache_control"] = {"type": "ephemeral"}
+
+        kwargs = {
+            "model": model if model != "default" else self.model,
+            "max_tokens": self.max_tokens,
+            "messages": [{"role": "user", "content": messages_content}],
+        }
+
+        # System prompt with optional caching
+        if self.system:
+            if self.cache_system:
+                kwargs["system"] = [
+                    {
+                        "type": "text",
+                        "text": self.system,
+                        "cache_control": {"type": "ephemeral"},
+                    }
+                ]
+            else:
+                kwargs["system"] = self.system
+
+        response = self.client.messages.create(**kwargs)
+        return response.content[0].text
+
+    def _convert_block(self, block: dict) -> Optional[dict]:
+        """Convert a generic content block to Anthropic format."""
+        block_type = block.get("type", "text")
+
+        if block_type == "text":
+            result = {"type": "text", "text": block["text"]}
+            if "cache_control" in block:
+                result["cache_control"] = block["cache_control"]
+            return result
+
+        if block_type == "image":
+            # Image from base64 data
+            if "data" in block:
+                media_type = block.get("media_type", "image/png")
+                return {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": media_type,
+                        "data": block["data"],
+                    },
+                }
+
+            # Image from file path
+            if "path" in block:
+                path = block["path"]
+                media_type = mimetypes.guess_type(path)[0] or "image/png"
+                with open(path, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("utf-8")
+                return {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": media_type,
+                        "data": data,
+                    },
+                }
+
+            # Image from URL
+            if "url" in block:
+                return {
+                    "type": "image",
+                    "source": {
+                        "type": "url",
+                        "url": block["url"],
+                    },
+                }
+
+        if block_type == "file":
+            # PDF/document support via Anthropic's document content type
+            mime_type = block.get("mime_type", "application/pdf")
+
+            if "data" in block:
+                return {
+                    "type": "document",
+                    "source": {
+                        "type": "base64",
+                        "media_type": mime_type,
+                        "data": block["data"],
+                    },
+                }
+
+            if "path" in block:
+                path = block["path"]
+                detected_mime = mimetypes.guess_type(path)[0] or mime_type
+                with open(path, "rb") as f:
+                    data = base64.b64encode(f.read()).decode("utf-8")
+                return {
+                    "type": "document",
+                    "source": {
+                        "type": "base64",
+                        "media_type": detected_mime,
+                        "data": data,
+                    },
+                }
+
+        if block_type == "audio":
+            import warnings
+            warnings.warn(
+                "AnthropicRuntime does not support audio content blocks. "
+                "Audio block will be skipped. Consider using GeminiRuntime or OpenAIRuntime for audio.",
+                UserWarning,
+                stacklevel=3,
+            )
+            return None
+
+        if block_type == "video":
+            import warnings
+            warnings.warn(
+                "AnthropicRuntime does not support video content blocks. "
+                "Video block will be skipped. Consider using GeminiRuntime for video.",
+                UserWarning,
+                stacklevel=3,
+            )
+            return None
+
+        # Unknown block type — pass text representation
+        if "text" in block:
+            return {"type": "text", "text": block["text"]}
+
+        return None