turnloop 0.1.0__py3-none-any.whl

turnloop/core/events.py

@@ -0,0 +1,145 @@
+"""Streaming events.
+
+One event union covers model output, provider status, and tool progress, so the
+TUI needs exactly one inbound pathway. In particular a 29-minute GLM cold boot
+reports progress through `ProviderStatus` on the same channel as tokens.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, TypeAlias
+
+from turnloop.core.messages import Message, Usage
+
+# --- model output ----------------------------------------------------------
+
+
+@dataclass(slots=True)
+class TextDelta:
+    text: str
+
+
+@dataclass(slots=True)
+class ThinkingDelta:
+    text: str
+
+
+@dataclass(slots=True)
+class ToolUseStart:
+    index: int
+    id: str
+    name: str
+
+
+@dataclass(slots=True)
+class ToolUseArgsDelta:
+    """A fragment of the JSON argument string.
+
+    Both Anthropic (`input_json_delta`) and OpenAI-compatible endpoints stream
+    tool arguments as unparseable partial JSON. Fragments are accumulated per
+    `index` and parsed only once the block closes.
+    """
+
+    index: int
+    fragment: str
+
+
+@dataclass(slots=True)
+class MessageDone:
+    message: Message
+    usage: Usage
+    stop_reason: str
+
+
+# --- provider / transport status -------------------------------------------
+
+StatusPhase: TypeAlias = Literal["connecting", "cold_boot", "retrying", "ready", "streaming"]
+
+
+@dataclass(slots=True)
+class ProviderStatus:
+    text: str
+    phase: StatusPhase = "connecting"
+    elapsed_s: float = 0.0
+
+
+# --- tool execution -------------------------------------------------------
+
+
+@dataclass(slots=True)
+class ToolStarted:
+    tool_use_id: str
+    name: str
+    summary: str  # one-line human description, e.g. "Read src/app.py"
+    subagent_id: str | None = None
+
+
+@dataclass(slots=True)
+class ToolProgress:
+    """Incremental output from a running tool (bash lines, subagent turns)."""
+
+    tool_use_id: str
+    text: str
+    subagent_id: str | None = None
+
+
+@dataclass(slots=True)
+class ToolFinished:
+    tool_use_id: str
+    name: str
+    is_error: bool
+    display: str | None = None
+    duration_s: float = 0.0
+    subagent_id: str | None = None
+
+
+# --- session-level UI updates ---------------------------------------------
+
+
+@dataclass(slots=True)
+class StatusUpdate:
+    """Pushed after every request so the status bar never computes anything."""
+
+    context_tokens: int = 0
+    context_max: int = 0
+    cost_usd: float = 0.0
+    usage: Usage = field(default_factory=Usage)
+    gpu_seconds: float | None = None  # self-hosted, wall-clock-billed providers
+    note: str = ""
+
+
+@dataclass(slots=True)
+class TurnStarted:
+    turn: int
+
+
+@dataclass(slots=True)
+class TurnFinished:
+    turn: int
+    stop_reason: str
+
+
+@dataclass(slots=True)
+class CompactionHappened:
+    # "hard" is the last-resort tier: a single message larger than the whole
+    # window, truncated in place because no cut point can help.
+    tier: Literal["micro", "thinking", "full", "hard"]
+    tokens_before: int
+    tokens_after: int
+
+
+StreamEvent: TypeAlias = (
+    TextDelta | ThinkingDelta | ToolUseStart | ToolUseArgsDelta | MessageDone | ProviderStatus
+)
+
+UIEvent: TypeAlias = (
+    StreamEvent
+    | ToolStarted
+    | ToolProgress
+    | ToolFinished
+    | StatusUpdate
+    | TurnStarted
+    | TurnFinished
+    | CompactionHappened
+)

turnloop/core/ids.py

@@ -0,0 +1,29 @@
+"""Identifier generation.
+
+Indirected through a module-level counter so golden-transcript tests can make
+ids deterministic by calling `use_deterministic_ids()`.
+"""
+
+from __future__ import annotations
+
+import itertools
+from uuid import uuid4
+
+_counter: itertools.count | None = None
+
+
+def new_id(prefix: str) -> str:
+    if _counter is not None:
+        return f"{prefix}_{next(_counter):08d}"
+    return f"{prefix}_{uuid4().hex[:16]}"
+
+
+def use_deterministic_ids(start: int = 1) -> None:
+    """Make new_id() emit prefix_00000001, prefix_00000002, ... (tests only)."""
+    global _counter
+    _counter = itertools.count(start)
+
+
+def use_random_ids() -> None:
+    global _counter
+    _counter = None

turnloop/core/messages.py

@@ -0,0 +1,217 @@
+"""The internal message model.
+
+Deliberately Anthropic-shaped: content blocks with an explicit `thinking` type
+and tool results carrying an `is_error` flag. That shape is a strict superset of
+what OpenAI-compatible and Gemini endpoints express, so every adapter is
+lossy-on-the-way-in and lossless-on-the-way-out rather than the reverse.
+
+Nothing in this module knows about HTTP or about any provider.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, TypeAlias
+
+from pydantic import BaseModel, Field
+
+StopReason: TypeAlias = Literal[
+    "end_turn",  # model finished talking
+    "tool_use",  # model wants tools run; the loop continues
+    "max_tokens",  # output cap hit mid-sentence
+    "stop_sequence",
+    "refusal",
+    "error",  # our own marker for a truncated/failed stream
+]
+
+
+class Usage(BaseModel):
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+    def __add__(self, other: Usage) -> Usage:
+        return Usage(
+            input_tokens=self.input_tokens + other.input_tokens,
+            output_tokens=self.output_tokens + other.output_tokens,
+            cache_read_tokens=self.cache_read_tokens + other.cache_read_tokens,
+            cache_write_tokens=self.cache_write_tokens + other.cache_write_tokens,
+        )
+
+    @property
+    def total(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+class TextBlock(BaseModel):
+    type: Literal["text"] = "text"
+    text: str = ""
+
+
+class ThinkingBlock(BaseModel):
+    """Reasoning output.
+
+    `signature` is Anthropic's cryptographic signature over the thinking text;
+    it must be echoed verbatim if the block is ever sent back. Endpoints that
+    surface reasoning as plain text (GLM's `reasoning_content`, Groq) have no
+    signature, so those blocks are display/trace only and are never resent —
+    see providers/openai_compat.py.
+    """
+
+    type: Literal["thinking"] = "thinking"
+    text: str = ""
+    signature: str | None = None
+    provider: str | None = None  # provenance, e.g. "glm:reasoning_content"
+
+    @property
+    def resendable(self) -> bool:
+        return self.signature is not None
+
+
+class ToolUseBlock(BaseModel):
+    type: Literal["tool_use"] = "tool_use"
+    id: str
+    name: str
+    args: dict = Field(default_factory=dict)
+
+
+class ToolResultBlock(BaseModel):
+    type: Literal["tool_result"] = "tool_result"
+    tool_use_id: str
+    content: str = ""
+    is_error: bool = False
+    # Rich rendering for the TUI. Never crosses the wire — keeping it out of
+    # `content` is what lets a tool show a colored diff to the human while
+    # sending the model a plain summary.
+    display: str | None = Field(default=None, exclude=False)
+    truncated: bool = False  # set by micro-compaction so it only happens once
+
+
+ContentBlock: TypeAlias = Annotated[
+    TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock,
+    Field(discriminator="type"),
+]
+
+
+class Message(BaseModel):
+    role: Literal["user", "assistant"]
+    content: list[ContentBlock] = Field(default_factory=list)
+    usage: Usage | None = None
+    stop_reason: StopReason | None = None
+    # provider, model, latency_ms, ttft_ms, compaction markers, subagent_id
+    meta: dict = Field(default_factory=dict)
+
+    # --- convenience accessors used all over the loop -----------------------
+
+    @property
+    def text(self) -> str:
+        return "".join(b.text for b in self.content if isinstance(b, TextBlock))
+
+    @property
+    def tool_uses(self) -> list[ToolUseBlock]:
+        return [b for b in self.content if isinstance(b, ToolUseBlock)]
+
+    @property
+    def tool_results(self) -> list[ToolResultBlock]:
+        return [b for b in self.content if isinstance(b, ToolResultBlock)]
+
+    @property
+    def thinking(self) -> list[ThinkingBlock]:
+        return [b for b in self.content if isinstance(b, ThinkingBlock)]
+
+    @property
+    def is_empty(self) -> bool:
+        return not any(
+            (isinstance(b, TextBlock | ThinkingBlock) and b.text.strip())
+            or isinstance(b, ToolUseBlock | ToolResultBlock)
+            for b in self.content
+        )
+
+    @classmethod
+    def user_text(cls, text: str, **meta) -> Message:
+        return cls(role="user", content=[TextBlock(text=text)], meta=meta)
+
+    @classmethod
+    def assistant_text(cls, text: str, **meta) -> Message:
+        return cls(role="assistant", content=[TextBlock(text=text)], meta=meta)
+
+
+class ToolSpec(BaseModel):
+    """A tool as presented to a model. Built from a Tool class by the registry."""
+
+    name: str
+    description: str
+    input_schema: dict
+
+    def to_anthropic(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.input_schema,
+        }
+
+    def to_openai(self) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.input_schema,
+            },
+        }
+
+    def to_gemini(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": strip_unsupported_schema(self.input_schema),
+        }
+
+
+_GEMINI_UNSUPPORTED = {
+    "additionalProperties",
+    "$schema",
+    "$defs",
+    "definitions",
+    "discriminator",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "const",
+    "examples",
+    "default",
+    "title",
+}
+
+
+def strip_unsupported_schema(schema: dict, defs: dict | None = None) -> dict:
+    """Inline $refs and drop keywords Gemini's function-declaration parser rejects.
+
+    Gemini returns a 400 for a schema containing `$defs`/`additionalProperties`,
+    which pydantic emits routinely for nested models (e.g. Edit's list[EditOp]).
+    """
+    defs = defs or schema.get("$defs") or schema.get("definitions") or {}
+    out: dict = {}
+    for key, value in schema.items():
+        if key == "$ref":
+            target = str(value).rsplit("/", 1)[-1]
+            resolved = defs.get(target, {})
+            out.update(strip_unsupported_schema(resolved, defs))
+            continue
+        if key in _GEMINI_UNSUPPORTED:
+            continue
+        if key == "anyOf":
+            # Gemini has no union type. Take the first non-null branch; the
+            # description is expected to carry the nuance.
+            branches = [b for b in value if b.get("type") != "null"]
+            if branches:
+                out.update(strip_unsupported_schema(branches[0], defs))
+            continue
+        if isinstance(value, dict):
+            out[key] = strip_unsupported_schema(value, defs)
+        elif isinstance(value, list):
+            out[key] = [
+                strip_unsupported_schema(v, defs) if isinstance(v, dict) else v for v in value
+            ]
+        else:
+            out[key] = value
+    return out

