limbo-code 0.1.0__py3-none-any.whl

limbo/history.py

@@ -0,0 +1,90 @@
+"""Message-history bookkeeping for tool calls.
+
+Owns the invariant that keeps the OpenAI API happy: every assistant
+``tool_call`` must have exactly one ``role="tool"`` result message.
+"""
+
+from __future__ import annotations
+
+from limbo.models import Message
+
+INTERRUPTED_CONTENT = "[session restored: tool call interrupted]"
+NOT_EXECUTED_AFTER_FAILURE = "Action not executed: earlier tool failed."
+
+
+class ToolHistory:
+    """Bookkeeper for tool-call results inside a message list."""
+
+    def __init__(self, messages: list[Message]):
+        self.messages = messages
+
+    def record_result(self, tool_call_id: str, content: str) -> None:
+        """Replace the existing result for a call, or append a new one."""
+        for idx, msg in enumerate(self.messages):
+            if msg.role == "tool" and msg.tool_call_id == tool_call_id:
+                self.messages[idx] = msg.model_copy(update={"content": content})
+                break
+        else:
+            self.messages.append(
+                Message(role="tool", content=content, tool_call_id=tool_call_id)
+            )
+
+    def record_error(
+        self,
+        assistant: Message,
+        start_idx: int,
+        crashed_id: str,
+        error_message: str,
+    ) -> None:
+        """Record an error for a crashed call and cancel its later siblings."""
+        tool_calls = assistant.tool_calls or []
+        for idx in range(start_idx, len(tool_calls)):
+            tc = tool_calls[idx]
+            content = (
+                error_message
+                if tc["id"] == crashed_id
+                else NOT_EXECUTED_AFTER_FAILURE
+            )
+            self.record_result(tc["id"], content)
+
+
+def repair(messages: list[Message]) -> list[Message]:
+    """Prepare persisted messages for reuse as LLM history.
+
+    - Drops the leading system message (a fresh one is generated on resume).
+    - Repairs dangling tool_calls: if the previous session crashed between a
+      tool call and its result, placeholder tool messages are inserted
+      immediately after the assistant message so the API history stays valid.
+    """
+    history = list(messages)
+    if history and history[0].role == "system":
+        history = history[1:]
+
+    restored: list[Message] = []
+    pending_tool_ids: list[str] = []
+
+    def flush_pending() -> None:
+        for tool_id in pending_tool_ids:
+            restored.append(
+                Message(
+                    role="tool",
+                    tool_call_id=tool_id,
+                    content=INTERRUPTED_CONTENT,
+                )
+            )
+        pending_tool_ids.clear()
+
+    for msg in history:
+        if msg.role == "assistant" and msg.tool_calls:
+            flush_pending()
+            pending_tool_ids.extend(
+                tc["id"] for tc in msg.tool_calls if tc.get("id")
+            )
+        elif msg.role == "tool":
+            if msg.tool_call_id in pending_tool_ids:
+                pending_tool_ids.remove(msg.tool_call_id)
+        else:
+            flush_pending()
+        restored.append(msg)
+    flush_pending()
+    return restored

limbo/llm/__init__.py

@@ -0,0 +1 @@
+"""LLM client package."""

limbo/llm/anthropic_client.py

