tabulaflow 0.1.0__py3-none-any.whl

tabulaflow/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("tabulaflow")

tabulaflow/_paths.py

@@ -0,0 +1,5 @@
+"""Package-wide filesystem defaults."""
+
+from pathlib import Path
+
+DEFAULT_HOME_DIR = Path.home() / ".tabulaflow"

tabulaflow/agents/__init__.py

@@ -0,0 +1,42 @@
+"""Agent runtime, reusable chat sessions, tools, and LLM-powered modules."""
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tabulaflow.agents.chat.input import ChatInput
+    from tabulaflow.agents.chat.session import ChatSession
+    from tabulaflow.agents.config import AgentRuntimeConfig
+    from tabulaflow.agents.runtime import initialize_agent_runtime, set_llm_requests_per_minute
+    from tabulaflow.agents.trace import instrument_agents
+
+_LAZY_EXPORTS = {
+    "AgentRuntimeConfig": ("tabulaflow.agents.config", "AgentRuntimeConfig"),
+    "ChatInput": ("tabulaflow.agents.chat.input", "ChatInput"),
+    "ChatSession": ("tabulaflow.agents.chat", "ChatSession"),
+    "initialize_agent_runtime": ("tabulaflow.agents.runtime", "initialize_agent_runtime"),
+    "set_llm_requests_per_minute": ("tabulaflow.agents.runtime", "set_llm_requests_per_minute"),
+    "instrument_agents": ("tabulaflow.agents.trace", "instrument_agents"),
+}
+
+__all__ = [
+    "AgentRuntimeConfig",
+    "ChatInput",
+    "ChatSession",
+    "initialize_agent_runtime",
+    "instrument_agents",
+    "set_llm_requests_per_minute",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr_name = _LAZY_EXPORTS[name]
+    value = getattr(import_module(module_name), attr_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_LAZY_EXPORTS})

tabulaflow/agents/_cache.py

