surf-agentic-base 0.3.0__py3-none-any.whl

agentic_base/client.py

@@ -0,0 +1,172 @@
+"""Recording a run from someone else's agent.
+
+The point of this file is that recording has to be easier than not recording, because whoever is
+trying to get one thing working will otherwise wrap the HTTP API themselves, and their wrapper
+becomes the real interface.
+
+Two arguments have no default, and that is deliberate. See `RunRecordCreate` for the corpus that
+resulted from making provenance optional.
+
+Usage:
+
+    recorder = RunRecorder("https://agentic-base.example.org", tenant="hpml",
+                           code_revision=git_sha())
+
+    with recorder.run(item="issue-4312", arm="baseline") as run:
+        answer = my_agent(task)
+        run.messages = transcript
+        run.model = "some-model"
+
+    recorder.label(run.run_id, resolved=True, label_source=LabelSource.OFFICIAL_HARNESS,
+                   instrument="harness-1.4")
+
+The context manager records on exit, including when the body raises, because a run that crashed
+is a measurement and losing it biases whatever it was part of.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any, Literal
+
+import httpx
+
+from agentic_base.domain.outcomes import LabelSource, RunStatus
+
+
+def git_revision(path: str = ".") -> str:
+    """The current commit, or an empty string if this is not a checkout.
+
+    Returns empty rather than raising so a caller can decide. An empty revision will be refused
+    by the service, which is the intended outcome: a run that cannot say which code produced it
+    cannot be placed against a later change in what a field means.
+    """
+    try:
+        out = subprocess.run(
+            ["git", "-C", path, "rev-parse", "HEAD"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return out.stdout.strip() if out.returncode == 0 else ""
+
+
+@dataclass
+class PendingRun:
+    """A run in progress. Fill in what you know; it is recorded when the block exits."""
+
+    item: str = ""
+    arm: str = ""
+    arm_fingerprint: str = ""
+    system_prompt: str = ""
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    model: str = ""
+    endpoint: str = ""
+    precision: str = ""
+    status: RunStatus = RunStatus.COMPLETED
+    failure_kind: str = ""
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    joules: float = 0.0
+    num_steps: int = 0
+    total_tool_calls: int = 0
+    extra: dict[str, Any] = field(default_factory=dict)
+    run_id: str = ""
+    elapsed_ms: float = 0.0
+
+
+class RunRecorder:
+    """Records runs against a platform instance."""
+
+    def __init__(
+        self,
+        base_url: str,
+        tenant: str,
+        code_revision: str,
+        *,
+        timeout_s: float = 10.0,
+    ) -> None:
+        if not tenant:
+            raise ValueError("tenant is required")
+        if not code_revision:
+            raise ValueError(
+                "code_revision is required. Use git_revision(), or pass the build identifier of "
+                "whatever produced this run. A run that cannot name its code cannot be placed "
+                "against a later change in what a field means."
+            )
+        self.base_url = base_url.rstrip("/")
+        self.tenant = tenant
+        self.code_revision = code_revision
+        self._timeout = timeout_s
+
+    def run(self, **kwargs: Any) -> _RunContext:
+        """Open a run. Records on exit, including on an exception."""
+        return _RunContext(self, PendingRun(**kwargs))
+
+    def record(self, pending: PendingRun) -> str:
+        payload = {
+            "tenant": self.tenant,
+            "code_revision": self.code_revision,
+            **{
+                key: (value.value if hasattr(value, "value") else value)
+                for key, value in vars(pending).items()
+                if key not in ("run_id",)
+            },
+        }
+        response = httpx.post(
+            f"{self.base_url}/runs", json=payload, timeout=self._timeout
+        )
+        response.raise_for_status()
+        return response.json()["run_id"]
+
+    def label(
+        self,
+        run_id: str,
+        *,
+        resolved: bool,
+        label_source: LabelSource,
+        instrument: str = "",
+        degraded: bool = False,
+    ) -> None:
+        """Attach an outcome. The scorer is a required argument and has no default."""
+        response = httpx.post(
+            f"{self.base_url}/runs/{run_id}/label",
+            json={
+                "resolved": resolved,
+                "label_source": label_source.value,
+                "instrument": instrument,
+                "degraded": degraded,
+            },
+            timeout=self._timeout,
+        )
+        response.raise_for_status()
+
+
+class _RunContext:
+    def __init__(self, recorder: RunRecorder, pending: PendingRun) -> None:
+        self._recorder = recorder
+        self._pending = pending
+        self._started = 0.0
+
+    def __enter__(self) -> PendingRun:
+        self._started = time.monotonic()
+        return self._pending
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> Literal[False]:
+        self._pending.elapsed_ms = (time.monotonic() - self._started) * 1000
+        if exc_type is not None and self._pending.status is RunStatus.COMPLETED:
+            self._pending.status = RunStatus.FAILED
+            self._pending.failure_kind = exc_type.__name__
+        self._pending.run_id = self._recorder.record(self._pending)
+        return False

agentic_base/code_policy/policy.py

@@ -0,0 +1,122 @@
+"""A cheap structural pre-filter for model-generated Python.
+
+Read this before relying on it.
+
+This is not an isolation boundary and must never be described as one. It bounds accidental
+damage and rejects the known reflection-escape class before code reaches an executor. Real
+isolation is the executor's job: a container with a read-only root filesystem and no bind
+mounts, or a sandboxed runtime such as gVisor, or a microVM. On Kubernetes those exist and
+should be used. This file is what runs in front of them, for free, to catch the obvious cases
+without paying for a process.
+
+The check is on the parsed syntax tree rather than on the text. A blocklist of patterns over
+source text was verifiably escaped in the predecessor project by writing the attribute name as
+two concatenated string literals, then walking the object graph to reach the file builtin. A
+structural walk sees the same code as the interpreter does, so that trick has nothing to hide
+behind.
+
+One route the tree does not show, and which is handled separately: format-string fields resolve
+attributes at runtime, so a dunder inside a field of a literal string is attribute access that
+never appears as an attribute node.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+FORBIDDEN_NAMES = frozenset(
+    {
+        "getattr",
+        "setattr",
+        "delattr",
+        "vars",
+        "globals",
+        "locals",
+        "eval",
+        "exec",
+        "compile",
+        "open",
+        "__import__",
+        "breakpoint",
+        "input",
+        "object",
+        "super",
+        "memoryview",
+        "exit",
+        "quit",
+    }
+)
+"""Builtins that hand back the object graph or the import system."""
+
+
+def is_dunder(name: str) -> bool:
+    return name.startswith("__") and name.endswith("__")
+
+
+def format_field_reaches_dunder(text: str) -> bool:
+    """Whether a format field inside a literal string resolves a dunder attribute.
+
+    `"{0.__class__}".format(1)` performs attribute access that no attribute node describes.
+    Only the fields are inspected, so prose mentioning a dunder is untouched.
+    """
+    i = 0
+    while True:
+        i = text.find("{", i)
+        if i == -1:
+            return False
+        j = text.find("}", i + 1)
+        if j == -1:
+            return False
+        field = text[i + 1 : j]
+        for sep in ("[", "]", "!", ":"):
+            field = field.replace(sep, ".")
+        if any(is_dunder(part.strip()) for part in field.split(".")):
+            return True
+        i = j + 1
+
+
+@dataclass(frozen=True)
+class Violation:
+    kind: str
+    detail: str
+
+    def __str__(self) -> str:
+        return f"{self.kind}: {self.detail}"
+
+
+def inspect(code: str) -> list[Violation]:
+    """Structural violations in the given source.
+
+    Code that does not parse is a violation rather than a pass. Unparseable input must not reach
+    an executor, and reporting it as clean would be the same defect as a probe whose failure
+    returns zero.
+    """
+    try:
+        tree = ast.parse(code)
+    except SyntaxError as exc:
+        return [Violation("syntax", f"code does not parse ({exc.msg})")]
+
+    found: list[Violation] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import | ast.ImportFrom):
+            found.append(Violation("import", "import statement"))
+        elif isinstance(node, ast.Attribute) and is_dunder(node.attr):
+            found.append(
+                Violation("reflection", f"dunder attribute access ({node.attr})")
+            )
+        elif isinstance(node, ast.Name) and node.id in FORBIDDEN_NAMES:
+            found.append(Violation("builtin", f"forbidden name ({node.id})"))
+        elif isinstance(node, ast.Constant) and isinstance(node.value, str):
+            if is_dunder(node.value):
+                found.append(
+                    Violation("reflection", f"dunder string literal ({node.value})")
+                )
+            elif format_field_reaches_dunder(node.value):
+                found.append(Violation("reflection", "dunder inside a format field"))
+    return found
+
+
+def is_acceptable(code: str) -> bool:
+    """Whether the code passes the pre-filter. Passing is not a guarantee of safety."""
+    return not inspect(code)

