llmcode-cli 1.0.0__py3-none-any.whl

llm_code/api/client.py

@@ -0,0 +1,90 @@
+"""Provider client factory — routes model names to the correct provider."""
+from __future__ import annotations
+
+from llm_code.api.provider import LLMProvider
+from llm_code.runtime.model_aliases import resolve_model
+
+
+class ProviderClient:
+    """Factory for creating LLMProvider instances based on model name."""
+
+    @staticmethod
+    def from_model(
+        model: str,
+        base_url: str = "",
+        api_key: str = "",
+        timeout: float = 120.0,
+        max_retries: int = 2,
+        native_tools: bool = True,
+        custom_aliases: dict[str, str] | None = None,
+    ) -> LLMProvider:
+        """Return the appropriate LLMProvider for the given model name.
+
+        Routing rules:
+        - Models starting with "claude-" → AnthropicProvider (requires
+          the ``anthropic`` SDK to be installed).
+        - Everything else → OpenAICompatProvider.
+        """
+        model = resolve_model(model, custom_aliases)
+        if model.startswith("claude-"):
+            return ProviderClient._make_anthropic(
+                model=model,
+                api_key=api_key,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+
+        return ProviderClient._make_openai_compat(
+            model=model,
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            native_tools=native_tools,
+        )
+
+    # ------------------------------------------------------------------
+    # Private factory helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _make_openai_compat(
+        model: str,
+        base_url: str,
+        api_key: str,
+        timeout: float,
+        max_retries: int,
+        native_tools: bool,
+    ) -> LLMProvider:
+        from llm_code.api.openai_compat import OpenAICompatProvider
+
+        return OpenAICompatProvider(
+            base_url=base_url,
+            api_key=api_key,
+            model_name=model,
+            timeout=timeout,
+            max_retries=max_retries,
+            native_tools=native_tools,
+        )
+
+    @staticmethod
+    def _make_anthropic(
+        model: str,
+        api_key: str,
+        timeout: float,
+        max_retries: int,
+    ) -> LLMProvider:
+        try:
+            from llm_code.api.anthropic_provider import AnthropicProvider  # type: ignore[import]
+        except ImportError:
+            raise ImportError(
+                "The 'anthropic' SDK is required to use Claude models. "
+                "Install it with: pip install anthropic"
+            )
+
+        return AnthropicProvider(
+            api_key=api_key,
+            model_name=model,
+            timeout=timeout,
+            max_retries=max_retries,
+        )

llm_code/api/errors.py

