Radicas Python SDK

radicas is the one pip-installable package that connects your AI agent to Radicas correct-by-construction: the right endpoint, the right auth, the right feature tag, the right tenant semantics — exactly what the onboarding wizard hands out.

Quickstart

pip install "radicas[adk]"          # pick the extra for your framework

import radicas
radicas.init(service="pricing-agent", feature="flight-pricing")
# ... run your agent — spans, metrics, and logs export to Radicas ...

That is the whole integration. init() resolves configuration (env-first — see configuration), checks connectivity, wires the OpenTelemetry providers, and auto-activates instrumentation for every framework it detects. radicas.shutdown() is registered via atexit; call it explicitly at the end of short-lived runs if you want deterministic flushing.

Without an API key the SDK targets the LOCAL lab (http://localhost:4317, gRPC, no auth — a local OTLP collector). Set RADICAS_API_KEY and it targets hosted Radicas (https://ingest.radicas.io, Bearer auth). Same code, environment swap only.

What Radicas does with the telemetry

Radicas binds everything to one canonical contract — the OpenTelemetry gen_ai span tree (invoke_agent → generate_content → execute_tool, see the telemetry reference) — and computes from it: estimated cost per LLM call (tokens × price book), feature/user allocation (radicas.feature, user.id), and reconciliation against provider invoices (the estimated cost is later joined, span-to-line-item, with authoritative FOCUS billing data).

The three-layer normalization story

Frameworks disagree about telemetry: ADK emits canonical gen_ai.*; OpenInference-based instrumentation emits llm.*. Radicas normalizes with three layers, all generated from the same per-framework registry card — write the mapping once, enforce it three times:

The SDK makes the right thing easy; the server makes the wrong thing harmless. Renames are additive (originals are kept), and every recognized span is stamped with radicas.source_framework so you can see which adapter fired.

Framework & provider support matrix

Status is honest per the integration bench: only Google ADK is verified end-to-end (fixture captured, registry card filled). Experimental strategies are implemented in the SDK but their emitted telemetry has not been fixture-verified yet; planned means not implemented.

Two categories: agent frameworks build the agent loop for you (agent/tool span tree). Providers are raw LLM SDKs / routers — valid telemetry sources, but you'd hand-write the loop yourself (single LLM span per call, no agent/tool tree).

Agent frameworks

Providers (raw SDK / router — recipes, not agent frameworks)

Next steps

• Installation — extras, Python versions, LOCAL vs ONLINE
• Configuration — every kwarg, env var, and default
• Authentication — API keys and why the client never sends a tenant
• Feature tagging — cost allocation by feature and user
• Troubleshooting — when spans do not show up