{"id":50295182,"url":"https://github.com/mercurialsolo/augur-sdk","last_synced_at":"2026-05-28T08:32:10.481Z","repository":{"id":358992964,"uuid":"1244034994","full_name":"mercurialsolo/augur-sdk","owner":"mercurialsolo","description":"Instrument any screenshot-grounded computer-use agent (CUA). Local bundle writer + Sentry-style DSN streaming.","archived":false,"fork":false,"pushed_at":"2026-05-20T00:59:00.000Z","size":269,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T01:53:37.883Z","etag":null,"topics":["computer-use","cua","debugger","instrumentation","observability","python","sdk"],"latest_commit_sha":null,"homepage":"https://mercurialsolo.github.io/augur-sdk/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mercurialsolo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T22:51:18.000Z","updated_at":"2026-05-20T00:59:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mercurialsolo/augur-sdk","commit_stats":null,"previous_names":["mercurialsolo/augur-sdk"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mercurialsolo/augur-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Faugur-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Faugur-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Faugur-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Faugur-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mercurialsolo","download_url":"https://codeload.github.com/mercurialsolo/augur-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Faugur-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33601380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-use","cua","debugger","instrumentation","observability","python","sdk"],"created_at":"2026-05-28T08:32:09.863Z","updated_at":"2026-05-28T08:32:10.475Z","avatar_url":"https://github.com/mercurialsolo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# augur-sdk\n\n[![PyPI](https://img.shields.io/pypi/v/augur-sdk.svg)](https://pypi.org/project/augur-sdk/)\n[![Python](https://img.shields.io/pypi/pyversions/augur-sdk.svg)](https://pypi.org/project/augur-sdk/)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)\n[![Docs](https://img.shields.io/badge/docs-mercurialsolo.github.io/augur--sdk-blue.svg)](https://mercurialsolo.github.io/augur-sdk/)\n\n**Full docs:** https://mercurialsolo.github.io/augur-sdk/\n\nInstrument any **screenshot-grounded computer-use agent** (CUA) with one\ncontext manager. Streams traces to **Augur** (a hosted cloud service for\nCUA observability) over a Sentry-style DSN AND writes a path-stable\nbundle to disk — both work, both at once, no extra glue.\n\n\u003e This is the **public client SDK**. The Augur server, viewer, and CLI\n\u003e are a managed cloud service — sign up at augur (URL TBD) to get a DSN.\n\u003e The SDK also works standalone in local-bundle mode with no account.\n\n```python\nfrom augur_sdk import CaptureMode, DebugSession\n\nwith DebugSession(\n    run_id=\"run_abc\",\n    client_name=\"myagent\",\n    capture_mode=CaptureMode.SCREENSHOTS,\n    out_dir=\"/var/log/augur/run_abc\",\n) as session:\n    pre  = session.attach_observation(step_index=0, kind=\"pre\",  png_bytes=...)\n    post = session.attach_observation(step_index=0, kind=\"post\", png_bytes=...)\n    session.record_step({\n        \"step_id\":          \"run_abc/step/0000\",\n        \"step_index\":       0,\n        \"step_type\":        \"click\",\n        \"intent\":           \"Click the login button\",\n        \"status\":           \"succeeded\",\n        \"started_at\":       \"2026-05-19T00:00:00Z\",\n        \"observation_pre\":  pre,\n        \"observation_post\": post,\n        \"action\":   {\"type\": \"click\", \"params\": {\"x\": 100, \"y\": 200},\n                     \"coordinate_space\": \"viewport_css_px\",\n                     \"dispatch_backend\": \"playwright\"},\n        \"grounding\": {\"provider\": \"myagent\", \"provenance\": \"screenshot\"},\n        \"verdict\":   {\"status\": \"passed\"},\n    })\n```\n\nSet `AUGUR_DSN=…` and the same code streams to your Augur server. No code\nchange required to switch between local-only and hosted modes.\n\n## Install\n\n### From PyPI (when published)\n\n```bash\npip install augur-sdk\n# or\nuv pip install augur-sdk\n```\n\n### From source (today)\n\n```bash\ngit clone https://github.com/mercurialsolo/augur-sdk.git\ncd augur-sdk\npip install -e .\n# or\nuv pip install -e .\n```\n\n### Requirements\n\n- Python ≥ 3.11\n- `jsonschema`, `referencing`, `urllib3` (installed automatically)\n\nThe SDK is self-contained: JSON Schemas are vendored inside the package\n(`augur_sdk._schema`), so `import augur_sdk` requires no other Augur\ncomponents. The Augur server, viewer, and CLI are operated as a hosted\nservice — you only need this package on the **client side** (your CUA\nruntime).\n\n## Quickstart — three modes\n\n### 1. Local-only (no server)\n\nThe default. Bundles are written under `out_dir/`. Use `augur view \u003cdir\u003e`\nfrom the main Augur repo to render them in the viewer, or hand the path\nto a coding agent.\n\n```python\nfrom augur_sdk import CaptureMode, DebugSession\n\nwith DebugSession(\n    run_id=\"run_abc\",\n    client_name=\"myagent\",\n    out_dir=\"/var/log/augur/run_abc\",\n    capture_mode=CaptureMode.SCREENSHOTS,\n) as session:\n    ...\n```\n\n### 2. Stream to an Augur server (Sentry-style)\n\nSet one env var; nothing else changes.\n\n```bash\nexport AUGUR_DSN='https://augur.example/api/v1?token=\u003capi_key\u003e\u0026tenant=\u003ctenant_slug\u003e'\n```\n\nThe SDK heart-beats every 15 s while a session is open so the server's\nconnection-status indicator stays green. Each step + screenshot + event\nstreams over HTTPS with `Authorization: Bearer \u003capi_key\u003e`. The local\nbundle is still written; streaming is observe-only on top.\n\nOr pass the DSN directly:\n\n```python\nDebugSession(dsn=\"https://augur.example/api/v1?token=...\u0026tenant=...\", ...)\n```\n\nGet a DSN by asking an Augur admin to run:\n\n```bash\naugur admin dsn-issue --tenant \u003cyour-tenant\u003e --label \u003cclient-name\u003e\n```\n\n### 3. Adapter pattern (existing CUA exports)\n\nAlready have a trace exporter (Mantis-style)? Write a small adapter that\nmaps your shape to Augur records. See the\n[adapter authoring guide](docs/reference/adapter-authoring.md).\n\n## What gets written\n\nEvery bundle is path-stable — no discovery needed:\n\n```text\nout_dir/\n  manifest.json           # envelope: schema_version, bundle_format, paths, signatures\n  trace.json              # session + ordered steps[]\n  AGENT.md                # coding-agent-friendly index (first-read hints, layout)\n  steps/0000.json         # one StepTrace per file\n  events/0000.jsonl       # decision events per step (planner / grounding / verifier / recovery)\n  screenshots/0000_pre.png\n  screenshots/0000_post.png\n  diagnostics/findings.json   # if `augur diagnose` has been run\n  schema/*.schema.json    # canonical record schemas (vendored for offline validation)\n```\n\nThe same bundle drives the viewer, the CLI, and any coding agent. See\n[`docs/concepts/bundle-layout.md`](docs/concepts/bundle-layout.md) for\nthe full normative spec.\n\n## Capture modes\n\nThe `capture_mode` arg controls how much the SDK writes:\n\n| Mode          | What it captures                                                | Cost |\n|---------------|-----------------------------------------------------------------|------|\n| `off`         | Manifest envelope only                                          | none |\n| `metadata`    | + run/step ids, status, action type, failure class              | tiny |\n| `trace`       | + decisions, verifier output, recovery, grounding summary       | low  |\n| `screenshots` | + pre/post PNGs + coordinate overlays                           | med  |\n| `video`       | + video / MJPEG references                                      | med  |\n| `model_io`    | + prompts, model responses, redacted secrets                    | med  |\n| `dispatch`    | + input dispatch details, retries, post-action state checks     | low  |\n| `replay`      | + observation/task/context state for replay fixtures            | med  |\n| `full`        | All above, subject to redaction + retention                     | high |\n\nSet via `capture_mode=CaptureMode.FULL` or `AUGUR_CAPTURE_MODE=full`.\n\n## Redaction\n\n`default-pii-v1` ships in the box and is applied to every bundle:\n\n- Drops `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` headers entirely.\n- Masks `token`, `api_key`, `ssn`, `credit_card`, `cvv` keys.\n- Regex-scrubs bearer tokens, AWS keys, JWTs, password=… patterns out of strings.\n- Honors `sensitive=True` on a step: pre/post screenshots are dropped.\n\nSubclass `augur_sdk.RedactionPolicy` for tighter rules:\n\n```python\nfrom augur_sdk import DebugSession, RedactionPolicy\n\nclass StrictPolicy(RedactionPolicy):\n    id = \"strict-v1\"\n    drop_keys = RedactionPolicy.drop_keys | frozenset({\"customer_email\"})\n\nDebugSession(redaction_policy=StrictPolicy(), ...)\n```\n\n## Diagnostics\n\nAugur ships a generic CUA rules pack you can run against any bundle:\n\n```python\nfrom augur_sdk.diagnostics import RulesEngine, load_pack\n\nengine = RulesEngine(load_pack(\"cua\"))\nfindings = engine.evaluate(\"/path/to/bundle\")\nfor f in findings:\n    print(f[\"severity\"], f[\"rule_id\"], f[\"summary\"])\n```\n\nAdapter-specific packs (e.g. `mantis`) are registered via the\n`augur.rule_packs` entry-point group; install the corresponding adapter\npackage alongside this SDK and they appear automatically in\n`load_pack(...)`.\n\n## CUA contract — what the SDK enforces\n\nPer Augur's design invariant: **runtime action selection MUST remain\nscreenshot-grounded**. The SDK doesn't enforce this at write time, but\nthe diagnostic-rules engine and the viewer both flag DOM-derived\ncoordinates that show up in `grounding.provenance != \"screenshot\"` and\nget used as runtime inputs. Tag DOM probes as `provenance: dom` so they\nstay visible as **diagnostic** evidence without being mistaken for the\nagent's real target.\n\n## Develop\n\n```bash\ngit clone https://github.com/mercurialsolo/augur-sdk.git\ncd augur-sdk\nuv sync                 # creates .venv and installs dev deps\nuv run pytest           # tests\nuv run ruff check .     # lint\nuv run mypy -p augur_sdk  # types\n```\n\n## Publish to PyPI\n\nReleases are tag-driven and run through `.github/workflows/release.yml`,\nwhich authenticates to PyPI via **OIDC Trusted Publishing** — no API\ntoken is stored anywhere.\n\n### One-time setup\n\n1. Register the project on PyPI as a pending publisher:\n   https://pypi.org/manage/account/publishing/\n   - PyPI project name: `augur-sdk`\n   - Owner: `mercurialsolo`\n   - Repository: `augur-sdk`\n   - Workflow name: `release.yml`\n   - Environment name: `pypi`\n2. (Optional) Pre-create the `pypi` GitHub Environment if you want to\n   gate releases behind required reviewers:\n\n   ```bash\n   gh api -X PUT /repos/mercurialsolo/augur-sdk/environments/pypi\n   ```\n\n### Cut a release\n\n1. Bump `__version__` in `src/augur_sdk/_version.py` and `version` in\n   `pyproject.toml`.\n2. Move the `[Unreleased]` block in `CHANGELOG.md` under the new version.\n3. Commit, tag, push:\n\n   ```bash\n   git commit -am \"Release v0.1.0\"\n   git tag v0.1.0 -m \"Initial release\"\n   git push origin main v0.1.0\n   ```\n\nThe tag push triggers `release.yml`: lint → typecheck → test → `uv build`\n→ publish to PyPI via OIDC. The wheel + sdist are also uploaded as\nworkflow artefacts.\n\n### Local build / manual upload (escape hatch)\n\nIf you need to publish outside CI (don't, normally):\n\n```bash\nuv build              # produces dist/*.whl + dist/*.tar.gz\nuv publish            # uses ~/.pypirc or UV_PUBLISH_TOKEN\n```\n\n## Where Augur lives\n\nAugur (server, viewer, CLI, diagnostic rule packs, Mantis adapter) is a\n**hosted cloud service** — not open source. This SDK is the only\ncomponent your CUA runtime needs; everything else is operated for you.\n\n- **Get a DSN / sign up**: contact your Augur workspace admin, or reach\n  out at the project email below.\n- **Issues for this SDK**: https://github.com/mercurialsolo/augur-sdk/issues\n- **Schemas**: vendored under `src/augur_sdk/_schema/json/` in this repo.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmercurialsolo%2Faugur-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmercurialsolo%2Faugur-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmercurialsolo%2Faugur-sdk/lists"}