augur-sdk 0.1.0__py3-none-any.whl

augur_sdk/__init__.py

@@ -0,0 +1,60 @@
+"""Augur SDK — public surface.
+
+Spec §6. The capture controller, event recorder, redaction pipeline, and
+bundle writer are exposed here. Adapter authors should import from
+`augur_sdk.adapter` and `augur_sdk.models`.
+"""
+
+from augur_sdk._version import SUPPORTED_SCHEMA_RANGE, __version__
+from augur_sdk.adapter import Adapter
+from augur_sdk.capture import CaptureMode, resolve_capture_mode
+from augur_sdk.models import (
+    Action,
+    BundleManifest,
+    BundleTrace,
+    DecisionEvent,
+    DiagnosticFinding,
+    Grounding,
+    Observation,
+    RecoveryDecision,
+    ReplayFixture,
+    StepTrace,
+    Verdict,
+)
+from augur_sdk.models import (
+    DebugSession as DebugSessionRecord,
+)
+from augur_sdk.redaction import (
+    DEFAULT_POLICY_ID,
+    DefaultRedactionPolicy,
+    RedactionPolicy,
+)
+from augur_sdk.session import DebugSession
+from augur_sdk.storage import LocalFSStore, S3Store, Store
+
+__all__ = [
+    "Action",
+    "Adapter",
+    "BundleManifest",
+    "BundleTrace",
+    "CaptureMode",
+    "DEFAULT_POLICY_ID",
+    "DebugSession",
+    "DebugSessionRecord",
+    "DecisionEvent",
+    "DefaultRedactionPolicy",
+    "DiagnosticFinding",
+    "Grounding",
+    "LocalFSStore",
+    "Observation",
+    "RecoveryDecision",
+    "RedactionPolicy",
+    "ReplayFixture",
+    "S3Store",
+    "StepTrace",
+    "Store",
+    "SUPPORTED_SCHEMA_RANGE",
+    "Verdict",
+    "__version__",
+    "resolve_capture_mode",
+]

augur_sdk/_schema/__init__.py

