puremethod 0.1.0__py3-none-any.whl

ledger/storage.py

@@ -0,0 +1,226 @@
+"""Entry, rejection and artifact-index storage: SQLite or PostgreSQL (04-ledger.md §4).
+
+Both refuse UPDATE and DELETE with triggers, as a second barrier behind the API (§5 step 4).
+Payloads and refs are stored as canonical JSON text, so the stored bytes are the hashed bytes.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Protocol
+
+from .canonical import canonical_json
+from .errors import LedgerError
+from .model import Entry, Rejection
+
+EntryBuilder = Callable[[str | None, int], Entry]
+
+_TABLES = ("entries", "rejections", "artifacts")
+
+
+class Storage(Protocol):
+    def append(self, run_id: str, build: EntryBuilder) -> Entry: ...
+    def entries(self, run_id: str, since_seq: int = 0) -> list[Entry]: ...
+    def run_exists(self, run_id: str) -> bool: ...
+    def add_rejection(self, rejection: Rejection) -> None: ...
+    def rejections(self, run_id: str) -> list[Rejection]: ...
+    def add_artifact(self, run_id: str, digest: str, kind: str, size: int, at: str) -> None: ...
+    def artifact_kind(self, run_id: str, digest: str) -> str | None: ...
+    def close(self) -> None: ...
+
+
+def _row_to_entry(row: tuple[Any, ...]) -> Entry:
+    run_id, seq, entry_id, type_, at, actor, payload, refs, prev_hash, hash_ = row
+    return Entry(run_id=run_id, seq=int(seq), entry_id=entry_id, type=type_, at=at,
+                 actor=actor, payload=json.loads(payload), refs=json.loads(refs),
+                 prev_hash=prev_hash, hash=hash_)
+
+
+def _entry_params(e: Entry) -> tuple[Any, ...]:
+    return (e.run_id, e.seq, e.entry_id, e.type, e.at, e.actor, canonical_json(e.payload),
+            canonical_json(e.refs), e.prev_hash, e.hash)
+
+
+_COLUMNS = "run_id, seq, entry_id, type, at, actor, payload, refs, prev_hash, hash"
+
+
+class SQLiteStorage:
+    def __init__(self, path: str) -> None:
+        if path != ":memory:":
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(path, isolation_level=None, check_same_thread=False)
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        if path != ":memory:":
+            self._conn.execute("PRAGMA journal_mode = WAL")
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        c = self._conn
+        c.execute("""CREATE TABLE IF NOT EXISTS entries (
+            run_id TEXT NOT NULL, seq INTEGER NOT NULL, entry_id TEXT NOT NULL UNIQUE,
+            type TEXT NOT NULL, at TEXT NOT NULL, actor TEXT NOT NULL, payload TEXT NOT NULL,
+            refs TEXT NOT NULL, prev_hash TEXT NOT NULL, hash TEXT NOT NULL,
+            PRIMARY KEY (run_id, seq))""")
+        c.execute("""CREATE TABLE IF NOT EXISTS rejections (
+            id INTEGER PRIMARY KEY AUTOINCREMENT, run_id TEXT NOT NULL, at TEXT NOT NULL,
+            target TEXT NOT NULL, rule TEXT NOT NULL, message TEXT NOT NULL)""")
+        c.execute("""CREATE TABLE IF NOT EXISTS artifacts (
+            run_id TEXT NOT NULL, digest TEXT NOT NULL, kind TEXT NOT NULL,
+            size INTEGER NOT NULL, at TEXT NOT NULL, PRIMARY KEY (run_id, digest))""")
+        for table in _TABLES:
+            for op in ("UPDATE", "DELETE"):
+                c.execute(
+                    f"CREATE TRIGGER IF NOT EXISTS {table}_no_{op.lower()} BEFORE {op} ON "
+                    f"{table} BEGIN SELECT RAISE(ABORT, 'ledger: {table} is append-only'); END"
+                )
+
+    @contextmanager
+    def _tx(self) -> Iterator[sqlite3.Connection]:
+        self._conn.execute("BEGIN IMMEDIATE")
+        try:
+            yield self._conn
+        except BaseException:
+            self._conn.execute("ROLLBACK")
+            raise
+        else:
+            self._conn.execute("COMMIT")
+
+    def append(self, run_id: str, build: EntryBuilder) -> Entry:
+        with self._tx() as c:
+            row = c.execute("SELECT seq, hash FROM entries WHERE run_id = ? "
+                            "ORDER BY seq DESC LIMIT 1", (run_id,)).fetchone()
+            prev_hash, next_seq = (None, 1) if row is None else (row[1], int(row[0]) + 1)
+            entry = build(prev_hash, next_seq)
+            c.execute(f"INSERT INTO entries ({_COLUMNS}) VALUES (?,?,?,?,?,?,?,?,?,?)",  # noqa: S608
+                      _entry_params(entry))
+            return entry
+
+    def entries(self, run_id: str, since_seq: int = 0) -> list[Entry]:
+        rows = self._conn.execute(
+            f"SELECT {_COLUMNS} FROM entries WHERE run_id = ? AND seq > ? ORDER BY seq",  # noqa: S608
+            (run_id, since_seq)).fetchall()
+        return [_row_to_entry(r) for r in rows]
+
+    def run_exists(self, run_id: str) -> bool:
+        row = self._conn.execute("SELECT 1 FROM entries WHERE run_id = ? AND seq = 1",
+                                 (run_id,)).fetchone()
+        return row is not None
+
+    def add_rejection(self, rejection: Rejection) -> None:
+        self._conn.execute(
+            "INSERT INTO rejections (run_id, at, target, rule, message) VALUES (?,?,?,?,?)",
+            (rejection.run_id, rejection.at, rejection.target, rejection.rule,
+             rejection.message))
+
+    def rejections(self, run_id: str) -> list[Rejection]:
+        rows = self._conn.execute("SELECT run_id, at, target, rule, message FROM rejections "
+                                  "WHERE run_id = ? ORDER BY id", (run_id,)).fetchall()
+        return [Rejection(*r) for r in rows]
+
+    def add_artifact(self, run_id: str, digest: str, kind: str, size: int, at: str) -> None:
+        self._conn.execute("INSERT OR IGNORE INTO artifacts (run_id, digest, kind, size, at) "
+                           "VALUES (?,?,?,?,?)", (run_id, digest, kind, size, at))
+
+    def artifact_kind(self, run_id: str, digest: str) -> str | None:
+        row = self._conn.execute("SELECT kind FROM artifacts WHERE run_id = ? AND digest = ?",
+                                 (run_id, digest)).fetchone()
+        return None if row is None else str(row[0])
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+class PostgresStorage:
+    def __init__(self, url: str) -> None:
+        import psycopg
+
+        self._conn = psycopg.connect(url, autocommit=True)
+        self._init_schema()
+
+    def _init_schema(self) -> None:
+        with self._conn.transaction():
+            c = self._conn
+            c.execute("""CREATE TABLE IF NOT EXISTS entries (
+                run_id TEXT NOT NULL, seq BIGINT NOT NULL, entry_id TEXT NOT NULL UNIQUE,
+                type TEXT NOT NULL, at TEXT NOT NULL, actor TEXT NOT NULL, payload TEXT NOT NULL,
+                refs TEXT NOT NULL, prev_hash TEXT NOT NULL, hash TEXT NOT NULL,
+                PRIMARY KEY (run_id, seq))""")
+            c.execute("""CREATE TABLE IF NOT EXISTS rejections (
+                id BIGSERIAL PRIMARY KEY, run_id TEXT NOT NULL, at TEXT NOT NULL,
+                target TEXT NOT NULL, rule TEXT NOT NULL, message TEXT NOT NULL)""")
+            c.execute("""CREATE TABLE IF NOT EXISTS artifacts (
+                run_id TEXT NOT NULL, digest TEXT NOT NULL, kind TEXT NOT NULL,
+                size BIGINT NOT NULL, at TEXT NOT NULL, PRIMARY KEY (run_id, digest))""")
+            c.execute("""CREATE OR REPLACE FUNCTION ledger_append_only() RETURNS trigger
+                LANGUAGE plpgsql AS $$ BEGIN
+                RAISE EXCEPTION 'ledger: % is append-only', TG_TABLE_NAME; END $$""")
+            for table in _TABLES:
+                c.execute(f"DROP TRIGGER IF EXISTS {table}_append_only ON {table}")
+                c.execute(f"CREATE TRIGGER {table}_append_only BEFORE UPDATE OR DELETE ON "
+                          f"{table} FOR EACH ROW EXECUTE FUNCTION ledger_append_only()")
+                c.execute(f"DROP TRIGGER IF EXISTS {table}_no_truncate ON {table}")
+                c.execute(f"CREATE TRIGGER {table}_no_truncate BEFORE TRUNCATE ON {table} "
+                          f"FOR EACH STATEMENT EXECUTE FUNCTION ledger_append_only()")
+
+    def append(self, run_id: str, build: EntryBuilder) -> Entry:
+        with self._conn.transaction():
+            c = self._conn
+            c.execute("SELECT pg_advisory_xact_lock(hashtextextended(%s, 0))", (run_id,))
+            row = c.execute("SELECT seq, hash FROM entries WHERE run_id = %s "
+                            "ORDER BY seq DESC LIMIT 1", (run_id,)).fetchone()
+            prev_hash, next_seq = (None, 1) if row is None else (row[1], int(row[0]) + 1)
+            entry = build(prev_hash, next_seq)
+            c.execute(f"INSERT INTO entries ({_COLUMNS}) VALUES "  # noqa: S608
+                      "(%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)", _entry_params(entry))
+            return entry
+
+    def entries(self, run_id: str, since_seq: int = 0) -> list[Entry]:
+        rows = self._conn.execute(
+            f"SELECT {_COLUMNS} FROM entries WHERE run_id = %s AND seq > %s ORDER BY seq",  # noqa: S608
+            (run_id, since_seq)).fetchall()
+        return [_row_to_entry(tuple(r)) for r in rows]
+
+    def run_exists(self, run_id: str) -> bool:
+        row = self._conn.execute("SELECT 1 FROM entries WHERE run_id = %s AND seq = 1",
+                                 (run_id,)).fetchone()
+        return row is not None
+
+    def add_rejection(self, rejection: Rejection) -> None:
+        self._conn.execute(
+            "INSERT INTO rejections (run_id, at, target, rule, message) "
+            "VALUES (%s,%s,%s,%s,%s)",
+            (rejection.run_id, rejection.at, rejection.target, rejection.rule,
+             rejection.message))
+
+    def rejections(self, run_id: str) -> list[Rejection]:
+        rows = self._conn.execute("SELECT run_id, at, target, rule, message FROM rejections "
+                                  "WHERE run_id = %s ORDER BY id", (run_id,)).fetchall()
+        return [Rejection(*r) for r in rows]
+
+    def add_artifact(self, run_id: str, digest: str, kind: str, size: int, at: str) -> None:
+        self._conn.execute("INSERT INTO artifacts (run_id, digest, kind, size, at) "
+                           "VALUES (%s,%s,%s,%s,%s) ON CONFLICT DO NOTHING",
+                           (run_id, digest, kind, size, at))
+
+    def artifact_kind(self, run_id: str, digest: str) -> str | None:
+        row = self._conn.execute("SELECT kind FROM artifacts WHERE run_id = %s AND digest = %s",
+                                 (run_id, digest)).fetchone()
+        return None if row is None else str(row[0])
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+def open_storage(url: str) -> Storage:
+    if url.startswith("sqlite:///"):
+        return SQLiteStorage(url.removeprefix("sqlite:///"))
+    if url == "sqlite://":
+        return SQLiteStorage(":memory:")
+    if url.startswith(("postgresql://", "postgres://")):
+        return PostgresStorage(url)
+    # Never echo the URL: a PostgreSQL URL can carry a password.
+    raise LedgerError("unsupported storage URL scheme (use sqlite:/// or postgresql://)")

llm/__init__.py

@@ -0,0 +1,45 @@
+"""llm: model-agnostic, metered LLM calls (docs/knowledge_base/07-llm.md)."""
+
+from .core import LLM, QUOTE_RULE, PreflightReport
+from .prices import DEFAULT_PRICES, ModelPrice, PriceTable, bound_usd, cost_usd
+from .tokens import estimate_tokens
+from .types import (
+    ROLES,
+    AuthError,
+    CallRecord,
+    InvalidOutput,
+    LLMError,
+    LLMResult,
+    Message,
+    PriceUnknown,
+    ProviderUnavailable,
+    QuotaExhausted,
+    RateLimited,
+    RequestRejected,
+    Usage,
+)
+
+__all__ = [
+    "DEFAULT_PRICES",
+    "LLM",
+    "QUOTE_RULE",
+    "ROLES",
+    "AuthError",
+    "CallRecord",
+    "InvalidOutput",
+    "LLMError",
+    "LLMResult",
+    "Message",
+    "ModelPrice",
+    "PreflightReport",
+    "PriceTable",
+    "PriceUnknown",
+    "ProviderUnavailable",
+    "QuotaExhausted",
+    "RateLimited",
+    "RequestRejected",
+    "Usage",
+    "bound_usd",
+    "cost_usd",
+    "estimate_tokens",
+]

llm/backends/anthropic_backend.py

@@ -0,0 +1,145 @@
+"""Anthropic backend (official `anthropic` SDK, 2.x).
+
+- Token counts come from `messages.count_tokens`, exact for the same request shape,
+  including the structured-output schema (07-llm.md §5 step 2).
+- Sampling parameters are not sent: API version 2026-10-21 rejects `temperature` on every
+  model (§5 step 8, "where supported").
+- The SDK's own retries are off, so each attempt gets its own CallRecord (INV-1).
+- Server-side refusal fallbacks are not enabled: they would switch models without the run
+  config naming the fallback (INV-4).
+- Structured output sends what the API can enforce: the SDK's `transform_schema` drops
+  unsupported constraints (`maxItems`, `minLength`, `minimum`, ...) into descriptions. A schema
+  it cannot express (an object used as a map) goes in the system prompt instead. Either way
+  `LLM.complete` validates the reply against the full schema and retries (07-llm.md §5 step 4,
+  INV-6), so no constraint is lost.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import anthropic
+
+from ..types import Message, Usage
+from .base import BackendError, Completion, scrub
+
+_SCHEMA_INSTRUCTION = "Reply with only a JSON value that matches this JSON Schema:\n"
+
+
+def _has_map(schema: Any) -> bool:
+    """An object whose extra keys are allowed: structured outputs only take
+    `additionalProperties: false`, so its shape cannot be enforced."""
+    if isinstance(schema, dict):
+        extra = schema.get("additionalProperties", False)
+        if schema.get("type") == "object" and extra is not False and (
+                extra is not None or not schema.get("properties")):
+            return True
+        return any(_has_map(v) for v in schema.values())
+    if isinstance(schema, list):
+        return any(_has_map(v) for v in schema)
+    return False
+
+
+def _typed(schema: Any) -> Any:
+    """A copy in which an `enum` of strings without a `type` says `"type": "string"`, which
+    `transform_schema` requires; the accepted values are unchanged."""
+    if isinstance(schema, list):
+        return [_typed(v) for v in schema]
+    if not isinstance(schema, dict):
+        return schema
+    out = {k: _typed(v) for k, v in schema.items()}
+    enum = out.get("enum")
+    if "type" not in out and isinstance(enum, list) and enum and all(
+            isinstance(v, str) for v in enum):
+        out["type"] = "string"
+    return out
+
+
+def _enforceable(schema: dict[str, Any]) -> dict[str, Any] | None:
+    """The schema as structured outputs can take it, or None when it cannot."""
+    if _has_map(schema):
+        return None
+    try:
+        return anthropic.transform_schema(_typed(schema))
+    except (ValueError, TypeError, AssertionError):
+        return None
+
+
+class AnthropicBackend:
+    provider = "anthropic"
+
+    def __init__(self, api_key: str, base_url: str | None = None,
+                 timeout_s: float = 600.0) -> None:
+        self._secrets = [api_key]
+        self._client = anthropic.Anthropic(api_key=api_key, base_url=base_url, max_retries=0,
+                                           timeout=timeout_s)
+
+    def _classify(self, exc: Exception) -> BackendError:
+        msg = scrub(f"{type(exc).__name__}: {getattr(exc, 'message', '')}", self._secrets)
+        if isinstance(exc, anthropic.RateLimitError):
+            return BackendError("rate_limited", msg)
+        if isinstance(exc, anthropic.AuthenticationError | anthropic.PermissionDeniedError):
+            return BackendError("auth", msg)
+        if isinstance(exc, anthropic.APIStatusError):
+            if exc.status_code == 402:
+                return BackendError("quota", msg)
+            if exc.status_code >= 500:
+                return BackendError("transient", msg)
+            return BackendError("rejected", msg)
+        if isinstance(exc, anthropic.APIConnectionError):  # includes timeouts
+            return BackendError("transient", msg)
+        return BackendError("transient", scrub(type(exc).__name__, self._secrets))
+
+    @staticmethod
+    def _params(system: str, messages: list[Message],
+                schema: dict[str, Any] | None) -> dict[str, Any]:
+        params: dict[str, Any] = {
+            "messages": [{"role": m["role"], "content": m["content"]} for m in messages],
+        }
+        sent = _enforceable(schema) if schema is not None else None
+        if schema is not None and sent is None:
+            system = (f"{system}\n\n" if system else "") + _SCHEMA_INSTRUCTION + json.dumps(
+                schema, sort_keys=True)
+        if system:
+            params["system"] = system
+        if sent is not None:
+            params["output_config"] = {"format": {"type": "json_schema", "schema": sent}}
+        return params
+
+    def check_model(self, model: str) -> str | None:
+        try:
+            self._client.models.retrieve(model)
+        except Exception as exc:
+            return self._classify(exc).message
+        return None
+
+    def count_input_tokens(self, model: str, system: str, messages: list[Message],
+                           schema: dict[str, Any] | None) -> int | None:
+        try:
+            resp = self._client.messages.count_tokens(model=model,
+                                                      **self._params(system, messages, schema))
+        except Exception as exc:
+            raise self._classify(exc) from None
+        return int(resp.input_tokens)
+
+    def complete(self, model: str, system: str, messages: list[Message], *, max_tokens: int,
+                 temperature: float | None, seed: int | None,
+                 schema: dict[str, Any] | None) -> Completion:
+        try:
+            # Streaming, so large max_tokens values do not hit request timeouts.
+            with self._client.messages.stream(model=model, max_tokens=max_tokens,
+                                              **self._params(system, messages,
+                                                             schema)) as stream:
+                resp = stream.get_final_message()
+        except Exception as exc:
+            raise self._classify(exc) from None
+        text = "".join(b.text for b in resp.content if b.type == "text")
+        u = resp.usage
+        usage = Usage(input_tokens=u.input_tokens, output_tokens=u.output_tokens,
+                      cache_read_tokens=u.cache_read_input_tokens or 0,
+                      cache_write_tokens=u.cache_creation_input_tokens or 0)
+        return Completion(text=text, usage=usage, model_reported=resp.model,
+                          stop_reason=resp.stop_reason,
+                          sent={"max_tokens": max_tokens, "temperature": None, "seed": None,
+                                "structured_output": schema is not None})

