swarph-mesh 0.1.0__tar.gz

swarph_mesh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Samson and Claude Opus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swarph_mesh-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: swarph-mesh
+Version: 0.1.0
+Summary: Model-agnostic Python substrate for the swarph-mesh ecosystem. v0.1.0 ships SwarphCall + GeminiAdapter (Phase 1 substrate per PLAN.md §13).
+Author: Pierre Samson, Claude Opus
+License: MIT
+Project-URL: Homepage, https://github.com/darw007d/swarph-mesh
+Project-URL: Source, https://github.com/darw007d/swarph-mesh
+Project-URL: CLI, https://github.com/darw007d/swarph-cli
+Project-URL: Plugin, https://github.com/darw007d/swarph-meshlm
+Project-URL: Spec, https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md
+Keywords: swarph,llm,mesh,cli,multi-llm,gemini,claude,deepseek
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: swarph-shared>=0.2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: langgraph-genai-bridge>=0.1.5
+Requires-Dist: langchain-core>=0.3
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# swarph-mesh
+
+Model-agnostic Python substrate for the swarph-mesh ecosystem. Pure library, no CLI.
+
+Designed to fill the gap left by existing tools (`aichat`, `mods`, Simon Willison's `llm`, `gemini-cli`, `claude-cli`): none expose mesh-gateway participation, per-caller attribution, structured-output discipline, or the cooperative-protocol patterns the swarph encodes.
+
+This is one of three repos in the v0.3.x architecture:
+
+| Repo | Role |
+|---|---|
+| [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) | This package — typed Protocol + adapters + SwarphCall + MeshClient |
+| [`swarph-cli`](https://github.com/darw007d/swarph-cli) | The `swarph` binary. Thin client over `swarph-mesh` |
+| [`swarph-meshlm`](https://github.com/darw007d/swarph-meshlm) | Simon Willison `llm` plugin. Same primitives wired into `llm`'s plugin host |
+
+All three sit on top of [`swarph-shared`](https://github.com/darw007d/swarph-shared) which provides the cross-billing-path attribution + subprocess env scrubbing + JSON-mode harness + peer-name registry primitives.
+
+## Status
+
+**v0.1.0 — Phase 1 substrate.** Live `SwarphCall(provider="gemini")` works end-to-end against real Gemini API per PLAN.md §13 falsifiability gate.
+
+Public surface:
+
+- `LLMAdapter` Protocol (runtime-checkable) + `ChatMessage` + `LLMResponse`
+- `SwarphCall` — public entry point with caller-convention validation, hooks, attribution
+- `GeminiAdapter` — wraps `langgraph-genai-bridge` (Flex tier, context caching)
+- JSON-mode harness — retry-once with [USER]-turn feedback (per swarph-shared invariant)
+- Attribution: `FileAttributionWriter` default; `set_default_writer()` for production TSDB consumers
+
+Tests: **43/43 passing** (42 offline + 1 live smoke gated on `GEMINI_API_KEY`).
+
+```python
+from swarph_mesh import SwarphCall, ChatMessage
+
+result = await SwarphCall(
+    provider="gemini",
+    caller="orchestrator.boss",
+).chat(
+    messages=[ChatMessage(role="user", content="hi")],
+)
+print(result.text, result.cost_usd, result.input_tokens)
+```
+
+## Spec
+
+The canonical PLAN with sequencing, falsifiability gates, and design rationale lives at:
+
+→ [hedge-fund-mcp / research/swarph_cli/PLAN.md](https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md)
+
+## Phase rollout
+
+| Phase | Scope |
+|---|---|
+| **0** (v0.0.1) | Typed substrate — Protocol + dataclasses + exceptions |
+| **1** (v0.1.0 — this release) | Gemini adapter + `SwarphCall` surface + caller convention import + JSON-mode harness + attribution hook |
+| **3** | `MeshClient` — replaces hand-rolled curl in `lab_loop_drain.py` etc. |
+| **4** | DeepSeek + Claude (subscription) + OpenAI adapters |
+| **5.5** | `swarph onboard` + `swarph ratify` (lives in `swarph-cli`, depends on this) |
+| **5.7** | `swarph daemon` + REPL drain coroutine (lives in `swarph-cli`) |
+| **6** | PyPI publish |
+| **7** | `swarph-meshlm` plugin (separate repo, this dep) |
+
+## Install (dev)
+
+```bash
+git clone https://github.com/darw007d/swarph-mesh
+cd swarph-mesh
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. Pierre Samson + Claude Opus, 2026.

swarph_mesh-0.1.0/README.md

@@ -0,0 +1,74 @@
+# swarph-mesh
+
+Model-agnostic Python substrate for the swarph-mesh ecosystem. Pure library, no CLI.
+
+Designed to fill the gap left by existing tools (`aichat`, `mods`, Simon Willison's `llm`, `gemini-cli`, `claude-cli`): none expose mesh-gateway participation, per-caller attribution, structured-output discipline, or the cooperative-protocol patterns the swarph encodes.
+
+This is one of three repos in the v0.3.x architecture:
+
+| Repo | Role |
+|---|---|
+| [`swarph-mesh`](https://github.com/darw007d/swarph-mesh) | This package — typed Protocol + adapters + SwarphCall + MeshClient |
+| [`swarph-cli`](https://github.com/darw007d/swarph-cli) | The `swarph` binary. Thin client over `swarph-mesh` |
+| [`swarph-meshlm`](https://github.com/darw007d/swarph-meshlm) | Simon Willison `llm` plugin. Same primitives wired into `llm`'s plugin host |
+
+All three sit on top of [`swarph-shared`](https://github.com/darw007d/swarph-shared) which provides the cross-billing-path attribution + subprocess env scrubbing + JSON-mode harness + peer-name registry primitives.
+
+## Status
+
+**v0.1.0 — Phase 1 substrate.** Live `SwarphCall(provider="gemini")` works end-to-end against real Gemini API per PLAN.md §13 falsifiability gate.
+
+Public surface:
+
+- `LLMAdapter` Protocol (runtime-checkable) + `ChatMessage` + `LLMResponse`
+- `SwarphCall` — public entry point with caller-convention validation, hooks, attribution
+- `GeminiAdapter` — wraps `langgraph-genai-bridge` (Flex tier, context caching)
+- JSON-mode harness — retry-once with [USER]-turn feedback (per swarph-shared invariant)
+- Attribution: `FileAttributionWriter` default; `set_default_writer()` for production TSDB consumers
+
+Tests: **43/43 passing** (42 offline + 1 live smoke gated on `GEMINI_API_KEY`).
+
+```python
+from swarph_mesh import SwarphCall, ChatMessage
+
+result = await SwarphCall(
+    provider="gemini",
+    caller="orchestrator.boss",
+).chat(
+    messages=[ChatMessage(role="user", content="hi")],
+)
+print(result.text, result.cost_usd, result.input_tokens)
+```
+
+## Spec
+
+The canonical PLAN with sequencing, falsifiability gates, and design rationale lives at:
+
+→ [hedge-fund-mcp / research/swarph_cli/PLAN.md](https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md)
+
+## Phase rollout
+
+| Phase | Scope |
+|---|---|
+| **0** (v0.0.1) | Typed substrate — Protocol + dataclasses + exceptions |
+| **1** (v0.1.0 — this release) | Gemini adapter + `SwarphCall` surface + caller convention import + JSON-mode harness + attribution hook |
+| **3** | `MeshClient` — replaces hand-rolled curl in `lab_loop_drain.py` etc. |
+| **4** | DeepSeek + Claude (subscription) + OpenAI adapters |
+| **5.5** | `swarph onboard` + `swarph ratify` (lives in `swarph-cli`, depends on this) |
+| **5.7** | `swarph daemon` + REPL drain coroutine (lives in `swarph-cli`) |
+| **6** | PyPI publish |
+| **7** | `swarph-meshlm` plugin (separate repo, this dep) |
+
+## Install (dev)
+
+```bash
+git clone https://github.com/darw007d/swarph-mesh
+cd swarph-mesh
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT. Pierre Samson + Claude Opus, 2026.

swarph_mesh-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "swarph-mesh"
+version = "0.1.0"
+description = "Model-agnostic Python substrate for the swarph-mesh ecosystem. v0.1.0 ships SwarphCall + GeminiAdapter (Phase 1 substrate per PLAN.md §13)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Pierre Samson" },
+    { name = "Claude Opus" },
+]
+keywords = ["swarph", "llm", "mesh", "cli", "multi-llm", "gemini", "claude", "deepseek"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "swarph-shared>=0.2.0",
+    "pydantic>=2.0",
+    # Phase 1 — Gemini adapter wraps the bridge (PLAN.md §3 ship order #1)
+    "langgraph-genai-bridge>=0.1.5",
+    "langchain-core>=0.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/darw007d/swarph-mesh"
+Source = "https://github.com/darw007d/swarph-mesh"
+CLI = "https://github.com/darw007d/swarph-cli"
+Plugin = "https://github.com/darw007d/swarph-meshlm"
+Spec = "https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+# NOTE: this repo is the substrate Python package only — pure library.
+# The `swarph` CLI binary lives in `darw007d/swarph-cli`; the Simon
+# Willison `llm` plugin in `darw007d/swarph-meshlm`. All three import
+# from this package as the bottom layer.
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"

swarph_mesh-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

swarph_mesh-0.1.0/src/swarph_mesh/__init__.py

@@ -0,0 +1,95 @@
+"""swarph-mesh — model-agnostic Python substrate for the swarph-mesh ecosystem.
+
+The substrate gap the existing CLIs (``aichat`` / ``mods`` / Simon Willison's
+``llm`` / ``gemini-cli`` / ``claude-cli``) leave open: none expose
+mesh-gateway participation, per-caller attribution, structured-output
+discipline, or the cooperative-protocol patterns the swarph encodes.
+
+This package fills it as a pure Python library. Three repos make up
+the v0.3.x architecture:
+
+* ``swarph-mesh`` (this package)   — typed Protocol + adapters + SwarphCall.
+                                     Pure library, no CLI.
+* ``swarph-cli`` (separate repo)   — the ``swarph`` binary. Thin client
+                                     on top of ``swarph-mesh``.
+* ``swarph-meshlm`` (separate)     — Simon Willison ``llm`` plugin.
+
+See the canonical PLAN at:
+``https://github.com/darw007d/hedge-fund-mcp/blob/main/research/swarph_cli/PLAN.md``
+
+v0.1.0 — Phase 1 substrate. Ships:
+
+* :class:`LLMAdapter` Protocol + ``ChatMessage`` + ``LLMResponse`` (from v0.0.1)
+* :class:`SwarphCall` public surface — caller-validated, hook-wired entry-point
+* :class:`GeminiAdapter` — wraps ``langgraph-genai-bridge`` (Flex tier, caching)
+* JSON-mode harness — retry-once with [USER]-turn feedback (per PR #125 invariant)
+* Attribution hooks + writers (FileAttributionWriter default;
+  ``set_default_writer`` for production TSDB consumers)
+
+Future phases (per PLAN.md §13):
+  3      MeshClient — mesh-gateway HTTP wrapper
+  4      DeepSeek + Claude (subscription) + OpenAI + Grok adapters
+  2.5+   ``swarph import`` (lives in swarph-cli)
+"""
+
+from __future__ import annotations
+
+# Public types
+from swarph_mesh.exceptions import (
+    AdapterError,
+    SwarphMeshError,
+    UnknownProvider,
+)
+from swarph_mesh.types import (
+    ChatMessage,
+    LLMAdapter,
+    LLMResponse,
+)
+
+# Phase 1 surfaces
+from swarph_mesh.swarph_call import SwarphCall
+from swarph_mesh.adapters import get_adapter, register_adapter
+from swarph_mesh.attribution import (
+    AttributionEvent,
+    AttributionWriter,
+    FileAttributionWriter,
+    NullAttributionWriter,
+    get_default_writer,
+    set_default_writer,
+)
+from swarph_mesh.hooks import (
+    CallContext,
+    HookSet,
+    attribution_post_call,
+    default_hooks,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # types
+    "ChatMessage",
+    "LLMResponse",
+    "LLMAdapter",
+    # exceptions
+    "SwarphMeshError",
+    "AdapterError",
+    "UnknownProvider",
+    # SwarphCall public surface
+    "SwarphCall",
+    "get_adapter",
+    "register_adapter",
+    # attribution
+    "AttributionEvent",
+    "AttributionWriter",
+    "FileAttributionWriter",
+    "NullAttributionWriter",
+    "get_default_writer",
+    "set_default_writer",
+    # hooks
+    "CallContext",
+    "HookSet",
+    "attribution_post_call",
+    "default_hooks",
+]

swarph_mesh-0.1.0/src/swarph_mesh/adapters/__init__.py

@@ -0,0 +1,56 @@
+"""Provider adapters — registry + dispatch.
+
+Phase 1 ships only the Gemini adapter (PLAN.md §3 ship order).
+Subsequent phases add DeepSeek / Claude / OpenAI / Grok by adding
+modules here + registering them in :func:`get_adapter`.
+
+Adapters are singletons per provider — instantiated on first
+request, reused for the rest of the process. This matches the
+"adapter registry" shape from PLAN.md §4.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from swarph_mesh.exceptions import UnknownProvider
+from swarph_mesh.types import LLMAdapter
+
+# Registry of instantiated singletons (one per provider name)
+_REGISTRY: dict[str, LLMAdapter] = {}
+
+
+def get_adapter(provider: str, *, api_key: Optional[str] = None) -> LLMAdapter:
+    """Return the adapter for ``provider``, instantiating on first request.
+
+    Phase 1: only ``"gemini"`` is registered. Other providers raise
+    :class:`UnknownProvider`. Phase 4+ adds DeepSeek, Claude, OpenAI, Grok.
+    """
+    if provider in _REGISTRY:
+        return _REGISTRY[provider]
+
+    if provider == "gemini":
+        from swarph_mesh.adapters.gemini import GeminiAdapter
+
+        adapter = GeminiAdapter(api_key=api_key)
+        _REGISTRY[provider] = adapter
+        return adapter
+
+    raise UnknownProvider(
+        f"no adapter registered for provider {provider!r}. "
+        "Phase 1 ships gemini only; DeepSeek/Claude/OpenAI/Grok ship in Phase 4+."
+    )
+
+
+def register_adapter(provider: str, adapter: LLMAdapter) -> None:
+    """Programmatic adapter registration. Test fixtures use this to
+    inject mocks; production consumers normally don't need it."""
+    _REGISTRY[provider] = adapter
+
+
+def reset_registry() -> None:
+    """Test-only: clear the registry. Not part of the public API."""
+    _REGISTRY.clear()
+
+
+__all__ = ["get_adapter", "register_adapter", "reset_registry"]

swarph_mesh-0.1.0/src/swarph_mesh/adapters/gemini.py

@@ -0,0 +1,195 @@
+"""Gemini adapter — wraps ``langgraph-genai-bridge`` per PLAN.md §3.
+
+Why the bridge and not raw ``google.genai``: the bridge ships
+production-tested Flex tier handling, context caching (Pro tier),
+and usage-metadata extraction in a clean abstraction. Re-implementing
+those features in this adapter would duplicate ~200 LOC for no
+substrate benefit. The bridge is a stable v0.1.5 PyPI package that
+both lab and droplet have run in production for weeks.
+
+Cost calculation uses Google's published per-Mtok pricing as of
+2026-04-29; update the ``PRICING`` table when Google revises rates.
+Flex tier (``flex=True``) gets a 50% rebate per Google's announced
+pricing — applied after the base cost computation.
+
+The adapter exposes the swarph_mesh :class:`LLMAdapter` Protocol
+shape: async ``chat`` + ``stream`` + sync ``cost_per_token``.
+``stream`` is a v0.2.0 stretch (PLAN.md doesn't gate Phase 1 on
+streaming; the bridge supports it but we keep the surface simple
+for now and raise ``NotImplementedError``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import AsyncIterator, Optional
+
+from swarph_mesh.exceptions import AdapterError
+from swarph_mesh.types import ChatMessage, LLMResponse
+
+
+# Gemini per-Mtok pricing (USD), 2026-04-29 baseline.
+# Flex tier applies a 50% rebate after base computation.
+PRICING: dict[str, tuple[float, float]] = {
+    # model_id: (input_per_mtok, output_per_mtok)
+    "gemini-2.5-flash": (0.075, 0.30),
+    "gemini-2.5-flash-lite": (0.019, 0.075),
+    "gemini-2.5-pro": (1.25, 5.00),
+    "gemini-2.5-pro-preview": (1.25, 5.00),
+    # Default fallback used when an unknown model id is requested
+    "_default": (0.075, 0.30),
+}
+
+
+def _to_langchain_messages(messages: list[ChatMessage]) -> list:
+    """Convert our ChatMessage list to LangChain BaseMessage list.
+
+    The bridge ``invoke()`` method takes LangChain messages; we
+    keep our package's user-facing surface as plain dataclasses
+    (no LangChain dep at the public API).
+    """
+    from langchain_core.messages import (
+        AIMessage,
+        HumanMessage,
+        SystemMessage,
+    )
+
+    out: list = []
+    for m in messages:
+        if m.role == "user":
+            out.append(HumanMessage(content=m.content))
+        elif m.role == "assistant":
+            out.append(AIMessage(content=m.content))
+        elif m.role == "system":
+            out.append(SystemMessage(content=m.content))
+        else:
+            # Unknown role — let the bridge surface the error
+            out.append(HumanMessage(content=f"[{m.role}] {m.content}"))
+    return out
+
+
+def _compute_cost(
+    model: str, input_tokens: int, output_tokens: int, flex: bool
+) -> float:
+    """Per-Mtok cost using ``PRICING``. Flex applies 50% rebate."""
+    in_per_mtok, out_per_mtok = PRICING.get(model, PRICING["_default"])
+    cost = (input_tokens / 1_000_000.0) * in_per_mtok + (
+        output_tokens / 1_000_000.0
+    ) * out_per_mtok
+    if flex:
+        cost *= 0.5
+    return cost
+
+
+class GeminiAdapter:
+    """``LLMAdapter`` implementation backed by ``langgraph-genai-bridge``."""
+
+    name = "gemini"
+    default_model = "gemini-2.5-flash"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        flex: bool = True,
+    ):
+        """``api_key`` falls back to ``GEMINI_API_KEY`` env. ``flex``
+        defaults to True per OMEGA's standard production config —
+        Flex tier costs 50% less for latency-tolerant workloads."""
+        self._api_key = api_key or os.environ.get("GEMINI_API_KEY")
+        self._flex = flex
+        # Per-model bridge instances are cached so we don't re-init
+        # the SDK client for every call. Keyed by (model, flex).
+        self._bridges: dict[tuple[str, bool], object] = {}
+
+    def _get_bridge(self, model: str, flex: bool) -> object:
+        from langgraph_genai_bridge import GenAIBridge
+
+        key = (model, flex)
+        if key in self._bridges:
+            return self._bridges[key]
+        if not self._api_key:
+            raise AdapterError(
+                "GeminiAdapter requires GEMINI_API_KEY env or api_key kwarg"
+            )
+        b = GenAIBridge(api_key=self._api_key, model=model, flex=flex)
+        self._bridges[key] = b
+        return b
+
+    async def chat(
+        self,
+        messages: list[ChatMessage],
+        model: str,
+        system_prompt: Optional[str] = None,
+        json_schema: Optional[dict] = None,
+        temperature: float = 0.7,
+        max_tokens: Optional[int] = None,
+    ) -> LLMResponse:
+        """Single multi-turn completion. Calls the bridge via
+        ``asyncio.to_thread`` so the sync bridge fits in async code."""
+        # json_schema enforcement is the JSON harness's job — this
+        # method just returns text. The harness handles the parse +
+        # retry orchestration.
+        del json_schema  # not used directly here
+
+        lc_messages = _to_langchain_messages(messages)
+        bridge = self._get_bridge(model, self._flex)
+
+        start = time.monotonic()
+        try:
+            ai_message = await asyncio.to_thread(
+                bridge.invoke,
+                lc_messages,
+                system_prompt,
+            )
+        except Exception as exc:
+            duration_s = time.monotonic() - start
+            raise AdapterError(
+                f"GeminiAdapter.chat failed for model {model!r}: {exc}"
+            ) from exc
+        duration_s = time.monotonic() - start
+
+        # Extract usage from the AIMessage
+        usage = getattr(ai_message, "usage_metadata", None) or {}
+        input_tokens = int(usage.get("input_tokens", 0))
+        output_tokens = int(usage.get("output_tokens", 0))
+        cached_tokens_dict = usage.get("input_token_details", {}) or {}
+        cached_tokens = int(cached_tokens_dict.get("cache_read", 0))
+
+        cost = _compute_cost(model, input_tokens, output_tokens, self._flex)
+
+        return LLMResponse(
+            text=ai_message.content if isinstance(ai_message.content, str) else str(ai_message.content),
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_usd=cost,
+            duration_s=duration_s,
+            cached=cached_tokens > 0,
+            raw_response={
+                "cached_tokens": cached_tokens,
+                "model": model,
+                "flex": self._flex,
+            },
+        )
+
+    async def stream(
+        self,
+        messages: list[ChatMessage],
+        model: str,
+        **kwargs,
+    ) -> AsyncIterator[str]:
+        """Token-by-token streaming. Phase 1 v0.1.0 raises
+        NotImplementedError; bridge supports streaming, this adapter
+        will wire it up in v0.2.0."""
+        raise NotImplementedError(
+            "GeminiAdapter.stream is v0.2.0 stretch; use chat() for now."
+        )
+        # Unreachable, but keeps the AsyncIterator return type valid for
+        # static analysis.
+        yield ""  # pragma: no cover
+
+    def cost_per_token(self, model: str) -> tuple[float, float]:
+        """Return (input_per_mtok, output_per_mtok) USD for ``model``.
+        Flex tier rebate is applied at call time, not in this lookup."""
+        return PRICING.get(model, PRICING["_default"])