Quickstart

Two lines. Every Anthropic and OpenAI call tracked automatically. No other changes required.

Install

$ pip install apeiros-sdk

Add two lines to your startup file

Open the file that starts your agent — main.py, app.py, wherever your workflow boots. Add these before any model calls:

main.py

import apeiros

# Two lines. Nothing else changes.
apeiros.instrument()  # patches Anthropic + OpenAI automatically
apeiros.start_session(budget=5.00)

# Your existing code — completely unchanged
response = client.messages.create(...)

If you're already tracking input_tokens + output_tokens manually on each call, remove that code. apeiros.instrument() replaces it entirely.

How is this different from tracking tokens yourself?

If you're already logging token counts per call, you're tracking volume. Apeiros adds three things on top:

1. Per-customer margin visibility

Raw token counts tell you what you spent. Apeiros tells you who caused it and whether that customer is profitable against your plan price.

  Customer             Monthly Cost    Revenue    Margin   Status
  ─────────────────────────────────────────────────────────────
  acme-corp              $  5.70       $299.00    98.1%    ✓ healthy
  greenleaf-inc          $ 49.28       $299.00    83.5%    ✓ healthy
  nova-ventures          $184.00       $299.00    38.5%    ⚠ watch
  bloom-agency           $332.72       $299.00   -11.3%    ✗ underwater

2. Automatic anomaly detection

Your token log shows a number. Apeiros tells you why it's high — retry loops, context bloat, tool spikes — at the call level, automatically.

⚠️  Retry loop detected (3 similar requests). Estimated waste: $0.0017
→ Stop retrying; diagnose the root cause instead.

⚠️  Context grew 4.5× since step 1.
⚠️  Token count accelerating at +453% over last 3 steps.
→ Clear or summarise context before the next step.

3. One line replaces your manual tracking

apeiros.instrument() patches the client globally at startup. Remove the per-call tracking you wrote yourself and replace it with one line.

What gets detected automatically

retry_loopSame call repeated 3+ times — your agent is spinning

context_bloatContext window grew 2× since the first step

token_accelerationEach of the last 3 steps is larger than the one before

budget_exceededTotal cost crossed the budget you set in start_session()

tool_amplificationOne step spiked 2× above the rolling average

Per-customer cost attribution

anywhere in your codebase

from apeiros import ApeirosAgent

agent = ApeirosAgent(customer_id="acme-corp", model="claude-sonnet-4-6")
agent.start_task("process support ticket")
# ... your LLM call — unchanged ...
agent.update_tokens(response.usage.input_tokens + response.usage.output_tokens)
agent.end_task()

print(ApeirosAgent.customer_report(plan_price=299.0))

"How do I know I can trust this?"

Read it. The entire SDK is ~600 lines across 7 files. A developer can audit the whole thing in 20 minutes — that's a stronger trust signal than a SOC 2 badge from a black-box SaaS.

What instrument() does: patches the Anthropic/OpenAI client in memory, reads token counts from the response object after each call, stores them in a local Python dict.

What it does not do: send data anywhere, store API keys or prompts, make any network requests, write to disk, or persist anything after the process ends.

If you want full control, vendor it — copy the files directly into your repo and skip PyPI entirely:

# Copy apeiros/ into your project — MIT licensed, modify freely
cp -r apeiros-protocol/apeiros ./your_project/apeiros

# Import locally
from apeiros import instrument, start_session

interceptor.py

150 lines — instrumentation layer

detectors.py

130 lines — what fires after each call

session.py

85 lines — all state management

GitHub →PyPI →Website →Issues →