GuidesSDK Guides
Python SDK Quickstart
Install and use the CoreValue Python SDK to wrap LLM calls with FinOps metadata in minutes.
Python SDK Quickstart
Get started with cova-gateway — the thin header helper that surfaces per-call FinOps metadata from CoreValue Gateway.
Tier: The SDK is free and open source. Gateway access available on all tiers.
Install
pip install cova-gatewaybuild_headers
Build Cova-* request headers for user tracking, properties, and fallback chains.
from cova_gateway import build_headers, CovaHeaderOptions
headers = build_headers(CovaHeaderOptions(
user_id="user_123",
prompt_id="prompt_abc",
properties={"feature": "search", "team": "growth"},
fallbacks=["gpt-4o", "claude-3-5-sonnet", "llama-3.3-70b"],
))Validation: user_id and prompt_id must match [a-zA-Z0-9_\-:.] (max 256 chars).
Property names must match [a-zA-Z0-9_] (max 64 chars). Values max 256 chars.
Fallbacks max 5 models. Invalid input raises ValueError.
wrap (Non-Streaming)
Parse Cova-* response headers into typed CovaResponse.
from openai import OpenAI
from cova_gateway import wrap, build_headers, CovaHeaderOptions
client = OpenAI(
api_key="sk-cova-...",
base_url="https://gateway.corevalue.dev/v1",
)
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Hello"}],
extra_headers=build_headers(CovaHeaderOptions(user_id="user_123")),
)
cova_response = wrap(response, dict(response.headers))
print(cova_response.gateway.request_id)
print(cova_response.gateway.provider)
print(cova_response.gateway.model)
print(cova_response.gateway.status)
print(cova_response.gateway.request_cost)
print(cova_response.gateway.estimated_cost)
print(cova_response.gateway.credits_remaining)
print(cova_response.gateway.gateway_mode)fetch_native (Native Format)
Call a native-format endpoint (Anthropic, Google) and extract FinOps metadata.
from cova_gateway import fetch_native, build_headers, CovaHeaderOptions
response, gateway = fetch_native(
"https://gateway.corevalue.dev/v1/messages",
init={
"method": "POST",
"headers": {
"Authorization": "Bearer sk-cova-...",
"Content-Type": "application/json",
},
"body": '{"model": "claude-3-5-sonnet", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 1024}',
},
cova_opts=CovaHeaderOptions(user_id="user_123"),
)
print(gateway.request_id)
print(gateway.provider)
print(gateway.request_cost)
print(gateway.credits_remaining)CovaGatewayMeta Fields
| Field | Type | Source |
|---|---|---|
request_id | str | Cova-Id header |
provider | str | Cova-Provider header |
model | str | Cova-Model header |
status | str ("success" | "error") | Cova-Status header |
request_cost | float? | Cova-Request-Cost |
estimated_cost | float? | Cova-Request-Cost-Estimate |
credits_remaining | float? | Cova-Credits-Remaining |
gateway_mode | str? ("passthrough" | "translated") | Cova-Gateway-Mode |
translation_warning | str? | Cova-Translation-Warning |