dexcost

Agent Unit Economics SDK — track end-to-end business-task costs for AI agents.

dexcost attributes LLM calls, non-LLM service fees, and retry waste to customers, projects, and workflows so you can answer "what does each AI task actually cost?"

Install

pip install dexcost

With every supported provider, framework, and GPU integration:

pip install dexcost[all]

Or install only the provider integration you use:

pip install "dexcost[openai]"
pip install "dexcost[anthropic]"
pip install "dexcost[litellm]"
pip install "dexcost[gemini]"
pip install "dexcost[bedrock]"
pip install "dexcost[cohere]"
pip install "dexcost[mcp]"
pip install "dexcost[ollama]"
pip install "dexcost[openrouter]"
pip install "dexcost[perplexity]"
pip install "dexcost[fal]"
pip install "dexcost[gpu]"  # NVIDIA NVML task-level GPU accounting

The Gemini extra currently supports google-genai 1.x and 2.x and is bounded to <3.0.0, matching Google's announced next-major breaking-change boundary.

Quick Start

Global API (recommended)

import dexcost

dexcost.init(api_key="dx_live_...")  # or set DEXCOST_API_KEY env var
dexcost.set_context(customer_id="acme-corp")

with dexcost.task(task_type="summarise_doc") as t:
    # LLM calls are auto-captured — just use OpenAI/Anthropic/etc normally
    response = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Summarise this document"}],
    )

    # Record non-LLM costs manually
    t.record_cost(service="pdf_parser", cost_usd="0.002")

    # Record an actual business result explicitly; task success alone is not
    # treated as an achieved outcome.
    t.record_outcome("document_delivered", value=True)

dexcost.close()

Instance API (for multi-tracker scenarios)

from dexcost import CostTracker
from dexcost.storage.sqlite import SQLiteStorage

tracker = CostTracker(storage=SQLiteStorage("/tmp/demo.db"))

with tracker.task(task_type="summarise_doc", customer_id="acme") as t:
    t.record_llm_call("openai", "gpt-4o", input_tokens=800, output_tokens=150)
    t.record_cost(service="pdf_parser", cost_usd="0.002")

CrewAI and Griptape

Install only the framework integration you use:

pip install "dexcost[crewai]"
pip install "dexcost[griptape]"

The wrappers preserve the original framework object and public method signatures. They create one canonical DexCost task when no task is active, or reuse the caller's active task. Sync, async, streaming, failure, cancellation, early-close, and framework-native tool events share that same lifecycle.

import dexcost

dexcost.init(api_key="dx_live_...")

# Existing CrewAI Crew, Agent, LiteAgent, and Flow objects are supported.
tracked_crew = dexcost.track_crewai(crew)
crew_output = tracked_crew.kickoff(inputs={"topic": "unit economics"})

# Existing Griptape Structure objects are supported without replacing drivers.
tracked_agent = dexcost.track_griptape(agent)
tracked_agent.run("Build the report")

For an instance tracker, pass it as the second argument:

from dexcost.integrations import track_crewai, track_griptape

tracked_crew = track_crewai(crew, tracker)
tracked_structure = track_griptape(structure, tracker)

Provider instrumentation is the authoritative LLM-cost path and prevents double counting. Framework event fallback is opt-in for custom providers that DexCost cannot instrument:

tracked_crew = dexcost.track_crewai(crew, capture_llm_events=True)

Do not enable that fallback for the same calls already captured by OpenAI, Anthropic, LiteLLM, Gemini, Bedrock, or another provider instrument. Native tool capture stores only bounded tool identity, opaque framework IDs, status, cache/attempt dimensions, and exact duration when the framework exposes it. Prompts, tool arguments, chain-of-thought, outputs, and error messages are not stored. See FRAMEWORK-COMPATIBILITY.md for the current execution surface and compatibility evidence.

Business outcomes

Outcomes are durable, revisioned business facts linked to a task. DexCost does not infer them from a successful task because completing technical work is not the same as achieving a customer result.

from decimal import Decimal

with dexcost.task(task_type="campaign_export") as task:
    # ...generate and export the campaign...
    exported = task.record_outcome("campaign_exported", value=True)
    task.record_outcome("approved_creative_count", value=2)
    task.record_outcome("quality_score", value=Decimal("0.92"))

# Correct a previously recorded outcome by preserving its identity and
# incrementing the revision. The local ledger rejects gaps and invalid state
# transitions before they reach the control plane.
dexcost.record_outcome(
    "campaign_exported",
    task_id=task.task_id,
    outcome_id=exported.outcome_id,
    revision=2,
    state="missed",
    value=False,
)

Values are exact typed facts: Python strings, booleans, integers, and Decimal values map to the corresponding wire types. Use canonical lowercase names such as campaign_exported; do not place secrets or personal data in an outcome name or value.

Agent and workflow identity

Keep the business workflow, deployed agent, and technical task type as separate dimensions. Set the stable identity once; nested tasks inherit it automatically.

