agent-tokenops 0.1.0__py3-none-any.whl

agent_tokenops-0.1.0.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: agent-tokenops
+Version: 0.1.0
+Summary: TokenOps control plane and SDK for run-aware agent token governance
+Author: Susheem Koul, Tisha Chawla
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/theagentplane/tokenops
+Project-URL: Repository, https://github.com/theagentplane/tokenops
+Project-URL: Issues, https://github.com/theagentplane/tokenops/issues
+Project-URL: Changelog, https://github.com/theagentplane/tokenops/blob/main/CHANGELOG.md
+Keywords: llm,agents,governance,token-budget,multi-agent,control-plane,cost-control
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: agent-chronicle>=0.1.1
+Requires-Dist: openai>=1.0
+Requires-Dist: anthropic>=0.40
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: streamlit>=1.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.32
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: ddgs>=9.0; extra == "examples"
+Requires-Dist: langchain-core>=0.3; extra == "examples"
+Requires-Dist: langchain-openai>=0.2; extra == "examples"
+Requires-Dist: langchain-anthropic>=0.2; extra == "examples"
+Dynamic: license-file
+
+<div align="center">
+
+# TokenOps
+
+**Run-aware token governance for multi-agent systems.**<br>
+Cap spend and steer behavior across a whole agent workflow — not per request — with a shared ledger and in-path enforcement.
+
+[![CI](https://github.com/theagentplane/tokenops/actions/workflows/test.yml/badge.svg)](https://github.com/theagentplane/tokenops/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-tokenops.svg)](https://pypi.org/project/agent-tokenops/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://github.com/theagentplane/tokenops)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+[![Status](https://img.shields.io/badge/status-0.x%20%7C%20draft-7B61FF?style=flat-square)](https://semver.org/)
+[![Stars](https://img.shields.io/github/stars/theagentplane/tokenops?style=flat&color=yellow)](https://github.com/theagentplane/tokenops/stargazers)
+
+<br>
+
+<img src="https://raw.githubusercontent.com/theagentplane/tokenops/main/examples/demo-assets/videos/02_governance_on_budget_cap.png" alt="TokenOps Dashboard: governance halt when worst-case cost exceeds remaining run budget" width="720" />
+
+</div>
+
+<br>
+
+TokenOps is a **control plane + SDK** for agent stacks. Entry agents register a run; every LLM and tool crossing shares one `run_id` and one ledger. Policies can halt, mutate, or inject before the next call executes — so a research → summarize → review pipeline stays inside a single budget even across processes.
+
+**[Why](#why-tokenops) · [Architecture](#architecture) · [Install](#install) · [Quick start](#quick-start) · [Demos](#demos) · [Comparison](#how-tokenops-compares) · [Make targets](#make-targets) · [Roadmap](#roadmap)**
+
+## Why TokenOps
+
+- **Govern the run, not the request.** One `run_id` spans every model, tool, and A2A hop in a workflow.
+- **Shared ledger across processes.** Spend, inflight, and halt live in SQLite so multi-agent stacks cannot each burn the full cap locally.
+- **In-path enforcement.** `wrap_complete` runs detect → decide → apply *before* the next LLM call; Chronicle `@boundary` + a crossing hook ingest tool spend.
+- **Steer or stop.** Actuators: `HALT` · `MUTATE` · `INJECT` · reject/queue — not just post-hoc analytics.
+- **Batteries included.** Control plane (`:7700`), Admin + Dashboard UI, ten seeded policies, and runnable A2A benches (two-agent, triad, LangChain brief).
+
+## Architecture
+
+TokenOps is two layers that share one artifact, the **run**: a control plane that registers runs and stores budgets/policies, and an in-process SDK that enforces at every boundary crossing.
+
+```mermaid
+flowchart LR
+    subgraph PLANE["Control plane (:7700)"]
+        R["POST /v1/runs"] --> DB[("SQLite TOKENOPS_DB<br/>registrations · budgets · policies · ledger")]
+        UI["Admin + Dashboard"] --> DB
+    end
+
+    subgraph AGENTS["Agent processes (SDK)"]
+        E["Entry agent<br/>entry_task_run_scope"] -->|"register_run"| R
+        E -->|"X-TokenOps-Run-Id"| D["Downstream agents"]
+        E & D -->|"wrap_complete"| G["Governor<br/>pre_call → detect → decide → apply"]
+        E & D -->|"@boundary + crossing hook"| G
+        G --> L["Shared ledger<br/>(same run_id)"]
+    end
+
+    L --> DB
+    DB -->|"governance_config_for"| G
+```
+
+| Piece | Owns | Does not own |
+|---|---|---|
+| **Control plane** (`python -m tokenops.server`) | `POST /v1/runs`, shared SQLite, Admin/Dashboard | Agent loops, LLM calls, tools |
+| **SDK (in agents)** | `wrap_complete`, ledger/policies, Chronicle crossing hook, run propagation | Ad-hoc run IDs; mounting `/v1/runs` when `TOKENOPS_URL` is set |
+
+Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See [Chronicle](https://github.com/theagentplane/chronicle) for record-and-replay.
+
+## Install
+
+```bash
+pip install agent-tokenops
+
+# With example / bench extras (LangChain, ddgs):
+pip install "agent-tokenops[examples]"
+
+# From source (development):
+pip install -e ".[dev,examples]"
+```
+
+Requires Python 3.10+. PyPI name is `agent-tokenops`; import is still `tokenops`
+(same pattern as Chronicle). See [`RELEASING.md`](RELEASING.md) for releases.
+
+## Quick start
+
+```bash
+make install
+cp .env.example .env   # optional API keys for demos / your agents
+
+make db-reset          # optional: clean SQLite + seed governance from default.yaml
+make run               # control plane :7700 + Admin/Dashboard :8501
+```
+
+Wire governance into an agent: register the run at the **entry**, wrap the LLM, and install the Chronicle crossing hook for tools.
+
+```python
+from tokenops import ControlPlaneClient
+from tokenops.control import (
+    wrap_complete,
+    entry_task_run_scope,
+    governance_scope,
+    install_crossing_hook,
+)
+from tokenops.providers import complete
+
+install_crossing_hook()  # once per process; Chronicle on_crossing → Governor.observe
+
+client = ControlPlaneClient.from_env()  # TOKENOPS_URL or embedded Store
+
+# Entry agent: UI omits run_id; entry opens the run on the plane
+with entry_task_run_scope(store, headers=headers, payload=payload, service="planner"):
+    with governance_scope(governor, attr, provider=..., model=...):
+        governed = wrap_complete(
+            governor, controls, attr,
+            provider=provider, model=model,
+            dispatch=complete, service="planner",
+        )
+        run_agent(..., complete_fn=governed)
+```
+
+Point agents at the plane and share one DB:
+
+```bash
+export TOKENOPS_URL=http://localhost:7700
+export TOKENOPS_DB=tokenops.db   # plane + all agents
+make control-plane               # :7700
+make ui                          # Admin + Dashboard :8501
+```
+
+Full integration checklist: [`.cursor/skills/integrate-tokenops/SKILL.md`](.cursor/skills/integrate-tokenops/SKILL.md) · field guide: [`docs/guides/field-guide-add-tokenops.md`](docs/guides/field-guide-add-tokenops.md).
+
+## Demos
+
+Each bench is a multi-agent stack with a shared run ledger. Start the plane, agents, and Admin UI with one make target.
+
+| Demo | Agents | Run |
+|---|---|---|
+| Two-agent | Research → Summarize | `make demo` |
+| Triad | Planner → Researcher → Writer | `make demo-triad` |
+| Brief | Scout → Analyst → Editor (LangChain) | `make demo-brief` |
+| Bench UI | Chat + Simulator only | `make bench-ui` |
+
+```bash
+make demo              # plane + research/summarize + Admin UI
+make demo-triad        # plane + planner/researcher/writer
+make demo-brief        # plane + scout/analyst/editor
+```
+
+Docker:
+
+```bash
+docker compose up --build
+# optional UI: docker compose --profile ui up --build
+# two-agent stack:
+docker compose -f docker-compose.examples.yml up --build
+```
+
+See [`examples/README.md`](examples/README.md) and [`docs/control-plane-deploy.md`](docs/control-plane-deploy.md).
+
+## How TokenOps compares
+
+TokenOps is not a gateway or a tracing dashboard. It governs the **run** — a full agent workflow — and sits alongside the tools you already use for routing and observability.
+
+| | TokenOps | LiteLLM / Portkey / AI Gateway | Langfuse |
+|---|:---:|:---:|:---:|
+| Primary focus | Run (stateful) | Request | Trace (observe) |
+| Multi-agent workflow as one unit | Yes | No | Manual stitch |
+| Budget enforcement in-path | Yes (run-aware) | Yes (key/team) | No (analytics) |
+| Steer next call (mutate / inject) | Yes | Routing / fallbacks | No |
+| Shared ledger across agent processes | Yes | N/A | N/A |
+
+What this does **not** do: replace your LLM gateway, replace Chronicle-style record-and-replay, or host a SaaS control plane for you. Fail-closed integrity (refuse on missing registration) is optional and upcoming.
+
+Longer table with logos: [`docs/product/comparison.md`](docs/product/comparison.md).
+
+## Make targets
+
+<details>
+<summary>Command reference</summary>
+
+| Target | Role |
+|--------|------|
+| `make install` | Editable install with dev + examples extras |
+| `make dist` / `check-dist` | Build sdist+wheel / `twine check` |
+| `make control-plane` | Standalone plane (`python -m tokenops.server`) on `:7700` |
+| `make ui` | Admin + Dashboard on `:8501` |
+| `make run` | Plane + Admin/Dashboard |
+| `make demo` / `demo-triad` / `demo-brief` | Runnable A2A stacks |
+| `make bench-ui` | Chat + Simulator |
+| `make db-reset` | Clear SQLite + reseed from `TOKENOPS_CONFIG` |
+| `make stop` | Kill listeners on `:7700` / `:8501` |
+
+</details>
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `TOKENOPS_URL` | Remote plane base URL (e.g. `http://localhost:7700`) → HTTP `register_run` |
+| `TOKENOPS_EMBEDDED` | Set to `1` to force in-process `Store` (tests / single-process) |
+| `TOKENOPS_DB` | SQLite path shared by plane + agents |
+| `TOKENOPS_CONFIG` | YAML for governance seed (core: `src/tokenops/config/default.yaml`) |
+
+Production / multi-process: set `TOKENOPS_URL`; agents must **not** mount `/v1/runs`. Tests: `TOKENOPS_EMBEDDED=1` (or omit URL).
+
+## Project structure
+
+Only `src/tokenops/` is the installable package. Demos and benches stay under `examples/`.
+
+```
+src/tokenops/              # installable package
+├── server/                # control plane (:7700, POST /v1/runs)
+├── control/               # SDK: ledger, policies, wrap_complete, crossing hook
+├── providers/             # OpenAI / Anthropic complete dispatch
+├── config/                # default.yaml governance seed
+└── ui/                    # Admin + Dashboard (Streamlit)
+examples/                  # A2A benches (two-agent, triad, brief) + Chat/Simulator
+benchmarking/              # MetaGPT / browser-use live harness
+docs/                      # architecture, policies, guides, product
+tests/                     # unit + e2e
+```
+
+## Roadmap
+
+TokenOps is early (0.x). Near-term:
+
+- User/tag segment-scoped budgets (machinery exists; seed is run-only today).
+- Optional fail-closed mode on missing registration or exceeded budget.
+- Remote observe / decide (fatter plane) for multi-host stacks.
+- Documentation site.
+
+Status of each control-plane job: [`CONTROL_PLANE.md`](CONTROL_PLANE.md). Ideas welcome via GitHub issues.
+
+## Documentation
+
+- [Control plane status](CONTROL_PLANE.md)
+- [Architecture](docs/architecture.md)
+- [Run attribution](docs/run-attribution.md)
+- [Control plane deploy](docs/control-plane-deploy.md)
+- [Field guide](docs/guides/field-guide-add-tokenops.md)
+- [Examples](examples/README.md)
+- [Product: comparison](docs/product/comparison.md) · [shared ledger](docs/product/shared-ledger.md)
+
+## Contributing
+
+Issues and PRs are welcome. Dev setup:
+
+```bash
+make install
+python -m pytest -q
+```
+
+## Contributors
+
+Thanks to everyone who has contributed.
+
+[![Contributors](https://contrib.rocks/image?repo=theagentplane/tokenops)](https://github.com/theagentplane/tokenops/graphs/contributors)
+
+---
+
+If TokenOps saves you a runaway agent bill, please [⭐ star the repo](https://github.com/theagentplane/tokenops) so more people can find it.
+
+<div align="center">
+
+Built by Susheem Koul and Tisha Chawla
+
+</div>

agent_tokenops-0.1.0.dist-info/RECORD

@@ -0,0 +1,63 @@
+agent_tokenops-0.1.0.dist-info/licenses/LICENSE.txt,sha256=pflS2CCLsAIr6pIhUOZSJudBKOC5c0R-B4s5OcO3Lb4,1086
+tokenops/__init__.py,sha256=F9jVo9QvXx-NrfbuLB2ZirWX0Y4_sw6l0Ork-SlKurg,300
+tokenops/env.py,sha256=-97XzDyMajrkmRtu9ZyPT0t2JmfTuQKJZmqu4bcbyU0,510
+tokenops/config/__init__.py,sha256=9NdrlHt040-ZKdU2u-VdtQXnW0HSSoR2pTbx7rSyhVA,92
+tokenops/config/default.yaml,sha256=DbLQeb1OxwVU89OM8Xxfq7WLh1qmSQV2zhaW651yV1Y,956
+tokenops/config/loader.py,sha256=5mMMvC_2S3Pt7NkXkm09o_8GHR9NmC8XLpu-TmNhy4A,824
+tokenops/control/__init__.py,sha256=4eEUCHIf7yGr7fdfeZI6L5JQUk7rSecZye6uupgm7yY,3802
+tokenops/control/attribution.py,sha256=kDyfjXyJOv8_Q-cGMAr-mDtwu9ms77oRaPcZhaHXnBc,6174
+tokenops/control/boundary.py,sha256=8c9uaplqdKIXbEA3JlJn0dh6SV52jiEN0_DzaA1W20o,4586
+tokenops/control/client.py,sha256=zTq-hsG_AGx3Y710nmv1ypZ95narMrL8G-Z4XUxoc-c,5014
+tokenops/control/config.py,sha256=UF_LkpTOK4_viojr4wPHXqWEC3F2dR2g3p6lF6ORv4k,6732
+tokenops/control/context.py,sha256=IiGuKhDPeOdaqPwDyPvA6h9SsEpt1Yl0pZCwWrAeEQM,3612
+tokenops/control/core.py,sha256=EOXEdFjZeehUxiX2W15wBOs3VB9WWKSl4KzrxS-CpBw,11809
+tokenops/control/crossing.py,sha256=C7Wc5yDLuN7JM63UI3ZTLa5pRvNgaXQzN8O2_fRS6Qk,3323
+tokenops/control/engine.py,sha256=PoJ9G2LGnj8UE6oSrTmxEzSQxDm_3iSRL9n5ah4WUZM,12164
+tokenops/control/http.py,sha256=tl3Xvr-Duhb6Z7ayAkT1A_gHTaOEoD9W0Io50oU4HFE,4460
+tokenops/control/integration.py,sha256=sh5a577c7NqAHugVAGj6a06iWcXw22bSTmixSako38Y,13211
+tokenops/control/ledger.py,sha256=azouZ8F67Ki-IAdl0qAr2JHC8xj9fhy7RrzjAZfmZ1Q,12421
+tokenops/control/models.py,sha256=a55xCutw7lFyXjAdBpfqNa50ZvSGxtShFJVgWzUe3qA,3686
+tokenops/control/pricing.py,sha256=k8DRnAx7hEQU8Gfcl4BcqWSJNbGlGHgUhbvxrZ_pi1M,2521
+tokenops/control/propagate.py,sha256=rIbgugNL0E8VtoGTBzLudivee6gspx4eS9_h-LKnOfc,1458
+tokenops/control/store.py,sha256=WupP0vkYgvZZvEw1HWGaUnZEd0f43zReRdzKzE80v5A,28726
+tokenops/control/policies/__init__.py,sha256=ockfgVmW8IQZUPF5KlSib2RElWZSUhVFO7SWUWDszGo,812
+tokenops/control/policies/_util.py,sha256=yLCepRFcI24grWlLrYBTCTo2EQjUgc2_Q2jukyrCwxw,2969
+tokenops/control/policies/concurrency_cap.py,sha256=EcY6_ayeXfNoyDUqZlZS-px-F2PykOze-PuLn81zPPk,2942
+tokenops/control/policies/context_compaction.py,sha256=nlrLOmG0TajyoJkijdReJkOjNYiRe4AX1a4A-Yn_efE,3335
+tokenops/control/policies/cost_budget.py,sha256=CtwdJkPT2dfPbS2Tpq1VCqjvUBezJ8bQpS5vwEvBPq8,2475
+tokenops/control/policies/cost_guard.py,sha256=cd4nENinLXkGgUHFPW9QN8RoAygcDKFG3uDIE3DFoPA,4019
+tokenops/control/policies/output_runaway.py,sha256=UkmQJDFrfV5qZJdSEnRvC0rQAQ7OJGlWanRNpism7iA,3838
+tokenops/control/policies/pre_call_worst_case.py,sha256=fs842tt4B0QS6p3vsEImKNx2pHG7nG6l2pCc1iShO6s,4411
+tokenops/control/policies/progress_guard.py,sha256=tuVHHd__5khe-ToQOobBETtcYoRwSr8OpIPkp8wqb2Q,4490
+tokenops/control/policies/step_cap.py,sha256=qEXDLCx7Xp2qveX-fiagdL5xeyevG0IM41Prc06xEr4,1781
+tokenops/control/policies/tool_fix.py,sha256=z0_ZOPJUoqtEyYhYbJcE-9l_ssUPBspKb2hk5Hjw3FE,3754
+tokenops/control/policies/tool_output_cap.py,sha256=aC9he9esKMZNHy6pT2QLVXj-Hjz7GjEZQQRN5KZQP10,3458
+tokenops/control/policies/trajectory_hint.py,sha256=FA8nfOGuEpP1qfCPVySmnMtyj_0dC0_G6taPu_-Xruk,9071
+tokenops/control/trajectory/__init__.py,sha256=iSpsn4ZUPUqFoHSA_bDGcAkbL7kpu7UmZkYfYgCRXrM,571
+tokenops/control/trajectory/compress.py,sha256=rI75aR7vEYU01ZquPMaIIRxQ6QODwJbNeqbE61Iy8pc,1507
+tokenops/control/trajectory/enqueue.py,sha256=ETq2Id_pnHLOr4gyq1Lt1E8si-WLn5OtBFzNnaFTj8I,2165
+tokenops/control/trajectory/gates.py,sha256=FajuRbrVr9iUbcjf1WtE1sUL0FtVyDc3_cD1HB9-2Gc,1014
+tokenops/control/trajectory/hint.py,sha256=b5rJFPQpLZYuTZwdUxMPNA76iOur43-6xeMHnY6momc,2391
+tokenops/control/trajectory/scope.py,sha256=zZxt9z4-sz-ezzhTV9aS0uSHc0qRWRAMd5SfvqztvGQ,1796
+tokenops/control/trajectory/serialize.py,sha256=oxBHyKhHlRnp8OybsrprMwjuatSK4wg0-hGnU91iMdI,1909
+tokenops/control/trajectory/worker.py,sha256=nTpIJf5A7t0d7u_0jdC3JH3oju7M9aTr6wfsnVQFf8E,766
+tokenops/providers/__init__.py,sha256=q65odkbUvGJ2y28j9E2NwJbRRTesVtjdcQCXISNs1JI,176
+tokenops/providers/anthropic.py,sha256=uA0_0vbtQxmY3jnRZBRbQ1JKGUP_Pgw1eTR8ji_DwrQ,1101
+tokenops/providers/factory.py,sha256=aLEGVNQf44uQDv8MKsCC-Af5fs5uU7uVUC9Dzz1RHAQ,1898
+tokenops/providers/openai.py,sha256=BHJbOkYr3j15SSfPo_iu8oUtmFD9sCrP20RHKI0zsDQ,2549
+tokenops/providers/types.py,sha256=hYwEhL1FIsM7VXR5zHbeXGOBULDP4eWzlRfpgepu06o,174
+tokenops/server/__init__.py,sha256=jNWsprfEaSGrAeYISIuXX-M_hR9td4oy_P5PRAp9o20,124
+tokenops/server/__main__.py,sha256=gm3oqpJit2csUb4ZG4rH2ZAJV4F6evWot0Go_6lR4Eo,557
+tokenops/server/app.py,sha256=qh7OuDpC7kTzhBpZNjTS0-aSUMpDiLREms3tfwtz-00,1164
+tokenops/ui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tokenops/ui/app.py,sha256=4RroN7XQTbiNrdnuu0X4NsKbYbB_677bzPqYKVXbUMs,600
+tokenops/ui/run_detail.py,sha256=aLGwbQ-bWkm9-iVJvnG1qR8DVpyauLsqo0Dabi4Y-YQ,4197
+tokenops/ui/store_client.py,sha256=X-WyVzUpd8LjmxLdYHKrs8BE5HU1QVefZdijG48recg,842
+tokenops/ui/theme.py,sha256=sz-voqQ_RKPWdZ1Igx4eVL8YhIjWVnvKUx9vhBoC5OY,4306
+tokenops/ui/views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tokenops/ui/views/admin.py,sha256=1KoxHmJlkFxZBdkCipiTiyfZNGjVOGFz6J0qav-Afpg,11342
+tokenops/ui/views/dashboard.py,sha256=_slUKO5Oy6cigz3X3TylqPLPaWbUK3ZU6gUI3l2wJCs,5573
+agent_tokenops-0.1.0.dist-info/METADATA,sha256=SbOHh3DozfdKt_qEdKSFdRh4VUZ50nrGW1YBEhKuo00,12774
+agent_tokenops-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agent_tokenops-0.1.0.dist-info/top_level.txt,sha256=MVWkw-7ZGkeuBcMqJ4Dp_r6ovKtrjxSnjLPOnAzE-qg,9
+agent_tokenops-0.1.0.dist-info/RECORD,,

agent_tokenops-0.1.0.dist-info/WHEEL

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

agent_tokenops-0.1.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tisha Chawla and Susheem Koul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_tokenops-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tokenops

tokenops/__init__.py

@@ -0,0 +1,12 @@
+"""TokenOps control plane and SDK."""
+
+from tokenops.env import load_env
+
+load_env()
+
+__version__ = "0.1.0"
+
+# First-class SDK surface for agents / UIs talking to the plane.
+from tokenops.control.client import ControlPlaneClient as ControlPlaneClient
+
+__all__ = ["ControlPlaneClient", "__version__"]

tokenops/config/__init__.py

@@ -0,0 +1,3 @@
+from tokenops.config.loader import load_governance_yaml
+
+__all__ = ["load_governance_yaml"]

tokenops/config/default.yaml

@@ -0,0 +1,37 @@
+# TokenOps control plane seed. Consumed by tokenops.control.build_governor / Store auto-seed.
+# Budgets are spend caps bound to a segment; policies are the (detect, fix) templates.
+governance:
+  budgets:
+    - id: run_llm_cap
+      limit_micros: 2000000          # $2.00 per run; null/omitted -> unlimited accumulator
+      dimension: run
+  policies:
+    cost_budget:
+      budget: run_llm_cap
+    pre_call_worst_case:
+      budget: run_llm_cap
+      default_max_output: 1024
+    step_cap:
+      max_steps: 20
+    concurrency_cap:
+      max_concurrent: 4
+      mode: reject
+    tool_fix:
+      registry: [search]
+      k: 3
+    tool_output_cap:
+      cap_tokens: 8000
+    progress_guard:
+      window: 6
+      repeats: 3
+      max_corrections: 2
+    cost_guard:
+      budget: run_llm_cap
+      threshold: 0.8
+      mode: minimize
+    context_compaction:
+      ctx_max: 100000
+      has_hook: false
+    output_runaway:
+      repeats: 4
+      max_retries: 2

tokenops/config/loader.py

@@ -0,0 +1,30 @@
+"""Governance YAML loading for the TokenOps control plane.
+
+Agent/server bench config lives under ``examples.app_config``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+DEFAULT_CONFIG = Path(__file__).resolve().parent / "default.yaml"
+
+
+def _default_path() -> Path:
+    env = os.environ.get("TOKENOPS_CONFIG")
+    if env:
+        return Path(env)
+    return DEFAULT_CONFIG
+
+
+def load_governance_yaml(path: Path | str | None = None) -> dict:
+    """Return the ``governance:`` block from the config YAML (budgets + policies)."""
+    config_path = Path(path) if path else _default_path()
+    if not config_path.exists():
+        return {}
+    data = yaml.safe_load(config_path.read_text()) or {}
+    block = data.get("governance")
+    return block if isinstance(block, dict) else {}

tokenops/control/__init__.py

@@ -0,0 +1,111 @@
+"""TokenOps control layer (v1).
+
+The Account (ledger) + Enforce (policies) half of the control plane. Consumes
+attributed boundary crossings, records them, and decides: steer or stop.
+
+Ten policies (delegation_cap dropped — fan-out is concurrency_cap, spend is
+cost_budget / pre_call_worst_case), evaluated by moment:
+  pre_call : concurrency_cap, tool_fix, context_compaction, cost_guard, pre_call_worst_case
+  stream   : output_runaway
+  observe  : cost_budget, step_cap, tool_output_cap, progress_guard
+
+Source of truth: docs/policies/ and docs/governance-policy.md. ``core.py`` is the
+canonical vocabulary.
+"""
+
+from tokenops.control.core import (
+    Action,
+    ActionKind,
+    Attribution,
+    BoundaryStep,
+    CallRequest,
+    Detector,
+    Halt,
+    LedgerView,
+    Observation,
+    Policy,
+    Severity,
+    Signal,
+    Usage,
+)
+from tokenops.control.config import build_governor, build_governance_stack
+from tokenops.control.engine import (
+    AgentControls,
+    ApplyControls,
+    Governor,
+    PreviewControls,
+    RaiseControls,
+    Throttled,
+    governance_events_payload,
+    halt_detector_from_events,
+)
+from tokenops.control.integration import (
+    apply_carry_to_messages,
+    consume_carry,
+    make_on_step,
+    step_to_observation,
+    wrap_complete,
+    wrap_stream,
+)
+from tokenops.control.ledger import Budget, Ledger, RunState, segment_key
+from tokenops.control.attribution import (
+    begin_downstream_run,
+    begin_entry_run,
+    begin_entry_task_run,
+    build_attribution,
+    downstream_run_scope,
+    entry_run_scope,
+    entry_task_run_scope,
+    require_registration,
+)
+from tokenops.control.context import (
+    PARENT_SPAN_ID_HEADER,
+    RUN_ID_HEADER,
+    GovernanceContext,
+    SpanContext,
+    governance_scope,
+)
+from tokenops.control.boundary import emit_observation, observation_from_crossing
+from tokenops.control.crossing import install_crossing_hook, on_crossing
+
+# Process-wide: re-attach after every reset_session (Chronicle clears on_crossing).
+install_crossing_hook()
+
+from tokenops.control.http import (
+    mount_run_registration,
+    post_run,
+    post_run_sync,
+    with_governance_errors,
+)
+from tokenops.control.client import ControlPlaneClient, should_mount_run_registration
+from tokenops.control.models import GovernanceMode, RunRegistration, parse_governance_mode
+from tokenops.control.propagate import merge_propagation_headers, propagation_headers
+
+__all__ = [
+    # vocabulary
+    "Action", "ActionKind", "Attribution", "BoundaryStep", "CallRequest",
+    "Detector", "Halt", "LedgerView", "Observation", "Policy", "Severity",
+    "Signal", "Usage",
+    # ledger
+    "Budget", "Ledger", "RunState", "segment_key",
+    # harness
+    "Governor", "RaiseControls", "AgentControls", "ApplyControls", "PreviewControls", "Throttled",
+    # config factory
+    "build_governor", "build_governance_stack",
+    # data-plane integration
+    "make_on_step", "wrap_complete", "wrap_stream", "apply_carry_to_messages", "consume_carry",
+    "step_to_observation",
+    # attribution
+    "RunRegistration", "GovernanceMode", "parse_governance_mode", "build_attribution", "begin_entry_run", "begin_downstream_run",
+    "begin_entry_task_run",
+    "require_registration", "entry_run_scope", "entry_task_run_scope", "downstream_run_scope",
+    "RUN_ID_HEADER", "PARENT_SPAN_ID_HEADER", "SpanContext", "GovernanceContext",
+    "governance_scope", "observation_from_crossing", "emit_observation",
+    # Chronicle crossing hook
+    "install_crossing_hook", "on_crossing",
+    # HTTP (A2A mount + clients)
+    "mount_run_registration", "with_governance_errors", "post_run", "post_run_sync",
+    "ControlPlaneClient", "should_mount_run_registration",
+    # HTTP propagation (auto run_id / parent span)
+    "propagation_headers", "merge_propagation_headers",
+]