fastapi-startkit 0.50.0__tar.gz → 0.52.0__tar.gz

{fastapi_startkit-0.50.0 → fastapi_startkit-0.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-startkit
-Version: 0.50.0
+Version: 0.52.0
 Summary: A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console.
 Keywords: fastapi,framework,async,web,asgi,orm,sqlalchemy,pydantic,ioc-container,dependency-injection,service-provider,cli,console,configuration,microservices,starter-kit,boilerplate
 Author: Bedram Tamang
@@ -22,6 +22,7 @@ Requires-Dist: dotenv>=0.9.9
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: langchain>=1.0.0 ; extra == 'ai'
 Requires-Dist: langchain-core>=1.0.0 ; extra == 'ai'
+Requires-Dist: langgraph>=1.0.0 ; extra == 'ai'
 Requires-Dist: faker>=40.13.0 ; extra == 'database'
 Requires-Dist: sqlalchemy[asyncio]>=2.0.38 ; extra == 'database'
 Requires-Dist: fastapi[standard]>=0.124.4 ; extra == 'fastapi'
@@ -46,3 +47,63 @@ Provides-Extra: mysql
 Provides-Extra: postgres
 Provides-Extra: sqlite
 Provides-Extra: vite
+Description-Content-Type: text/markdown
+
+# FastAPI Startkit
+
+[![codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework/graph/badge.svg)](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+
+A modular, provider-driven framework for building Python applications with FastAPI. It bundles a
+service container, configuration system, an async-first ORM, facades, and a Cleo-powered console into
+a single cohesive foundation.
+
+## Installation
+
+```bash
+pip install fastapi-startkit
+```
+
+Optional extras enable additional capabilities:
+
+```bash
+fastapi-startkit[fastapi]    # FastAPI + Starlette
+fastapi-startkit[database]   # SQLAlchemy async ORM
+fastapi-startkit[vite]       # Jinja2 for Vite integration
+```
+
+## Features
+
+- **Service container** — IoC container with `bind`/`make`/`resolve` auto-wiring and lifecycle hooks.
+- **Configuration** — dataclass-based config sourced from the environment with dotted-key access.
+- **Providers** — two-phase (`register` / `boot`) service registration.
+- **Routing** — a `Router` wrapper around FastAPI's `APIRouter` with a `resource()` CRUD shortcut.
+- **ORM** — async-first Masonite ORM fork on SQLAlchemy async, with relationships and migrations.
+- **Facades** — static-like access to container-resolved services (`Config`, `Auth`, ...).
+- **Console** — Cleo-based CLI (`artisan`) for migrations, seeders, and code generation.
+
+## Documentation
+
+Full documentation is available at
+[fastapi-startkit.github.io](https://fastapi-startkit.github.io).
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --group dev --extra database --extra sqlite --extra fastapi --extra vite --extra postgres
+
+# Run the test suite
+uv run pytest tests/ -v
+
+# Run tests with coverage
+uv run pytest --cov --cov-report=term-missing
+```
+
+Coverage is collected in CI and reported to
+[Codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework).
+
+## License
+
+See the repository root for license details.

fastapi_startkit-0.52.0/README.md

@@ -0,0 +1,58 @@
+# FastAPI Startkit
+
+[![codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework/graph/badge.svg)](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework)
+[![PyPI version](https://img.shields.io/pypi/v/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fastapi-startkit.svg)](https://pypi.org/project/fastapi-startkit/)
+
+A modular, provider-driven framework for building Python applications with FastAPI. It bundles a
+service container, configuration system, an async-first ORM, facades, and a Cleo-powered console into
+a single cohesive foundation.
+
+## Installation
+
+```bash
+pip install fastapi-startkit
+```
+
+Optional extras enable additional capabilities:
+
+```bash
+fastapi-startkit[fastapi]    # FastAPI + Starlette
+fastapi-startkit[database]   # SQLAlchemy async ORM
+fastapi-startkit[vite]       # Jinja2 for Vite integration
+```
+
+## Features
+
+- **Service container** — IoC container with `bind`/`make`/`resolve` auto-wiring and lifecycle hooks.
+- **Configuration** — dataclass-based config sourced from the environment with dotted-key access.
+- **Providers** — two-phase (`register` / `boot`) service registration.
+- **Routing** — a `Router` wrapper around FastAPI's `APIRouter` with a `resource()` CRUD shortcut.
+- **ORM** — async-first Masonite ORM fork on SQLAlchemy async, with relationships and migrations.
+- **Facades** — static-like access to container-resolved services (`Config`, `Auth`, ...).
+- **Console** — Cleo-based CLI (`artisan`) for migrations, seeders, and code generation.
+
+## Documentation
+
+Full documentation is available at
+[fastapi-startkit.github.io](https://fastapi-startkit.github.io).
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --group dev --extra database --extra sqlite --extra fastapi --extra vite --extra postgres
+
+# Run the test suite
+uv run pytest tests/ -v
+
+# Run tests with coverage
+uv run pytest --cov --cov-report=term-missing
+```
+
+Coverage is collected in CI and reported to
+[Codecov](https://codecov.io/gh/fastapi-startkit/fastapi-startkit-framework).
+
+## License
+
+See the repository root for license details.

{fastapi_startkit-0.50.0 → fastapi_startkit-0.52.0}/pyproject.toml

@@ -1,7 +1,8 @@
 [project]
 name = "fastapi-startkit"
-version = "0.50.0"
+version = "0.52.0"
 description = "A modular, provider-driven framework for building async Python web applications with FastAPI — bundling a service container, configuration system, an async-first ORM, facades, and a Cleo-powered console."
+readme = "README.md"
 keywords = [
     "fastapi",
     "framework",
@@ -86,6 +87,7 @@ inertia = [
 ai = [
     "langchain>=1.0.0",
     "langchain-core>=1.0.0",
+    "langgraph>=1.0.0",
 ]
 
 [dependency-groups]
@@ -129,7 +131,7 @@ exclude = [
     "**/__pycache__",
     "**/.venv",
 ]
-typeCheckingMode = "basic"
+typeCheckingMode = "standard"
 pythonVersion = "3.12"
 
 [tool.pytest.ini_options]
@@ -148,7 +150,7 @@ omit = [
 [tool.coverage.report]
 show_missing = true
 skip_covered = false
-fail_under = 68
+fail_under = 80
 exclude_lines = [
     "pragma: no cover",
     "if TYPE_CHECKING:",

{fastapi_startkit-0.50.0 → fastapi_startkit-0.52.0}/src/fastapi_startkit/ai/__init__.py

@@ -6,31 +6,31 @@ from .config.config import AnthropicConfig, ElevenLabsConfig, GoogleConfig, Open
 from .config.ai import AIConfig
 from .decorators import max_steps, max_tokens, model, provider, timeout, top_p
 from .document import Document
-from .fakes import fake_chat_model
 from .image import Image, ImageResponse
 from .image_factory import ImageFactory
+from .ai import Ai
+from .judge import JudgeAgent
 from .providers.ai_provider import AIProvider
-from .response import AgentResponse, AgentSnapshot
-from .testing import AgentBinding, FakeAgent, NoFakeResponse, RecordingAgent
+from . import state
+from .testing import AgentFake, AgentRecordFake, AssertToolCall
 
 __all__ = [
     "Agent",
+    "Ai",
     "Middleware",
-    "AgentBinding",
-    "AgentResponse",
-    "AgentSnapshot",
+    "AgentFake",
+    "state",
     "AIConfig",
     "AIProvider",
     "AnthropicConfig",
-    "FakeAgent",
-    "NoFakeResponse",
-    "RecordingAgent",
+    "JudgeAgent",
+    "AgentRecordFake",
+    "AssertToolCall",
     "Audio",
     "AudioResponse",
     "AudioFactory",
     "Document",
     "ElevenLabsConfig",
-    "fake_chat_model",
     "GoogleConfig",
     "Image",
     "ImageFactory",

fastapi_startkit-0.52.0/src/fastapi_startkit/ai/agent.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, AsyncIterator, Callable, Generic, Optional, Type, TypeVar
+
+from .document import Document
+from .runner import BaseRunner, Runner
+
+if TYPE_CHECKING:
+    from langchain_core.tools import BaseTool
+
+    from .testing import AgentFake, AgentRecordFake
+    from .types import Middleware
+
+_R = TypeVar("_R")
+
+
+class _hybridmethod(Generic[_R]):
+    """A method callable on the class (bound to a freshly built instance) or on an
+    existing instance (bound to that instance). Lets ``Agent.record()`` and
+    ``Agent(state, config).record()`` both work, the latter keeping its state."""
+
+    def __init__(self, func: Callable[..., _R]) -> None:
+        self._func = func
+
+    def __get__(self, instance: object, owner: type) -> Callable[..., _R]:
+        target = instance if instance is not None else owner()
+        return functools.partial(self._func, target)
+
+
+class Agent:
+    provider: str | None = None
+    model: str | None = None
+    max_steps: int = 10
+    max_tokens: int = 4096
+    timeout: float = 30.0
+    top_p: float = 1.0
+    temperature: float | None = None
+    tool_choice: str | None = None
+
+    def messages(self) -> list[dict]:
+        return []
+
+    def instructions(self) -> str | None:
+        return None
+
+    def schema(self) -> Optional[Type]:
+        return None
+
+    def tools(self) -> list[BaseTool]:
+        return []
+
+    def middleware(self) -> list[Middleware]:
+        return []
+
+    def provider_options(self) -> dict:
+        return {}
+
+    async def prompt(
+        self,
+        message: str,
+        *,
+        model: str | None = None,
+        attachments: list[Document] | None = None,
+        provider_options: dict | None = None,
+    ) -> dict:
+        """Returns the turn as ``{"messages": [HumanMessage, AIMessage, ToolMessage,
+        ...]}`` — the same state langchain's ``create_agent().invoke()`` yields —
+        plus ``"structured_response"`` when the agent defines a schema()."""
+        return await self.runner().run(message, model=model, attachments=attachments, provider_options=provider_options)
+
+    async def stream(
+        self,
+        message: str,
+        *,
+        model: str | None = None,
+        provider_options: dict | None = None,
+    ) -> AsyncIterator[dict]:
+        """Yields StandardStreamEvent dicts — the same shape LangChain's
+        astream_events produces: on_chat_model_(start|stream|end) for the model
+        turn (data.chunk carries each AIMessageChunk) and on_tool_(start|end)
+        around each tool execution."""
+        async for chunk in self.runner().stream(message, model=model, provider_options=provider_options):
+            yield chunk
+
+    def runner(self) -> BaseRunner:
+        return Runner(self)
+
+    @classmethod
+    def fake(cls, responses: list) -> "AgentFake":
+        from .testing import AgentFake
+
+        return AgentFake(cls, responses)
+
+    @_hybridmethod
+    def record(self, cassette: str | None = None, messages: list | None = None) -> "AgentRecordFake":
+        from .testing import AgentRecordFake
+
+        return AgentRecordFake(self, cassette, messages)

fastapi_startkit-0.52.0/src/fastapi_startkit/ai/ai.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .lab import Lab
+
+if TYPE_CHECKING:
+    from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+
+    from .agent import Agent
+
+
+class Ai:
+    _fakes: dict[str, GenericFakeChatModel] = {}
+
+    def __init__(self) -> None:
+        pass
+
+    @staticmethod
+    def _key(agent: "Agent | str") -> str:
+        return agent if isinstance(agent, str) else type(agent).__name__
+
+    @classmethod
+    def fake(cls, agent: "Agent | str", messages: list) -> Any:
+        from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+        from langchain_core.messages import AIMessage
+
+        turns = [message if hasattr(message, "content") else AIMessage(content=str(message)) for message in messages]
+        model = GenericFakeChatModel(messages=iter(turns))
+        cls._fakes[cls._key(agent)] = model
+        return model
+
+    @classmethod
+    def has_fake_model_for(cls, agent: "Agent | str") -> bool:
+        return cls._key(agent) in cls._fakes
+
+    @classmethod
+    def get_fake_model_for(cls, agent: "Agent | str") -> Any:
+        return cls._fakes[cls._key(agent)]
+
+    @classmethod
+    def forget(cls, agent: "Agent | str") -> None:
+        cls._fakes.pop(cls._key(agent), None)
+
+    @classmethod
+    def reset_fakes(cls) -> None:
+        cls._fakes.clear()
+
+    def get_model_for(
+        self,
+        agent: "Agent",
+        model: str | None = None,
+        provider_options: dict | None = None,
+    ) -> Any:
+        if self.has_fake_model_for(agent):
+            return self.get_fake_model_for(agent)
+        return self.build(agent, model, provider_options)
+
+    def build(
+        self,
+        agent: "Agent",
+        model: str | None = None,
+        provider_options: dict | None = None,
+    ) -> Any:
+        from langchain.chat_models import init_chat_model  # noqa: PLC0415
+
+        lab = Lab.get_provider(agent.provider)
+        kwargs: dict[str, Any] = {"model_provider": lab.get_provider_key()}
+
+        api_key = lab.get_api_key()
+        if api_key:
+            kwargs["api_key"] = api_key
+        if agent.max_tokens:
+            kwargs["max_tokens"] = agent.max_tokens
+        if agent.top_p != 1.0:
+            kwargs["top_p"] = agent.top_p
+        if agent.temperature is not None:
+            kwargs["temperature"] = agent.temperature
+        if agent.timeout:
+            kwargs["timeout"] = agent.timeout
+
+        kwargs.update(self._resolve_provider_options(agent, provider_options))
+
+        chat_model = init_chat_model(self._resolve_model(agent, model), **kwargs)
+
+        tools = list(agent.tools())
+        if tools:
+            if agent.tool_choice:
+                chat_model = chat_model.bind_tools(tools, tool_choice=agent.tool_choice)
+            else:
+                chat_model = chat_model.bind_tools(tools)
+
+        schema = agent.schema()
+        if schema is not None:
+            chat_model = chat_model.with_structured_output(schema, include_raw=True)
+
+        return chat_model
+
+    def _resolve_model(self, agent: "Agent", override: str | None = None) -> str:
+        return Lab.get_provider(agent.provider).get_model(override or agent.model or None)
+
+    def _resolve_provider_options(self, agent: "Agent", override: dict | None = None) -> dict:
+        options = dict(agent.provider_options().get(agent.provider, {}))
+        if override:
+            provider_specific = override.get(agent.provider, override)
+            if isinstance(provider_specific, dict):
+                options.update(provider_specific)
+        return options

fastapi_startkit-0.52.0/src/fastapi_startkit/ai/judge.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from .agent import Agent
+
+
+class Verdict(BaseModel):
+    passed: bool
+    reasoning: str = ""
+
+
+class JudgeAgent(Agent):
+    """Grades a response against a natural-language expectation.
+
+    A plain ``Agent`` whose ``schema()`` is a ``Verdict`` model, so the JSON
+    reply is parsed into a typed result through the standard structured-output
+    path — no hand-rolled verdict parsing. Set ``.model``/``.provider`` like
+    any other agent; it's fakeable via ``fake()`` and replayable via
+    ``record()`` for free.
+    """
+
+    def instructions(self) -> str:
+        return (
+            "You are grading whether an AI agent's response satisfies an expectation. "
+            'Reply with strict JSON only, no prose: {"passed": true|false, "reasoning": "<one sentence>"}'
+        )
+
+    def schema(self):
+        return Verdict
+
+    async def judge(self, expectation: str, content: str) -> dict:
+        state = await self.prompt(f"Expectation: {expectation}\n\nResponse to grade:\n{content}")
+        return state["structured_response"].model_dump()

{fastapi_startkit-0.50.0 → fastapi_startkit-0.52.0}/src/fastapi_startkit/ai/pipeline.py

@@ -40,13 +40,33 @@ class Response:
                 await result
         return final
 
+    @staticmethod
+    def _merge(accumulated: Any, chunk: Any) -> Any:
+        # Stream events (astream_events shape) merge into joined text for the
+        # after-hooks: model chunks and tool outputs contribute their text, the
+        # start/end envelopes add nothing. Any other dict (e.g. a
+        # structured-output result carrying "raw"/"parsed") passes through whole.
+        if isinstance(chunk, dict) and "event" in chunk:
+            data = chunk.get("data") or {}
+            if chunk["event"] == "on_chat_model_stream":
+                text = getattr(data.get("chunk"), "content", "") or ""
+            elif chunk["event"] == "on_tool_end":
+                text = getattr(data.get("output"), "content", "") or ""
+            else:
+                text = ""
+            text = text if isinstance(text, str) else str(text)
+            if accumulated is None:
+                return text or None
+            return accumulated + text
+        return chunk if accumulated is None else accumulated + chunk
+
     def __aiter__(self) -> AsyncIterator:
         async def _it() -> AsyncIterator:
             accumulated = None
             finished = False
             try:
                 async for chunk in self._source():
-                    accumulated = chunk if accumulated is None else accumulated + chunk
+                    accumulated = self._merge(accumulated, chunk)
                     yield chunk
                 finished = True
                 await self._finish(accumulated)
@@ -63,7 +83,7 @@ class Response:
         async def _run() -> Any:
             accumulated = None
             async for chunk in self._source():
-                accumulated = chunk if accumulated is None else accumulated + chunk
+                accumulated = self._merge(accumulated, chunk)
             return await self._finish(accumulated)
 
         return _run().__await__()

fastapi_startkit-0.52.0/src/fastapi_startkit/ai/recording.py

@@ -0,0 +1,182 @@
+"""Ordered per-turn recording format for ``Agent.record()`` cassettes.
+
+A recorded turn is an ordered list of message dicts that captures the full
+interaction for one user input — the human prompt, every model turn (with its
+token ``uses`` and ``response_time``), and every tool call (with the tool's
+response and its own ``response_time``). Persisting the whole ordered exchange —
+rather than only the final answer — lets recordings be replayed and inspected
+faithfully.
+
+    [
+      {"type": "human", "content": "suggest me jobs"},
+      {"type": "ai", "tool_calls": [...], "uses": {...}, "response_time": 12.0},
+      {"type": "tool_response", "content_type": "json", "content": "[...]", "response_time": 5.0},
+      {"type": "ai", "content": "Here is a job...", "uses": {...}, "response_time": 8.0},
+    ]
+
+``response_time`` is milliseconds; ``uses`` mirrors LangChain ``usage_metadata``
+as ``input_token`` / ``output_token`` / ``cache_token`` / ``total_token``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, ToolMessage
+
+
+def _infer_content_type(content: str) -> str:
+    try:
+        json.loads(content)
+    except (ValueError, TypeError):
+        return "text"
+    return "json"
+
+
+def uses_from_usage_metadata(meta: dict | None) -> dict:
+    """Map a LangChain ``usage_metadata`` dict onto the cassette ``uses`` shape."""
+    meta = meta or {}
+    details = meta.get("input_token_details") or {}
+    return {
+        "input_token": meta.get("input_tokens", 0),
+        "output_token": meta.get("output_tokens", 0),
+        "cache_token": details.get("cache_read", 0),
+        "total_token": meta.get("total_tokens", 0),
+    }
+
+
+def is_transcript(value: Any) -> bool:
+    """True when ``value`` is a new-format ordered transcript (list of typed entries)."""
+    return isinstance(value, list) and bool(value) and isinstance(value[0], dict) and "type" in value[0]
+
+
+def human(content: str) -> dict:
+    """Build a ``human`` transcript entry."""
+    return {"type": "human", "content": content}
+
+
+def ai(
+    content: str = "",
+    tool_calls: list[dict] | None = None,
+    uses: dict | None = None,
+    response_time: float = 0.0,
+    chunks: list[str] | None = None,
+) -> dict:
+    """Build an ``ai`` transcript entry (a model turn: answer and/or tool calls)."""
+    entry: dict[str, Any] = {"type": "ai"}
+    if content:
+        entry["content"] = content
+    if tool_calls:
+        entry["tool_calls"] = tool_calls
+    entry["uses"] = uses or {}
+    entry["response_time"] = response_time
+    if chunks is not None:
+        entry["chunks"] = chunks
+    return entry
+
+
+def tool_response(content: str, response_time: float = 0.0, content_type: str | None = None) -> dict:
+    """Build a ``tool_response`` transcript entry (a tool's output)."""
+    return {
+        "type": "tool_response",
+        "content_type": content_type or _infer_content_type(content),
+        "content": content,
+        "response_time": response_time,
+    }
+
+
+def usage_metadata_from_uses(uses: dict) -> dict:
+    """Map a cassette ``uses`` dict back onto LangChain ``usage_metadata``."""
+    return {
+        "input_tokens": uses.get("input_token", 0),
+        "output_tokens": uses.get("output_token", 0),
+        "total_tokens": uses.get("total_token", 0),
+        "input_token_details": {"cache_read": uses.get("cache_token", 0)},
+    }
+
+
+def _as_text(content: Any) -> str:
+    return content if isinstance(content, str) else str(content)
+
+
+def entries_from_messages(messages: list[BaseMessage]) -> list[dict]:
+    """Convert a turn's AI/tool LangChain messages into cassette entries.
+
+    Human (and system) messages are skipped — the cassette turn opens with its
+    own ``human`` entry. ``response_time`` is read from ``additional_kwargs``,
+    where the runner stamps it on every AI and tool message."""
+    entries: list[dict] = []
+    for message in messages or []:
+        kind = getattr(message, "type", "")
+        response_time = (getattr(message, "additional_kwargs", None) or {}).get("response_time", 0.0)
+        if kind == "ai":
+            entries.append(
+                ai(
+                    content=_as_text(message.content),
+                    tool_calls=list(getattr(message, "tool_calls", None) or []),
+                    uses=uses_from_usage_metadata(getattr(message, "usage_metadata", None)),
+                    response_time=response_time,
+                )
+            )
+        elif kind == "tool":
+            entries.append(tool_response(content=_as_text(message.content), response_time=response_time))
+    return entries
+
+
+def messages_from_transcript(transcript: list[dict]) -> list[BaseMessage]:
+    """Rebuild the turn's LangChain messages from cassette entries, so a replayed
+    response carries the same ``messages`` a live run produces. Cassette entries
+    don't store the tool's name/call id, so those stay empty on replay."""
+    messages: list[BaseMessage] = []
+    for entry in transcript:
+        kind = entry.get("type")
+        if kind == "human":
+            messages.append(HumanMessage(content=entry.get("content", "")))
+        elif kind == "ai":
+            uses = entry.get("uses") or {}
+            messages.append(
+                AIMessage(
+                    content=entry.get("content", ""),
+                    tool_calls=entry.get("tool_calls") or [],
+                    additional_kwargs={"response_time": entry.get("response_time", 0.0)},
+                    usage_metadata=usage_metadata_from_uses(uses) if uses else None,
+                )
+            )
+        elif kind == "tool_response":
+            messages.append(
+                ToolMessage(
+                    content=entry.get("content", ""),
+                    tool_call_id="",
+                    additional_kwargs={"response_time": entry.get("response_time", 0.0)},
+                )
+            )
+    return messages
+
+
+def to_state(transcript: list[dict]) -> dict:
+    """Reconstruct a turn's ``{"messages": [...]}`` state from cassette entries,
+    so a replayed turn has the same shape a live run returns."""
+    return {"messages": messages_from_transcript(transcript)}
+
+
+def accumulate_uses(messages: list, totals: dict) -> None:
+    """Add every AI message's token usage in a turn's ``messages`` into ``totals``
+    (keys: input, output, cache, total)."""
+    for message in messages or []:
+        if getattr(message, "type", "") != "ai":
+            continue
+        uses = uses_from_usage_metadata(getattr(message, "usage_metadata", None))
+        totals["input"] += uses["input_token"]
+        totals["output"] += uses["output_token"]
+        totals["cache"] += uses["cache_token"]
+        totals["total"] += uses["total_token"]
+
+
+def chunks_from_transcript(transcript: list[dict]) -> list[str]:
+    """Collect streamed chunks recorded on the turn's ``ai`` messages."""
+    chunks: list[str] = []
+    for entry in transcript:
+        if entry.get("type") == "ai" and entry.get("chunks"):
+            chunks.extend(entry["chunks"])
+    return chunks