dexcost.set_context(
    customer_id="dexcost-internal",
    project_id="dexcost-marketing-campaign",
    agent="campaign_director",
    agent_version="demo-v1",
    workflow_id="campaign_generation",
    workflow_session_id="campaign-2026-08-17",
)

with dexcost.task(task_type="campaign.run") as campaign:
    with dexcost.task(task_type="campaign.script.generate"):
        generate_script()

    with dexcost.task(task_type="campaign.narration.generate"):
        generate_narration()

    campaign.record_outcome("campaign_exported", value=True)

This produces one canonical campaign hierarchy while preserving the actual work-step task types. Agent identity never replaces task_type, and technical success is not presented as a business outcome unless the application records one explicitly.

Attribution observation fields (contract v3)

Observations are emitted on the schema_version: "3" wire contract. The following optional fields were added to v3 in place — old payloads that omit them stay valid, and the bundled JSON schema (dexcost/attribution/attribution-v3-schema.json) is validated strictly on every emit.

dexcost.init(environment="production")  # emitted as observation.environment

dexcost.set_context(
    customer_id="acme-corp",
    project_id="proj-alpha",
    user_id="user-42",              # the end user the work is performed for
    product_id="support-console",   # the product surface driving the work
)

A failed tool call therefore reaches the control plane as:

{
  "schema_version": "3",
  "environment": "production",
  "component": "external",
  "resource": { "type": "tool", "id": "web_browser" },
  "operation": {
    "status": "failed",
    "latency_ms": 1250,
    "error": { "type": "timeout", "code": "ETIMEDOUT" }
  },
  "usage_snapshot": "full",
  "usage": []
}

A succeeded operation must not carry operation.error; the SDK rejects that observation locally instead of shipping it.

Auto-Instrumentation

dexcost auto-instruments 10 AI provider SDKs, the MCP tool client, and 5 HTTP libraries.

LLM Providers

Every supported AI call inside a tracked task is captured automatically. LiteLLM also preserves canonical routed-provider identity for OpenAI, Anthropic, Google/Vertex, Azure/Azure AI, Bedrock, Cohere, Hugging Face, Together, Ollama, Mistral, Groq, OpenRouter, Perplexity, fal.ai, xAI, DeepSeek, Fireworks AI, Nvidia NIM, nano-gpt, and other explicit LiteLLM provider/model routes. OpenAI and Google multimodal paths preserve native text/image/audio/video/cache, reasoning, tool-input, character, and media-count quantities, calculate against the active catalog, and retain only quantities and opaque provider IDs. Prompts, media, transcripts, tool payloads, and generated output are not stored. Google stream success is recorded only on natural completion; early close is cancelled and stream exceptions are failed.

HTTP Libraries (Non-LLM Cost Capture)

HTTP calls matching the active service catalog (Pinecone, Twilio, SendGrid, Stripe, Firecrawl, Exa, etc.) are automatically captured as external_cost events with cost extracted from the response. Catalog releases are distributed by the control plane as immutable, content-addressed artifacts and evaluated locally. The SDK validates and caches a last-known-good release for offline use; the bundled catalog remains an emergency bootstrap until Python and TypeScript joint migration gates allow it to be reduced safely.

For signed authority, configure rotated Ed25519 public keys and require a signature. Keys are raw 32-byte public keys encoded as unpadded base64url. Supplying keys requires signatures by default; setting the boolean explicitly is shown for clarity:

dexcost.init(
    api_key="dx_live_...",
    catalog_trusted_keys={"dexcost-prod-2026-01": "<public-key-base64url>"},
    catalog_require_signature=True,
)

Air-gapped hosts use the same validation and activation path:

dexcost.init(
    storage="local",
    catalog_trusted_keys={"dexcost-prod-2026-01": "<public-key-base64url>"},
    catalog_require_signature=True,
)
dexcost.import_catalog_bundle("dexcost-catalog-release.dcr.json")

Import never bypasses signature, expiry, downgrade, size, hash, schema, or semantic checks. The previous release remains available if import fails. When the packaged production trust document has no keys, remote catalog refresh and bundle activation stay disabled and bundled pricing remains active. This state is exposed by dexcost.catalog_status().signature_verification as "disabled_no_trust"; an empty trust document is never treated as permission to accept unsigned catalogs. catalog_require_signature=False is an explicit, temporary migration override and enables unsigned refresh deliberately.

Controlling Instrumentation

# Instrument only specific providers
dexcost.init(auto_instrument=["openai", "gemini"])

# Disable all auto-instrumentation
dexcost.init(auto_instrument=[])

# Disable HTTP tracking
dexcost.init(track_http=False)

Configuration

dexcost.init() Parameters

Environment Variables

Catalog trust resolves from an explicit option, then the environment, then the public trust document shipped in the package. Private signing keys are never part of an SDK or SDK environment.