@@ -0,0 +1,73 @@
+"""Exception hierarchy for the llm-code API layer."""
+from __future__ import annotations
+
+
+class LLMCodeError(Exception):
+    """Base exception for all llm-code errors."""
+
+
+class ProviderError(LLMCodeError):
+    """Error returned by or related to an LLM provider."""
+
+    def __init__(self, message: str, *, is_retryable: bool = False) -> None:
+        super().__init__(message)
+        self.is_retryable = is_retryable
+
+
+class ProviderConnectionError(ProviderError):
+    """Network-level failure connecting to the provider (retryable)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, is_retryable=True)
+
+
+class ProviderAuthError(ProviderError):
+    """Authentication / authorisation failure (not retryable)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, is_retryable=False)
+
+
+class ProviderRateLimitError(ProviderError):
+    """Provider rate-limit exceeded (retryable)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, is_retryable=True)
+
+
+class ProviderModelNotFoundError(ProviderError):
+    """Requested model does not exist on the provider (not retryable)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, is_retryable=False)
+
+
+class ProviderOverloadError(ProviderError):
+    """Provider is overloaded (HTTP 529); retryable with long backoff."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, is_retryable=True)
+
+
+class ToolError(LLMCodeError):
+    """Base exception for tool-related errors."""
+
+
+class ToolNotFoundError(ToolError):
+    """A tool referenced by name does not exist in the registry."""
+
+
+class ToolPermissionDenied(ToolError):
+    """The tool is not permitted under the current permission policy."""
+
+
+class ToolExecutionError(ToolError):
+    """A tool raised an error during execution."""
+
+
+class ConfigError(LLMCodeError):
+    """Invalid or missing configuration."""
+
+
+class SessionError(LLMCodeError):
+    """Error related to conversation session state."""

llm_code/api/openai_compat.py

@@ -0,0 +1,390 @@
+"""OpenAI-compatible provider implementation."""
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import AsyncIterator
+
+import httpx
+
+from llm_code.api.errors import (
+    ProviderAuthError,
+    ProviderConnectionError,
+    ProviderModelNotFoundError,
+    ProviderOverloadError,
+    ProviderRateLimitError,
+)
+from llm_code.api.provider import LLMProvider
+from llm_code.api.sse import parse_sse_events
+from llm_code.api.types import (
+    ContentBlock,
+    ImageBlock,
+    Message,
+    MessageRequest,
+    MessageResponse,
+    StreamEvent,
+    StreamMessageStop,
+    StreamTextDelta,
+    StreamToolUseInputDelta,
+    StreamToolUseStart,
+    TextBlock,
+    TokenUsage,
+    ToolDefinition,
+    ToolResultBlock,
+    ToolUseBlock,
+)
+
+
+class OpenAICompatProvider(LLMProvider):
+    """Provider adapter for OpenAI-compatible APIs (Ollama, vLLM, LM Studio, etc.)."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str = "",
+        model_name: str = "",
+        max_retries: int = 2,
+        timeout: float = 120.0,
+        native_tools: bool = True,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._model_name = model_name
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._native_tools = native_tools
+
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        self._client = httpx.AsyncClient(
+            headers=headers,
+            timeout=httpx.Timeout(timeout),
+        )
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    async def send_message(self, request: MessageRequest) -> MessageResponse:
+        payload = self._build_payload(request, stream=False)
+        response = await self._post_with_retry(payload)
+        return self._parse_response(response)
+
+    async def stream_message(self, request: MessageRequest) -> AsyncIterator[StreamEvent]:
+        payload = self._build_payload(request, stream=True)
+        response = await self._post_with_retry(payload)
+        return self._iter_stream_events(response.text)
+
+    def supports_native_tools(self) -> bool:
+        return self._native_tools
+
+    def supports_images(self) -> bool:
+        return False
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _build_messages(
+        self,
+        messages: tuple[Message, ...],
+        system: str | None = None,
+    ) -> list[dict]:
+        result: list[dict] = []
+
+        if system:
+            result.append({"role": "system", "content": system})
+
+        for msg in messages:
+            result.append(self._convert_message(msg))
+
+        return result
+
+    def _convert_message(self, msg: Message) -> dict:
+        # Tool result messages use the "tool" role in OpenAI format
+        if msg.role == "tool" or (
+            len(msg.content) == 1 and isinstance(msg.content[0], ToolResultBlock)
+        ):
+            block = msg.content[0]
+            assert isinstance(block, ToolResultBlock)
+            return {
+                "role": "tool",
+                "tool_call_id": block.tool_use_id,
+                "content": block.content,
+            }
+
+        # Check if content is mixed (has images or multiple block types)
+        has_image = any(isinstance(b, ImageBlock) for b in msg.content)
+        has_multiple = len(msg.content) > 1
+
+        if has_image or has_multiple:
+            parts: list[dict] = []
+            for block in msg.content:
+                if isinstance(block, TextBlock):
+                    parts.append({"type": "text", "text": block.text})
+                elif isinstance(block, ImageBlock):
+                    parts.append({
+                        "type": "image_url",
+                        "image_url": {
+                            "url": f"data:{block.media_type};base64,{block.data}"
+                        },
+                    })
+            return {"role": msg.role, "content": parts}
+
+        # Single text block — use string content for simplicity
+        if len(msg.content) == 1 and isinstance(msg.content[0], TextBlock):
+            return {"role": msg.role, "content": msg.content[0].text}
+
+        # Fallback: concatenate text blocks
+        text = "".join(
+            b.text for b in msg.content if isinstance(b, TextBlock)
+        )
+        return {"role": msg.role, "content": text}
+
+    def _build_payload(self, request: MessageRequest, *, stream: bool) -> dict:
+        payload: dict = {
+            "model": request.model or self._model_name,
+            "messages": self._build_messages(request.messages, system=request.system),
+            "max_tokens": request.max_tokens,
+            "temperature": request.temperature,
+            "stream": stream,
+        }
+
+        if request.tools and self._native_tools:
+            payload["tools"] = [
+                self._convert_tool(t) for t in request.tools
+            ]
+
+        if stream:
+            payload["stream_options"] = {"include_usage": True}
+
+        if request.extra_body:
+            payload.update(request.extra_body)
+
+        return payload
+
+    def _convert_tool(self, tool: ToolDefinition) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": tool.name,
+                "description": tool.description,
+                "parameters": tool.input_schema,
+            },
+        }
+
+    async def _post_with_retry(self, payload: dict) -> httpx.Response:
+        url = f"{self._base_url}/chat/completions"
+        last_exc: Exception | None = None
+
+        # 529 Overload: separate long-backoff retry track (30s -> 60s -> 120s, max 3 attempts)
+        _OVERLOAD_BACKOFFS = [30, 60, 120]
+        _overload_attempt = 0
+        attempt = 0
+
+        while attempt <= self._max_retries:
+            try:
+                response = await self._client.post(url, json=payload)
+                self._raise_for_status(response)
+                return response
+            except ProviderOverloadError as exc:
+                last_exc = exc
+                if _overload_attempt < len(_OVERLOAD_BACKOFFS):
+                    backoff = _OVERLOAD_BACKOFFS[_overload_attempt]
+                    _overload_attempt += 1
+                    await asyncio.sleep(backoff)
+                    # Overload retries don't count against normal retry budget
+                    continue
+                raise
+            except (ProviderConnectionError, ProviderRateLimitError) as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    await asyncio.sleep(2 ** attempt)
+                    attempt += 1
+                    continue
+                raise
+            except (ProviderAuthError, ProviderModelNotFoundError):
+                raise
+            except httpx.ConnectError as exc:
+                last_exc = ProviderConnectionError(str(exc))
+                if attempt < self._max_retries:
+                    await asyncio.sleep(2 ** attempt)
+                    attempt += 1
+                    continue
+                raise last_exc from exc
+            attempt += 1
+
+        raise last_exc  # type: ignore[misc]
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code == 200:
+            return
+        try:
+            body = response.json()
+            msg = body.get("error", {}).get("message", response.text)
+        except Exception:
+            msg = response.text
+
+        if response.status_code == 401:
+            raise ProviderAuthError(msg)
+        if response.status_code == 404:
+            raise ProviderModelNotFoundError(msg)
+        if response.status_code == 429:
+            raise ProviderRateLimitError(msg)
+        if response.status_code == 529:
+            raise ProviderOverloadError(msg)
+        if response.status_code >= 500:
+            raise ProviderConnectionError(msg)
+        # Other 4xx — treat as connection error
+        raise ProviderConnectionError(f"HTTP {response.status_code}: {msg}")
+
+    def _parse_response(self, response: httpx.Response) -> MessageResponse:
+        data = response.json()
+        choices = data.get("choices")
+        if not choices:
+            raise ProviderConnectionError(f"No choices in API response: {str(data)[:200]}")
+        choice = choices[0]
+        message = choice.get("message")
+        if not message:
+            raise ProviderConnectionError(f"No message in API choice: {str(choice)[:200]}")
+        finish_reason = choice.get("finish_reason") or "stop"
+
+        content_blocks: list[ContentBlock] = []
+
+        tool_calls = message.get("tool_calls")
+        if tool_calls:
+            for tc in tool_calls:
+                fn = tc["function"]
+                try:
+                    args = json.loads(fn["arguments"])
+                except (json.JSONDecodeError, KeyError):
+                    args = {}
+                content_blocks.append(
+                    ToolUseBlock(id=tc["id"], name=fn["name"], input=args)
+                )
+        else:
+            text = message.get("content") or ""
+            content_blocks.append(TextBlock(text=text))
+
+        usage_data = data.get("usage", {})
+        usage = TokenUsage(
+            input_tokens=usage_data.get("prompt_tokens", 0),
+            output_tokens=usage_data.get("completion_tokens", 0),
+        )
+
+        return MessageResponse(
+            content=tuple(content_blocks),
+            usage=usage,
+            stop_reason=finish_reason,
+        )
+
+    def _iter_stream_events(self, raw: str) -> _StreamIterator:
+        """Return async iterator over parsed SSE stream events."""
+        return _StreamIterator(raw)
+
+
+class _StreamIterator:
+    """Async iterator that wraps synchronous SSE parsing."""
+
+    def __init__(self, raw: str) -> None:
+        self._events = list(parse_sse_events(raw))
+        self._index = 0
+        self._pending_tool_calls: dict[int, dict] = {}
+        self._processed: list[StreamEvent] = []
+        self._done = False
+        self._build_events()
+
+    def _build_events(self) -> None:
+        events: list[StreamEvent] = []
+        pending_tools: dict[int, dict] = {}
+        _stop_emitted = False
+        _last_usage: dict = {}
+
+        for chunk in self._events:
+            # Some providers (vLLM, Ollama) send usage in a standalone
+            # final chunk with no choices.  Capture it regardless.
+            chunk_usage = chunk.get("usage")
+            if chunk_usage:
+                _last_usage = chunk_usage
+
+            choices = chunk.get("choices", [])
+            for choice in choices:
+                delta = choice.get("delta", {})
+                finish_reason = choice.get("finish_reason")
+
+                # Text content delta
+                text = delta.get("content")
+                if text:
+                    events.append(StreamTextDelta(text=text))
+
+                # Tool call deltas
+                tool_calls = delta.get("tool_calls", [])
+                for tc in tool_calls:
+                    idx = tc.get("index", 0)
+                    if idx not in pending_tools:
+                        pending_tools[idx] = {
+                            "id": tc.get("id", ""),
+                            "name": tc.get("function", {}).get("name", ""),
+                            "args": "",
+                        }
+                        if pending_tools[idx]["name"]:
+                            events.append(
+                                StreamToolUseStart(
+                                    id=pending_tools[idx]["id"],
+                                    name=pending_tools[idx]["name"],
+                                )
+                            )
+                    # Accumulate argument fragments
+                    args_fragment = tc.get("function", {}).get("arguments", "")
+                    if args_fragment:
+                        pending_tools[idx]["args"] += args_fragment
+                        events.append(
+                            StreamToolUseInputDelta(
+                                id=pending_tools[idx]["id"],
+                                partial_json=args_fragment,
+                            )
+                        )
+
+                # Stop event — emitted exactly once at the end
+                if finish_reason and not _stop_emitted:
+                    _stop_emitted = True
+                    usage_data = chunk_usage or _last_usage or {}
+                    usage = TokenUsage(
+                        input_tokens=usage_data.get("prompt_tokens", 0),
+                        output_tokens=usage_data.get("completion_tokens", 0),
+                    )
+                    events.append(
+                        StreamMessageStop(usage=usage, stop_reason=finish_reason)
+                    )
+
+        # If usage arrived in a trailing chunk after finish_reason, patch it
+        if _stop_emitted and _last_usage:
+            for i in range(len(events) - 1, -1, -1):
+                if isinstance(events[i], StreamMessageStop):
+                    existing = events[i]
+                    if existing.usage.input_tokens == 0 and existing.usage.output_tokens == 0:
+                        events[i] = StreamMessageStop(
+                            usage=TokenUsage(
+                                input_tokens=_last_usage.get("prompt_tokens", 0),
+                                output_tokens=_last_usage.get("completion_tokens", 0),
+                            ),
+                            stop_reason=existing.stop_reason,
+                        )
+                    break
+
+        self._processed = events
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> StreamEvent:
+        if self._index >= len(self._processed):
+            raise StopAsyncIteration
+        event = self._processed[self._index]
+        self._index += 1
+        return event

