SDK Overview

Install and configure the AsyncPikarc Python client.

Installation

pip install pikarc

Requires Python 3.11+. The SDK depends on httpx and Pydantic v2.

Imports

from pikarc import AsyncPikarc, PikarcBlockedError

AsyncPikarc

The main client. Creates an underlying httpx.AsyncClient configured with your API key.

guard = AsyncPikarc(
    api_key="lg_xxxx_your_api_key",
    base_url="http://localhost:8000",  # default
)

Parameters

Parameter	Type	Default	Description
api_key	str	required	Your Pikarc API key (lg_<prefix>_<secret>)
base_url	str	"http://localhost:8000"	Pikarc API server URL

Methods

run(user_id, metadata?)

Async context manager that starts a guarded run and auto-ends it on exit.

async with guard.run(user_id="alice", metadata={"agent": "support-bot"}) as run:
    # run is a GuardedRun instance
    response = await run.model_call(...)

Parameter	Type	Default	Description
user_id	str	required	SDK user identifier (not the dashboard account)
metadata	dict[str, Any] | None	None	Arbitrary metadata attached to the run

Lifecycle:

• On entry: calls POST /v1/runs/ and evaluates guardrails. Raises PikarcBlockedError if denied.
• On clean exit: calls POST /v1/runs/{id}/end with status COMPLETED.
• On exception: calls POST /v1/runs/{id}/end with status FAILED, then re-raises.

close()

Closes the underlying HTTP client. Call this when you’re done with the guard instance.

await guard.close()

Async Only

The SDK is async-only for the MVP. All methods must be called with await inside an async context. If you need sync usage, wrap calls with asyncio.run():

import asyncio

result = asyncio.run(chat("alice", "Hello"))