agentspend-sdk 0.1.0__tar.gz

agentspend_sdk-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Environment
+.env
+.env.local
+
+# Database
+*.db
+*.sqlite3
+
+# Reports output
+reports_output/
+
+# Dashboard
+dashboard/node_modules/
+dashboard/.next/
+
+#testing files
+test_pipeline.py
+sample_data.csv

agentspend_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: agentspend-sdk
+Version: 0.1.0
+Summary: AgentSpend — runtime cost optimizer for AI agents. Route LLM calls to the cheapest capable model with fallbacks, loop guards, and telemetry.
+Requires-Python: <3.14,>=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: alembic>=1.14
+Requires-Dist: fastapi>=0.115
+Requires-Dist: google-auth>=2.48.0
+Requires-Dist: google-cloud-aiplatform>=1.139.0
+Requires-Dist: litellm>=1.50
+Requires-Dist: pandas>=2.2
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.15
+Requires-Dist: uvicorn[standard]>=0.32
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# token-aud
+
+AI cost optimization toolkit for LLM workloads.
+
+`token-aud` now includes two complementary workflows:
+
+- **Audit mode (CLI/API):** Analyze historical usage logs and estimate savings opportunities with Student-Teacher-Judge sampling.
+- **AgentSpend SDK:** Route live agent steps (`plan`, `reason`, `tool`, `verify`, `draft`, `summarize`) to cost/quality-appropriate models with fallbacks, loop guards, and telemetry.
+
+## Installation
+
+```bash
+uv sync --no-editable
+```
+
+For local development tooling (tests):
+
+```bash
+uv sync --no-editable --extra dev
+```
+
+## Quick Start (AgentSpend)
+
+Run these three commands from repo root:
+
+```bash
+uv sync --no-editable --extra dev
+uv run --no-sync python -m pytest tests/agent -q
+uv run --no-sync python examples/agent_routing_demo.py
+```
+
+Expected results:
+
+- Agent tests pass.
+- Demo prints routed step decisions, per-step telemetry, and total run cost.
+- `agent_telemetry.jsonl` is generated locally.
+
+## AgentSpend Usage
+
+### 1) Default policy
+
+```python
+from token_aud.agent import AgentSpend
+
+agent = AgentSpend.default()
+result = agent.route_call(
+    step="plan",
+    messages=[{"role": "user", "content": "Break this task into a plan"}],
+)
+
+print(result.model_used, result.cost_usd, result.content)
+```
+
+### 2) Custom policy YAML
+
+```python
+from token_aud.agent import AgentSpend
+
+agent = AgentSpend.from_yaml("routing_policy.yaml")
+result = agent.route_call(
+    step="reason",
+    messages=[{"role": "user", "content": "Compare two architectures"}],
+)
+
+print(result.model_used, result.fallbacks_tried)
+```
+
+Built-in default policy path:
+
+- `src/token_aud/data/default_routing_policy.yaml`
+
+## AgentSpend Core Components
+
+- `src/token_aud/agent/policy.py`: Pydantic policy schema + YAML loading
+- `src/token_aud/agent/router.py`: deterministic model selection
+- `src/token_aud/agent/runtime.py`: `route_call()` execution + fallbacks
+- `src/token_aud/agent/loop_guard.py`: repeated-turn loop detection
+- `src/token_aud/agent/telemetry.py`: JSONL/HTTP telemetry sinks
+- `src/token_aud/agent/adaptive.py`: optional adaptive routing layer
+
+## AgentSpend Examples
+
+- `examples/agent_routing_demo.py`: end-to-end routed run with telemetry
+- `examples/custom_policy_demo.py`: loop escalation and hard-stop behavior
+- `examples/framework_agnostic_integration.py`: generic agent-loop integration with explicit success feedback
+- `scripts/summarize_telemetry.py`: convert `agent_telemetry.jsonl` into cost/fallback/latency summary
+
+```bash
+uv run --no-sync python scripts/summarize_telemetry.py agent_telemetry.jsonl
+```
+
+## Audit CLI (legacy + still supported)
+
+```bash
+uv run --no-sync token-aud --help
+uv run --no-sync token-aud analyze sample_data.csv --dry-run
+```
+
+## Environment Variables
+
+Common provider credentials:
+
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY` or `GOOGLE_API_KEY` (depending on provider path)
+
+For Google Vertex flows, ensure ADC is configured (`gcloud auth application-default login`).

agentspend_sdk-0.1.0/README.md

@@ -0,0 +1,107 @@
+# token-aud
+
+AI cost optimization toolkit for LLM workloads.
+
+`token-aud` now includes two complementary workflows:
+
+- **Audit mode (CLI/API):** Analyze historical usage logs and estimate savings opportunities with Student-Teacher-Judge sampling.
+- **AgentSpend SDK:** Route live agent steps (`plan`, `reason`, `tool`, `verify`, `draft`, `summarize`) to cost/quality-appropriate models with fallbacks, loop guards, and telemetry.
+
+## Installation
+
+```bash
+uv sync --no-editable
+```
+
+For local development tooling (tests):
+
+```bash
+uv sync --no-editable --extra dev
+```
+
+## Quick Start (AgentSpend)
+
+Run these three commands from repo root:
+
+```bash
+uv sync --no-editable --extra dev
+uv run --no-sync python -m pytest tests/agent -q
+uv run --no-sync python examples/agent_routing_demo.py
+```
+
+Expected results:
+
+- Agent tests pass.
+- Demo prints routed step decisions, per-step telemetry, and total run cost.
+- `agent_telemetry.jsonl` is generated locally.
+
+## AgentSpend Usage
+
+### 1) Default policy
+
+```python
+from token_aud.agent import AgentSpend
+
+agent = AgentSpend.default()
+result = agent.route_call(
+    step="plan",
+    messages=[{"role": "user", "content": "Break this task into a plan"}],
+)
+
+print(result.model_used, result.cost_usd, result.content)
+```
+
+### 2) Custom policy YAML
+
+```python
+from token_aud.agent import AgentSpend
+
+agent = AgentSpend.from_yaml("routing_policy.yaml")
+result = agent.route_call(
+    step="reason",
+    messages=[{"role": "user", "content": "Compare two architectures"}],
+)
+
+print(result.model_used, result.fallbacks_tried)
+```
+
+Built-in default policy path:
+
+- `src/token_aud/data/default_routing_policy.yaml`
+
+## AgentSpend Core Components
+
+- `src/token_aud/agent/policy.py`: Pydantic policy schema + YAML loading
+- `src/token_aud/agent/router.py`: deterministic model selection
+- `src/token_aud/agent/runtime.py`: `route_call()` execution + fallbacks
+- `src/token_aud/agent/loop_guard.py`: repeated-turn loop detection
+- `src/token_aud/agent/telemetry.py`: JSONL/HTTP telemetry sinks
+- `src/token_aud/agent/adaptive.py`: optional adaptive routing layer
+
+## AgentSpend Examples
+
+- `examples/agent_routing_demo.py`: end-to-end routed run with telemetry
+- `examples/custom_policy_demo.py`: loop escalation and hard-stop behavior
+- `examples/framework_agnostic_integration.py`: generic agent-loop integration with explicit success feedback
+- `scripts/summarize_telemetry.py`: convert `agent_telemetry.jsonl` into cost/fallback/latency summary
+
+```bash
+uv run --no-sync python scripts/summarize_telemetry.py agent_telemetry.jsonl
+```
+
+## Audit CLI (legacy + still supported)
+
+```bash
+uv run --no-sync token-aud --help
+uv run --no-sync token-aud analyze sample_data.csv --dry-run
+```
+
+## Environment Variables
+
+Common provider credentials:
+
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY` or `GOOGLE_API_KEY` (depending on provider path)
+
+For Google Vertex flows, ensure ADC is configured (`gcloud auth application-default login`).

agentspend_sdk-0.1.0/dashboard/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

agentspend_sdk-0.1.0/dashboard/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

agentspend_sdk-0.1.0/dashboard/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

agentspend_sdk-0.1.0/dashboard/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

agentspend_sdk-0.1.0/dashboard/next.config.ts

@@ -0,0 +1,14 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  async rewrites() {
+    return [
+      {
+        source: "/api/:path*",
+        destination: "http://localhost:8000/api/:path*",
+      },
+    ];
+  },
+};
+
+export default nextConfig;