agent-tokenops 0.1.0__tar.gz

agent_tokenops-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,263 @@
+<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/pyproject.toml

@@ -0,0 +1,85 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-tokenops"
+version = "0.1.0"
+description = "TokenOps control plane and SDK for run-aware agent token governance"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE.txt"]
+authors = [
+  { name = "Susheem Koul" },
+  { name = "Tisha Chawla" },
+]
+keywords = [
+  "llm",
+  "agents",
+  "governance",
+  "token-budget",
+  "multi-agent",
+  "control-plane",
+  "cost-control",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = [
+  "agent-chronicle>=0.1.1",
+  "openai>=1.0",
+  "anthropic>=0.40",
+  "pyyaml>=6.0",
+  "python-dotenv>=1.0",
+  "streamlit>=1.30",
+  "httpx>=0.27",
+  "fastapi>=0.115",
+  "uvicorn>=0.32",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "build>=1.2",
+  "twine>=6.0",
+]
+examples = [
+  "ddgs>=9.0",
+  "langchain-core>=0.3",
+  "langchain-openai>=0.2",
+  "langchain-anthropic>=0.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/theagentplane/tokenops"
+Repository = "https://github.com/theagentplane/tokenops"
+Issues = "https://github.com/theagentplane/tokenops/issues"
+Changelog = "https://github.com/theagentplane/tokenops/blob/main/CHANGELOG.md"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "."]
+markers = [
+  "e2e: example / bench end-to-end tests (not run in default CI)",
+  "live: requires API keys or vendored frameworks",
+]
+addopts = "-m 'not e2e and not live'"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["tokenops*"]
+
+# Ship the default governance YAML with the wheel (loader resolves via Path(__file__)).
+[tool.setuptools.package-data]
+tokenops = ["config/*.yaml"]

agent_tokenops-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+