@@ -0,0 +1,320 @@
+"""Anthropic Messages API client (e.g. Kimi For Coding).
+
+Implemented directly on httpx SSE rather than the anthropic SDK so that
+newer dialect features — adaptive thinking (``thinking: {type: adaptive}``
+plus ``output_config.effort``), thinking signatures, and interleaved
+thinking deltas — work regardless of the installed SDK version.
+
+Conventions follow pi's anthropic-messages provider:
+
+- API keys authenticate via the ``x-api-key`` header.
+- Reasoning models use adaptive thinking; ``temperature`` is omitted while
+  thinking is enabled.
+- Assistant messages replay their thinking block first, carrying the stored
+  signature (Kimi accepts empty signatures).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import warnings
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from limbo.config import Config
+from limbo.llm.catalog import (
+    ModelSpec,
+    resolve_api_key,
+    resolve_base_url,
+    resolve_model,
+)
+from limbo.llm.client import RequestHook
+from limbo.models import (
+    CompletionMeta,
+    LLMEvent,
+    Message,
+    TextChunk,
+    ThinkingChunk,
+    ToolCallEvent,
+)
+
+ANTHROPIC_VERSION = "2023-06-01"
+
+
+class AnthropicMessagesClient:
+    """Client for the Anthropic Messages API with SSE streaming."""
+
+    def __init__(self, config: Config):
+        self.config = config
+        self.spec: ModelSpec = resolve_model(config.llm.model)
+        self._client: httpx.AsyncClient | None = None
+
+    @property
+    def client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            api_key = resolve_api_key(self.spec, self.config.llm.api_key)
+            if not api_key:
+                env = self.spec.provider.api_key_env
+                raise ValueError(
+                    f"No API key for provider {self.spec.provider.id!r}. "
+                    f"Set [llm] api_key in ~/.limbo/config.toml"
+                    + (f" or the ${env} environment variable." if env else ".")
+                )
+            self._client = httpx.AsyncClient(
+                base_url=resolve_base_url(self.spec, self.config.llm.base_url).rstrip("/"),
+                headers={
+                    "x-api-key": api_key,
+                    "anthropic-version": ANTHROPIC_VERSION,
+                    "accept": "application/json",
+                    **self.spec.provider.headers,
+                },
+                timeout=httpx.Timeout(600.0, connect=30.0),
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client if it has been created."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    # -- request building ----------------------------------------------------
+
+    def _thinking_params(self) -> dict[str, Any]:
+        """Adaptive thinking config for reasoning models."""
+        spec = self.spec
+        if not spec.reasoning or spec.thinking_format != "anthropic-adaptive":
+            return {}
+        params: dict[str, Any] = {
+            "thinking": {"type": "adaptive", "display": "summarized"}
+        }
+        effort = self.config.llm.thinking_effort
+        if effort is not None:
+            value = spec.thinking_levels.get(effort)
+            if value is None:
+                warnings.warn(
+                    f"thinking_effort={effort!r} is not supported by {spec.id} "
+                    f"(supported: {sorted(spec.thinking_levels)}); ignoring.",
+                    stacklevel=2,
+                )
+            else:
+                params["output_config"] = {"effort": value}
+        return params
+
+    def _build_body(
+        self, messages: list[Message], tools: list[dict[str, Any]]
+    ) -> dict[str, Any]:
+        system, request_messages = _messages_to_anthropic(messages)
+        body: dict[str, Any] = {
+            "model": self.config.llm.model,
+            "max_tokens": self.config.llm.max_tokens or self.spec.max_tokens,
+            "messages": request_messages,
+            "stream": True,
+        }
+        if system:
+            body["system"] = system
+        body.update(self._thinking_params())
+        if "thinking" not in body:
+            # Temperature is incompatible with extended thinking.
+            body["temperature"] = self.config.llm.temperature
+        if tools:
+            body["tools"] = [_tool_to_anthropic(t) for t in tools]
+        return body
+
+    # -- streaming -----------------------------------------------------------
+
+    async def chat(
+        self,
+        messages: list[Message],
+        tools: list[dict[str, Any]],
+        on_request: RequestHook | None = None,
+    ) -> AsyncIterator[LLMEvent]:
+        body = self._build_body(messages, tools)
+        if on_request is not None:
+            on_request(body)
+        start = time.monotonic()
+        ttft: float | None = None
+        usage: dict[str, Any] = {}
+        finish_reason: str | None = None
+        async with self.client.stream("POST", "/v1/messages", json=body) as resp:
+            if resp.status_code != 200:
+                error_body = (await resp.aread()).decode("utf-8", "replace")
+                raise RuntimeError(f"Error code: {resp.status_code} - {error_body}")
+
+            # Tool-use blocks accumulate streamed partial JSON by index.
+            tool_blocks: dict[int, dict[str, Any]] = {}
+            async for event in _iter_sse(resp):
+                if ttft is None:
+                    ttft = time.monotonic() - start
+                event_type = event.get("type")
+                if event_type == "message_start":
+                    # usage here carries input tokens, incl. Anthropic cache
+                    # counters (cache_read_input_tokens = cache hits).
+                    message_usage = event.get("message", {}).get("usage")
+                    if isinstance(message_usage, dict):
+                        usage.update(message_usage)
+                elif event_type == "message_delta":
+                    delta_usage = event.get("usage")
+                    if isinstance(delta_usage, dict):
+                        usage.update(delta_usage)
+                    stop = event.get("delta", {}).get("stop_reason")
+                    if stop:
+                        finish_reason = stop
+                elif event_type == "content_block_start":
+                    block = event.get("content_block", {})
+                    if block.get("type") == "tool_use":
+                        tool_blocks[event["index"]] = {
+                            "id": block.get("id", ""),
+                            "name": block.get("name", ""),
+                            "json": "",
+                        }
+                elif event_type == "content_block_delta":
+                    delta = event.get("delta", {})
+                    delta_type = delta.get("type")
+                    if delta_type == "thinking_delta":
+                        yield ThinkingChunk(text=delta.get("thinking", ""))
+                    elif delta_type == "signature_delta":
+                        yield ThinkingChunk(
+                            text="", signature=delta.get("signature", "")
+                        )
+                    elif delta_type == "text_delta":
+                        yield TextChunk(text=delta.get("text", ""))
+                    elif delta_type == "input_json_delta":
+                        block = tool_blocks.get(event["index"])
+                        if block is not None:
+                            block["json"] += delta.get("partial_json", "")
+                elif event_type == "content_block_stop":
+                    block = tool_blocks.pop(event["index"], None)
+                    if block is not None:
+                        yield _tool_call_event(block)
+                elif event_type == "error":
+                    error = event.get("error", {})
+                    raise RuntimeError(
+                        f"{error.get('type', 'error')}: "
+                        f"{error.get('message', 'unknown stream error')}"
+                    )
+
+            # A truncated stream may leave tool blocks open; flush them so the
+            # agent loop can surface the (possibly partial) call.
+            for index in sorted(tool_blocks):
+                yield _tool_call_event(tool_blocks[index])
+
+        yield CompletionMeta(
+            usage=usage or None,
+            finish_reason=finish_reason,
+            ttft=ttft,
+            duration=time.monotonic() - start,
+        )
+
+
+def _tool_call_event(block: dict[str, Any]) -> ToolCallEvent:
+    raw = block["json"]
+    try:
+        args = json.loads(raw) if raw else {}
+    except json.JSONDecodeError as e:
+        args = {"raw_arguments": raw, "parse_error": str(e)}
+    return ToolCallEvent(id=block["id"], name=block["name"], arguments=args)
+
+
+async def _iter_sse(resp: httpx.Response) -> AsyncIterator[dict[str, Any]]:
+    """Yield parsed ``data:`` payloads from an Anthropic SSE stream."""
+    data_lines: list[str] = []
+    async for line in resp.aiter_lines():
+        if not line:
+            if data_lines:
+                payload = "\n".join(data_lines)
+                data_lines = []
+                try:
+                    yield json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+            continue
+        if line.startswith("data:"):
+            data_lines.append(line[len("data:"):].strip())
+        # event:/id:/retry: lines and comments (: ping) are ignored; the
+        # payload's own "type" field drives dispatch.
+
+
+def _tool_to_anthropic(tool: dict[str, Any]) -> dict[str, Any]:
+    """Convert an OpenAI function tool definition to Anthropic's shape."""
+    function = tool.get("function", tool)
+    return {
+        "name": function["name"],
+        "description": function.get("description", ""),
+        "input_schema": function.get("parameters", {"type": "object"}),
+    }
+
+
+def _messages_to_anthropic(
+    messages: list[Message],
+) -> tuple[str, list[dict[str, Any]]]:
+    """Convert internal messages to Anthropic's system/messages split.
+
+    System messages are joined into the top-level ``system`` parameter.
+    Consecutive tool results are merged into a single user message, as the
+    API requires tool_result blocks inside a user turn.
+    """
+    system_parts: list[str] = []
+    converted: list[dict[str, Any]] = []
+
+    for message in messages:
+        if message.role == "system":
+            if message.content:
+                system_parts.append(message.content)
+        elif message.role == "user":
+            converted.append({"role": "user", "content": message.content or ""})
+        elif message.role == "assistant":
+            converted.append(
+                {"role": "assistant", "content": _assistant_blocks(message)}
+            )
+        elif message.role == "tool":
+            block = {
+                "type": "tool_result",
+                "tool_use_id": message.tool_call_id or "",
+                "content": message.content or "",
+            }
+            previous = converted[-1] if converted else None
+            if previous is not None and previous.get("role") == "user" and isinstance(
+                previous.get("content"), list
+            ):
+                previous["content"].append(block)
+            else:
+                converted.append({"role": "user", "content": [block]})
+
+    return "\n\n".join(system_parts), converted
+
+
+def _assistant_blocks(message: Message) -> list[dict[str, Any]]:
+    blocks: list[dict[str, Any]] = []
+    if message.reasoning:
+        # Kimi accepts empty signatures on replayed thinking blocks; real
+        # Anthropic models get the stored signature.
+        blocks.append(
+            {
+                "type": "thinking",
+                "thinking": message.reasoning,
+                "signature": message.reasoning_signature or "",
+            }
+        )
+    if message.content:
+        blocks.append({"type": "text", "text": message.content})
+    for tc in message.tool_calls or []:
+        function = tc.get("function", {})
+        arguments = function.get("arguments", {})
+        blocks.append(
+            {
+                "type": "tool_use",
+                "id": tc.get("id", ""),
+                "name": function.get("name", ""),
+                "input": (
+                    arguments
+                    if isinstance(arguments, dict)
+                    else json.loads(arguments or "{}")
+                ),
+            }
+        )
+    # The API rejects assistant messages with no content blocks.
+    return blocks or [{"type": "text", "text": ""}]

