metricai 0.5.0

Python SDK for MetricAI — AI billing and metering proxy

metricai

Python SDK for MetricAI — AI billing and metering proxy.

Quick reference

• Config / headers: MetricAIConfig, MetricAI(...).headers(agent_id, user_id, ...)
• Native OpenAI / Anthropic SDKs: openai_sdk(), anthropic_sdk(), gemini_sdk(), grok_sdk()
• Shared session id for SDK calls: proxy_sdk_session(...) → MetricAIProxyClientSession
• Telemetry (existing): track() / MetricAISession — unchanged
• LangChain / LangGraph / CrewAI: metricai.integrations (lazy imports for optional deps)
• Standalone workflow: from metricai.workflow import MetricAIAgent, MetricAIPipeline

Margin-ready integration checklist (under 30 minutes)

For live per-agent and per-end-user attribution in the dashboard, include these on every SDK call:

• agent_id: stable agent identifier (for example support-agent-v1)
• user_id: end-user/customer identifier (for example acct_42)

For explicit margin reporting, include revenue metadata on tracked events:

• Prefer sending revenue_usd in track(..., extra={...}) when available.
• If your app uses outcome billing, billable_amount_inr is derived from outcome and can be used server-side as revenue.

Verification flow:

1. Send at least one billable event with agent_id + user_id.
2. Open dashboard Cost & Margin attribution view.
3. Confirm non-empty rows under both by-agent and by-end-user tables.

Examples live under examples/ (e.g. byok_openai_sdk.py, standalone_workflow.py).

Official SDK URL paths (via MetricAI proxy)

The hosted API mirrors what the OpenAI / Anthropic clients append to base_url:

SDK	base_url ends with	Effective POST path
openai.OpenAI	/v1/proxy/openai	/v1/proxy/openai/chat/completions
anthropic.Anthropic	/v1/proxy/claude	/v1/proxy/claude/v1/messages
openai.OpenAI (Gemini route)	/v1/proxy/gemini	/v1/proxy/gemini/chat/completions
openai.OpenAI (Grok route)	/v1/proxy/grok	/v1/proxy/grok/chat/completions

Legacy single-segment POSTs (/v1/proxy/openai, /claude, /gemini, /grok) still work.

Response shape: MetricAIProxy uses the .../chat/completions path for OpenAI-shaped providers so the HTTP body matches the native OpenAI chat.completion JSON (what openai.OpenAI expects). Posts to the legacy /v1/proxy/openai path without /chat/completions return the MetricAI metering envelope unless you send header X-MetricAI-Response-Format: metricai on the chat path (optional).

Programmatic usage: GET /v1/usage?window=7d (same auth as the proxy: JWT or X-MetricAI-API-Key) returns dashboard-aligned summaries; see backend docs/PILOT_DATA_PROCESSING.md.

Use examples/provider_sdk_check.py to smoke-test providers when keys are set.

Most examples honor METRICAI_EXAMPLE_PROVIDER (openai | claude | gemini | grok) and shared env documented in examples/_provider_env.py.

See METRICAI_SDK.md for full developer documentation (patterns, headers, sessions, governance v1, changelog). \x00