@@ -0,0 +1,73 @@
+"""Cache-mode orchestration for expensive agent capabilities."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from tabulaflow.agents.config import AgentCacheMode
+from tabulaflow.core._cache import cache_lock, read_cached_model, remove_cached_file, write_cached_model
+
+_T = TypeVar("_T")
+_ModelT = TypeVar("_ModelT", bound=BaseModel)
+
+
+class InvalidCacheEntry(ValueError):
+    """A cache file exists but cannot be decoded as its expected value."""
+
+
+async def load_or_compute(
+    *,
+    path: Path,
+    mode: AgentCacheMode,
+    load: Callable[[Path], Awaitable[_T]],
+    compute: Callable[[], Awaitable[_T]],
+    store: Callable[[Path, _T], Awaitable[None]],
+) -> _T:
+    """Resolve one cache entry according to the configured cache mode."""
+    if mode == "off":
+        return await compute()
+
+    async with cache_lock(path):
+        if mode in ("read_write", "cache_only") and path.exists():
+            try:
+                return await load(path)
+            except InvalidCacheEntry:
+                if mode == "cache_only":
+                    raise
+                await remove_cached_file(path)
+
+        if mode == "cache_only":
+            raise FileNotFoundError(f"Cache entry not found: {path}")
+
+        value = await compute()
+        if mode in ("read_write", "refresh"):
+            await store(path, value)
+        return value
+
+
+async def load_or_compute_model(
+    *,
+    path: Path,
+    mode: AgentCacheMode,
+    model_type: type[_ModelT],
+    compute: Callable[[], Awaitable[_ModelT]],
+) -> _ModelT:
+    """Load or compute a Pydantic model under the configured cache policy."""
+
+    async def load(cache_path: Path) -> _ModelT:
+        try:
+            return await read_cached_model(cache_path, model_type)
+        except ValidationError as exc:
+            raise InvalidCacheEntry(f"Invalid cache entry: {cache_path}") from exc
+
+    return await load_or_compute(
+        path=path,
+        mode=mode,
+        load=load,
+        compute=compute,
+        store=write_cached_model,
+    )

tabulaflow/agents/chat/__init__.py

@@ -0,0 +1,80 @@
+"""Stateful chat sessions and their semantic event stream.
+
+Use :meth:`ChatSession.run` for a final result or :meth:`ChatSession.run_stream`
+for live events ending in :class:`TurnFinished`. Close each session with
+``await session.aclose()``.
+"""
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tabulaflow.agents.chat.compaction import CompactionConfig
+    from tabulaflow.agents.chat.input import ChatInput
+    from tabulaflow.agents.chat.events import (
+        AnswerDelta,
+        ChatEvent,
+        ChatResult,
+        CompactionFinished,
+        CompactionStarted,
+        TurnFinished,
+        NarrationDelta,
+        ThinkingDelta,
+        ToolCallOutcome,
+        ToolFinished,
+        ToolProgress,
+        ToolStarted,
+        UsageUpdated,
+    )
+    from tabulaflow.agents.chat.session import ChatSession
+
+_LAZY_EXPORTS = {
+    "AnswerDelta": ("tabulaflow.agents.chat.events", "AnswerDelta"),
+    "ChatEvent": ("tabulaflow.agents.chat.events", "ChatEvent"),
+    "ChatResult": ("tabulaflow.agents.chat.events", "ChatResult"),
+    "CompactionFinished": ("tabulaflow.agents.chat.events", "CompactionFinished"),
+    "CompactionStarted": ("tabulaflow.agents.chat.events", "CompactionStarted"),
+    "ChatSession": ("tabulaflow.agents.chat.session", "ChatSession"),
+    "ChatInput": ("tabulaflow.agents.chat.input", "ChatInput"),
+    "CompactionConfig": ("tabulaflow.agents.chat.compaction", "CompactionConfig"),
+    "TurnFinished": ("tabulaflow.agents.chat.events", "TurnFinished"),
+    "NarrationDelta": ("tabulaflow.agents.chat.events", "NarrationDelta"),
+    "ThinkingDelta": ("tabulaflow.agents.chat.events", "ThinkingDelta"),
+    "ToolCallOutcome": ("tabulaflow.agents.chat.events", "ToolCallOutcome"),
+    "ToolFinished": ("tabulaflow.agents.chat.events", "ToolFinished"),
+    "ToolProgress": ("tabulaflow.agents.chat.events", "ToolProgress"),
+    "ToolStarted": ("tabulaflow.agents.chat.events", "ToolStarted"),
+    "UsageUpdated": ("tabulaflow.agents.chat.events", "UsageUpdated"),
+}
+
+__all__ = [
+    "AnswerDelta",
+    "ChatEvent",
+    "ChatResult",
+    "CompactionFinished",
+    "CompactionStarted",
+    "ChatSession",
+    "ChatInput",
+    "CompactionConfig",
+    "TurnFinished",
+    "NarrationDelta",
+    "ThinkingDelta",
+    "ToolCallOutcome",
+    "ToolFinished",
+    "ToolProgress",
+    "ToolStarted",
+    "UsageUpdated",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name not in _LAZY_EXPORTS:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attr_name = _LAZY_EXPORTS[name]
+    value = getattr(import_module(module_name), attr_name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_LAZY_EXPORTS})

tabulaflow/agents/chat/compaction.py

@@ -0,0 +1,323 @@
+"""Simple, provider-agnostic checkpoint compaction for interactive chat sessions.
+
+Rather than combining multiple trimming strategies or sending a flattened transcript
+to a separate summarizer, the current agent writes one checkpoint from its native
+conversation. This preserves recent tool context, keeps provider-carried reasoning
+state available, reuses the existing prompt prefix for the checkpoint request, and
+avoids a second model configuration.
+
+The remaining rewrite is deterministic: retain only turns after the previous
+checkpoint, replace tool-result payloads, append the new checkpoint, then progressively
+remove execution details and assistant dialogue before evicting oldest user prompts.
+Tool structure is removed as a whole, preserving provider-valid pairing while keeping
+the user's recent requests for as long as the budget permits.
+
+The checkpoint and latest user request are never silently truncated. If those alone
+cannot fit, compaction fails explicitly.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass, replace
+from typing import Any, cast
+
+import genai_prices
+from pydantic_ai.messages import (
+    BinaryContent,
+    ModelMessage,
+    ModelRequest,
+    ModelResponse,
+    TextPart,
+    ToolCallPart,
+    ToolReturnPart,
+    UserPromptPart,
+)
+
+from tabulaflow.agents.chat.input import ChatInput, describe_chat_input
+
+
+_CHARS_PER_TOKEN = 4
+_MESSAGE_OVERHEAD_CHARS = 16
+_PART_OVERHEAD_CHARS = 8
+_CONTEXT_RESERVE_TOKENS = 32_000
+_CHECKPOINT_TOKEN_LIMIT = 4_000
+_TOOL_RESULT_PLACEHOLDER = "[tool result omitted after execution during context compaction]"
+# Marks synthetic checkpoint messages so a later compaction replaces, rather than
+# summarizes and retains, the previous checkpoint exchange.
+_CHECKPOINT_METADATA = "tabulaflow.context-checkpoint"
+# Host notifications use UserPromptPart for model visibility, but are not user turns.
+HOST_EVENT_METADATA_KEY = "tabulaflow.host-event"
+_CHECKPOINT_PROMPT = """
+Create a compact, self-contained checkpoint that will replace the earlier conversation.
+
+<requirements>
+- Preserve goals, constraints, decisions, important exact details, current state, and next steps.
+- Preserve durable information not recoverable from the local repository, such as user preferences, external paths, and external state.
+- Preserve recurring workflows, operating conventions, and preferred procedures established in the conversation.
+- Record work already performed, its outcomes, and enough workflow or provenance to avoid repeating or contradicting it.
+- Omit filler, superseded information, and low-level execution traces.
+- Do not use tools unless needed to retrieve referenced content, and do not change external state.
+- Write at most approximately {checkpoint_tokens:,} tokens.
+- Return only the checkpoint.
+</requirements>
+""".strip()
+
+
+@dataclass(frozen=True)
+class CompactionConfig:
+    """User-facing controls for automatic conversation compaction.
+
+    ``trigger_tokens`` starts checkpointing and ``target_tokens`` bounds the rewritten
+    history.
+    """
+
+    trigger_tokens: int = 240_000
+    target_tokens: int = 32_000
+
+    def __post_init__(self) -> None:
+        if not 0 < self.target_tokens < self.trigger_tokens:
+            raise ValueError("expected 0 < target_tokens < trigger_tokens")
+
+
+def checkpoint_prompt(config: CompactionConfig) -> str:
+    """Return the internal request, deriving its size from the context target."""
+    return _CHECKPOINT_PROMPT.format(checkpoint_tokens=min(_CHECKPOINT_TOKEN_LIMIT, config.target_tokens // 4)).strip()
+
+
+def effective_compaction_config(config: CompactionConfig, model: str) -> CompactionConfig:
+    """Scale the compaction policy to fit the model context window.
+
+    Unknown models use the configured policy. Known smaller models preserve its
+    trigger-to-target ratio while leaving room to generate the checkpoint.
+    """
+    context_window = _context_window(model)
+    if context_window is None:
+        return config
+    reserve = min(_CONTEXT_RESERVE_TOKENS, context_window // 4)
+    trigger = min(config.trigger_tokens, context_window - reserve)
+    if trigger == config.trigger_tokens:
+        return config
+    target = config.target_tokens * trigger // config.trigger_tokens
+    if target <= 0:
+        raise ValueError(f"model context window is too small for context compaction: {context_window}")
+    return CompactionConfig(trigger_tokens=trigger, target_tokens=target)
+
+
+def estimate_context_tokens(messages: list[ModelMessage], additional_content: ChatInput = "") -> int:
+    """Estimate a prospective request from its latest provider-usage anchor.
+
+    The latest uncompacted response's provider-reported input plus output usage is
+    ground truth for history through that response. Only later messages and pending
+    content use the four-characters-per-token estimate. A checkpoint is a rewrite
+    boundary, so estimates after one start from the compacted messages instead of an
+    obsolete pre-compaction usage anchor.
+    """
+    additional = _estimate_text_tokens(describe_chat_input(additional_content))
+    for index in range(len(messages) - 1, -1, -1):
+        message = messages[index]
+        if not isinstance(message, ModelResponse):
+            continue
+        if message.metadata and message.metadata.get(_CHECKPOINT_METADATA):
+            break
+        anchored = message.usage.input_tokens + message.usage.output_tokens
+        if anchored:
+            return anchored + _estimate_messages_tokens(messages[index + 1 :]) + additional
+    return _estimate_messages_tokens(messages) + additional
+
+
+def compact_history(
+    messages: list[ModelMessage],
+    *,
+    checkpoint_request: str,
+    checkpoint_text: str,
+    config: CompactionConfig,
+) -> list[ModelMessage]:
+    """Return provider-valid history bounded by ``config.target_tokens``.
+
+    The previous checkpoint supersedes every raw turn before it. Newer turns initially
+    retain their native messages with tool-result payloads replaced. If the result is
+    too large, turns degrade oldest-first to dialogue-only and then user-only before
+    oldest turns are evicted.
+    """
+    turns = _group_turns_since_checkpoint(messages)
+    compacted = [_project_execution(turn) for turn in turns]
+    compacted = [turn for turn in compacted if turn]
+
+    checkpoint_exchange: list[ModelMessage] = [
+        ModelRequest(
+            parts=[UserPromptPart(content=checkpoint_request)],
+            metadata={_CHECKPOINT_METADATA: True},
+        ),
+        ModelResponse(
+            parts=[TextPart(content=checkpoint_text)],
+            metadata={_CHECKPOINT_METADATA: True},
+        ),
+    ]
+
+    for index in range(len(compacted)):
+        if _estimate_turns(compacted, checkpoint_exchange) <= config.target_tokens:
+            break
+        compacted[index] = _project_dialogue(turns[index])
+
+    for index in range(len(compacted)):
+        if _estimate_turns(compacted, checkpoint_exchange) <= config.target_tokens:
+            break
+        compacted[index] = _project_user(turns[index])
+
+    while len(compacted) > 1 and _estimate_turns(compacted, checkpoint_exchange) > config.target_tokens:
+        compacted.pop(0)
+
+    rewritten = [message for turn in compacted for message in turn] + checkpoint_exchange
+    if _estimate_messages_tokens(rewritten) > config.target_tokens:
+        raise ValueError("checkpoint and latest user message exceed the compaction target")
+    return rewritten
+
+
+def _group_turns_since_checkpoint(messages: list[ModelMessage]) -> list[list[ModelMessage]]:
+    """Group real user turns completed after the previous checkpoint.
+
+    The new checkpoint summarizes the whole supplied context, so the previous checkpoint
+    and every raw turn it already covered are superseded. Host notifications do not open
+    turns.
+    """
+    start = max(
+        (
+            index + 1
+            for index, message in enumerate(messages)
+            if message.metadata and message.metadata.get(_CHECKPOINT_METADATA)
+        ),
+        default=0,
+    )
+    turns: list[list[ModelMessage]] = []
+    for message in messages[start:]:
+        if _is_user_request(message):
+            turns.append([message])
+        elif turns:
+            turns[-1].append(message)
+    return turns
+
+
+def _is_user_request(message: ModelMessage) -> bool:
+    """Return whether a request is an actual user turn rather than a host event."""
+    return (
+        isinstance(message, ModelRequest)
+        and not (message.metadata and message.metadata.get(HOST_EVENT_METADATA_KEY))
+        and any(isinstance(part, UserPromptPart) for part in message.parts)
+    )
+
+
+def _project_execution(turn: list[ModelMessage]) -> list[ModelMessage]:
+    """Keep a turn's execution structure while replacing tool-result payloads."""
+    compacted: list[ModelMessage] = []
+    for message in turn:
+        if not isinstance(message, ModelRequest):
+            compacted.append(message)
+            continue
+        parts = [
+            replace(part, content=_tool_result_placeholder(part)) if isinstance(part, ToolReturnPart) else part
+            for part in message.parts
+        ]
+        compacted.append(replace(message, parts=parts))
+    return compacted
+
+
+def _project_dialogue(turn: list[ModelMessage]) -> list[ModelMessage]:
+    """Project a turn to user prompts and final assistant text only.
+
+    Responses containing tool calls are execution steps, not final answers. Rebuilt
+    text responses intentionally drop provider IDs, signatures, and usage that no
+    longer describe the projected history.
+    """
+    dialogue: list[ModelMessage] = []
+    for message in turn:
+        if isinstance(message, ModelRequest):
+            if message.metadata and message.metadata.get(HOST_EVENT_METADATA_KEY):
+                continue
+            parts = [part for part in message.parts if isinstance(part, UserPromptPart)]
+            if parts:
+                dialogue.append(replace(message, parts=parts))
+            continue
+        if any(isinstance(part, ToolCallPart) for part in message.parts):
+            continue
+        text = "".join(part.content for part in message.parts if isinstance(part, TextPart))
+        if text:
+            dialogue.append(_text_response(message, text))
+    return dialogue
+
+
+def _project_user(turn: list[ModelMessage]) -> list[ModelMessage]:
+    """Project a turn to its user request."""
+    for message in turn:
+        if isinstance(message, ModelRequest) and _is_user_request(message):
+            parts = [part for part in message.parts if isinstance(part, UserPromptPart)]
+            return [replace(message, parts=parts)]
+    return []
+
+
+def _tool_result_placeholder(part: ToolReturnPart) -> str:
+    """Return an omission marker, retaining a stored-message pointer when present."""
+    if isinstance(part.metadata, dict) and (message_id := part.metadata.get("message_id")):
+        return f"{_TOOL_RESULT_PLACEHOLDER}; full result: {message_id}"
+    return _TOOL_RESULT_PLACEHOLDER
+
+
+def _text_response(message: ModelResponse, content: str) -> ModelResponse:
+    """Build a clean text-only projection of an assistant response."""
+    return ModelResponse(
+        parts=[TextPart(content=content)],
+        model_name=message.model_name,
+        timestamp=message.timestamp,
+        run_id=message.run_id,
+        conversation_id=message.conversation_id,
+    )
+
+
+def _estimate_turns(turns: list[list[ModelMessage]], checkpoint: list[ModelMessage]) -> int:
+    """Estimate flattened turns together with their protected checkpoint."""
+    return _estimate_messages_tokens([message for turn in turns for message in turn] + checkpoint)
+
+
+def _estimate_messages_tokens(messages: list[ModelMessage]) -> int:
+    """Estimate model-visible content without counting internal bookkeeping."""
+    chars = 0
+    for message in messages:
+        chars += _MESSAGE_OVERHEAD_CHARS
+        if isinstance(message, ModelRequest) and message.instructions:
+            chars += len(message.instructions)
+        for part in message.parts:
+            chars += _PART_OVERHEAD_CHARS
+            if isinstance(part, UserPromptPart):
+                chars += len(describe_chat_input(cast(ChatInput, part.content)))
+                continue
+            for field in ("tool_name", "args", "content", "transcript", "signature", "tools_added"):
+                chars += _estimate_value_chars(getattr(part, field, None))
+    return math.ceil(chars / _CHARS_PER_TOKEN)
+
+
+def _estimate_value_chars(value: Any) -> int:
+    if value is None:
+        return 0
+    if isinstance(value, str):
+        return len(value)
+    if isinstance(value, BinaryContent):
+        return len(describe_chat_input([value]))
+    return len(json.dumps(value, ensure_ascii=False, separators=(",", ":"), default=str))
+
+
+def _estimate_text_tokens(text: str) -> int:
+    return math.ceil(len(text) / _CHARS_PER_TOKEN)
+
+
+def _context_window(model: str) -> int | None:
+    """Resolve the model context window from genai-prices when known."""
+    model_ref = model.partition(":")[2] or model
+    try:
+        calculation = genai_prices.calc_price(
+            genai_prices.Usage(input_tokens=0, output_tokens=0),
+            model_ref,
+        )
+    except LookupError:
+        return None
+    return calculation.model.context_window

tabulaflow/agents/chat/events.py

@@ -0,0 +1,161 @@
+"""The chat ⇄ frontend event contract.
+
+``ChatSession.run_stream()`` yields a stream of these events; any frontend (the TUI, a
+browser client, a CLI logger, a test harness) consumes the stream and decides how
+to render each one. Events are **semantic** — they carry the data of what the
+agent did, never pre-rendered presentation — so a frontend renders / words /
+truncates however it wants. Rendering is deliberately the frontend's job; this
+module ships no summarizers.
+
+They're pydantic models forming a **discriminated union** on ``kind`` (consistent
+with the other serialized schema models), which gives a frontend free, robust, two-way
+wire (de)serialization:
+
+    raw = event.model_dump_json()                       # produce (server)
+    event = TypeAdapter(ChatEvent).validate_json(raw)    # consume (client)
+
+The stream ends with exactly one ``TurnFinished`` (carrying the result) on normal
+completion. Failures propagate as exceptions; an interrupted run raises
+``CancelledError`` and the agent's message history / usage reflect the partial run.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal, TypeAlias, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from tabulaflow.output.specs import OutputSpec
+from tabulaflow.agents.trace import Usage
+from tabulaflow.agents.tools.protocols import ToolCallOutcome as ToolCallOutcome
+
+
+# ---------------------------------------------------------------------------
+# Streaming events (emitted during a turn)
+# ---------------------------------------------------------------------------
+
+
+class _ChatEvent(BaseModel):
+    """Base for all chat events (immutable)."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class AnswerDelta(_ChatEvent):
+    """A chunk of the assistant's streaming final answer (the user-facing reply)."""
+
+    kind: Literal["answer_delta"] = "answer_delta"
+    content: str
+
+
+class NarrationDelta(_ChatEvent):
+    """A chunk of mid-turn narration — text the model emits while working, before its
+    final answer. Distinct from ``AnswerDelta`` so a frontend can drop or dim it
+    separately (the TUI drops it; a webapp might show it greyed)."""
+
+    kind: Literal["narration_delta"] = "narration_delta"
+    content: str
+
+
+class ThinkingDelta(_ChatEvent):
+    """A chunk of the model's reasoning summary (reasoning models only). Distinct
+    from ``AnswerDelta`` so a frontend can show / collapse it separately from the answer."""
+
+    kind: Literal["thinking_delta"] = "thinking_delta"
+    content: str
+
+
+class ToolStarted(_ChatEvent):
+    """The agent invoked a tool. ``args`` is the raw tool-call arguments (lossless,
+    so a frontend can show the full query / spec, or render its own compact line)."""
+
+    kind: Literal["tool_started"] = "tool_started"
+    tool_call_id: str
+    name: str
+    args: dict[str, Any]
+
+
+class ToolFinished(_ChatEvent):
+    """A tool call returned. ``outcome`` is structured so a frontend can reword it;
+    ``None`` means plain completion with no suffix-worthy fact. The full result
+    (if any) arrives later in ``TurnFinished.result``."""
+
+    kind: Literal["tool_finished"] = "tool_finished"
+    tool_call_id: str
+    name: str
+    outcome: ToolCallOutcome | None = None
+
+
+class ToolProgress(_ChatEvent):
+    """Progress within a long-running / fan-out tool (e.g. per-row subagents).
+
+    ``tool_call_id`` identifies which in-flight tool when several run at once;
+    ``None`` means "the current fan-out" for simple single-tool cases.
+    """
+
+    kind: Literal["tool_progress"] = "tool_progress"
+    completed: int
+    # ``None`` total means an open-ended running count with no known denominator
+    # (e.g. entities extracted so far) — rendered as a bare count, not a fraction.
+    total: int | None
+    # Optional noun for the open-ended count, e.g. ``"rows"`` -> ``"47 rows"``.
+    unit: str | None = None
+    stage: str | None = None
+    tool_call_id: str | None = None
+
+
+class UsageUpdated(_ChatEvent):
+    """Cumulative token/cost usage so far this turn (for a live cost readout)."""
+
+    kind: Literal["usage_updated"] = "usage_updated"
+    usage: Usage
+
+
+class CompactionStarted(_ChatEvent):
+    """The session started compacting context before the pending user turn."""
+
+    kind: Literal["compaction_started"] = "compaction_started"
+
+
+class CompactionFinished(_ChatEvent):
+    """Context compaction ended and normal processing is resuming."""
+
+    kind: Literal["compaction_finished"] = "compaction_finished"
+
+
+# ---------------------------------------------------------------------------
+# Terminal event (ends the stream on normal completion)
+# ---------------------------------------------------------------------------
+
+
+class ChatResult(BaseModel):
+    """Logical result of one chat turn."""
+
+    text: str
+    output: OutputSpec = Field(default_factory=OutputSpec)
+    usage: Usage | None = None
+
+
+class TurnFinished(_ChatEvent):
+    """The turn completed normally; carries the full result. The only terminal
+    event — failures and interrupts surface as exceptions on the iterator, not here."""
+
+    kind: Literal["turn_finished"] = "turn_finished"
+    result: ChatResult
+
+
+ChatEvent: TypeAlias = Annotated[
+    Union[
+        AnswerDelta,
+        NarrationDelta,
+        ThinkingDelta,
+        ToolStarted,
+        ToolFinished,
+        ToolProgress,
+        UsageUpdated,
+        CompactionStarted,
+        CompactionFinished,
+        TurnFinished,
+    ],
+    Field(discriminator="kind"),
+]