Note: DEXCOST_ENDPOINT is no longer read. The Control Layer URL is configured only via init(endpoint="https://...") (default https://api.dexcost.io). This prevents an attacker who controls the process environment from redirecting telemetry and the Bearer API key to a hostile collector.

Task Tracking

Context Manager

with dexcost.task(task_type="resolve_ticket") as t:
    # All LLM/HTTP calls inside are automatically captured
    pass

Decorator

@tracker.track_task(task_type="generate_report", customer_id="acme")
def generate_report(data):
    # LLM calls here are tracked
    pass

Manual Start/End

t = tracker.start_task(task_type="batch_job", customer_id="acme")
# ... do work ...
t.end(status="success")

Cross-process campaign or workflow hierarchy

Use stable UUIDs when a workflow spans workers or short-lived tool processes. Supplying root_task_id opts the task into the revisioned business-identity contract. Create the root once, then pass both root and parent IDs to children:

import uuid

campaign_root = uuid.uuid5(uuid.NAMESPACE_URL, "campaign:dexcost-launch")

with dexcost.task(
    task_type="campaign.run",
    task_id=campaign_root,
    root_task_id=campaign_root,
    experiment_id="creative-angle",
):
    pass

# This may execute in a different process.
with dexcost.task(
    task_type="campaign.scene.render",
    root_task_id=campaign_root,
    parent_task_id=campaign_root,
    experiment_id="creative-angle",
    variant="proof-first",
):
    render_scene()

The identity snapshot is published with the final task update. Task type and assignment fields are immutable for that SDK task identity. The Python SDK currently emits revision 1 only; later corrections belong in the workspace business-attribution API rather than rewriting provider usage.

Local NVIDIA GPU usage

Opt in only on the leaf task that owns the GPU work:

with tracker.task(task_type="local_whisper", track_gpu=True):
    transcribe_on_local_gpu()

DexCost records measured GPU-seconds, the normalized device model, and utilization evidence. Without an explicit user-owned rate, a local GPU and local network transfer remain unpriced; the SDK does not apply public-cloud fallbacks to locally owned infrastructure.

To attribute your own amortized hardware, electricity, hosting, or bandwidth rate, load a versioned YAML file during initialization. The values below are illustrative user inputs, not DexCost public-list prices:

version: 2
rates: {}
infrastructure:
  gpu:
    nvidia-geforce-rtx-5060-ti:
      per: gpu_hour
      cost_usd: "0.25"
  network:
    local:
      per: gb_transferred
      cost_usd: "0.02"

dexcost.init(
    api_key="dx_live_...",
    rates_path="rates.yaml",
)

GPU units can be gpu_second or gpu_hour. Network units can be gb_transferred (request plus response bytes) or gb_egress. Keys are normalized and matched exactly; there is no default-rate fallback. Configured costs carry sdk_rate_registry evidence and a deterministic pricing version. Do not enable GPU measurement on both a parent and its child, because they would measure the same hardware interval twice.

TrackedTask Methods

with dexcost.task(task_type="...") as t:
    # Record LLM call manually (usually auto-captured)
    t.record_llm_call("openai", "gpt-4o", input_tokens=800, output_tokens=150)

    # Record non-LLM cost
    t.record_cost(service="pinecone", cost_usd="0.001")

    # Record usage (cost computed from registered rates)
    t.record_usage(service="s3_storage", units=1024)

    # Mark a retry
    t.mark_retry(reason="rate_limit", cost_usd="0.005")

    # Link to external trace
    t.link_trace(provider="datadog", trace_id="abc123")

Customer Attribution

dexcost.set_context(
    customer_id="acme-corp",
    project_id="proj-alpha",
    user_id="user-42",
    product_id="support-console",
)

# All tasks created after this inherit customer_id, project_id, user_id and
# product_id; they are shipped as the business identity `assignment` snapshot.
with dexcost.task(task_type="...") as t:
    pass  # t.task.customer_id == "acme-corp"

Dev Mode

Set DEXCOST_ENV=development or pass environment="development" to init(). In dev mode:

• Cost events are printed to the terminal
• No data is pushed to the cloud
• Useful for local development and debugging

CLI

dexcost status          # DB location, event count, sync status
dexcost rates --list    # Show registered cost rates
dexcost scan .          # Find untracked cost points in your code
dexcost scan . --generate-stubs  # Generate record_cost() stubs for manual points

Development

pip install -e ".[all]"
pip install ruff black mypy pytest

make lint        # ruff
make format      # black
make typecheck   # mypy strict
make test        # pytest

Releases

Releases are generated from Conventional Commit pull-request titles and are squash-merged to main. Use feat(python): ... for features and fix(python): ... for fixes. See CONTRIBUTING.md and CHANGELOG.md.

Privacy

When you connect to the Dexcost Control Layer, the SDK transmits usage data subject to our Privacy Policy.

License

MIT — see LICENSE.