icdev 1.0.0__py3-none-any.whl

icdev/tools/llm/provider.py

@@ -0,0 +1,355 @@
+# [TEMPLATE: CUI // SP-CTI]
+"""Vendor-agnostic LLM provider base classes and data types.
+
+Defines the universal request/response format and abstract interfaces
+that all provider implementations must satisfy.
+"""
+
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterator, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Vendor-agnostic request / response
+# ---------------------------------------------------------------------------
+@dataclass
+class LLMRequest:
+    """Vendor-agnostic LLM invocation request."""
+    messages: List[Dict[str, Any]] = field(default_factory=list)
+    system_prompt: str = ""
+    model: str = ""                          # logical name from config
+    max_tokens: int = 4096
+    temperature: float = 1.0
+    tools: Optional[List[Dict]] = None       # OpenAI function-calling format
+    output_schema: Optional[Dict] = None
+    stop_sequences: Optional[List[str]] = None
+    effort: str = "medium"                   # low, medium, high, max
+    # Tracking metadata
+    agent_id: str = ""
+    project_id: str = ""
+    classification: str = "CUI"
+
+
+@dataclass
+class LLMResponse:
+    """Vendor-agnostic LLM invocation response."""
+    content: str = ""
+    tool_calls: List[Dict] = field(default_factory=list)
+    structured_output: Optional[Dict] = None
+    model_id: str = ""                       # actual provider model ID used
+    provider: str = ""                       # "bedrock", "anthropic", "openai", "ollama"
+    input_tokens: int = 0
+    output_tokens: int = 0
+    thinking_tokens: int = 0                 # 0 for non-Anthropic
+    duration_ms: int = 0
+    stop_reason: str = ""
+    classification: str = "CUI"
+
+
+# ---------------------------------------------------------------------------
+# Abstract base: LLM Provider
+# ---------------------------------------------------------------------------
+class LLMProvider(ABC):
+    """Abstract base class for LLM providers.
+
+    Each provider implementation handles:
+    - Message format translation (universal <-> vendor)
+    - Tool format translation
+    - API invocation with retry
+    - Response parsing back to LLMResponse
+    """
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the provider identifier (e.g. 'bedrock', 'openai')."""
+
+    @abstractmethod
+    def invoke(self, request: LLMRequest, model_id: str, model_config: dict) -> LLMResponse:
+        """Invoke the LLM synchronously.
+
+        Args:
+            request: Vendor-agnostic request.
+            model_id: Provider-specific model identifier.
+            model_config: Model configuration from llm_config.yaml.
+
+        Returns:
+            Vendor-agnostic response.
+        """
+
+    def invoke_streaming(self, request: LLMRequest, model_id: str,
+                         model_config: dict) -> Iterator[dict]:
+        """Invoke the LLM with streaming response.
+
+        Default implementation falls back to non-streaming invoke.
+
+        Yields dicts with type key: text, thinking, tool_use_start,
+        tool_use_input, message_delta, message_stop, error.
+        """
+        resp = self.invoke(request, model_id, model_config)
+        yield {"type": "text", "text": resp.content}
+        yield {
+            "type": "message_stop",
+            "model_id": resp.model_id,
+            "duration_ms": resp.duration_ms,
+        }
+
+    @abstractmethod
+    def check_availability(self, model_id: str) -> bool:
+        """Check if a specific model is available.
+
+        Args:
+            model_id: Provider-specific model identifier.
+
+        Returns:
+            True if the model can accept requests.
+        """
+
+
+# ---------------------------------------------------------------------------
+# Abstract base: Embedding Provider
+# ---------------------------------------------------------------------------
+class EmbeddingProvider(ABC):
+    """Abstract base class for embedding providers."""
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the provider identifier."""
+
+    @property
+    @abstractmethod
+    def dimensions(self) -> int:
+        """Return the embedding dimensionality."""
+
+    @abstractmethod
+    def embed(self, text: str) -> List[float]:
+        """Generate an embedding vector for a single text.
+
+        Args:
+            text: Input text to embed.
+
+        Returns:
+            List of floats representing the embedding vector.
+        """
+
+    def embed_batch(self, texts: List[str]) -> List[List[float]]:
+        """Generate embeddings for multiple texts.
+
+        Default implementation calls embed() in a loop.
+        Providers with batch APIs should override.
+
+        Args:
+            texts: List of input texts.
+
+        Returns:
+            List of embedding vectors.
+        """
+        return [self.embed(t) for t in texts]
+
+    @abstractmethod
+    def check_availability(self) -> bool:
+        """Check if the embedding model is available."""
+
+
+# ---------------------------------------------------------------------------
+# Message format translators
+# ---------------------------------------------------------------------------
+def _convert_image_block_to_anthropic(block: dict) -> dict:
+    """Convert an OpenAI image_url block to Anthropic image block.
+
+    OpenAI: {"type": "image_url", "image_url": {"url": "data:image/png;base64,DATA"}}
+    Anthropic: {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "DATA"}}
+    """
+    url = block.get("image_url", {}).get("url", "")
+    if url.startswith("data:"):
+        # Parse data URI: data:image/png;base64,DATA
+        header, _, b64_data = url.partition(",")
+        media_type = header.split(":")[1].split(";")[0] if ":" in header else "image/png"
+        return {
+            "type": "image",
+            "source": {"type": "base64", "media_type": media_type, "data": b64_data},
+        }
+    # Non-data URI (URL reference) — pass through as-is for providers that support it
+    return block
+
+
+def _convert_image_block_to_openai(block: dict) -> dict:
+    """Convert an Anthropic image block to OpenAI image_url block.
+
+    Anthropic: {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "DATA"}}
+    OpenAI: {"type": "image_url", "image_url": {"url": "data:image/png;base64,DATA"}}
+    """
+    source = block.get("source", {})
+    media_type = source.get("media_type", "image/png")
+    b64_data = source.get("data", "")
+    return {
+        "type": "image_url",
+        "image_url": {"url": f"data:{media_type};base64,{b64_data}"},
+    }
+
+
+def _has_image_blocks(content: list) -> bool:
+    """Check if a content block list contains any image blocks."""
+    for block in content:
+        if isinstance(block, dict):
+            btype = block.get("type", "")
+            if btype in ("image", "image_url"):
+                return True
+    return False
+
+
+def messages_to_anthropic(messages: List[Dict]) -> List[Dict]:
+    """Convert universal message format to Anthropic format.
+
+    Anthropic expects: {"role": "user"/"assistant", "content": [{"type": "text", "text": "..."}]}
+    Universal may use: {"role": "user", "content": "plain string"} (OpenAI style)
+
+    Handles image blocks:
+    - OpenAI image_url blocks are converted to Anthropic image blocks
+    - Anthropic image blocks are passed through unchanged
+    """
+    result = []
+    for msg in messages:
+        content = msg.get("content", "")
+        role = msg.get("role", "user")
+        if isinstance(content, str):
+            result.append({
+                "role": role,
+                "content": [{"type": "text", "text": content}],
+            })
+        elif isinstance(content, list):
+            # Convert any OpenAI image_url blocks to Anthropic format
+            converted_blocks = []
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "image_url":
+                    converted_blocks.append(_convert_image_block_to_anthropic(block))
+                else:
+                    converted_blocks.append(block)
+            result.append({"role": role, "content": converted_blocks})
+        else:
+            result.append(msg)
+    return result
+
+
+def messages_to_openai(messages: List[Dict]) -> List[Dict]:
+    """Convert universal message format to OpenAI format.
+
+    OpenAI expects: {"role": "user"/"assistant"/"system", "content": "string"}
+    Anthropic sends: {"role": "user", "content": [{"type": "text", "text": "..."}]}
+
+    For multimodal messages (containing images), preserves list-of-blocks format
+    using OpenAI vision content parts instead of flattening to string.
+    """
+    result = []
+    for msg in messages:
+        content = msg.get("content", "")
+        role = msg.get("role", "user")
+        if isinstance(content, list):
+            if _has_image_blocks(content):
+                # Multimodal: preserve as list of content parts (OpenAI vision format)
+                parts = []
+                for block in content:
+                    if isinstance(block, dict):
+                        btype = block.get("type", "")
+                        if btype == "text":
+                            parts.append({"type": "text", "text": block.get("text", "")})
+                        elif btype == "image_url":
+                            # Already in OpenAI format
+                            parts.append(block)
+                        elif btype == "image":
+                            # Convert Anthropic image to OpenAI image_url
+                            parts.append(_convert_image_block_to_openai(block))
+                        elif btype == "tool_result":
+                            inner = block.get("content", [])
+                            for ib in inner:
+                                if isinstance(ib, dict) and ib.get("type") == "text":
+                                    parts.append({"type": "text", "text": ib.get("text", "")})
+                result.append({"role": role, "content": parts})
+            else:
+                # Text-only: flatten to string (original behavior)
+                text_parts = []
+                for block in content:
+                    if isinstance(block, dict):
+                        if block.get("type") == "text":
+                            text_parts.append(block.get("text", ""))
+                        elif block.get("type") == "tool_result":
+                            inner = block.get("content", [])
+                            for ib in inner:
+                                if isinstance(ib, dict) and ib.get("type") == "text":
+                                    text_parts.append(ib.get("text", ""))
+                result.append({"role": role, "content": "\n".join(text_parts)})
+        else:
+            result.append({"role": role, "content": content})
+    return result
+
+
+def tools_to_anthropic(tools: List[Dict]) -> List[Dict]:
+    """Convert OpenAI function-calling tool format to Anthropic tool format.
+
+    OpenAI: {"type": "function", "function": {"name": ..., "parameters": ...}}
+    Anthropic: {"name": ..., "description": ..., "input_schema": ...}
+    """
+    result = []
+    for tool in tools:
+        if "function" in tool:
+            func = tool["function"]
+            result.append({
+                "name": func.get("name", ""),
+                "description": func.get("description", ""),
+                "input_schema": func.get("parameters", {}),
+            })
+        elif "name" in tool and "input_schema" in tool:
+            # Already in Anthropic format
+            result.append(tool)
+        else:
+            result.append(tool)
+    return result
+
+
+def tools_to_openai(tools: List[Dict]) -> List[Dict]:
+    """Convert Anthropic tool format to OpenAI function-calling format.
+
+    Anthropic: {"name": ..., "description": ..., "input_schema": ...}
+    OpenAI: {"type": "function", "function": {"name": ..., "parameters": ...}}
+    """
+    result = []
+    for tool in tools:
+        if "function" in tool:
+            # Already in OpenAI format
+            result.append(tool)
+        elif "name" in tool:
+            result.append({
+                "type": "function",
+                "function": {
+                    "name": tool.get("name", ""),
+                    "description": tool.get("description", ""),
+                    "parameters": tool.get("input_schema", tool.get("inputSchema", {})),
+                },
+            })
+        else:
+            result.append(tool)
+    return result
+
+
+def tool_calls_from_openai(choices_message: dict) -> List[Dict]:
+    """Extract tool calls from OpenAI response format into universal format.
+
+    Returns list of {"id": ..., "name": ..., "input": ...}
+    """
+    result = []
+    for tc in choices_message.get("tool_calls", []):
+        func = tc.get("function", {})
+        args_str = func.get("arguments", "{}")
+        try:
+            args = json.loads(args_str)
+        except (json.JSONDecodeError, ValueError):
+            args = {"raw": args_str}
+        result.append({
+            "id": tc.get("id", ""),
+            "name": func.get("name", ""),
+            "input": args,
+        })
+    return result