llm/backends/base.py

@@ -0,0 +1,87 @@
+"""The provider backend interface. Each backend lives in its own file and SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+from ..types import Message, Usage
+
+ErrorKind = Literal["transient", "rate_limited", "quota", "auth", "rejected"]
+
+
+class BackendError(Exception):
+    """A classified provider failure. `message` is already scrubbed of credentials."""
+
+    def __init__(self, kind: ErrorKind, message: str) -> None:
+        super().__init__(f"{kind}: {message}")
+        self.kind: ErrorKind = kind
+        self.message = message
+
+
+@dataclass(frozen=True)
+class Completion:
+    text: str
+    usage: Usage
+    model_reported: str | None
+    stop_reason: str | None
+    sent: dict[str, Any] = field(default_factory=dict)  # parameters actually sent
+
+
+class Backend(Protocol):
+    provider: str
+
+    def check_model(self, model: str) -> str | None:
+        """None if the model is usable with these credentials, else the problem."""
+        ...
+
+    def count_input_tokens(self, model: str, system: str, messages: list[Message],
+                           schema: dict[str, Any] | None) -> int | None:
+        """Exact or upper-bound input tokens, or None when only the estimate is available."""
+        ...
+
+    def complete(self, model: str, system: str, messages: list[Message], *, max_tokens: int,
+                 temperature: float | None, seed: int | None,
+                 schema: dict[str, Any] | None) -> Completion: ...
+
+
+@dataclass(frozen=True)
+class ServerInfo:
+    """What a self-hosted server says about a model, where it says it (§3, KB-036)."""
+    kind: str | None = None  # "ollama", "vllm", "lmstudio", "llama.cpp"
+    context_length: int | None = None  # the context the server serves the model with
+    digest: str | None = None  # model digest and quantization, e.g. "sha256:… Q4_K_M"
+    local: bool | None = None  # False: the server forwards it to a hosted service
+
+
+def private_address(host: str) -> bool:
+    """True if `host` is, or resolves to, a loopback, link-local, private or otherwise
+    non-public address (IPv4, IPv6, IPv4-mapped). An unresolvable name counts as private:
+    refusing is the safe answer (08-app.md INV-11)."""
+    import ipaddress
+    import socket
+
+    name = host.strip("[]")
+    try:
+        addrs = [ipaddress.ip_address(name)]
+    except ValueError:
+        try:
+            infos = socket.getaddrinfo(name, None)
+        except OSError:
+            return True
+        addrs = [ipaddress.ip_address(str(i[4][0]).split("%")[0]) for i in infos]
+    for a in addrs:
+        mapped = getattr(a, "ipv4_mapped", None)
+        if mapped is not None:
+            a = mapped
+        if not a.is_global or a.is_multicast:
+            return True
+    return not addrs
+
+
+def scrub(text: str, secrets: list[str]) -> str:
+    """Remove credential values from text that came from a provider or its SDK (INV-7)."""
+    for secret in secrets:
+        if secret:
+            text = text.replace(secret, "[REDACTED]")
+    return text[:500]