paygent

>-

# Paygent integration specialist

You help teams wire **Paygent** so AI usage is attributed to the right **agent**, **customer**, and **indicator** without leaking secrets or blocking hot paths.

## Your priorities

1. **Correct identifiers**: Confirm `paygent_agent_id` matches the dashboard agent’s external id; use stable `customer_id` values from the host product’s identity model.
2. **Minimal friction**: Prefer `paygent_sdk.init()` plus automatic kwargs on supported providers when the stack allows it.
3. **Honest observability**: For LangChain/LangGraph/LiveKit/Vapi flows, anchor on the official callbacks and hooks rather than reinventing metering.
4. **Security**: Never echo or commit API keys; recommend env vars and secret stores; avoid logging raw request payloads that contain keys.
5. **Resilience**: Treat Paygent calls as **best-effort telemetry** — the app must stay up if billing transport is degraded.

## Response style

Be concrete: cite file-level changes, show the smallest working snippet, and name the indicator you would create in the dashboard for the use case.

When requirements are ambiguous, ask one focused question (e.g. “Is this chat or voice?”) before proposing code.

Patterns for integrating Paygent usage-based billing (Python SDK, agents, customers, indicators). Apply when adding or reviewing Paygent tracking in application code.

# Paygent integration (Python)

## Product model

- **Agents** map to your AI workloads (e.g. chatbot, voice agent). Use the **external agent id** from the Paygent dashboard.
- **Customers** are billable end users or tenants. Prefer your **database customer id** as `customer_id` / `external_id`.
- **Indicators** are billable events (activity or outcome): e.g. `message-sent`, `voice-call-completed`.

## Prefer automatic tracking

When using supported providers after `paygent_sdk.init(api_key)`, add these **optional kwargs** on supported calls:

- `paygent_agent_id`
- `paygent_customer_id`
- `paygent_indicator`

The SDK patches supported clients so usage is emitted without blocking the request path.

## Manual tracking

Use `Client.new_client(api_key)` (or the client from `init`) and:

- Build `UsageData` / `RawUsageData` from provider response usage objects.
- Call `send_usage` / `send_usage_v2` with non-empty `agent_id`, `customer_id`, and `indicator`.

## Safety and reliability (SDK design)

- Outbound tracking is **fire-and-forget**; do not assume synchronous confirmation in app logic.
- Never log or commit **API keys**. Use environment variables (e.g. `PAYGENT_API_KEY`).

## Voice and multi-modal

- Voice flows use session APIs: `initialize_voice_session`, `track_voice_stt`, `track_voice_llm`, `track_voice_tts`, `set_voice_indicator`, etc., as in the official docs.
- For LangChain / LangGraph, prefer the official **callbacks** so every model in a pipeline shares one billing context.

## References

- Dashboard and signup: `https://withpaygent.com`
- Python package: `pip install paygent-sdk`

>-

# Paygent Python SDK integration

## When to apply

- Installing or configuring `paygent-sdk` for the first time.
- Choosing between **automatic** (monkeypatch + `paygent_*` kwargs) vs **manual** (`Client`, `UsageData`, `send_usage`).
- Wiring **LangChain** (`PaygentLangChainCallback`) or **LangGraph** (`PaygentLangGraphCallback`).
- Implementing **voice** (session-based STT / LLM / TTS) or **standalone** STT/TTS/STS helpers.
- Integrating **LiveKit** (`LiveKitPaygentHook`) or **Vapi** (`VapiPaygentHook`).

## Install

```bash
pip install paygent-sdk
```

Set `PAYGENT_API_KEY` (or equivalent secret manager reference) — never commit keys.

## Core concepts

| Concept | Meaning |
| -------- | ------- |
| Agent | Your AI product surface; identified by dashboard **external agent id**. |
| Customer | Who you bill; use stable ids from **your** datastore as `customer_id`. |
| Indicator | A priced **event** (message sent, call completed, article generated). |

## Automatic tracking (recommended for LLM HTTP clients)

1. Once at startup:

```python
import paygent_sdk

paygent_sdk.init(api_key=os.environ["PAYGENT_API_KEY"])
```

2. On supported provider calls, pass:

- `paygent_agent_id="<external-agent-id>"`
- `paygent_customer_id="<customer-id>"`
- `paygent_indicator="<indicator-name>"`

This matches the product “Quick Start” flow: initialize once, then annotate calls.

## Manual tracking

Use `paygent_sdk.Client.new_client(api_key)` and construct `UsageData` (or `RawUsageData` for V2 paths) from the provider response’s token usage, then `send_usage` / `send_usage_v2`. Keep `agent_id`, `customer_id`, and `indicator` non-empty — the client drops invalid calls and logs.

## Framework integrations

- **LangChain**: one `PaygentLangChainCallback` instance; attach `callbacks=[paygent_cb]` to each `ChatModel` in the pipeline; reuse the same callback for multi-model flows.
- **LangGraph**: same idea with `PaygentLangGraphCallback` across nodes.
- **LiveKit**: `LiveKitPaygentHook` with `agent_id`, customer fields, `session_id`, indicator(s), optional `LLMConfig` / `STTConfig` / `TTSConfig`.
- **Vapi**: `VapiPaygentHook` plus org **Server URL** and `paygent-api-key` header as documented — server-side webhooks attribute usage to your Paygent workspace.

## Operational expectations

The SDK sends usage to Paygent’s API over HTTPS in a **non-blocking** way; design app code so billing never blocks user-facing latency and never raises into core paths for tracking failures.

## Doc and product links

- Product: `https://withpaygent.com`
- This plugin’s commands folder includes copy-paste checklists for common tasks.

>-

# Paygent domain model (for implementers)

## Agents

An **agent** is a deployable AI surface you charge for — e.g. a support bot, sales copilot, or voice agent.

- In code you pass **`paygent_agent_id`** (or equivalent) using the agent’s **external id** from the Paygent dashboard.
- One codebase can host multiple agents; each should have distinct external ids if you need separate pricing or analytics.

## Customers

A **customer** is who ultimately pays — often mapped to your **tenant**, **account**, or **end-user id** in your database.

- Use a **stable string** (`paygent_customer_id`) you can re-use across sessions.
- Optional: `create_or_get_customer` / customer name fields where the SDK supports onboarding flows.

## Indicators

An **indicator** is a **billable event** — activity-based (e.g. `message-sent`) or outcome-based (e.g. `meeting-booked`).

- You choose indicator names when modeling pricing in the dashboard; code must use the **same names** consistently.
- Prefer one indicator per distinct priced action rather than overloading a single indicator for unrelated behaviors.

## Mental model

```
Agent (what product) + Customer (who) + Indicator (what happened) + Usage payload (tokens, audio, etc.)
```

Share this structure with PM and billing stakeholders before locking API contracts.

>-

# Scaffold Paygent Python tracking

Use this command when the user wants **automatic** LLM tracking with minimal code churn.

## Preconditions

- [ ] Paygent account and API key from [withpaygent.com](https://withpaygent.com)
- [ ] An **Agent** and at least one **Indicator** created in the dashboard; note the agent **external id** and indicator name
- [ ] Python dependency: `pip install paygent-sdk`

## Steps

1. **Initialize once** at process start (not per request):

```python
import paygent_sdk

paygent_sdk.init(api_key=os.environ["PAYGENT_API_KEY"])
```

2. **Annotate** each billable model call with:

- `paygent_agent_id="<dashboard-external-agent-id>"`
- `paygent_customer_id="<your-customer-id>"`
- `paygent_indicator="<indicator-name>"`

3. **Verify** in the Paygent dashboard that usage appears for a test call.

4. **Harden** — ensure the API key is only read from environment or a secret manager; add no logging of the key.

## If automatic patching does not apply

Fall back to `Client.new_client` + `UsageData` / `send_usage` from provider response token fields, or use framework callbacks (LangChain / LangGraph) from the `paygent-python-sdk` skill.