llm_code/api/provider.py

@@ -0,0 +1,35 @@
+"""Abstract base class for LLM provider implementations."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import AsyncIterator
+
+from llm_code.api.types import MessageRequest, MessageResponse, StreamEvent
+
+
+class LLMProvider(ABC):
+    """Interface that all LLM provider adapters must implement.
+
+    Concrete implementations (e.g. OpenAI-compatible, Anthropic) subclass
+    this and fill in the four abstract methods.
+    """
+
+    @abstractmethod
+    async def send_message(self, request: MessageRequest) -> MessageResponse:
+        """Send a complete (non-streaming) message and return the full response."""
+        ...
+
+    @abstractmethod
+    async def stream_message(self, request: MessageRequest) -> AsyncIterator[StreamEvent]:
+        """Stream a message and return an async iterator of stream events."""
+        ...
+
+    @abstractmethod
+    def supports_native_tools(self) -> bool:
+        """Return True if the provider supports native/function-calling tools."""
+        ...
+
+    @abstractmethod
+    def supports_images(self) -> bool:
+        """Return True if the provider supports image inputs."""
+        ...

llm_code/api/sse.py

@@ -0,0 +1,52 @@
+"""Server-Sent Events (SSE) parser for streaming LLM responses."""
+from __future__ import annotations
+
+import json
+import re
+from typing import Iterator
+
+# Split on blank lines — handles both \n\n and \r\n\r\n
+_BLOCK_SEPARATOR = re.compile(r'\r?\n\r?\n')
+
+
+def parse_sse_events(raw: str) -> Iterator[dict]:
+    """Parse a raw SSE string and yield each event as a parsed dict.
+
+    Rules:
+    - Split on blank-line boundaries (\\n\\n or \\r\\n\\r\\n).
+    - Lines starting with ':' are comments — skipped.
+    - Lines starting with 'data: ' contribute to the event data.
+    - Multiple data lines within one block are joined with '\\n'.
+    - 'data: [DONE]' stops iteration.
+    - Non-data fields (event:, id:, retry:) are silently ignored.
+    - JSON is parsed and yielded as a dict.
+    """
+    for block in _BLOCK_SEPARATOR.split(raw):
+        block = block.strip()
+        if not block:
+            continue
+
+        data_parts: list[str] = []
+        for line in re.split(r'\r?\n', block):
+            if line.startswith(':'):
+                # Comment line — skip
+                continue
+            if line.startswith('data:'):
+                # Strip the field name and a single optional space
+                value = line[5:]
+                if value.startswith(' '):
+                    value = value[1:]
+                if value == '[DONE]':
+                    return
+                data_parts.append(value)
+            # event:, id:, retry: — ignore
+
+        if not data_parts:
+            continue
+
+        joined = '\n'.join(data_parts)
+        try:
+            yield json.loads(joined)
+        except json.JSONDecodeError:
+            # Malformed JSON — skip silently (could log in production)
+            continue