agentic_base/config.py

@@ -0,0 +1,24 @@
+"""Application settings related files."""
+
+from functools import cache
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings for this service."""
+
+    log_level: str = "INFO"
+    log_json_format: bool = False
+    log_plain_traceback: bool = False
+    project_name: str = "Agentic Platform"
+    metrics_port: int = 9000
+    database_url: str = "sqlite:///./agentic-base.db"
+    """PostgreSQL in every deployed environment; SQLite locally so the service runs with no infrastructure."""
+
+
+@cache
+def get_settings() -> Settings:
+    """Retrieve the application settings."""
+
+    return Settings()

agentic_base/db.py

@@ -0,0 +1,42 @@
+"""Database wiring.
+
+SQLModel over PostgreSQL in every deployed environment, which the platform provides as a
+tenant resource. SQLite is the local-development and test default so the service can be run
+and tested without infrastructure.
+"""
+
+from collections.abc import Iterator
+from functools import cache
+
+from sqlmodel import Session, SQLModel, create_engine
+
+from agentic_base.config import get_settings
+
+
+@cache
+def get_engine():  # noqa: ANN201 - engine type is a SQLAlchemy internal
+    """Create the process-wide engine."""
+    settings = get_settings()
+    connect_args = (
+        {"check_same_thread": False}
+        if settings.database_url.startswith("sqlite")
+        else {}
+    )
+    return create_engine(settings.database_url, connect_args=connect_args)
+
+
+def init_db() -> None:
+    """Create tables that do not exist yet.
+
+    Schema evolution in a deployed environment is Alembic's job. This exists so that local
+    runs and tests do not need a migration step.
+    """
+    import agentic_base.domain.run_record  # noqa: F401  - registers the table
+
+    SQLModel.metadata.create_all(get_engine())
+
+
+def get_session() -> Iterator[Session]:
+    """FastAPI dependency yielding a session."""
+    with Session(get_engine()) as session:
+        yield session

agentic_base/domain/__init__.py

@@ -0,0 +1 @@
+"""Domain models. The core carries mechanism and no application vocabulary."""

agentic_base/domain/epochs.py

@@ -0,0 +1,187 @@
+"""Declaring that a commit changed what a field means.
+
+A configuration fingerprint tells you two runs were configured the same way. It cannot tell you
+that the code underneath that configuration changed meaning between them, and that is where the
+expensive mistakes live. In the predecessor project every serious wound was a code change landing
+in the middle of a corpus: an arm that ran with the mechanism its own label said was disabled, a
+retrieval default flipping so that the same absent setting meant opposite things on either side,
+a benchmark whose scoring changed under a stable name.
+
+What saved or damaged us each time was whether someone had declared the boundary. So this is a
+small table of declarations, and a classifier that puts a record before a boundary, after it, or
+in the honest third state.
+
+The third state matters more than the other two. A record whose code revision is unknown cannot
+be placed, and guessing is how a corpus quietly mixes two things. Pooling across an unknown is
+refused, not estimated.
+
+This costs almost nothing today and cannot be added later, because a boundary cannot be declared
+for records that never recorded which code produced them.
+"""
+
+from __future__ import annotations
+
+import enum
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field
+
+
+class Epoch(str, enum.Enum):
+    BEFORE = "before"
+    AFTER = "after"
+    UNKNOWN = "unknown"
+    """The record cannot be placed. Not an error, and not poolable."""
+
+
+class MeaningChange(BaseModel):
+    """One declaration that a commit changed what something means.
+
+    A plain model rather than a table. Applying a boundary is what every consumer needs;
+    storing one is what this service happens to do, and a consumer that imports the classifier
+    must not thereby acquire a database driver.
+    """
+
+    commit: str = Field(description="The commit at which the new meaning starts.")
+    subject: str = Field(
+        description="What changed meaning: a field name, a metric, an arm label, a scorer.",
+    )
+    description: str = Field(description="What it meant before, and what it means now.")
+    component: str = Field(
+        default="",
+        description=(
+            "Which component changed. Empty means this application's own code, placed by its "
+            "revision. Named means a dependency, placed by the version the run recorded for it."
+        ),
+    )
+    min_version: str = Field(
+        default="",
+        description="First version of that component carrying the new meaning.",
+    )
+    effective_at: datetime = Field(
+        description=(
+            "When the commit landed. Used to place records whose own commit is not one we know "
+            "about, which is most of them."
+        )
+    )
+    declared_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    declared_by: str = Field(default="")
+
+
+@dataclass(frozen=True)
+class PoolVerdict:
+    """Whether a set of records may be compared as one population."""
+
+    poolable: bool
+    subject: str
+    counts: dict[Epoch, int]
+    reason: str = ""
+
+    @property
+    def records_examined(self) -> int:
+        return sum(self.counts.values())
+
+    def summary(self) -> str:
+        if self.records_examined == 0:
+            return f"inconclusive: no records examined for {self.subject!r}"
+        if self.poolable:
+            return f"poolable: {self.records_examined} records, all on one side of {self.subject!r}"
+        return f"not poolable: {self.reason}"
+
+
+def _version_tuple(value: str) -> tuple[int, ...] | None:
+    """Numeric parts of a dotted version, or None when it cannot be read as one.
+
+    Unreadable is not the same as old. A version this cannot parse yields no placement rather than
+    a guess, because a guess here silently pools two populations.
+    """
+    parts: list[int] = []
+    for chunk in value.split("."):
+        digits = "".join(c for c in chunk if c.isdigit())
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts) or None
+
+
+def classify(record, change: MeaningChange) -> Epoch:
+    """Place one record relative to one declared boundary.
+
+    A record whose own revision is the declaring commit is on the new side, because the commit is
+    the first to carry the new meaning.
+
+    A boundary declared on a component is placed by the version the run recorded for it. A run that
+    recorded no version for that component cannot be placed, which is the case that appears the
+    moment an application starts importing a library that moves underneath it.
+    """
+    if change.component:
+        versions = getattr(record, "component_versions", None) or {}
+        seen = versions.get(change.component)
+        if not seen or not change.min_version:
+            return Epoch.UNKNOWN
+        left, right = _version_tuple(seen), _version_tuple(change.min_version)
+        if left is None or right is None:
+            return Epoch.UNKNOWN
+        return Epoch.AFTER if left >= right else Epoch.BEFORE
+
+    revision = getattr(record, "code_revision", "") or ""
+    if revision and revision == change.commit:
+        return Epoch.AFTER
+
+    created = getattr(record, "created_at", None)
+    if created is None or change.effective_at is None:
+        return Epoch.UNKNOWN
+
+    # A record with no recorded revision can still be placed by time, but only if we accept that
+    # a rebuilt or backfilled record may carry a misleading timestamp. Say so at the call site.
+    if not revision:
+        return Epoch.UNKNOWN
+
+    record_at = created if created.tzinfo else created.replace(tzinfo=timezone.utc)
+    boundary_at = (
+        change.effective_at
+        if change.effective_at.tzinfo
+        else change.effective_at.replace(tzinfo=timezone.utc)
+    )
+    return Epoch.AFTER if record_at >= boundary_at else Epoch.BEFORE
+
+
+def classify_all(records: Iterable, change: MeaningChange) -> dict[Epoch, int]:
+    """Count how a set of records falls either side of a boundary."""
+    counts = {Epoch.BEFORE: 0, Epoch.AFTER: 0, Epoch.UNKNOWN: 0}
+    for record in records:
+        counts[classify(record, change)] += 1
+    return counts
+
+
+def check_poolable(records: Sequence, change: MeaningChange) -> PoolVerdict:
+    """Whether these records may be treated as one population across this boundary.
+
+    Refused when they straddle the boundary, and refused when any record cannot be placed. The
+    second refusal is the one that feels excessive and is the one that pays: an unplaceable record
+    is exactly the case where a guess is invisible afterwards.
+    """
+    counts = classify_all(records, change)
+    if counts[Epoch.UNKNOWN]:
+        return PoolVerdict(
+            poolable=False,
+            subject=change.subject,
+            counts=counts,
+            reason=(
+                f"{counts[Epoch.UNKNOWN]} record(s) carry no usable code revision, so they cannot "
+                f"be placed relative to {change.commit}"
+            ),
+        )
+    if counts[Epoch.BEFORE] and counts[Epoch.AFTER]:
+        return PoolVerdict(
+            poolable=False,
+            subject=change.subject,
+            counts=counts,
+            reason=(
+                f"records straddle {change.commit}: {counts[Epoch.BEFORE]} before and "
+                f"{counts[Epoch.AFTER]} after, where {change.subject!r} changed meaning"
+            ),
+        )
+    return PoolVerdict(poolable=True, subject=change.subject, counts=counts)

agentic_base/domain/integrity.py

@@ -0,0 +1,135 @@
+"""Integrity of the run record chain.
+
+Not tamper-evidence, which presupposes an adversary this platform does not have. This detects
+accidental edits, partial writes and silent corruption in a corpus nobody can afford to re-run,
+which is a smaller claim and the one the mechanism actually supports.
+
+Both regimes the platform has to answer to ask for records that can be shown to be intact. The
+AI Act asks providers of high-risk systems to keep automatically generated logs; the Digital
+Omnibus of July 2026 moved the Annex III date to December 2027 and left the requirement as it
+was. The Dutch Cybersecurity Act, in force since 15 August 2026 with no transition period, asks
+in-scope entities for incident handling and logging that stands up afterwards. In both cases a record that could have been edited after the
+fact is weaker evidence than one that could not.
+
+The mechanism here is deliberately modest. Each record gets a content hash over its
+audit-relevant fields, and each hash includes the previous one for its tenant, so removing or
+altering a record breaks every hash after it. This is a hash chain, not a ledger and not a
+signature. It detects tampering by anyone who does not rewrite the whole chain, which covers
+accident and casual edits. It does not defend against an attacker with write access to the
+database and the will to recompute, and it should never be described as if it does.
+
+Verification is a separate function from creation so it can be run on demand and on a schedule,
+which is what makes it evidence rather than decoration.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+GENESIS = "0" * 64
+"""The previous hash of the first record in a tenant's chain."""
+
+AUDIT_FIELDS = (
+    "run_id",
+    "created_at",
+    "tenant",
+    "item",
+    "arm",
+    "arm_fingerprint",
+    "model",
+    "endpoint",
+    "precision",
+    "code_revision",
+    "status",
+    "failure_kind",
+    "resolved",
+    "label_source",
+    "degraded",
+    "instrument",
+)
+"""Fields covered by the hash.
+
+Deliberately excludes the transcript. A transcript can be very large and is stored alongside
+rather than inline, so hashing it here would make verification cost the whole corpus. What is
+covered is the part an audit turns on: what ran, under what configuration, what was decided, and
+who decided it.
+"""
+
+
+def _canonical(values: dict[str, Any]) -> bytes:
+    """Stable bytes for a mapping, so the same record always hashes the same way."""
+    return json.dumps(
+        values, sort_keys=True, separators=(",", ":"), default=str
+    ).encode("utf-8")
+
+
+def content_hash(record: Any, previous_hash: str = GENESIS) -> str:
+    """Hash of a record's audit fields, chained to the previous record for its tenant."""
+    values = {field: getattr(record, field, None) for field in AUDIT_FIELDS}
+    values["previous_hash"] = previous_hash
+    return hashlib.sha256(_canonical(values)).hexdigest()
+
+
+@dataclass(frozen=True)
+class ChainVerdict:
+    """Whether a chain is intact, and enough context to read a clean result honestly."""
+
+    intact: bool
+    records_checked: int
+    first_broken_index: int | None = None
+    detail: str = ""
+
+    @property
+    def could_have_failed(self) -> bool:
+        """False when the input was too short to demonstrate anything.
+
+        An empty or single-record chain verifies trivially. Reporting that as intact without
+        saying so invites it to be read as evidence.
+        """
+        return self.records_checked >= 2
+
+    def summary(self) -> str:
+        if not self.could_have_failed:
+            return f"inconclusive: {self.records_checked} record(s), too few to verify a chain"
+        if self.intact:
+            return f"intact: {self.records_checked} records verified"
+        return f"broken at index {self.first_broken_index}: {self.detail}"
+
+
+def build_chain(records: Sequence[Any]) -> list[str]:
+    """Hashes for a sequence of records in the order they were written."""
+    hashes: list[str] = []
+    previous = GENESIS
+    for record in records:
+        previous = content_hash(record, previous)
+        hashes.append(previous)
+    return hashes
+
+
+def verify_chain(records: Sequence[Any], hashes: Iterable[str]) -> ChainVerdict:
+    """Recompute a chain and report the first place it diverges."""
+    stored = list(hashes)
+    if len(stored) != len(records):
+        return ChainVerdict(
+            intact=False,
+            records_checked=min(len(stored), len(records)),
+            first_broken_index=min(len(stored), len(records)),
+            detail=f"{len(records)} records against {len(stored)} hashes",
+        )
+
+    previous = GENESIS
+    for index, (record, expected) in enumerate(zip(records, stored, strict=True)):
+        actual = content_hash(record, previous)
+        if actual != expected:
+            return ChainVerdict(
+                intact=False,
+                records_checked=len(records),
+                first_broken_index=index,
+                detail="record content does not match its recorded hash",
+            )
+        previous = actual
+    return ChainVerdict(intact=True, records_checked=len(records))