> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pikarc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> Install and configure the AsyncPikarc Python client.

## Installation

```bash theme={null}
pip install pikarc
```

Requires Python 3.11+. The SDK depends on [httpx](https://www.python-httpx.org/) and [Pydantic](https://docs.pydantic.dev/) v2.

## Imports

```python theme={null}
from pikarc import AsyncPikarc, PikarcBlockedError
```

## AsyncPikarc

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

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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()`:

```python theme={null}
import asyncio

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