aid-runtime-python 0.1.39__py3-none-any.whl

aid_runtime/types.py

@@ -0,0 +1,332 @@
+"""Data shapes shared across the runtime.
+
+These are deliberately plain validated records: everything that crosses a process
+boundary (a provider response, a tool call, an eval baseline) is a Pydantic model
+so it round-trips through JSON without a bespoke encoder.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+__all__ = [
+    "Capability",
+    "CompletionRequest",
+    "CompletionResponse",
+    "CostProfile",
+    "FinishReason",
+    "GenerationResult",
+    "Message",
+    "ModelCacheConfig",
+    "ModelSpec",
+    "PinnedModel",
+    "Role",
+    "SemanticCacheConfig",
+    "StreamChunk",
+    "TokenUsage",
+    "ToolCall",
+    "ToolDefinition",
+    "ToolResult",
+]
+
+Role = Literal["system", "user", "assistant", "tool"]
+FinishReason = Literal["stop", "length", "tool-calls", "content-filter", "error"]
+
+
+class Capability(StrEnum):
+    """Capabilities a *model* can be negotiated against.
+
+    These are the model-side vocabulary. The IR's capability set
+    (``http-trigger``, ``json-schema``, ``otel``, ``streaming``, ``tool-calling``,
+    ``cursor-memory``) is a target-side vocabulary; the generator maps one to the
+    other. ``STREAMING`` is served: an adapter that advertises it also implements
+    :meth:`~aid_runtime.providers.Provider.stream`. ``EMBEDDINGS`` and
+    ``RERANK`` are likewise model-side: the IR's ``MODEL_CAPABILITIES`` already
+    admits both for embedding and rerank models, so declaring them here is what
+    lets a model be negotiated against a retrieval binding at all.
+    """
+
+    TOOL_CALLING = "tool-calling"
+    STRUCTURED_OUTPUT = "structured-output"
+    STREAMING = "streaming"
+    LONG_CONTEXT = "long-context"
+    EMBEDDINGS = "embeddings"
+    RERANK = "rerank"
+
+
+class ToolCall(BaseModel):
+    """A model's request to invoke a tool."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class Message(BaseModel):
+    """One turn of a chat transcript.
+
+    ``tool_calls`` on an assistant turn and ``tool_call_id`` on a tool turn are what
+    make a multi-step tool loop replayable: without them the next request would carry
+    an observation the provider cannot attribute to the call that produced it.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    role: Role
+    content: str
+    tool_calls: tuple[ToolCall, ...] = ()
+    tool_call_id: str | None = None
+    name: str | None = None
+
+    @classmethod
+    def system(cls, content: str) -> Message:
+        return cls(role="system", content=content)
+
+    @classmethod
+    def user(cls, content: str) -> Message:
+        return cls(role="user", content=content)
+
+    @classmethod
+    def assistant(cls, content: str) -> Message:
+        return cls(role="assistant", content=content)
+
+    @classmethod
+    def assistant_tool_calls(cls, content: str, tool_calls: Sequence[ToolCall]) -> Message:
+        return cls(role="assistant", content=content, tool_calls=tuple(tool_calls))
+
+    @classmethod
+    def tool(cls, call_id: str, content: str, *, name: str | None = None) -> Message:
+        return cls(role="tool", content=content, tool_call_id=call_id, name=name)
+
+
+class CostProfile(BaseModel):
+    """Published price for a pinned model, in USD per 1,000 tokens."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    input_per_1k_usd: float = Field(ge=0.0)
+    output_per_1k_usd: float = Field(ge=0.0)
+
+    def cost_usd(self, usage: TokenUsage) -> float:
+        raw = (
+            usage.input_tokens * self.input_per_1k_usd
+            + usage.output_tokens * self.output_per_1k_usd
+        ) / 1000.0
+        return round(raw, 6)
+
+
+class SemanticCacheConfig(BaseModel):
+    """Opt-in semantic reuse: an explicit threshold and TTL, with no defaults."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    threshold: float = Field(ge=0.0, le=1.0)
+    ttl_seconds: int = Field(gt=0)
+
+
+class ModelCacheConfig(BaseModel):
+    """Per-model cache policy carried by ``models[].cache`` (spec v0.3)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    prompt: bool = False
+    semantic: SemanticCacheConfig | None = None
+
+
+class ModelSpec(BaseModel):
+    """A *pinned* model: an exact provider model id, never a floating alias.
+
+    Pinning is the whole point of the alias table. ``name`` must be the
+    provider's immutable snapshot id (``gpt-4o-mini-2024-07-18``), because a
+    floating ``gpt-4o-mini`` silently changes behaviour under a stored eval
+    baseline and turns a real regression into a mystery.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str = Field(min_length=1)
+    provider: str = Field(min_length=1)
+    cost: CostProfile
+    context_window: int = Field(gt=0)
+    max_output_tokens: int = Field(gt=0)
+    capabilities: frozenset[Capability] = frozenset()
+    cache: ModelCacheConfig | None = None
+
+    @field_validator("capabilities", mode="before")
+    @classmethod
+    def _coerce_capabilities(cls, value: Any) -> Any:
+        if isinstance(value, (set, frozenset)):
+            return frozenset(Capability(v) for v in value)
+        return value
+
+
+class PinnedModel(BaseModel):
+    """An alias resolved against the pinned table, with its adapter attached."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
+
+    alias: str = Field(min_length=1)
+    spec: ModelSpec
+
+    @property
+    def provider(self) -> str:
+        return self.spec.provider
+
+    @property
+    def capabilities(self) -> frozenset[Capability]:
+        return self.spec.capabilities
+
+    def supports(self, capabilities: frozenset[Capability]) -> bool:
+        return capabilities <= self.spec.capabilities
+
+
+class TokenUsage(BaseModel):
+    """Token accounting for a single model call."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    input_tokens: int = Field(ge=0)
+    output_tokens: int = Field(ge=0)
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+    def __add__(self, other: TokenUsage) -> TokenUsage:
+        return TokenUsage(
+            input_tokens=self.input_tokens + other.input_tokens,
+            output_tokens=self.output_tokens + other.output_tokens,
+        )
+
+
+class ToolDefinition(BaseModel):
+    """A tool as the model sees it: name, description, JSON Schema parameters."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    name: str = Field(min_length=1)
+    description: str = ""
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+    def as_openai_tool(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters or {"type": "object", "properties": {}},
+            },
+        }
+
+
+class ToolResult(BaseModel):
+    """The outcome of executing a :class:`ToolCall`."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    call_id: str
+    name: str
+    content: str
+    is_error: bool = False
+
+    @classmethod
+    def from_value(cls, call: ToolCall, value: Any) -> ToolResult:
+        content = (
+            value if isinstance(value, str) else json.dumps(value, sort_keys=True, default=str)
+        )
+        return cls(call_id=call.id, name=call.name, content=content)
+
+    @classmethod
+    def from_error(cls, call: ToolCall, message: str) -> ToolResult:
+        return cls(call_id=call.id, name=call.name, content=message, is_error=True)
+
+
+class CompletionRequest(BaseModel):
+    """A single model call.
+
+    It may be served request/response (:meth:`ModelGateway.generate`) or as an SSE
+    byte stream (:meth:`ModelGateway.stream`). The same request shape feeds both.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    messages: tuple[Message, ...] = Field(min_length=1)
+    temperature: float | None = Field(default=None, ge=0.0, le=2.0)
+    max_output_tokens: int | None = Field(default=None, gt=0)
+    tools: tuple[ToolDefinition, ...] = ()
+    stop: tuple[str, ...] = ()
+    metadata: dict[str, str] = Field(default_factory=dict)
+
+    @classmethod
+    def prompt(cls, text: str, *, system: str | None = None) -> CompletionRequest:
+        messages = []
+        if system is not None:
+            messages.append(Message.system(system))
+        messages.append(Message.user(text))
+        return cls(messages=tuple(messages))
+
+    def fingerprint(self) -> str:
+        """Stable hash of everything that can change the model's output."""
+        payload = self.model_dump(mode="json", exclude_none=True)
+        blob = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+class CompletionResponse(BaseModel):
+    """A provider response plus the accounting needed to charge for it."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    text: str
+    model: str
+    provider: str
+    usage: TokenUsage
+    tool_calls: tuple[ToolCall, ...] = ()
+    finish_reason: FinishReason = "stop"
+
+
+class StreamChunk(BaseModel):
+    """One increment of a streamed completion.
+
+    ``delta`` is the new text since the previous chunk. The terminal chunk carries
+    ``finish_reason`` and ``usage`` so the gateway can account for the call exactly
+    as :meth:`ModelGateway.generate` does.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    delta: str = ""
+    finish_reason: FinishReason | None = None
+    usage: TokenUsage | None = None
+
+
+class GenerationResult(BaseModel):
+    """What the gateway returns: the response, what it cost, and how it got there."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    response: CompletionResponse
+    alias: str
+    cost_usd: float = Field(ge=0.0)
+    attempts: tuple[str, ...] = ()
+    cache_hit: bool = False
+
+    @property
+    def text(self) -> str:
+        return self.response.text
+
+    @property
+    def usage(self) -> TokenUsage:
+        return self.response.usage
+
+    @property
+    def fell_back(self) -> bool:
+        return len(self.attempts) > 1

aid_runtime_python-0.1.39.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: aid-runtime-python
+Version: 0.1.39
+Summary: The AID Framework Python runtime: model gateway with pinning and cost budgets, prompt registry, tool executor, OTel GenAI tracing, plain-async pipeline, and an eval harness that gates on statistical regression against a stored baseline.
+Author: The AID Framework authors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/aid-framework/aid-framework
+Project-URL: Documentation, https://github.com/aid-framework/aid-framework/blob/main/docs/design.md
+Project-URL: Issues, https://github.com/aid-framework/aid-framework/issues
+Keywords: ai,codegen,llm,evals,opentelemetry,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: opentelemetry-api<2,>=1.24
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pydantic-ai-slim<3,>=2
+Provides-Extra: pgvector
+Requires-Dist: psycopg[binary]<4,>=3.1; extra == "pgvector"
+Provides-Extra: deepagents
+Requires-Dist: deepagents==0.7.32; extra == "deepagents"
+Provides-Extra: dev
+Requires-Dist: mypy<3,>=1.11; extra == "dev"
+Requires-Dist: opentelemetry-sdk<2,>=1.24; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == "dev"
+Requires-Dist: ruff<1,>=0.6; extra == "dev"
+
+# AID runtime — Python
+
+The Python runtime library: the behavior layer imported by apps generated by the
+[`py-fastapi`](../../packages/generators/py-fastapi/) generator. Generated code is thin glue; this is where
+the behavior lives ([`docs/design.md` §4](../../docs/design.md), principle 1).
+
+Distribution name **`aid-runtime-python`**, import package **`aid_runtime`**. The two differ deliberately: a
+distribution name is conventionally hyphenated, and a Python import package cannot be. That asymmetry is
+asserted in `tests/test_package.py` so it cannot drift.
+
+Requires Python 3.11+.
+
+```sh
+pip install -e ".[dev]"        # the runtime plus its test/lint/type tooling
+pytest -q
+pip install -e ".[pgvector]"   # only if you want the pgvector store adapter
+```
+
+## What it provides
+
+| Module | Provides |
+| --- | --- |
+| `gateway.py` | `ModelGateway` — alias resolution, capability negotiation, ordered fallback, cost accounting, GenAI spans |
+| `providers/` | The `Provider` protocol, one HTTP adapter (`OpenAICompatibleProvider`), and one deterministic fake (`FakeProvider`) |
+| `prompts.py` | `PromptTemplate` / `PromptRegistry` — versioned prompts, typed rendering, few-shot assembly |
+| `structured.py` | `build_agent` — structured output via Pydantic AI only |
+| `tools.py` | `Tool` / `ToolExecutor` — declared definitions, argument validation, structured results |
+| `pipeline.py` | `Pipeline` / `PipelineContext` — plain-async named steps over a frozen context |
+| `agents/` | The native agent runtime: `AgentRuntime` — the loop, transfer vs. delegate, step/token/cost budgets with bounded degrade, memory, and a checkpointed human-in-the-loop pause |
+| `retrieval/` | Retrieval: connectors, chunkers, the `Embedder` / `Reranker` / `VectorStore` protocols, hybrid fusion, citations, and retrieval metrics |
+| `evals/` | Datasets, metrics, and the statistical baseline gate |
+| `tracing.py` | OTel GenAI spans: `llm_span`, `agent_span`, `record_usage`, `record_cost`, `record_attributes`, `record_hitl`, `record_exception` |
+| `cost.py` | `Budget`, `CostLedger`, `estimate_cost_usd`, `estimate_tokens` |
+| `types.py` | The request/response/usage/spec models everything else is typed against |
+
+194 names are exported from `aid_runtime`. The layering is acyclic and one-directional: `errors` and `types` import
+nothing else in the package, `gateway` is imported only by the package `__init__` and the eval runner, and no
+core module imports a higher layer back.
+
+## Model pinning
+
+An **alias resolves to an exact provider model id**, including a pinned version. That is not cosmetic: a
+baseline recorded against `gpt-4o` means nothing if the alias floats to `gpt-4o-2026-…` on the next run, so an
+**unknown alias is an error** (`UnknownModelAliasError`) rather than a silent fall-through to a provider
+default.
+
+```python
+from aid_runtime import (
+    Budget,
+    CompletionRequest,
+    CostProfile,
+    ModelGateway,
+    ModelSpec,
+    OpenAICompatibleProvider,
+    PinnedModel,
+)
+
+spec = ModelSpec(
+    name="gpt-4o-2024-08-06",
+    provider="openai-compatible",
+    cost=CostProfile(input_per_1k_usd=0.0025, output_per_1k_usd=0.01),
+    context_window=128_000,
+    max_output_tokens=4096,
+)
+
+gateway = ModelGateway(
+    providers={"openai-compatible": OpenAICompatibleProvider(api_key=...)},
+    aliases={"small": PinnedModel(alias="small", spec=spec)},
+    budget=Budget(max_usd=5.0, scope="nightly"),
+)
+
+result = await gateway.generate("small", CompletionRequest.prompt("hello"))
+result.text, result.usage, result.cost_usd, result.alias, result.attempts, result.fell_back
+```
+
+- `resolve(alias)` returns the `PinnedModel` (alias + `spec`); `provider_for(alias)` its provider. `require(alias,
+  capabilities)` asserts the capabilities *and* returns the pinned model, checking **both** sides — a model that
+  supports tool calling behind an adapter that does not serialise tool definitions cannot tool-call — and raises
+  `CapabilityMismatchError` naming what is missing.
+- `generate(alias, request, *, fallbacks=(), budget=None)` tries the alias then each fallback **in the order
+  given**, and reports the aliases actually attempted on the result. Fallbacks are ordered, not conditional.
+- Every charged call opens a span and updates the ledger. `CostLedger` tracks per-call `LedgerEntry` records
+  and yields a `SpendSummary`; `Budget` (`max_usd`, `max_total_tokens`, `scope`) is enforced before the call,
+  and `estimate_usage` / `estimate_cost_usd` price a request from a model's `CostProfile` when a caller wants
+  to check before spending.
+
+## The eval harness gates on statistics, not equality
+
+Phase 0 ratifies sampling-based gating: a model is **expected** to vary between runs, so a metric that
+compares two runs for equality is either always red or measuring nothing. Non-determinism here is not a bug to
+be fixed; it is the property the gate has to be robust against.
+
+- `Dataset` — versioned cases with inputs, expectations, tags and metadata; `from_records` / `from_json` /
+  `from_path`, `to_json`, and lookups by id (`case`) and by tag (`by_tag`).
+- Metrics — `ExactMatch`, `NormalizedContains`, `JsonSchemaValid`, and `LlmJudge`. `metric_names` and
+  `default_metrics` cover the common set.
+- `run_evaluation(dataset, runner, metrics, runs=5)` samples the runner **N times** and produces an `EvalRun`
+  of per-run metric means, so a single unlucky run does not decide the verdict. `evaluate_once` is the
+  single-pass primitive; a `DatasetRun` gives per-case outcomes and a rendered `summary()`.
+- `EvalBaseline.from_run(run, model=..., note=...)` stores a baseline as JSON: per metric the sample count,
+  mean and spread. `runtimes/python/tests/fixtures/capitals-baseline.json` is a committed example.
+- `BaselineGate(thresholds).evaluate(run, baseline)` compares the current sample against the baseline using a
+  one-sided normal test, with each `Threshold` carrying `metric`, an optional absolute `min_mean`, a
+  `max_regression` allowance, and an `alpha` significance level. A metric passes by clearing `min_mean`, by
+  being within `max_regression` of the baseline, or by regressing only within sampling noise.
+
+Two deliberate limits:
+
+- **`LlmJudge` is implemented and never CI-required.** A judge is itself a model call, and a gate that
+  depends on one non-deterministic call inside the gate you are trying to trust is the problem this design
+  avoids. `gateway_judge(gateway, alias)` builds the judge call when a caller wants it.
+- **`GateConfigurationError` refuses a threshold on a model-derived metric**, because an N-run sample of a
+  probabilistic judge cannot carry a fixed threshold honestly.
+
+`cost` is the enforced budget; a latency p95 budget belongs with Phase 2 dashboards, not here.
+
+## Retrieval
+
+`retrieval/` is an IR-driven layer: `binding_from_spec(retriever, embedding=..., store=...)` folds the IR's
+`retrievers`, `embeddings` and `stores` entries into one `RetrieverBinding`, which a `Retriever` then ingests
+and searches through. The runtime consumes the names the IR emits, field for field.
+
+- Three protocols, in the same style as `providers.Provider`: `Embedder`, `Reranker`, `VectorStore`. Phase 1
+  ships the implementations listed below and no others.
+- `FakeDeterministicEmbedder` maps text to a stable unit vector with a hash — keyless and offline, which is
+  what lets a retrieval gate run in CI. `OpenAICompatibleEmbedder` is the one hosted adapter: a single POST to
+  `/embeddings` over `httpx`, with the retry, timeout and error-chaining behaviour of the HTTP provider.
+- `LexicalReranker` is the only reranker. It is deterministic and lexical; there is no hosted rerank adapter.
+- Chunk ids are **content hashes**, so re-ingesting the same input produces the same ids and a no-op diff.
+  Ingest is therefore held to idempotence rather than to the byte-identical codegen guarantee.
+- **Pinning.** `embedModel` names an IR `embeddings` entry and resolves at codegen time to an exact `modelId`
+  plus its recorded width; the resolved id, width and store `kind` travel into the generated code. An alias is
+  never resolved at runtime, because a baseline recorded against a floating model means nothing.
+- **Cost.** Embedding calls charge the existing `CostLedger` through the existing `Budget`, using the catalog's
+  `CostProfile` for the pinned model. There is no retrieval-specific budgeting machinery.
+
+`RetrievalMetric` (`RecallAtK`, `MeanReciprocalRank`, `CitationGrounding`) is deliberately a **separate
+protocol** from the shipped `Metric`, which scores a single string prediction. Retrieval scores a *retrieved
+set*: recall@k and MRR need the ranked ids, and citation-grounding needs the passages behind the citations.
+Widening `Metric` would have changed an interface the existing gate already threshold-checks, for every
+existing implementation — so retrieval is sampled through `RetrievalGate.sample(...)` instead, producing a
+standard `EvalRun`, and then judged by the **unchanged** `BaselineGate`. Retrieval metrics are deterministic,
+so they pass the gate's own eligibility check.
+
+### pgvector
+
+`PgVectorStore` is a thin adapter over `psycopg` and the `vector` extension. Two consequences worth stating:
+
+- It is **locally provisioned and not covered by any gate.** No CI job starts a database, and no required
+  check touches one; the in-memory adapter carries the store gates, and the two adapters share the same
+  `VectorStore` protocol and the same `similarity` semantics. `compose.pgvector.yml` beside this README brings
+  up a database for local use.
+- The `[pgvector]` extra is **import-safe when absent**: importing `aid_runtime` or `aid_runtime.retrieval`
+  never imports the driver, and the adapter loading it raises a `ConfigurationError` naming the extra.
+
+## Control flow is plain async
+
+`Pipeline` is a list of named async (or plain) steps over a `PipelineContext` that is **frozen**, so a step
+cannot mutate what an earlier step observed — it returns a new context, which keeps a failed run's state
+inspectable. A step may return a context, a mapping, or `None`. Each step runs in its own span, a step raising
+anything aborts the run with the original exception chained (`PipelineError.__cause__`), and `StopPipeline` is
+the supported early exit.
+
+**Pydantic AI is used for structured output and nothing else** (`structured.build_agent`). The orchestration
+library stays out of the control-flow path deliberately, so it remains swappable, and **no graph/orchestration
+dependency is taken at all**: the agent loop in `agents/` is this package's own, and escalation routing and
+third-party orchestration frameworks remain out of scope ([`docs/design.md` §14](../../docs/design.md)).
+
+Tracing follows the OTel GenAI semantic conventions: `gen_ai.*` attributes for the operation, model, provider,
+request parameters and usage, with AID-specific values namespaced `aid.*` so the two never collide. A failing
+call records its exception exactly once.
+
+## The agent runtime
+
+`AgentRuntime.from_ir(document, providers=..., ...)` reads the emitted IR and runs an agent to a stop
+condition: model call, tool calls, observations, until a terminal answer, `maxSteps`, or a budget breach.
+Model calls go through `ModelGateway`, so fallback, cost accounting and tracing apply without a second
+implementation.
+
+**Transfer and delegation are different, and the API says which.** `_transfer` (`handoffs`) hands the
+conversation to the target and never resumes the caller, so `RunResult.agent_id` is the target and `path`
+grows. `_delegate` (`delegates`) runs the target in an isolated `[system, user]` context and returns its answer
+as a single tool observation, so `RunResult.agent_id` is the caller and `path` is unchanged. Both refuse to
+re-enter an agent already on the path.
+
+**A budget breach fails hard.** `BudgetExceededError` stops the run; the gateway preflight and the ledger both
+enforce the ceiling. An agent declaring `onBudgetExhausted: 'degrade'` (v0.2) instead steps exactly one rung
+down its declared alias ladder — no retry loop, and the build-time gate rejects the declaration when no
+strictly cheaper alias exists. Each degraded step is recorded in `StepRecord.degraded_from`, and a checkpoint
+carries its current alias so a resumed run re-routes from where it stopped.
+
+**Memory** is in-process plus one store-backed adapter. `thread` scope is the checkpointer unit: trimmed to its
+`tokenBudget`, never written to a store. `user` and `global` scopes read and write the store and render as one
+extra system message, so injection is visible in the request rather than hidden.
+
+**Human-in-the-loop** pauses by returning a checkpoint (completed steps, pending call, current alias), and
+`resume(checkpoint, decision)` continues it. The pause is recorded as an `aid.hitl` span event, not an
+attribute, because a run can pause more than once.
+
+## Development
+
+Four gates, all run by the `python` job in [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) over
+real content:
+
+```sh
+pytest
+ruff check .
+ruff format --check .
+mypy
+```
+
+`mypy` runs strict over `src` **and** `tests`, so the tests are type-checked too. The `python` job is a real
+gate but is **advisory**: the `main` ruleset requires the `node`, `workflows` and `licenses` contexts only.
+
+`tests/fixtures/capitals-baseline.json` is regenerated from `FakeProvider(accuracy=0.6, seed=0)` over 10 runs
+— the fake is seeded and deterministic per call, so the committed baseline reproduces exactly while a fresh
+sample of it still varies, which is exactly the property the gate has to tolerate.
+
+**Non-responsibility:** no app-specific prompts, tools, or rubrics. Those belong to the generated app's
+`business/` tier ([`docs/design.md` §8.4](../../docs/design.md), the seam).
+
+**Status:** Phase 0 scope implemented, plus the Phase 1 retrieval runtime. One thing deferred and
+undeclared, on purpose: `ModelGateway.stream` raises `FeatureDeferredError`, and no provider advertises
+`Capability.STREAMING` or target declares the capability, because the transport is request/response-only.
+Retrieval likewise fails loudly rather than
+approximating: non-file sources, `semantic` chunking, `incremental` refresh, retriever `filters`, a hosted
+reranker, and the `qdrant` / `pinecone` / `weaviate` / `custom` store kinds all raise `FeatureDeferredError`.
+Also deferred (§14): escalation routing, memory, guardrails, prompt/semantic caching, rate limiting, token
+buckets, and adapters beyond the one HTTP provider and the fake.
+
+Emitting retrieval into a generated app and indexing it from the CLI are later layers, so this package adds no
+entry point for either.
+
+Reference: [`docs/design.md` §9, §12, §14, §17 #2](../../docs/design.md).

aid_runtime_python-0.1.39.dist-info/RECORD

@@ -0,0 +1,52 @@
+aid_runtime/__init__.py,sha256=E8pW04ODgOND66tyve5B8CYcSjCjZeMuX93Mey_o0I0,11009
+aid_runtime/cache.py,sha256=jhw_EBd9dfWEUzYeibOvIkVBqqiLUjqF5WKEPz9GkhE,6836
+aid_runtime/concurrency.py,sha256=z0tFQHw35ttFLKfazGBjCMPOLQOnUotE_OPpvR1piH4,2829
+aid_runtime/control.py,sha256=u4U97QFdYSSjOPY3D6f1-GZhkGhygEdR-apdgw_jJok,13797
+aid_runtime/cost.py,sha256=Hc7X6mtkeanL9eJ1lEZZCQ9LxZurhL1it0gm3s9LpQE,5465
+aid_runtime/errors.py,sha256=TKkZyZZcFTl5yxNKlA8jUF4ORpYHLGFEvc6r9FK4X70,12572
+aid_runtime/gateway.py,sha256=p0qsaQUAYrwSzlWwpUi1wY6pdOeU98QjsWLzq8045Fo,18267
+aid_runtime/pipeline.py,sha256=Y2jiiYISLLxgBKGBj5J2rseEDzE8RXP8v5pJ_edjHfM,6334
+aid_runtime/prompts.py,sha256=eN3p_Yc-J6pyKaL2w4I-EmwvcPKErnXBvvI_Syq13ZM,7083
+aid_runtime/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aid_runtime/steps.py,sha256=44v8-ebN77VGZePmfhBYi0KORFBrH2GWFSzlfczaJhs,12047
+aid_runtime/structured.py,sha256=Uga-VoGJN56lUtr-M3nmUjAKGF32cAAk-p7WceUgPzg,5061
+aid_runtime/tools.py,sha256=7LeaPI5aJioNe3vexUv94tvIRpOwxj1Ujt723qvO3UI,9906
+aid_runtime/tracing.py,sha256=Ii2ypuHxHLZ4lmE6oYhcCJiA9dFE5KhXKRTsdQnDDLE,8524
+aid_runtime/types.py,sha256=cVYgmacDIhStQT5dX_X67-q57sPBBaWC5nybtGVqVsw,10389
+aid_runtime/agents/__init__.py,sha256=XOOecYSBtWzD0Ylaurbz3w2Tuffpzc_5nNeMIznCucU,2398
+aid_runtime/agents/chat_model.py,sha256=fZdCmSpoECuBVGZE1s8NmT2erT33RhDuLh3yJM6kAJE,14808
+aid_runtime/agents/deep_agents.py,sha256=ZM6ZSc92arCvtsYGsIGdF-NryqN_tvXtRqbdlHaGpeE,26948
+aid_runtime/agents/engine.py,sha256=RQUV49u7MLDmirnFv8YsRGdIutzUGsGaLA6Y2JT5wj0,4129
+aid_runtime/agents/guardrails.py,sha256=RM_iR_h7LQiulN8KA6scKeCyoTxECqywqJO0eLHPpKQ,19363
+aid_runtime/agents/ir.py,sha256=BaIGEzwHSQnP2q7s1GjNwRTICju9LsPGdAcsboA4KSw,24151
+aid_runtime/agents/loop.py,sha256=T-QnC9BQ9K3RyZfHdAuzWiwMXBpQjDLGdHrLgf2fnFM,52608
+aid_runtime/agents/memory.py,sha256=6_D6k2bzAiR2euNvzr6HB28wsUUq-R-WTQc12gkB8ao,9156
+aid_runtime/agents/policy.py,sha256=ael0EW_hWfLu95rbqFMrR4WyqAPtgiSNvNw97xnthdw,6122
+aid_runtime/agents/state.py,sha256=4itT7BWv2JKSeWpRrDyxLguOOVnz9gGH_qgRdCbWCaw,6086
+aid_runtime/evals/__init__.py,sha256=2eSGrGxdQHmnVQb5RJS146ZHc-5VARBJTUrTxcEdCv8,1379
+aid_runtime/evals/dataset.py,sha256=waG4tYSJsgsZ9DLxkhUvF_X-aQB8w2OexYxc7Wwdiyg,2494
+aid_runtime/evals/gate.py,sha256=_nLWXvcuHwq8nE3HpiONg_wBkrzZyGrGT49ZNeKMyTY,15524
+aid_runtime/evals/metrics.py,sha256=Z-rLJjG0dBTdTJTVGTt8WzE0avyYkIG_Ot8sLDaD99Y,10631
+aid_runtime/evals/predicate.py,sha256=JaeN1LJFpliI4JHYdFPtXfjH5_Aad-2-U3ZC6_hManE,8726
+aid_runtime/evals/runner.py,sha256=Lkl-kAVxegPO40pCBUcprRBKvfL6bjYzVf__xe6Z-Mc,7951
+aid_runtime/providers/__init__.py,sha256=KkRkwVRZwZ5H_Rqke8EsipxyMgYuwODB9CGXiHL_gDE,577
+aid_runtime/providers/base.py,sha256=1VYTZ_V9FR6f6pS0MB3LFeu-Zzv4toQvm3CwAQNbeT0,1851
+aid_runtime/providers/fake.py,sha256=oAcpaDOUIp7lmKGEEWG5ktagstg2dvoHR-9xaUeCDLo,9526
+aid_runtime/providers/http.py,sha256=c5DLmX1FqtAUO01MqDf0m82x8zHD480LyL-QtTrxnn4,13168
+aid_runtime/retrieval/__init__.py,sha256=LR6qyiE7pY9QsB1h4g9j1W7acpSINFbgxA9U1otLt90,4580
+aid_runtime/retrieval/chunking.py,sha256=GMJvY1GoIua-FkpCH1S5qNmUrWSaSbl6sBJPCrSDAg4,8296
+aid_runtime/retrieval/citations.py,sha256=UL9fsxLTzzO0n8tEW3X2O5erJ0hrk08NYMkZ9Pk8Jdg,4287
+aid_runtime/retrieval/connectors.py,sha256=JNEwq6S8zKX1GdlWe4Gn2Rdon87DWXlG_WNQfZTlN34,4744
+aid_runtime/retrieval/embedding.py,sha256=ZPjALe_nEzYpa8N5COExPGrojjZFX8awTz6vzJYfx_4,12374
+aid_runtime/retrieval/gate.py,sha256=fxrI7Og9d3J-NKUcn3QI-2N4K3o4-LQehXxCK19qzCM,4842
+aid_runtime/retrieval/hybrid.py,sha256=-GIBeI3njT5uaEvSeq2t151Zlv2yOPHOPje4TJLNVyU,5804
+aid_runtime/retrieval/metrics.py,sha256=LN36BIXzpbhkG9grzE0q5wncgXt_Y85-b5jGJ038-3Y,7904
+aid_runtime/retrieval/pgvector.py,sha256=kdE6Gdk9JhR6-QxN353CmuNYMLyr5eBvnQl4krLzLew,10040
+aid_runtime/retrieval/rerank.py,sha256=L4ICBi9YHDzhnKVtImKh5Wzre1HDzS8at-AKDkXBJMc,5114
+aid_runtime/retrieval/retriever.py,sha256=hVLP0xOLKioYsa-aS1akyJl5p-WbpVjm8OfCw26m4CE,13941
+aid_runtime/retrieval/stores.py,sha256=VEi68AaMHcQjdAbWOHflp3jCl1_1db71rIzZjTouLlo,5857
+aid_runtime/retrieval/types.py,sha256=8vKP21rmE9LglnB5gtv0dLBIkXzaPqdG3-GS98K0gpc,13498
+aid_runtime_python-0.1.39.dist-info/METADATA,sha256=NqIxXTImMqSvUWC2zPniEyZoopmh3ByGXVD2ICZVOGI,16364
+aid_runtime_python-0.1.39.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+aid_runtime_python-0.1.39.dist-info/top_level.txt,sha256=QvODgNVRDDMmLcTnoIQ4jYnhqf-N4b9sHWEmaUUxp44,12
+aid_runtime_python-0.1.39.dist-info/RECORD,,

aid_runtime_python-0.1.39.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aid_runtime_python-0.1.39.dist-info/top_level.txt

@@ -0,0 +1 @@
+aid_runtime