@@ -0,0 +1,93 @@
+"""Vendored JSON Schema package.
+
+Canonical Augur record schemas live here so the SDK has zero runtime
+dependency on a sibling `augur-schema` package. The schemas are
+byte-identical with the upstream `packages/schema/` in the main Augur
+monorepo — keep them in sync when bumping versions.
+
+See `docs/versioning.md` upstream for the schema versioning policy.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import cache
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import ValidationError
+from referencing import Registry, Resource
+from referencing.jsonschema import DRAFT202012
+
+SCHEMA_VERSION = "0.1"
+
+_SCHEMA_FILES: dict[str, str] = {
+    "manifest": "manifest.schema.json",
+    "trace": "trace.schema.json",
+    "debug_session": "debug_session.schema.json",
+    "step_trace": "step_trace.schema.json",
+    "observation": "observation.schema.json",
+    "decision_event": "decision_event.schema.json",
+    "replay_fixture": "replay_fixture.schema.json",
+    "diagnostic_finding": "diagnostic_finding.schema.json",
+    "coordinate_space": "coordinate_space.schema.json",
+    "provenance": "provenance.schema.json",
+    "capture_mode": "capture_mode.schema.json",
+    "failure_class": "failure_class.schema.json",
+}
+
+
+class SchemaError(Exception):
+    """Wraps schema lookup and validation failures."""
+
+
+def schemas_dir() -> Path:
+    """Return the on-disk path to the bundled JSON Schemas."""
+    return Path(resources.files("augur_sdk._schema") / "json")  # type: ignore[arg-type]
+
+
+def list_schemas() -> list[str]:
+    return sorted(_SCHEMA_FILES)
+
+
+@cache
+def load_schema(name: str) -> dict[str, Any]:
+    filename = _SCHEMA_FILES.get(name, name)
+    path = schemas_dir() / filename
+    if not path.exists():
+        raise SchemaError(f"unknown schema: {name!r}")
+    with path.open() as f:
+        loaded: dict[str, Any] = json.load(f)
+    return loaded
+
+
+@cache
+def _registry() -> Registry:
+    """Pre-register every schema by `$id` and filename so cross-schema
+    `$ref`s resolve without going to the network."""
+    resources_list: list[tuple[str, Resource[Any]]] = []
+    for short, filename in _SCHEMA_FILES.items():
+        schema = load_schema(short)
+        resource = DRAFT202012.create_resource(schema)
+        if "$id" in schema:
+            resources_list.append((schema["$id"], resource))
+        resources_list.append((filename, resource))
+    return Registry().with_resources(resources_list)
+
+
+def validator_for(name: str) -> Draft202012Validator:
+    schema = load_schema(name)
+    return Draft202012Validator(schema, registry=_registry())
+
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "SchemaError",
+    "ValidationError",
+    "list_schemas",
+    "load_schema",
+    "schemas_dir",
+    "validator_for",
+]

augur_sdk/_schema/json/capture_mode.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/capture_mode.schema.json",
+  "title": "CaptureMode",
+  "description": "Augur capture mode (spec §7). Ordered from least to most coverage.",
+  "type": "string",
+  "enum": [
+    "off",
+    "metadata",
+    "trace",
+    "screenshots",
+    "video",
+    "model_io",
+    "dispatch",
+    "replay",
+    "full"
+  ]
+}

augur_sdk/_schema/json/coordinate_space.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/coordinate_space.schema.json",
+  "title": "CoordinateSpace",
+  "description": "Coordinate space registry (spec §4, §9, issue #9). Every coordinate MUST be tagged with one of these spaces so viewers can render overlays correctly across viewport sizes and device pixel ratios.",
+  "type": "string",
+  "enum": [
+    "viewport_css_px",
+    "device_px",
+    "screenshot_px",
+    "dom_client_rect"
+  ],
+  "x-conversions": {
+    "note": "Conversion rules are non-normative here. See packages/sdk-python/src/augur_sdk/coordinates.py for the reference impl.",
+    "viewport_css_px<->device_px": "multiply by device_scale_factor on the source observation",
+    "viewport_css_px<->screenshot_px": "screenshots are captured at viewport scale by default; otherwise multiply by screenshot_scale",
+    "dom_client_rect": "Diagnostic-only space. MUST be paired with provenance=dom. Never a runtime input (spec §4)."
+  }
+}

augur_sdk/_schema/json/debug_session.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/debug_session.schema.json",
+  "title": "DebugSession",
+  "description": "One CUA run from the debugger's point of view. Spec §8.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "debug_session_id",
+    "run_id",
+    "client",
+    "capture_mode",
+    "started_at",
+    "status"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "description": "Augur schema version that this record conforms to. See docs/versioning.md.",
+      "pattern": "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$"
+    },
+    "debug_session_id": {
+      "type": "string",
+      "pattern": "^dbg_[A-Za-z0-9_\\-]+$"
+    },
+    "run_id": {
+      "type": "string",
+      "description": "Adapter-supplied run id. Often `run_<uuid>` but the format is not enforced."
+    },
+    "client": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string", "description": "Adapter name, e.g. `mantis`."},
+        "version": {"type": "string"},
+        "git_sha": {"type": "string"}
+      }
+    },
+    "capture_mode": {"$ref": "capture_mode.schema.json"},
+    "started_at": {"type": "string", "format": "date-time"},
+    "ended_at": {"type": ["string", "null"], "format": "date-time"},
+    "status": {
+      "type": "string",
+      "enum": ["running", "succeeded", "failed", "cancelled", "halted"]
+    },
+    "artifact_root": {
+      "type": "string",
+      "description": "URI to the artifact root. file:// for local bundles, s3:// or https:// otherwise."
+    },
+    "trace_uri": {"type": "string"},
+    "live": {
+      "type": ["object", "null"],
+      "description": "Live attach endpoints. Only populated while the run is active (spec §7, Phase 4).",
+      "additionalProperties": false,
+      "properties": {
+        "status_url": {"type": "string"},
+        "video_url": {"type": "string"},
+        "reasoning_url": {"type": "string"}
+      }
+    },
+    "tags": {
+      "type": "object",
+      "additionalProperties": {"type": "string"},
+      "description": "Free-form key/value tags (tenant, environment, plan signature, etc.)."
+    }
+  }
+}

augur_sdk/_schema/json/decision_event.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/decision_event.schema.json",
+  "title": "DecisionEvent",
+  "description": "An ordered record from planner, verifier, recovery, routing, or dispatch layers (spec §8). Stored one-per-line in JSONL files under events/.",
+  "type": "object",
+  "required": ["ts", "layer", "kind", "summary"],
+  "additionalProperties": false,
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 UTC timestamp."
+    },
+    "step_index": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Optional — events MAY be associated with a step or stand alone."
+    },
+    "layer": {
+      "type": "string",
+      "enum": [
+        "planner",
+        "grounding",
+        "model",
+        "dispatch",
+        "verifier",
+        "step_recovery",
+        "routing",
+        "runner",
+        "adapter"
+      ]
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["decision", "observation", "error", "info", "metric"]
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-line human summary. The detail object carries the structured payload."
+    },
+    "detail": {
+      "type": "object",
+      "description": "Layer-specific structured payload. Schema is intentionally open here; adapters MAY define their own shapes.",
+      "additionalProperties": true
+    }
+  }
+}

augur_sdk/_schema/json/diagnostic_finding.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/diagnostic_finding.schema.json",
+  "title": "DiagnosticFinding",
+  "description": "One output of the diagnostic rules engine. Spec §15.",
+  "type": "object",
+  "required": ["rule_id", "severity", "summary", "evidence"],
+  "additionalProperties": false,
+  "properties": {
+    "rule_id": {
+      "type": "string",
+      "description": "Stable rule identifier. Generic rules use `cua.*`; adapter packs MUST namespace under `<adapter>.*`.",
+      "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$"
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "low", "medium", "high", "critical"]
+    },
+    "summary": {"type": "string"},
+    "recommendation": {"type": "string"},
+    "step_index": {"type": "integer", "minimum": 0},
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "description": "At least one evidence reference. Each MUST point at a bundle-relative path. Optional `#L<n>` or `#L<a>-L<b>` anchors are honored for log refs.",
+      "items": {
+        "type": "object",
+        "required": ["type", "ref"],
+        "additionalProperties": false,
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": ["log", "step", "event", "screenshot", "diff", "crop", "trace"]
+          },
+          "ref": {"type": "string"}
+        }
+      }
+    }
+  }
+}

augur_sdk/_schema/json/failure_class.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/failure_class.schema.json",
+  "title": "FailureClass",
+  "description": "Generic CUA failure taxonomy. Adapter-specific failure classes MUST namespace under `<adapter>.<class>` (e.g. `mantis.modal_signature_missing`). Open string so adapters can extend without a schema bump; the diagnostic rules engine owns the authoritative list per pack.",
+  "type": "string",
+  "examples": [
+    "no_state_change",
+    "click_outside_viewport",
+    "coordinate_space_mismatch",
+    "verifier_disagrees",
+    "dispatch_ok_state_fail",
+    "invalid_action_schema",
+    "missing_observation",
+    "infra_failure",
+    "model_timeout",
+    "som_clicked_container",
+    "tab_walk_target_absent"
+  ],
+  "minLength": 1
+}

augur_sdk/_schema/json/manifest.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/manifest.schema.json",
+  "title": "BundleManifest",
+  "description": "Envelope for an Augur debug bundle. Spec §11. Lives at `manifest.json` at the bundle root.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "bundle_format",
+    "run_id",
+    "debug_session_id",
+    "client",
+    "capture_mode",
+    "created_at",
+    "trace",
+    "step_count",
+    "paths"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$",
+      "description": "Augur schema version that every record in this bundle conforms to."
+    },
+    "bundle_format": {
+      "type": "string",
+      "const": "augur-bundle",
+      "description": "Constant discriminator so consumers can sniff Augur bundles without parsing the rest."
+    },
+    "run_id": {"type": "string"},
+    "debug_session_id": {
+      "type": "string",
+      "pattern": "^dbg_[A-Za-z0-9_\\-]+$"
+    },
+    "client": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string"},
+        "version": {"type": "string"},
+        "git_sha": {"type": "string"}
+      }
+    },
+    "capture_mode": {"$ref": "capture_mode.schema.json"},
+    "created_at": {"type": "string", "format": "date-time"},
+    "redaction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["policy_id"],
+      "properties": {
+        "policy_id": {"type": "string"},
+        "applied": {"type": "boolean", "default": true}
+      }
+    },
+    "trace": {
+      "type": "string",
+      "description": "Bundle-relative path to the trace document (see trace.schema.json).",
+      "const": "trace.json"
+    },
+    "step_count": {"type": "integer", "minimum": 0},
+    "paths": {
+      "type": "object",
+      "description": "Path-stability map. Producers MUST emit exactly these top-level paths so consumers can rely on them.",
+      "additionalProperties": false,
+      "required": ["steps", "screenshots", "events", "logs"],
+      "properties": {
+        "steps": {"type": "string", "const": "steps/"},
+        "screenshots": {"type": "string", "const": "screenshots/"},
+        "crops": {"type": "string", "const": "crops/"},
+        "diffs": {"type": "string", "const": "diffs/"},
+        "events": {"type": "string", "const": "events/"},
+        "logs": {"type": "string", "const": "logs/"},
+        "replay": {"type": "string", "const": "replay/"},
+        "diagnostics": {"type": "string", "const": "diagnostics/"},
+        "schema": {"type": "string", "const": "schema/"},
+        "agent": {"type": "string", "const": "AGENT.md"}
+      }
+    },
+    "signatures": {
+      "type": "object",
+      "description": "Optional content hashes for integrity. Keys are bundle-relative file paths; values are sha256 hex digests.",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[0-9a-f]{64}$"
+      }
+    },
+    "missing": {
+      "type": "array",
+      "description": "Bundle-relative paths that are explicitly absent (e.g. screenshots before late-attach point). Consumers MUST treat anything not listed and not present as a producer bug.",
+      "items": {"type": "string"}
+    }
+  }
+}

augur_sdk/_schema/json/observation.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/observation.schema.json",
+  "title": "Observation",
+  "description": "A captured screenshot with enough metadata to render overlays correctly (spec §8).",
+  "type": "object",
+  "required": [
+    "artifact",
+    "media_type",
+    "width",
+    "height",
+    "coordinate_space"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "artifact": {
+      "type": "string",
+      "description": "Bundle-relative path or signed URI to the image."
+    },
+    "media_type": {
+      "type": "string",
+      "enum": ["image/png", "image/jpeg", "image/webp"]
+    },
+    "width": {"type": "integer", "minimum": 1},
+    "height": {"type": "integer", "minimum": 1},
+    "coordinate_space": {"$ref": "coordinate_space.schema.json"},
+    "viewport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["width", "height"],
+      "properties": {
+        "width": {"type": "integer", "minimum": 1},
+        "height": {"type": "integer", "minimum": 1},
+        "device_scale_factor": {"type": "number", "minimum": 0, "default": 1}
+      }
+    },
+    "url": {"type": "string"},
+    "title": {"type": "string"},
+    "scroll": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["x", "y"],
+      "properties": {
+        "x": {"type": "integer"},
+        "y": {"type": "integer"}
+      }
+    },
+    "hashes": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+        "phash_64": {
+          "type": "string",
+          "description": "64-bit perceptual hash, hex-encoded."
+        }
+      }
+    },
+    "redaction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["applied"],
+      "properties": {
+        "applied": {"type": "boolean"},
+        "policy_id": {"type": "string"},
+        "regions": {
+          "type": "array",
+          "description": "Optional list of regions that were masked.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["x1", "y1", "x2", "y2"],
+            "properties": {
+              "x1": {"type": "integer"},
+              "y1": {"type": "integer"},
+              "x2": {"type": "integer"},
+              "y2": {"type": "integer"},
+              "label": {"type": "string"}
+            }
+          }
+        }
+      }
+    },
+    "missing": {
+      "type": "boolean",
+      "default": false,
+      "description": "True if this observation is a placeholder for a frame that was not captured (e.g. late attach). The `artifact` MUST still be present but the consumer MUST NOT render a screenshot."
+    }
+  }
+}

augur_sdk/_schema/json/provenance.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/provenance.schema.json",
+  "title": "Provenance",
+  "description": "How a coordinate or signal was derived (spec §4). The viewer MUST visually distinguish non-CUA diagnostic evidence (dom, diagnostic).",
+  "type": "string",
+  "enum": [
+    "screenshot",
+    "dom",
+    "human_override",
+    "replay_candidate",
+    "diagnostic"
+  ]
+}

augur_sdk/_schema/json/replay_fixture.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://augur.dev/schemas/0.1/replay_fixture.schema.json",
+  "title": "ReplayFixture",
+  "description": "Seed data for replaying a single step (spec §8, §10). The fixture MUST be self-contained relative to the bundle.",
+  "type": "object",
+  "required": ["fixture_id", "step_id", "mode", "observation"],
+  "additionalProperties": false,
+  "properties": {
+    "fixture_id": {"type": "string"},
+    "step_id": {"type": "string"},
+    "mode": {
+      "type": "string",
+      "enum": [
+        "observation_replay",
+        "handler_replay",
+        "model_replay",
+        "sandbox_replay",
+        "shadow_replay"
+      ]
+    },
+    "task": {
+      "type": "string",
+      "description": "Human-readable task/intent string passed back to the agent under test."
+    },
+    "observation": {
+      "type": "string",
+      "description": "Bundle-relative path to the observation PNG used as the replay input."
+    },
+    "prior_steps": {
+      "type": ["string", "null"],
+      "description": "Bundle-relative path to a JSON file containing the prior steps' summaries (action + verdict only)."
+    },
+    "expected": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "action_type": {"type": "string"},
+        "acceptable_regions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["x1", "y1", "x2", "y2"],
+            "additionalProperties": false,
+            "properties": {
+              "x1": {"type": "number"},
+              "y1": {"type": "number"},
+              "x2": {"type": "number"},
+              "y2": {"type": "number"},
+              "label": {"type": "string"}
+            }
+          }
+        },
+        "verdict_status": {
+          "type": "string",
+          "enum": ["passed", "failed", "recoverable", "skipped", "unknown"]
+        }
+      }
+    },
+    "captured_versions": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Versions in effect when the fixture was captured. Replay output MUST also record the versions in effect at replay time so deltas can be attributed.",
+      "properties": {
+        "model": {"type": "string"},
+        "prompt": {"type": "string"},
+        "code_git_sha": {"type": "string"},
+        "grounder": {"type": "string"}
+      }
+    }
+  }
+}