icdev/tools/llm/provider_sdk.py

@@ -0,0 +1,175 @@
+# [TEMPLATE: CUI // SP-CTI]
+"""ICDEV LLM Provider SDK — Public API for custom provider development.
+
+Re-exports the core provider interfaces, request/response types, format
+helpers, and a test harness for validating custom implementations.
+
+Usage for building a custom provider::
+
+    from icdev.tools.llm.provider_sdk import (
+        BaseProvider,
+        LLMRequest,
+        LLMResponse,
+        EmbeddingProvider,
+        ProviderTestHarness,
+    )
+
+    class MyProvider(BaseProvider):
+        @property
+        def provider_name(self): return "my_provider"
+        def invoke(self, request, model_id, model_config): ...
+        def check_availability(self, model_id): ...
+
+    # Validate your implementation
+    harness = ProviderTestHarness(MyProvider())
+    harness.run_all()
+
+Decision D66: ABC + implementations provider pattern.
+Decision D67: OpenAI-compatible covers Ollama, vLLM, Azure.
+Decision D68: Function-level LLM routing (not agent-level).
+"""
+
+import logging
+from typing import List
+
+# Re-export core types
+from icdev.tools.llm.provider import (
+    LLMProvider as BaseProvider,
+    LLMRequest,
+    LLMResponse,
+    EmbeddingProvider,
+    messages_to_anthropic,
+    messages_to_openai,
+    tools_to_anthropic,
+    tools_to_openai,
+)
+
+logger = logging.getLogger("icdev.llm.provider_sdk")
+
+__all__ = [
+    "BaseProvider",
+    "LLMRequest",
+    "LLMResponse",
+    "EmbeddingProvider",
+    "messages_to_anthropic",
+    "messages_to_openai",
+    "tools_to_anthropic",
+    "tools_to_openai",
+    "ProviderTestHarness",
+]
+
+
+class ProviderTestHarness:
+    """Test harness for validating custom LLM provider implementations.
+
+    Usage::
+
+        from icdev.tools.llm.provider_sdk import BaseProvider, ProviderTestHarness
+
+        class MyProvider(BaseProvider):
+            ...
+
+        harness = ProviderTestHarness(MyProvider())
+        results = harness.run_all()
+        for name, passed, msg in results:
+            print(f"{'PASS' if passed else 'FAIL'}: {name} — {msg}")
+    """
+
+    def __init__(self, provider: BaseProvider):
+        self.provider = provider
+
+    def test_implements_abc(self) -> tuple:
+        """Verify the provider implements all required abstract methods."""
+        name = "implements_abc"
+        try:
+            assert hasattr(self.provider, "provider_name"), "Missing provider_name property"
+            assert hasattr(self.provider, "invoke"), "Missing invoke() method"
+            assert hasattr(self.provider, "check_availability"), "Missing check_availability()"
+            assert callable(self.provider.invoke), "invoke must be callable"
+            assert callable(self.provider.check_availability), "check_availability must be callable"
+            pname = self.provider.provider_name
+            assert isinstance(pname, str) and len(pname) > 0, "provider_name must be non-empty string"
+            return (name, True, "All ABC methods implemented")
+        except AssertionError as exc:
+            return (name, False, str(exc))
+        except Exception as exc:
+            return (name, False, f"Unexpected error: {exc}")
+
+    def test_invoke_returns_response(self) -> tuple:
+        """Test that invoke returns an LLMResponse (may fail if provider is offline)."""
+        name = "invoke_returns_response"
+        try:
+            req = LLMRequest(
+                messages=[{"role": "user", "content": "Say hello in exactly one word."}],
+                max_tokens=50,
+                temperature=0.0,
+            )
+            resp = self.provider.invoke(req, "test-model", {})
+            assert isinstance(resp, LLMResponse), f"Expected LLMResponse, got {type(resp)}"
+            assert isinstance(resp.content, str), "content must be a string"
+            return (name, True, f"Got response: {resp.content[:50]}")
+        except NotImplementedError:
+            return (name, False, "invoke() not implemented")
+        except Exception as exc:
+            return (name, False, f"Invocation failed (provider may be offline): {exc}")
+
+    def test_check_availability(self) -> tuple:
+        """Test that check_availability returns a boolean."""
+        name = "check_availability"
+        try:
+            result = self.provider.check_availability("test-model")
+            assert isinstance(result, bool), f"Expected bool, got {type(result)}"
+            return (name, True, f"Available: {result}")
+        except Exception as exc:
+            return (name, False, f"Error: {exc}")
+
+    def test_streaming_fallback(self) -> tuple:
+        """Test that invoke_streaming works (at least via fallback)."""
+        name = "streaming_fallback"
+        try:
+            req = LLMRequest(
+                messages=[{"role": "user", "content": "Say hi."}],
+                max_tokens=20,
+            )
+            chunks = list(self.provider.invoke_streaming(req, "test-model", {}))
+            assert len(chunks) > 0, "No chunks returned"
+            assert any(c.get("type") == "text" for c in chunks), "No text chunk found"
+            return (name, True, f"Got {len(chunks)} chunks")
+        except Exception as exc:
+            return (name, False, f"Streaming failed: {exc}")
+
+    def test_error_handling(self) -> tuple:
+        """Test that the provider handles invalid input gracefully."""
+        name = "error_handling"
+        try:
+            req = LLMRequest(messages=[], max_tokens=0)
+            try:
+                self.provider.invoke(req, "", {})
+                return (name, True, "No error on empty input (provider is lenient)")
+            except (ValueError, RuntimeError, TypeError):
+                return (name, True, "Provider correctly raises on invalid input")
+            except Exception as exc:
+                return (name, True, f"Provider raised {type(exc).__name__} on invalid input")
+        except Exception as exc:
+            return (name, False, f"Unexpected error: {exc}")
+
+    def run_all(self) -> List[tuple]:
+        """Run all test methods and return results.
+
+        Returns:
+            List of (test_name, passed, message) tuples.
+        """
+        results = [
+            self.test_implements_abc(),
+            self.test_check_availability(),
+            self.test_invoke_returns_response(),
+            self.test_streaming_fallback(),
+            self.test_error_handling(),
+        ]
+        passed = sum(1 for _, p, _ in results if p)
+        total = len(results)
+        logger.info(
+            "ProviderTestHarness: %d/%d tests passed for %s",
+            passed, total, self.provider.provider_name,
+        )
+        return results