agent-tokenops 0.2.0__tar.gz → 0.3.0__tar.gz

agent_tokenops-0.3.0/PKG-INFO

@@ -0,0 +1,402 @@
+Metadata-Version: 2.4
+Name: agent-tokenops
+Version: 0.3.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.3.0
+Requires-Dist: openai>=1.0
+Requires-Dist: anthropic>=0.40
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: streamlit<2,>=1.38
+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: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: mypy>=1.13; extra == "dev"
+Requires-Dist: pre-commit>=4.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Provides-Extra: contract
+Requires-Dist: agentplane-control-plane>=0.2.0; extra == "contract"
+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
+
+**Cuts wasted agent spend by up to `65%`, governing what the run has already spent before every call.**<br>
+<sub>Toward token governance as a first-class discipline, not an afterthought.</sub>
+
+[![PyPI](https://img.shields.io/pypi/v/agent-tokenops.svg)](https://pypi.org/project/agent-tokenops/)
+[![Downloads](https://img.shields.io/pepy/dt/agent-tokenops)](https://pepy.tech/project/agent-tokenops)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+[![GitHub stars](https://img.shields.io/github/stars/theagentplane/tokenops?style=social)](https://github.com/theagentplane/tokenops/stargazers)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?logo=linkedin&logoColor=white)](https://www.linkedin.com/company/the-agent-plane/)
+[![GitHub Discussions](https://img.shields.io/badge/Discussions-24292f?logo=github&logoColor=white)](https://github.com/theagentplane/tokenops/discussions)
+
+[![Featured by Microsoft Developer](https://img.shields.io/badge/Featured-Microsoft%20Developer-5E5E5E)](https://www.linkedin.com/posts/microsoft-developers_who-spent-all-the-tokens-tokenops-gives-activity-7499191980715982848-224b)
+[![Featured by Command Line](https://img.shields.io/badge/Featured-Command%20Line-5E5E5E)](https://commandline.microsoft.com/tokenops-real-time-run-scoped-cost-control-ai-agents/)
+[![Featured by AI Engineer World's Fair](https://img.shields.io/badge/Featured-AI%20Engineer%20World's%20Fair-FF0000?logo=youtube&logoColor=white)](https://www.youtube.com/watch?v=GJX19pNhmSw)
+
+<sub>Built by <b><a href="https://www.linkedin.com/in/susheemkoul/">Susheem Koul</a></b> and <b><a href="https://www.linkedin.com/in/tisha-chawla/">Tisha Chawla</a></b></sub>
+
+<table><tr><td>
+
+<img src="https://raw.githubusercontent.com/theagentplane/tokenops/main/docs/assets/devto-cover.png" alt="TokenOps: one budget for one whole agent run, enforced before every model call" width="720" />
+
+</td></tr></table>
+
+<sub><i>See it stop a run mid-budget in the <a href="#-quickstart">Quickstart</a> below.</i></sub>
+
+<br>
+
+[Core features](#-core-features) · [Quickstart](#-quickstart) · [Quickdeploy](#-quickdeploy) · [How it compares](#-how-tokenops-compares) · [Policies](docs/policies/) · [Support](#-support) · [Contributing](#-open-to-contribution)
+
+</div>
+
+> ### 🙌 Open to contribution
+>
+> Token spend deserves the same first-class attention as compute or latency, and
+> we are growing the community working on that. Policies, actuators, and the
+> shared ledger are all open to extension. See
+> **[CONTRIBUTING.md](CONTRIBUTING.md)** to get started.
+
+## ✨ Core features
+
+An AI agent's workflow can run up cost fast: dozens of small, individually
+cheap steps that quietly add up to a surprisingly large bill. TokenOps sets
+a single budget for the whole workflow and enforces it before every step,
+so spending never gets away from you.
+
+<img src="docs/assets/core-features.svg" alt="TokenOps core features: enforced pre-call, run-scoped budget, shared across processes, steers not just stops, tool calls count too, ten policies included" width="850" />
+
+Ten policies ship configured in [`docs/policies/`](docs/policies/), and you can
+add your own.
+
+## 🚀 Quickstart
+
+Requires Python 3.10+ and a running control plane — TokenOps has no ledger of its
+own, so every agent (even a single process) governs against one. Zero-setup taste:
+`python -m tokenops.demo` launches a throwaway plane for you automatically. For your
+own agent, start one first (see [Quickdeploy](#-quickdeploy) below), then:
+
+### 1. Put it in your agent
+
+> [!TIP]
+> **Recommended.** Your coding assistant reads
+> [`SKILL.md`](.claude/skills/integrate-tokenops/SKILL.md), wires the one
+> enforcement point into your agent, and tells you what to check.
+
+In **Claude Code**, from a clone:
+
+```
+/integrate-tokenops
+```
+
+Anywhere else (Cursor, Copilot, ...), paste this:
+
+> Integrate TokenOps into this agent, following
+> https://github.com/theagentplane/tokenops/blob/main/.claude/skills/integrate-tokenops/SKILL.md
+
+<details>
+<summary><b>Manual</b>, about ten lines</summary>
+
+Wrap your model call once, then hand the wrapped version to your agent. Needs
+`CONTROL_PLANE_URL` (or `TOKENOPS_URL`) pointing at a running control plane —
+see [Quickdeploy](#-quickdeploy).
+
+```python
+from tokenops import ControlPlaneClient, tokenops_run
+from tokenops.control import Halt, wrap_complete
+from tokenops.providers import complete
+
+client = ControlPlaneClient.from_env()  # raises if CONTROL_PLANE_URL isn't set
+
+with tokenops_run(client=client, service="my-agent", intent="research",
+                  provider="openai", model="gpt-4o") as bound:
+    governed = wrap_complete(
+        bound.governor, bound.controls, bound.attr,
+        provider="openai", model="gpt-4o",
+        dispatch=complete, service="my-agent",
+    )
+    try:
+        agent.run(..., complete_fn=governed)   # <-- pass `governed`, not `complete`
+    except Halt as stopped:
+        print(f"run stopped: {stopped}")
+```
+
+Pass `governed` to your agent instead of `complete`; nothing else changes.
+`wrap_complete` checks the budget before each call and raises `Halt` when the
+run is out, even from another process.
+
+</details>
+
+### 2. When you need more
+
+| You want to | Go to |
+|---|---|
+| Change the budget | [Set the budget](.claude/skills/integrate-tokenops/SKILL.md#set-the-budget) |
+| One budget across several agent processes | [Shared plane](.claude/skills/integrate-tokenops/SKILL.md#tier-2--several-processes-one-budget) |
+| FastAPI or A2A services | [Instrumented app](.claude/skills/integrate-tokenops/SKILL.md#tier-3--fastapi--a2a) |
+| Something other than stopping | [The ten policies](docs/policies/) |
+| Cost per agent in a dashboard | [Quickdeploy](#-quickdeploy) |
+| A worked end-to-end example | [Field guide](docs/guides/field-guide-add-tokenops.md) |
+| Everything else | [Onboarding guide](docs/guides/onboarding.md) |
+
+### 3. See it in action
+
+<table><tr><td>
+
+<a href="https://github.com/theagentplane/tokenops/raw/main/examples/demo-assets/videos/02_governance_on_budget_cap.webm">
+<img src="https://raw.githubusercontent.com/theagentplane/tokenops/main/examples/demo-assets/videos/02_governance_on_budget_cap.gif" alt="TokenOps demo: the same task run twice - ungoverned, it completes over budget; governed, TokenOps halts it within the cap - then the Dashboard shows spend and governance per agent" width="760" />
+</a>
+
+</td></tr></table>
+
+<sub><i>Same task, run twice: ungoverned it completes over budget, governed it halts within the cap, then the Dashboard attributes cost per agent. <a href="https://github.com/theagentplane/tokenops/raw/main/examples/demo-assets/videos/02_governance_on_budget_cap.webm">Full video</a>.</i></sub>
+
+## 🐳 Quickdeploy
+
+> [!TIP]
+> Every agent needs a control plane running — TokenOps has no ledger of its own.
+> A single-process agent still needs one, just not the multi-process sharing this
+> section is about. `python -m tokenops.server` powers the dashboard too.
+
+One command, plane + dashboard:
+
+```bash
+git clone https://github.com/theagentplane/tokenops && cd tokenops
+docker compose --profile ui up --build
+```
+
+Plane: `localhost:7700/health` · Dashboard: `localhost:8501`. Plane only:
+`docker compose up --build`. Details: [`docs/control-plane-deploy.md`](docs/control-plane-deploy.md).
+
+<details>
+<summary><b>Without Docker</b> (make)</summary>
+
+```bash
+git clone https://github.com/theagentplane/tokenops && cd tokenops
+make install
+make run          # control plane :7700 + Admin/Dashboard :8501
+```
+
+Then open `localhost:8501` to see spend and governance per agent.
+
+</details>
+
+<details>
+<summary><b>Multi-agent benches</b>: watch one budget span several agents</summary>
+
+Each is a real multi-agent stack sharing one run ledger. One target starts the
+plane, the agents, and the Admin UI.
+
+| Bench | Agents | Run |
+|---|---|---|
+| Two-agent | Research to Summarize | `make demo` |
+| Triad | Planner to Researcher to Writer | `make demo-triad` |
+| Brief | Scout to Analyst to Editor (LangChain) | `make demo-brief` |
+| Bench UI | Chat + Simulator only | `make bench-ui` |
+
+`cp .env.example .env` first if you want them to call real models. See
+[`examples/README.md`](examples/README.md) for the bench profiles.
+
+</details>
+
+<details>
+<summary><b>Pointing several processes at one plane</b></summary>
+
+```bash
+export TOKENOPS_URL=http://localhost:7700
+export TOKENOPS_DB=tokenops.db   # plane and every agent read the same file
+```
+
+> tokenops has no ledger of its own — every process governs against the plane at
+> `TOKENOPS_URL`. There is no local-fallback env var to accidentally leave unset.
+
+PyPI name is `agent-tokenops`; the import is `tokenops`. Extras:
+`pip install "agent-tokenops[examples]"` for the LangChain benches,
+`".[dev,examples]"` from source. Releases: [`RELEASING.md`](RELEASING.md).
+
+</details>
+
+## 🆚 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 | Request | Trace |
+| Multi-agent workflow as one unit | Yes | No | Partial |
+| Budget enforcement in-path | Yes | Yes | No |
+| Steer next call (mutate / inject) | Yes | Partial | No |
+| Shared ledger across processes | Yes | — | — |
+
+What this does **not** do: replace your LLM gateway, replace Chronicle-style record-and-replay, or host a SaaS control plane for you.
+
+Longer table with logos: [`docs/product/comparison.md`](docs/product/comparison.md).
+
+## Reference
+
+Things you will want eventually, not now.
+
+<details>
+<summary><b>Architecture: how the plane and the SDK split the work</b></summary>
+
+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/>tokenops_run"] -->|"register_run"| R
+        E -->|"X-TokenOps-Run-Id"| D["Downstream agents<br/>tokenops_run"]
+        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)** | `tokenops_run`, `wrap_complete`, ledger/policies, Chronicle crossing hook | 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, accepted at [REALM](https://realm-workshop.github.io/) (Research on Agent Language Models), a workshop at EMNLP 2026.
+
+</details>
+
+<details>
+<summary><b>Environment variables</b></summary>
+
+| Variable | Purpose |
+|---|---|
+| `TOKENOPS_URL` (or `CONTROL_PLANE_URL`) | The control plane's base URL (e.g. `http://localhost:8800`) — **required** |
+| `TOKENOPS_CONFIG` | YAML for governance seed (core: `src/tokenops/config/default.yaml`) |
+
+tokenops has no ledger or run registry of its own — `ControlPlaneClient.from_env()`
+raises if `TOKENOPS_URL`/`CONTROL_PLANE_URL` isn't set, rather than silently falling
+back to anything local. Every process talks to the same plane, so they share one
+budget by construction. `TOKENOPS_URL` also accepts the alias
+`TOKENOPS_CONTROL_PLANE_URL`.
+
+</details>
+
+<details>
+<summary><b>Make targets</b></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-quick` | `python -m tokenops.demo`: no API keys, no server |
+| `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` |
+| `make sync-skills` | Regenerate the editor copies of the integration skill |
+
+</details>
+
+<details>
+<summary><b>Project structure</b></summary>
+
+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
+```
+
+</details>
+
+<details>
+<summary><b>More documentation</b></summary>
+
+- [Onboarding](docs/guides/onboarding.md): prereqs, minimum integration, FAQ, current limits
+- [Field guide](docs/guides/field-guide-add-tokenops.md): a triad walked through, with screenshots
+- [Policies](docs/policies/): one page per policy
+- [Run attribution](docs/run-attribution.md) - [control plane deploy](docs/control-plane-deploy.md) - [status](docs/control-plane-status.md)
+- [Examples](examples/README.md) - [comparison](docs/product/comparison.md) - [shared ledger](docs/product/shared-ledger.md)
+
+</details>
+
+## 📰 Talks & press
+
+- **Featured by Microsoft Developer**: “Who spent all the tokens?” on
+  [LinkedIn](https://www.linkedin.com/posts/microsoft-developers_who-spent-all-the-tokens-tokenops-gives-activity-7499191980715982848-224b) and [X](https://x.com/msdev/status/2093425027500978292).
+- **[Who spent all the tokens? Real-time, run-scoped cost control for AI agents](https://commandline.microsoft.com/tokenops-real-time-run-scoped-cost-control-ai-agents/)**: *Command Line*, a Microsoft publication.
+- **[FinOps for AI Agents: Who Spent All the Tokens?](https://www.youtube.com/watch?v=GJX19pNhmSw)**: talk at the **AI Engineer World's Fair**, San Francisco.
+- **Selected to participate in the [GitHub Secure Open Source Fund](https://github.com/open-source/github-secure-open-source-fund)** (Session 5), GitHub Security Lab's open source security program.
+
+## 🛟 Support
+
+| Need | Where |
+|---|---|
+| Bug | [Open an issue](https://github.com/theagentplane/tokenops/issues) |
+| Security issue | [SECURITY.md](SECURITY.md) |
+| Real-time help | [Slack](https://join.slack.com/t/theagentplane/shared_invite/zt-47lqx2xtc-0idr1cuLNJ_JDTgqxDiUsg) |
+| Longer-form discussion | [GitHub Discussions](https://github.com/theagentplane/tokenops/discussions) |
+| Talk it through | [Office hours](https://calendly.com/theagentplane/theagentplane) |
+| Talks & writing | [theagentplane.github.io/media](https://theagentplane.github.io/media.html) |
+
+## Contributors
+
+Thanks to everyone who has contributed.
+
+[![Contributors](https://contrib.rocks/image?repo=theagentplane/tokenops)](https://github.com/theagentplane/tokenops/graphs/contributors)
+
+---
+
+Saved you tokens? [⭐ Star the repo](https://github.com/theagentplane/tokenops).
+
+<div align="center">
+
+[Back to top](#tokenops)
+
+</div>