spatialagents 0.1.0__py3-none-any.whl

spatialagents/chat/static/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="referrer" content="no-referrer">
+  <title>{{TITLE}}</title>
+  <link rel="stylesheet" href="static/chat.css">
+  <!-- The page's settings: data, never run (the server's CSP allows no inline script). -->
+  <script type="application/json" id="spatialagents-settings">{{SETTINGS}}</script>
+</head>
+<body>
+  <main id="spatialagents-chat" class="sa-page"></main>
+  <script src="static/chat.js" data-global="SpatialAgentsChat"></script>
+</body>
+</html>

spatialagents/conversations.py

@@ -0,0 +1,292 @@
+"""Conversations on disk, and the service that runs their turns in the background.
+
+    <root>/<conversation_id>/
+        session.json      the record: frozen catalog and prefix, loaded tools,
+                          totals, board (SessionStore's atomic writes)
+        messages.json     the model-facing history (what the next call sends)
+        decisions.jsonl   the transcript: every event, numbered (`seq`)
+        control.json      pause / stop / approvals, written by the person's routes
+        offload/          large results, unless the product shares one root
+        .lock             the process driving it
+
+The root is the product's (Plexora's `<data_root>/.agent/ai/conversations/`,
+SCIMAP Pro's `<configDir>/ai-sessions/<id>/conversation/`).
+
+`ConversationStore` is a `SessionStore` of kind `chat` rooted there, plus the
+messages and the numbered transcript. `ChatService` is the process's one
+driver: `send` starts a turn on a thread and returns at once; `events(after,
+wait_s)` is a held poll over the transcript (what an SSE route and a poll
+fallback both read); `control` and `approve` write `control.json`, which the
+running turn reads before its next call. The service is given what a product
+binds -- a gateway factory, a backend factory, the profile, the cache and the
+trace -- and the product's surfaces (Plexora's `ai.chat_*` capabilities and
+Flask routes, a terminal loop) call it.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+
+from spatialagents.errors import AgentError
+from spatialagents.sessions import SessionStore, atomic_write
+
+#: Events of a turn that are not kept in the transcript once the turn is over:
+#: the deltas are replaced by the turn's `text` events.
+TRANSIENT = ("text_delta",)
+MAX_WAIT_S = 25.0
+
+
+class ConversationStore(SessionStore):
+    def __init__(self, root: Path | str):
+        super().__init__("chat", Path(root))
+        self._seq: dict = {}
+        self._live: dict = {}
+        self._cond = threading.Condition()
+
+    # -- messages ---------------------------------------------------------------
+
+    def save_messages(self, conversation_id: str, messages: list) -> None:
+        atomic_write(self.folder(conversation_id) / "messages.json",
+                json.dumps(messages, ensure_ascii=False, separators=(",", ":")))
+
+    def load_messages(self, conversation_id: str) -> list:
+        path = self.folder(conversation_id) / "messages.json"
+        if not path.is_file():
+            return []
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return []
+
+    # -- the transcript -----------------------------------------------------------
+
+    def _next_seq(self, conversation_id: str) -> int:
+        if conversation_id not in self._seq:
+            events = self.decisions(conversation_id)
+            self._seq[conversation_id] = max((int(e.get("seq") or 0) for e in events), default=0)
+        self._seq[conversation_id] += 1
+        return self._seq[conversation_id]
+
+    def append_event(self, conversation_id: str, event: dict) -> dict:
+        with self._cond:
+            numbered = {"seq": self._next_seq(conversation_id), "at": time.time(), **event}
+            if event.get("event") not in TRANSIENT:
+                self.log(conversation_id, numbered)
+                if event.get("event") == "turn_finished":
+                    # The turn's `text` events carry what its deltas spelled.
+                    self._live.pop(conversation_id, None)
+            else:
+                self._live.setdefault(conversation_id, []).append(numbered)
+                del self._live[conversation_id][:-2000]
+            self._cond.notify_all()
+        return numbered
+
+    def events(self, conversation_id: str, after: int = 0, *, wait_s: float = 0.0, still=None) -> list:
+        """Events with `seq > after`, oldest first; waits up to `wait_s` for one
+        while `still()` (default: always) says it is worth waiting."""
+        deadline = time.monotonic() + max(0.0, min(float(wait_s or 0), MAX_WAIT_S))
+        with self._cond:
+            while True:
+                kept = [e for e in self.decisions(conversation_id) if int(e.get("seq") or 0) > after]
+                live = [e for e in self._live.get(conversation_id, []) if int(e["seq"]) > after]
+                found = sorted(kept + live, key=lambda e: e["seq"])
+                remaining = deadline - time.monotonic()
+                if found or remaining <= 0 or (still is not None and not still()):
+                    return found
+                self._cond.wait(min(remaining, 1.0))
+
+    def last_seq(self, conversation_id: str) -> int:
+        with self._cond:
+            if conversation_id not in self._seq:
+                self._next_seq(conversation_id)
+                self._seq[conversation_id] -= 1
+            return self._seq[conversation_id]
+
+
+class ChatService:
+    """Every conversation this process drives.
+
+    `gateway_factory()` gives the gateway client a conversation calls through
+    (the product's, on its token source); `backend_factory()` the product's
+    `ToolBackend`. `profile`, `cache`, `trace` and `offload_root` are handed to
+    every runner, and `runner_options` (poll interval, model, step bounds) as
+    well. A product subclasses to supply its defaults lazily."""
+
+    def __init__(self, store: ConversationStore, *, gateway_factory, backend_factory, profile=None,
+                 cache=None, trace=None, offload_root=None, runner_options: dict | None = None):
+        self.store = store
+        self.gateway_factory = gateway_factory
+        self.backend_factory = backend_factory
+        self.profile = profile
+        self.cache = cache
+        self.trace = trace
+        self.offload_root = offload_root
+        self.runner_options = dict(runner_options or {})
+        self._runners: dict = {}
+        self._threads: dict = {}
+        self._lock = threading.Lock()
+
+    # -- what every runner is given (a product overrides these for its defaults) -----------
+
+    def _cache(self):
+        return self.cache
+
+    def _trace(self):
+        return self.trace
+
+    def _runner_class(self):
+        from spatialagents.runner import AgentRunner
+
+        return AgentRunner
+
+    def _options(self) -> dict:
+        return {"cache": self._cache(), "trace": self._trace(), "profile": self.profile,
+                "offload_root": self.offload_root, **self.runner_options}
+
+    # -- conversations ---------------------------------------------------------------
+
+    def start(self, policy, *, title: str | None = None, viewer: bool = False) -> dict:
+        runner = self._runner_class().create(self.store, gateway=self.gateway_factory(), policy=policy,
+                                             backend=self.backend_factory(), title=title, viewer=viewer,
+                                             **self._options())
+        with self._lock:
+            self._runners[runner.conversation_id] = runner
+        record = runner.record
+        self.store.append_event(runner.conversation_id, {"event": "disclosure", "text": record["disclosure"]})
+        return self.describe(runner.conversation_id)
+
+    def runner(self, conversation_id: str, policy=None):
+        with self._lock:
+            runner = self._runners.get(conversation_id)
+        if runner is None:
+            if not self.store.exists(conversation_id):
+                raise AgentError("invalid_input", f"no conversation {conversation_id!r}",
+                                 detail={"hint": "ai_chat_history lists the conversations"})
+            self.store.claim(conversation_id)
+            runner = self._runner_class().open(self.store, conversation_id, gateway=self.gateway_factory(),
+                                               backend=self.backend_factory(), **self._options())
+            with self._lock:
+                runner = self._runners.setdefault(conversation_id, runner)
+        if policy is not None:
+            runner.policy = policy
+        return runner
+
+    def running(self, conversation_id: str) -> bool:
+        with self._lock:
+            thread = self._threads.get(conversation_id)
+        return bool(thread and thread.is_alive())
+
+    def send(self, conversation_id: str, text: str, images=(), *, policy=None) -> dict:
+        runner = self.runner(conversation_id, policy)
+        with self._lock:
+            thread = self._threads.get(conversation_id)
+            if thread and thread.is_alive():
+                raise AgentError("conflict", "this conversation is still answering the last message",
+                                 detail={"hint": "wait for its done event, or stop it"}, retryable=True)
+            after = self.store.last_seq(conversation_id)
+            self.store.append_event(conversation_id, {"event": "user_message", "text": text,
+                                                      "images": len(images or ())})
+
+            def work():
+                try:
+                    runner.run_turn(text, images, lambda e: self.store.append_event(conversation_id, e))
+                except Exception as exc:        # noqa: BLE001 -- the transcript says why
+                    self.store.append_event(conversation_id, {"event": "error", "code": "internal_error",
+                                                              "message": f"{type(exc).__name__}: {exc}"})
+                finally:
+                    self.store.append_event(conversation_id, {"event": "turn_finished",
+                                                              "state": (runner.record or {}).get("state")})
+
+            thread = threading.Thread(target=work, name=f"spatialagents-chat-{conversation_id}", daemon=True)
+            self._threads[conversation_id] = thread
+            thread.start()
+        return {"conversation_id": conversation_id, "after": after, "running": True}
+
+    def note(self, conversation_id: str, text: str) -> None:
+        """Something the user did outside the conversation (an Undo chip) that the
+        model reads at the start of its next turn."""
+        with self.store.lock(conversation_id):
+            record = self.store.load(conversation_id)
+            record.setdefault("notes", []).append(text)
+            self.store.save(record)
+        with self._lock:
+            runner = self._runners.get(conversation_id)
+        if runner is not None and runner.record is not None:
+            runner.record.setdefault("notes", [])
+            if text not in runner.record["notes"]:
+                runner.record["notes"].append(text)
+
+    def wait(self, conversation_id: str, timeout: float | None = None) -> bool:
+        with self._lock:
+            thread = self._threads.get(conversation_id)
+        if thread is None:
+            return True
+        thread.join(timeout)
+        return not thread.is_alive()
+
+    def events(self, conversation_id: str, after: int = 0, wait_s: float = 0.0) -> dict:
+        if not self.store.exists(conversation_id):
+            raise AgentError("invalid_input", f"no conversation {conversation_id!r}")
+        found = self.store.events(conversation_id, after, wait_s=wait_s,
+                                  still=lambda: self.running(conversation_id) or wait_s > 0)
+        return {"conversation_id": conversation_id, "events": found,
+                "after": found[-1]["seq"] if found else after, "running": self.running(conversation_id),
+                "control": _public_control(self.store.control(conversation_id))}
+
+    def control(self, conversation_id: str, action: str) -> dict:
+        if not self.store.exists(conversation_id):
+            raise AgentError("invalid_input", f"no conversation {conversation_id!r}")
+        if action == "pause":
+            control = self.store.set_control(conversation_id, paused=True, paused_by="viewer")
+        elif action == "resume":
+            control = self.store.set_control(conversation_id, paused=False, paused_by=None)
+        elif action == "stop":
+            from spatialagents.runner import now_iso
+
+            control = self.store.set_control(conversation_id, stopped=True, stopped_by="viewer",
+                                             stopped_at=now_iso(), paused=False)
+        else:
+            raise AgentError("invalid_input", f"unknown action {action!r}; pause, resume or stop")
+        self.store.append_event(conversation_id, {"event": "control", "action": action})
+        return _public_control(control)
+
+    def approve(self, conversation_id: str, approval_id: str, approve: bool, *, by: str = "viewer") -> dict:
+        from spatialagents.approvals import decide
+
+        if not self.store.exists(conversation_id):
+            raise AgentError("invalid_input", f"no conversation {conversation_id!r}")
+        return decide(self.store, conversation_id, approval_id, approve, by=by)
+
+    def describe(self, conversation_id: str) -> dict:
+        record = self.store.load(conversation_id)
+        return {"conversation_id": conversation_id, "title": record.get("title") or "",
+                "state": record.get("state"), "created_at": record.get("created_at"),
+                "turns": record.get("turns", 0), "tools": len(record.get("catalog") or []),
+                "loaded_tools": record.get("loaded") or [], "prefix_fingerprint": record.get("prefix_fp"),
+                "charged_micro": record.get("charged_micro", 0),
+                "charged_credits": round(int(record.get("charged_micro") or 0) / 10_000, 2),
+                "usage": record.get("usage") or {}, "disclosure": record.get("disclosure"),
+                "running": self.running(conversation_id),
+                "control": _public_control(self.store.control(conversation_id))}
+
+    def history(self, conversation_id: str | None = None, *, after: int = 0, limit: int = 500,
+                wait_s: float = 0.0) -> dict:
+        if conversation_id is None:
+            return {"conversations": [
+                {k: r.get(k) for k in ("session_id", "title", "state", "created_at", "turns", "charged_micro")}
+                for r in self.store.list(limit=limit)]}
+        out = self.describe(conversation_id)
+        polled = self.events(conversation_id, after, wait_s)
+        out.update(events=polled["events"][-limit:], after=polled["after"])
+        return out
+
+
+def _public_control(control: dict) -> dict:
+    approvals = control.get("approvals") or {}
+    return {"paused": bool(control.get("paused")), "paused_by": control.get("paused_by"),
+            "stopped": bool(control.get("stopped")), "reason": control.get("reason"),
+            "pending_approvals": [a for a in approvals.values() if a.get("status") == "pending"]}
+

spatialagents/errors.py

@@ -0,0 +1,73 @@
+"""The one shape a failure reaches an agent in.
+
+An agent cannot read a traceback the way a person reads a dialog, and it should
+not have to: every failure is a `code` it can branch on, a `message` it can
+repeat to the user, a `detail` with whatever makes the failure actionable (the
+requirements a dataset is missing, the revision somebody else wrote, the
+session another process holds), and whether trying again could help.
+
+The codes are a closed list, so an agent's instructions (a product's skills)
+can name them and mean something. `CODES` are the ones every product shares
+and this package raises itself; a product adds its own once, at import, with
+`register` (Plexora's `unknown_project`, `viewer_not_available`, ...), and
+`AgentError` refuses any code nobody registered.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+#: Every product's codes. Each is a failure an agent can act on.
+CODES = (
+    "unknown_capability",
+    "invalid_input",
+    "precondition_missing",
+    "resource_unavailable",
+    "permission_required",
+    # A paid capability on a licence that does not unlock it. `detail` names
+    # the entitlement and the plan that unlocks it. Not retryable: a licence is
+    # not something trying again fixes.
+    "license_required",
+    "conflict",
+    "capability_unavailable",
+    "too_large",
+    "internal_error",
+)
+
+_KNOWN: dict[str, None] = dict.fromkeys(CODES)
+_GUARD = threading.Lock()
+
+
+def register(*codes: str) -> tuple:
+    """Add a product's codes to the closed list (idempotent); returns every
+    code now known, the shared ones first."""
+    with _GUARD:
+        for code in codes:
+            if not isinstance(code, str) or not code.replace("_", "").isalnum() or code != code.lower():
+                raise ValueError(f"an agent error code is lower snake case, not {code!r}")
+            _KNOWN.setdefault(code, None)
+        return tuple(_KNOWN)
+
+
+def known() -> tuple:
+    """Every code an `AgentError` may carry: the shared ones and every product's."""
+    return tuple(_KNOWN)
+
+
+class AgentError(Exception):
+    """A failure with a code an agent can act on."""
+
+    def __init__(self, code: str, message: str, *, detail: Any = None,
+                 retryable: bool = False):
+        if code not in _KNOWN:
+            raise ValueError(f"unknown agent error code {code!r}")
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.detail = detail
+        self.retryable = retryable
+
+    def to_problem(self) -> dict:
+        return {"code": self.code, "message": self.message,
+                "detail": self.detail, "retryable": self.retryable}

spatialagents/gateway.py

@@ -0,0 +1,192 @@
+"""Talking to the BioCognia AI gateway: the harness's model call.
+
+The transport is the shared BioCognia client's (`biocognia.gateway`): the
+30-minute `BIOCAI1` token obtained against the device's certificate, the
+gateway URL, one token refresh, server-sent event parsing, and the account
+endpoints (balance, usage, pricing, runs). The product injects its token
+source -- `biocognia.gateway.TokenSource(<its LICENSING>)` -- and nothing here
+ever reads a licence or writes a token source of its own. What is here is
+what belongs to the harness: `messages()` -- one streamed call, its retries,
+and reading Anthropic-shaped events between `biocognia.accepted` and
+`biocognia.usage` into a `ModelResponse` -- and naming the call's task on the
+wire as `<product>.<module>.<task>` (`wire_task`), the product being the one
+the token source's licence is for.
+
+`BIOCOGNIA_AI_TOKEN` supplies a token directly (a CI job, a test);
+`BIOCOGNIA_AI_GATEWAY` overrides the gateway's address; `BIOCOGNIA_AI_DEV=1`
+(or `dev=True`) uses the dev route, which only internal testing accounts may
+call and which bills at provider cost. `BIOCOGNIA_OFFLINE=1` refuses before
+any socket opens.
+
+Retries: a refusal that happened before anything reached a provider (rate
+limit, provider outage, unreachable gateway) is retried with the SAME
+idempotency key, which the gateway frees in exactly those cases; an expired
+token is refreshed once. Credit, cap and envelope refusals are never retried:
+they are surfaced so the run or conversation can pause (`PAUSE_CODES`).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+from biocognia import codes as _codes
+from biocognia import gateway as _shared
+from biocognia.gateway import (ENV_DEV, ENV_GATEWAY, ENV_TOKEN, RETRYABLE, GatewayError, TokenSource, dev_default,
+                               gateway_url, iter_sse)
+
+from spatialagents import wire
+from spatialagents.wire import ModelRequest, ModelResponse, Usage
+
+#: Tries in all for a provider whose circuit is open: it is down for a known
+#: while (`retry_after`), so waiting that out once is worth it and six blind
+#: tries are not -- the run pauses instead (PAUSE_CODES). The gateway says so
+#: as `provider_unavailable` with `details.failure: circuit_open`.
+CIRCUIT_ATTEMPTS = 2
+CALL_TIMEOUT = 300
+
+#: Refusals that pause the run or conversation for the person instead of
+#: failing it: the platform's (`biocognia.codes.PAUSE_CODES` -- credits, the
+#: organisation's, member's and product's monthly caps, the run's envelope, AI
+#: switched off or not licensed), and the harness's own -- a provider still
+#: down after its retries, a closed run, the dev route refused, no licence on
+#: this device, offline.
+PAUSE_CODES = (*_codes.PAUSE_CODES, "run_closed", "provider_unavailable", "circuit_open",
+               "provider_rate_limited", "dev_not_allowed", "no_license", "offline_refused")
+#: The pauses that money or a raised cap answers ("add credits, then resume").
+CREDIT_CODES = _codes.CREDIT_CODES
+
+__all__ = ["CALL_TIMEOUT", "CIRCUIT_ATTEMPTS", "CREDIT_CODES", "ENV_DEV", "ENV_GATEWAY", "ENV_TOKEN",
+           "PAUSE_CODES", "RETRYABLE", "GatewayClient", "GatewayError", "TokenSource", "dev_default",
+           "gateway_url", "iter_sse"]
+
+
+class GatewayClient(_shared.GatewayClient):
+    """The shared transport, plus the harness's streamed model call.
+
+    `tokens` is the product's `biocognia.gateway.TokenSource`; its licence's
+    product names every task this client sends, unless `product` says
+    otherwise."""
+
+    def __init__(self, tokens: TokenSource, base_url: str | None = None, *, dev: bool | None = None,
+                 max_attempts: int = 6, sleep=time.sleep, product: str | None = None):
+        super().__init__(tokens, base_url or None, dev=dev)
+        self.max_attempts = max_attempts
+        self._sleep = sleep
+        self._product = product
+
+    @property
+    def product(self) -> str:
+        """The product key every task is filed under on the gateway (the certificate's `aud`)."""
+        return self._product or self.tokens.licensing.product.id
+
+    def wire_task(self, task: str | None, *, module: str | None = None) -> str:
+        """`request.task` as the gateway knows it: `<product>.<module>.<task>`
+        (`wire.task_id`). A product with its own task registry overrides this
+        to use it."""
+        return wire.task_id(self.product, task, module=module)
+
+    # -- calls ---------------------------------------------------------------------
+
+    def messages(self, request: ModelRequest, *, idempotency_key: str, on_delta=None,
+                 on_retry=None) -> ModelResponse:
+        """One streamed call. `on_delta(text)` is called with each text delta as
+        it arrives (a retried call may repeat the deltas of a cut stream);
+        `on_retry(attempt, error)` before each retry. The response's
+        `attempts` says how many tries it took."""
+        path = "/v1/ai/dev/messages" if self.dev else "/v1/ai/messages"
+        module = (request.context or {}).get("feature")
+        body = request.envelope(self.wire_task(request.task, module=module))
+        if not self.dev:
+            body.pop("model", None)
+        delay = 2.0
+        for attempt in range(1, self.max_attempts + 1):
+            started = time.monotonic()
+            try:
+                with self.open("POST", path, body, {"Idempotency-Key": idempotency_key},
+                               timeout=CALL_TIMEOUT) as response:
+                    result = self._read_stream(response, on_delta)
+                result.latency_ms = int((time.monotonic() - started) * 1000)
+                result.attempts = attempt
+                return result
+            except GatewayError as exc:
+                limit = min(self.max_attempts, CIRCUIT_ATTEMPTS) if exc.circuit_open else self.max_attempts
+                if not exc.retryable or attempt >= limit:
+                    raise
+                if on_retry is not None:
+                    on_retry(attempt, exc)
+                self._sleep(min(exc.retry_after or delay, 120.0))
+                delay = min(delay * 3, 120.0)
+        raise AssertionError("unreachable")
+
+    def _read_stream(self, response, on_delta=None) -> ModelResponse:
+        text: list[str] = []
+        blocks: dict[int, dict] = {}
+        partial: dict[int, list[str]] = {}
+        usage_event: dict = {}
+        accepted: dict = {}
+        stop = None
+        for event, data in iter_sse(response):
+            try:
+                payload = json.loads(data)
+            except ValueError:
+                continue
+            if event == "biocognia.accepted":
+                accepted = payload
+            elif event == "biocognia.usage":
+                usage_event = payload
+            elif event == "biocognia.error":
+                raise GatewayError("The gateway stopped mid-answer.", code=payload.get("code", "interrupted"),
+                                   detail=payload)
+            elif event == "content_block_start":
+                block = dict(payload.get("content_block") or {})
+                index = int(payload.get("index") or 0)
+                if block.get("type") == "text":
+                    blocks[index] = {"type": "text", "text": block.get("text") or ""}
+                elif block.get("type") == "tool_use":
+                    blocks[index] = {"type": "tool_use", "id": block.get("id"), "name": block.get("name"),
+                                     "input": block.get("input") or {}}
+                    partial[index] = []
+            elif event == "content_block_delta":
+                delta = payload.get("delta") or {}
+                index = int(payload.get("index") or 0)
+                if delta.get("type") == "text_delta":
+                    piece = delta.get("text", "")
+                    text.append(piece)
+                    if index in blocks and blocks[index]["type"] == "text":
+                        blocks[index]["text"] += piece
+                    elif index not in blocks:
+                        blocks[index] = {"type": "text", "text": piece}
+                    if on_delta is not None and piece:
+                        on_delta(piece)
+                elif delta.get("type") == "input_json_delta" and index in partial:
+                    partial[index].append(delta.get("partial_json") or "")
+            elif event == "content_block_stop":
+                index = int(payload.get("index") or 0)
+                if index in partial:
+                    raw = "".join(partial.pop(index))
+                    try:
+                        blocks[index]["input"] = json.loads(raw) if raw.strip() else blocks[index]["input"]
+                    except ValueError:
+                        blocks[index]["input"] = {"_unparsed": raw}
+            elif event == "message_delta":
+                stop = (payload.get("delta") or {}).get("stop_reason") or stop
+            elif event == "error":
+                raise GatewayError("The model provider failed mid-answer.", code="provider_unavailable",
+                                   detail=payload)
+        if not usage_event:
+            raise GatewayError("The answer ended before the gateway settled it.", code="interrupted")
+        for index, raw in partial.items():           # a stream without content_block_stop
+            try:
+                blocks[index]["input"] = json.loads("".join(raw) or "{}")
+            except ValueError:
+                blocks[index]["input"] = {"_unparsed": "".join(raw)}
+        return ModelResponse(
+            blocks=[blocks[i] for i in sorted(blocks) if blocks[i]["type"] != "text" or blocks[i]["text"]],
+            text="".join(text), stop_reason=stop, usage=Usage.of(usage_event.get("usage")),
+            gateway_request_id=usage_event.get("gateway_request_id") or accepted.get("gateway_request_id"),
+            status=usage_event.get("status", "ok"), price_micro=int(usage_event.get("price_micro") or 0),
+            charged_micro=int(usage_event.get("charged_micro") or 0), cost_micro=usage_event.get("cost_micro"),
+            billing=usage_event.get("billing", "credits"), model=usage_event.get("model") or accepted.get("model"),
+            provider=usage_event.get("provider") or accepted.get("provider"),
+            balance=usage_event.get("balance") or {}, run=usage_event.get("run"))

spatialagents/offload.py

@@ -0,0 +1,92 @@
+"""Offloading large tool results: the model sees a stub, and asks for slices.
+
+A tool result above `threshold_tokens` (4k by default) is stored, content-
+addressed, as `<root>/<id>.txt` -- the root is the product's (Plexora shares
+one across conversations, SCIMAP Pro keeps one per session) -- and the model is
+given `{artifact_id, kind, head, tail, size}` instead -- the first and last
+few hundred characters, and how big the whole is. `read_artifact(id, range |
+query)` (a local tool in chat mode) returns a character range or the lines
+that match a query. Context stays small; nothing is lost; and the same result
+offloaded twice is stored once and has the same id.
+
+The stored text is JSON indented one space per level, so a query matches a
+line that means something (`"marker": "CD45"`) rather than the whole answer.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import threading
+from pathlib import Path
+
+from spatialagents import serialize
+
+CHARS_PER_TOKEN = 3.5
+ID_PATTERN = re.compile(r"^off_[0-9a-f]{20}$")
+HEAD_CHARS = 1200
+TAIL_CHARS = 600
+#: Characters one `read_artifact` slice returns at most.
+MAX_SLICE = 12_000
+MAX_MATCHES = 80
+#: The largest text stored at all (a bigger answer is cut, and says so).
+MAX_STORED = 8 * 1024 * 1024
+
+
+def _text(result) -> str:
+    return serialize.indented(result)
+
+
+def tokens(text: str) -> int:
+    return int(len(text) / CHARS_PER_TOKEN)
+
+
+def offload(result, threshold_tokens: int = 4000, *, root: Path | str, kind: str = "tool_result") -> dict | None:
+    """The stub for `result` when it is larger than `threshold_tokens`, after
+    storing it under `root`; None when it is small enough to send as it is.
+    `result` is text or JSON-able data (a backend's `serialize` output)."""
+    text = _text(result)
+    if tokens(text) <= threshold_tokens:
+        return None
+    cut = len(text) > MAX_STORED
+    if cut:
+        text = text[:MAX_STORED]
+    artifact_id = "off_" + hashlib.sha256(text.encode("utf-8")).hexdigest()[:20]
+    folder = Path(root)
+    path = folder / f"{artifact_id}.txt"
+    if not path.exists():
+        folder.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(f"{path.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+        tmp.write_text(text, encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+    stub = {"offloaded": True, "artifact_id": artifact_id, "kind": kind, "size": len(text),
+            "tokens": tokens(text), "lines": text.count("\n") + 1,
+            "head": text[:HEAD_CHARS], "tail": text[-TAIL_CHARS:],
+            "hint": "read_artifact with this artifact_id and a character range, or a query, "
+                    "returns the parts you need"}
+    if cut:
+        stub["truncated_at"] = MAX_STORED
+    return stub
+
+
+def read_artifact(artifact_id: str, *, root: Path | str, start: int | None = None, end: int | None = None,
+                  query: str | None = None) -> dict:
+    """A slice of an offloaded result: characters [start, end), or the lines
+    that contain `query` (case-insensitive) with their line numbers."""
+    if not ID_PATTERN.match(str(artifact_id)):
+        raise KeyError(f"not an offloaded artifact id: {artifact_id!r}")
+    path = Path(root) / f"{artifact_id}.txt"
+    if not path.is_file():
+        raise KeyError(f"no offloaded artifact {artifact_id!r}")
+    text = path.read_text(encoding="utf-8")
+    if query:
+        needle = str(query).lower()
+        matches = [{"line": n + 1, "text": line[:400]}
+                   for n, line in enumerate(text.splitlines()) if needle in line.lower()]
+        return {"artifact_id": artifact_id, "query": query, "matches": matches[:MAX_MATCHES],
+                "n_matches": len(matches), "truncated": len(matches) > MAX_MATCHES}
+    lo = max(0, int(start or 0))
+    hi = min(len(text), int(end) if end is not None else lo + MAX_SLICE, lo + MAX_SLICE)
+    return {"artifact_id": artifact_id, "start": lo, "end": hi, "size": len(text),
+            "text": text[lo:hi], "more": hi < len(text)}