SDK Reference

Complete API reference for the costara Python package (v0.1.x).

---

costara.init()

Initialize the Costara SDK. Call once at application startup.

costara.init(
    api_key: str,
    project: str,
    environment: str = "production",
    flush_interval: float = 2.0,
    batch_size: int = 50,
    disabled: bool = False,
)

| Parameter | Type | Required | Description | |---|---|---|---| | api_key | str | ✓ | Your Costara API key (cst_live_... or cst_test_...) | | project | str | ✓ | Project name as it appears in your dashboard | | environment | str | | "production", "staging", or "development". Default: "production" | | flush_interval | float | | How often (seconds) to flush the event queue. Default: 2.0 | | batch_size | int | | Max events per batch flush. Default: 50 | | disabled | bool | | Set True to disable all tracking (useful in tests). Default: False |

---

costara.track()

Record a single LLM API call event.

costara.track(
    provider: str,
    model: str,
    prompt_tokens: int,
    completion_tokens: int,
    cost: float,
    latency_ms: float,
    feature_tag: str = "default",
    metadata: dict | None = None,
)

| Parameter | Type | Required | Description | |---|---|---|---| | provider | str | ✓ | LLM provider: "openai", "anthropic", "google", or any string | | model | str | ✓ | Model identifier, e.g. "gpt-4o", "claude-3-5-sonnet-20241022" | | prompt_tokens | int | ✓ | Input token count from the API response | | completion_tokens | int | ✓ | Output token count from the API response | | cost | float | ✓ | Cost in USD. Use costara.estimate_cost() or supply your own | | latency_ms | float | ✓ | Request duration in milliseconds | | feature_tag | str | | The product feature that triggered this call. Default: "default" | | metadata | dict | | Optional dict of additional key-value pairs (not displayed in dashboards in v0.1) |

Events are queued in memory and flushed asynchronously — track() is non-blocking.

---

costara.estimate_cost()

Calculate the cost of an API call using Costara's built-in pricing data.

cost = costara.estimate_cost(
    provider: str,
    model: str,
    usage,  # the usage object from the API response
) -> float

Returns cost in USD as a float.

Supported providers and models (v0.1.0):

| Provider | Models | |---|---| | openai | gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo | | anthropic | claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229 | | google | gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash |

If a model is not in the built-in list, estimate_cost() returns 0.0 and logs a warning. You can supply your own cost in that case.

---

costara.patch_openai()

Auto-instrument the openai Python package. All subsequent openai.chat.completions.create() calls will be tracked automatically.

costara.patch_openai(
    default_feature_tag: str = "default",
)

| Parameter | Type | Description | |---|---|---| | default_feature_tag | str | Feature tag applied to all auto-instrumented calls unless overridden |

To override the tag per-call, pass extra_body={"costara_feature_tag": "my-feature"} in the OpenAI call.

Call patch_openai() after costara.init() and before any OpenAI calls.

---

costara.flush()

Manually flush all queued events to the Costara ingest API. Useful before process shutdown.

costara.flush(timeout: float = 5.0)

The SDK registers an atexit handler that calls flush() automatically, but calling it explicitly is recommended in short-lived scripts or Lambda functions.

---

Environment variables

All init() parameters can be set via environment variables (useful for 12-factor apps):

| Env var | Equivalent parameter | |---|---| | COSTARA_API_KEY | api_key | | COSTARA_PROJECT | project | | COSTARA_ENVIRONMENT | environment | | COSTARA_DISABLED | disabled (set to "true" to disable) |

If environment variables are set, you can call costara.init() with no arguments.