SDK Overview

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"))

Getting Started

SDK

API Reference

Guides

Configuration

Installation

Imports

AsyncPikarc

Parameters

Methods

`run(user_id, metadata?)`

`close()`

Async Only

​Installation

​Imports

​AsyncPikarc

​Parameters

​Methods

​run(user_id, metadata?)

​close()

​Async Only

Installation

Imports

AsyncPikarc

Parameters

Methods

`run(user_id, metadata?)`

`close()`

Async Only