SDK Reference

`carrot_ai.init()`

Initialize the SDK. Must be called before wrap() or patch_litellm() unless the CARROT_API_KEY environment variable is set.

carrot_ai.init(
    api_key="sk-...",
    base_url="https://api.carrotlabs.ai",
    flush_interval=5.0,
    batch_size=50,
)

Parameter	Type	Default	Description
`api_key`	`str`	`CARROT_API_KEY` env var	Your Carrot API key
`base_url`	`str`	`https://api.carrotlabs.ai`	API endpoint
`flush_interval`	`float`	`5.0`	Seconds between background flushes
`batch_size`	`int`	`50`	Max traces per batch

`carrot_ai.wrap()`

Wrap an LLM client for automatic trace capture. Returns a proxy with the same interface.

client = carrot_ai.wrap(OpenAI(), tags=["production"])

Parameter	Type	Default	Description
`client`	`OpenAI \| Anthropic`	required	The LLM client to wrap
`tags`	`list[str]`	`None`	Default tags for every trace from this client

Supported clients: OpenAI, AsyncOpenAI, Anthropic, AsyncAnthropic

`carrot_ai.patch_litellm()`

Enable automatic tracing for litellm.completion and litellm.acompletion.

carrot_ai.patch_litellm(tags=["production"])

Parameter	Type	Default	Description
`tags`	`list[str]`	`None`	Default tags for every litellm trace

Safe to call multiple times.

`@carrot_ai.trace`

Decorator for capturing multi-step functions as parent traces.

@carrot_ai.trace
def my_function():
    ...

@carrot_ai.trace("custom-name")
def my_function():
    ...

@carrot_ai.trace(name="custom-name", tags=["prod"], metadata={"version": "2"})
def my_function():
    ...

Parameter	Type	Default	Description
`name`	`str`	Function name	Trace name shown in the dashboard
`tags`	`list[str]`	`None`	Tags for filtering
`metadata`	`dict`	`None`	Arbitrary key-value metadata

Works with both sync and async functions.

`carrot_ai.flush()`

Force-flush all pending traces. Blocks until complete.

carrot_ai.flush()

Call this before process exit in short-lived scripts. The SDK also flushes automatically on normal shutdown.

Environment variables

Variable	Description
`CARROT_API_KEY`	API key (used if not passed to `init()`)
`CARROT_BASE_URL`	API base URL override

SDK Reference

carrot_ai.init()

carrot_ai.wrap()

carrot_ai.patch_litellm()

@carrot_ai.trace