limbo/llm/catalog.py

@@ -0,0 +1,234 @@
+"""Provider/model catalog.
+
+Follows pi's two-level metadata approach (built-in ``providers/data/*.json``
+plus ``~/.pi/agent/models.json``):
+
+- A **provider** owns the API dialect (``api``), endpoint (``base_url``), and
+  credential source (``api_key_env``). The ``api`` value decides which LLM
+  client implementation speaks to it (see ``limbo.llm.factory``).
+- A **model** belongs to a provider and carries its own API characteristics —
+  context window, max output tokens, reasoning capability, thinking-parameter
+  format, and compatibility quirks — so the client adapts request/response
+  handling per model instead of assuming one universal dialect.
+
+Unknown models fall back to a generic OpenAI-compatible provider with
+conservative defaults, so any OpenAI-compatible endpoint still works via
+``[llm] base_url`` + ``model``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+DEFAULT_BASE_URL = "https://api.deepseek.com/v1"
+DEFAULT_CONTEXT_WINDOW = 128_000
+DEFAULT_MAX_TOKENS = 16_384
+
+# API dialects. Only "openai-completions" has a client implementation today;
+# the factory raises a clear error for the rest until one is added.
+API_OPENAI_COMPLETIONS = "openai-completions"
+API_ANTHROPIC_MESSAGES = "anthropic-messages"
+
+# Mainland-China Moonshot endpoint; select via an explicit [llm] base_url
+# override (same API and model ids as the international endpoint).
+MOONSHOT_CN_BASE_URL = "https://api.moonshot.cn/v1"
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    """An API provider: dialect + endpoint + credential source."""
+
+    id: str
+    api: str
+    base_url: str = ""
+    api_key_env: str | None = None
+    # Extra headers sent on every request (e.g. Kimi For Coding requires a
+    # specific User-Agent).
+    headers: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """Per-model API characteristics."""
+
+    id: str
+    provider: ProviderSpec
+    context_window: int = DEFAULT_CONTEXT_WINDOW
+    max_tokens: int = DEFAULT_MAX_TOKENS
+    reasoning: bool = False
+    # How thinking is controlled: "openai" (reasoning_effort parameter),
+    # "deepseek" (thinking: {type: enabled|disabled}), or None (the model
+    # reasons but the API exposes no switch, e.g. deepseek-reasoner).
+    thinking_format: str | None = None
+    # Supported thinking levels mapped to provider values (openai format).
+    # A level absent from the map is unsupported by the model.
+    thinking_levels: dict[str, str] = field(default_factory=dict)
+    # Whether thinking can be turned off at all (deepseek format).
+    thinking_can_disable: bool = True
+    # Replay reasoning_content (empty string when absent) on assistant
+    # messages. Kimi K3 rejects tool-call replays without the field.
+    requires_reasoning_content: bool = False
+
+
+DEEPSEEK = ProviderSpec(
+    id="deepseek",
+    api=API_OPENAI_COMPLETIONS,
+    base_url=DEFAULT_BASE_URL,
+    api_key_env="DEEPSEEK_API_KEY",
+)
+
+MOONSHOT = ProviderSpec(
+    id="moonshotai",
+    api=API_OPENAI_COMPLETIONS,
+    base_url="https://api.moonshot.ai/v1",
+    api_key_env="MOONSHOT_API_KEY",
+)
+
+# Fallback for models not in the catalog.
+GENERIC_OPENAI = ProviderSpec(id="custom", api=API_OPENAI_COMPLETIONS)
+
+# Kimi For Coding (subscription): Anthropic Messages dialect. Mirrors pi's
+# kimi-coding provider (providers/data/kimi-coding.json).
+KIMI_CODING = ProviderSpec(
+    id="kimi-coding",
+    api=API_ANTHROPIC_MESSAGES,
+    base_url="https://api.kimi.com/coding",
+    api_key_env="KIMI_API_KEY",
+    headers={"User-Agent": "KimiCLI/1.5"},
+)
+
+
+def _kimi_coding(
+    model_id: str,
+    *,
+    context_window: int = 262_144,
+    max_tokens: int = 32_768,
+) -> ModelSpec:
+    # All Kimi For Coding models reason with Anthropic adaptive thinking
+    # (thinking: {type: adaptive} + output_config.effort); thinking cannot
+    # be disabled. Replayed thinking blocks may carry an empty signature.
+    return ModelSpec(
+        id=model_id,
+        provider=KIMI_CODING,
+        context_window=context_window,
+        max_tokens=max_tokens,
+        reasoning=True,
+        thinking_format="anthropic-adaptive",
+        thinking_levels={"low": "low", "high": "high", "max": "max"},
+        thinking_can_disable=False,
+    )
+
+
+def _moonshot(
+    model_id: str,
+    *,
+    context_window: int = 262_144,
+    max_tokens: int = 262_144,
+    reasoning: bool = False,
+    thinking_format: str | None = None,
+    thinking_levels: dict[str, str] | None = None,
+    thinking_can_disable: bool = True,
+    requires_reasoning_content: bool = False,
+) -> ModelSpec:
+    return ModelSpec(
+        id=model_id,
+        provider=MOONSHOT,
+        context_window=context_window,
+        max_tokens=max_tokens,
+        reasoning=reasoning,
+        thinking_format=thinking_format,
+        thinking_levels=thinking_levels or {},
+        thinking_can_disable=thinking_can_disable,
+        requires_reasoning_content=requires_reasoning_content,
+    )
+
+
+# Values mirror pi's built-in moonshotai catalog (providers/data/moonshotai.json).
+CATALOG: dict[str, ModelSpec] = {
+    "deepseek-chat": ModelSpec(
+        id="deepseek-chat", provider=DEEPSEEK, max_tokens=8_192
+    ),
+    "deepseek-reasoner": ModelSpec(
+        id="deepseek-reasoner",
+        provider=DEEPSEEK,
+        max_tokens=65_536,
+        reasoning=True,
+    ),
+    # -- Kimi (Moonshot AI) -------------------------------------------------
+    "kimi-k2-0711-preview": _moonshot(
+        "kimi-k2-0711-preview", context_window=131_072, max_tokens=16_384
+    ),
+    "kimi-k2-0905-preview": _moonshot("kimi-k2-0905-preview"),
+    "kimi-k2-turbo-preview": _moonshot("kimi-k2-turbo-preview"),
+    "kimi-k2-thinking": _moonshot(
+        "kimi-k2-thinking", reasoning=True, thinking_format="deepseek"
+    ),
+    "kimi-k2-thinking-turbo": _moonshot(
+        "kimi-k2-thinking-turbo", reasoning=True, thinking_format="deepseek"
+    ),
+    "kimi-k2.5": _moonshot(
+        "kimi-k2.5", reasoning=True, thinking_format="deepseek"
+    ),
+    "kimi-k2.6": _moonshot(
+        "kimi-k2.6", reasoning=True, thinking_format="deepseek"
+    ),
+    "kimi-k2.7-code": _moonshot(
+        "kimi-k2.7-code",
+        reasoning=True,
+        thinking_format="deepseek",
+        thinking_can_disable=False,
+    ),
+    "kimi-k2.7-code-highspeed": _moonshot(
+        "kimi-k2.7-code-highspeed",
+        reasoning=True,
+        thinking_format="deepseek",
+        thinking_can_disable=False,
+    ),
+    # Kimi K3: 1M context, OpenAI-style reasoning_effort, thinking cannot be
+    # disabled, and assistant replays must carry reasoning_content.
+    "kimi-k3": _moonshot(
+        "kimi-k3",
+        context_window=1_048_576,
+        max_tokens=131_072,
+        reasoning=True,
+        thinking_format="openai",
+        thinking_levels={"low": "low", "high": "high", "max": "max"},
+        thinking_can_disable=False,
+        requires_reasoning_content=True,
+    ),
+    # -- Kimi For Coding (Anthropic Messages dialect) ------------------------
+    "k3": _kimi_coding(
+        "k3", context_window=1_048_576, max_tokens=131_072
+    ),
+    "kimi-for-coding": _kimi_coding("kimi-for-coding"),
+    "kimi-for-coding-highspeed": _kimi_coding("kimi-for-coding-highspeed"),
+}
+
+
+def resolve_model(model_id: str) -> ModelSpec:
+    """Look up a model; unknown ids get a generic OpenAI-compatible spec."""
+    return CATALOG.get(model_id) or ModelSpec(id=model_id, provider=GENERIC_OPENAI)
+
+
+def resolve_base_url(spec: ModelSpec, configured: str) -> str:
+    """Resolve the effective base URL for a model.
+
+    An explicitly configured ``base_url`` always wins. When it is left at the
+    global DeepSeek default but the catalog knows a different endpoint for the
+    model's provider (e.g. switching to ``kimi-k3`` without editing
+    ``base_url``), the provider endpoint is used so model switching works out
+    of the box.
+    """
+    if configured != DEFAULT_BASE_URL or not spec.provider.base_url:
+        return configured
+    return spec.provider.base_url
+
+
+def resolve_api_key(spec: ModelSpec, configured: str | None) -> str | None:
+    """Resolve the API key: config first, then the provider's env var."""
+    if configured:
+        return configured
+    if spec.provider.api_key_env:
+        return os.environ.get(spec.provider.api_key_env)
+    return None

limbo/llm/client.py

@@ -0,0 +1,21 @@
+"""LLM client protocol."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from typing import Any, Protocol
+
+from limbo.models import LLMEvent, Message
+
+# Called with the exact request body (or SDK kwargs) about to be sent, on
+# every HTTP attempt. Used for trace logging; must not mutate the body.
+RequestHook = Callable[[dict[str, Any]], None]
+
+
+class LLMClient(Protocol):
+    def chat(
+        self,
+        messages: list[Message],
+        tools: list[dict[str, Any]],
+        on_request: RequestHook | None = None,
+    ) -> AsyncIterator[LLMEvent]: ...