turnloop/core/tokens.py

@@ -0,0 +1,104 @@
+"""Token estimation without a tokenizer dependency.
+
+Why no tiktoken: it is wrong for GLM and Gemini anyway, it is a 2 MB+ download
+with a vocab fetch at first use, and every provider reports exact usage in its
+response. So: estimate cheaply, then calibrate the estimator against reported
+usage with an EWMA. It converges within two turns and costs nothing.
+
+This matters concretely. A flat 4-chars-per-token guess is ~20% off on GLM's
+tokenizer, and 20% of a 65k window is 13k tokens — either wasted headroom or a
+context-overflow 400 mid-session.
+"""
+
+from __future__ import annotations
+
+from turnloop.core.messages import (
+    ContentBlock,
+    Message,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolSpec,
+    ToolUseBlock,
+)
+
+# Code and JSON tokenize denser than prose. Measured against several tokenizers
+# on mixed source-code corpora this sits closer than the usual 4.0.
+CHARS_PER_TOKEN = 3.6
+
+# Fixed overhead the wire format adds per message and per tool-call envelope.
+PER_MESSAGE_OVERHEAD = 4
+PER_TOOL_CALL_OVERHEAD = 12
+
+
+def rough_tokens(text: str) -> int:
+    if not text:
+        return 0
+    return max(1, int(len(text) / CHARS_PER_TOKEN))
+
+
+def block_tokens(block: ContentBlock) -> int:
+    if isinstance(block, TextBlock | ThinkingBlock):
+        return rough_tokens(block.text)
+    if isinstance(block, ToolUseBlock):
+        import json
+
+        return rough_tokens(block.name) + rough_tokens(json.dumps(block.args)) + PER_TOOL_CALL_OVERHEAD
+    if isinstance(block, ToolResultBlock):
+        return rough_tokens(block.content) + PER_TOOL_CALL_OVERHEAD
+    return 0
+
+
+def message_tokens(message: Message) -> int:
+    return PER_MESSAGE_OVERHEAD + sum(block_tokens(b) for b in message.content)
+
+
+def history_tokens(messages: list[Message]) -> int:
+    return sum(message_tokens(m) for m in messages)
+
+
+def tool_spec_tokens(specs: list[ToolSpec]) -> int:
+    import json
+
+    return sum(
+        rough_tokens(s.name) + rough_tokens(s.description) + rough_tokens(json.dumps(s.input_schema))
+        for s in specs
+    )
+
+
+class TokenEstimator:
+    """A self-calibrating estimator, one instance per provider.
+
+    `observe()` is called with the estimate that was made for a request and the
+    input_tokens the provider actually reported. The ratio is folded into a
+    correction factor with an EWMA, so `estimate()` tightens over a session.
+    """
+
+    def __init__(self, alpha: float = 0.4):
+        self.alpha = alpha
+        self.factor = 1.0
+        self.samples = 0
+
+    def estimate(self, raw: int) -> int:
+        return max(1, int(raw * self.factor))
+
+    def observe(self, estimated_raw: int, actual: int) -> None:
+        if estimated_raw <= 0 or actual <= 0:
+            return
+        observed = actual / estimated_raw
+        # Guard against a wild first sample (e.g. a cache-heavy request where
+        # reported input_tokens excludes cache reads).
+        if not 0.25 <= observed <= 4.0:
+            return
+        if self.samples == 0:
+            self.factor = observed
+        else:
+            self.factor = (1 - self.alpha) * self.factor + self.alpha * observed
+        self.samples += 1
+
+    def estimate_request(
+        self, messages: list[Message], system: str | list[str], specs: list[ToolSpec]
+    ) -> int:
+        system_text = system if isinstance(system, str) else "\n".join(system)
+        raw = history_tokens(messages) + rough_tokens(system_text) + tool_spec_tokens(specs)
+        return self.estimate(raw)