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

# Pylva SDK Quickstart

> Install the TypeScript or Python SDK, create an Agent SDK key, attach customer context, and send your first cost event safely.

Use this guide to connect a TypeScript or Python agent runtime to Pylva.

## 1. Install the SDK

```bash theme={null}
pnpm add @pylva/sdk
pip install pylva-sdk
```

The Python package installs from `pylva-sdk`, but the runtime import is `pylva`.

## 2. Create an Agent SDK key

Sign in to the Pylva dashboard and create an Agent SDK key. Store the plaintext key as `PYLVA_API_KEY` in your runtime secret store. The key is shown once.

## 3. Initialize the SDK

### TypeScript

```ts theme={null}
import { init } from "@pylva/sdk";

init({
  apiKey: process.env.PYLVA_API_KEY!,
});
```

### Python

```python theme={null}
import os
import pylva

pylva.init(api_key=os.environ["PYLVA_API_KEY"])
```

The default cloud endpoint is `https://api.pylva.com`. Self-hosted deployments can pass an `endpoint` override.

## 4. Attribute calls to a customer and step

### TypeScript

```ts theme={null}
import { track } from "@pylva/sdk";

await track(
  "acme-corp",
  { step: "evaluate" },
  async () => {
    return openai.chat.completions.create({
      model: "gpt-4o-mini",
      messages,
    });
  },
);
```

### Python

```python theme={null}
from pylva import track_context

with track_context(customer_id="acme-corp", step="evaluate"):
    response = openai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=messages,
    )
```

## 5. Check the dashboard

After events arrive, use the dashboard to review:

* Total cost and cost by customer.
* Expensive agent steps.
* Unknown pricing tasks that need a pricing rule.
* Rule events, warnings, and alerts.

## Production checklist

* Use opaque `customer_id` values.
* Use stable `step` labels such as `retrieve_context`, `evaluate`, or `summarize`.
* Do not send prompts, completions, emails, phone numbers, or raw messages in telemetry metadata.
* Configure pricing for any non-LLM metrics before relying on margin reports.