Metadata-Version: 2.4
Name: agentdevlabs
Version: 0.1.0
Summary: Capture and replay LLM calls from the OpenAI and Anthropic Python SDKs.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cryptography==46.0.3
Requires-Dist: httpx2==2.16.0
Requires-Dist: rfc8785==0.1.4
Provides-Extra: anthropic
Requires-Dist: anthropic<3,>=2; extra == 'anthropic'
Provides-Extra: openai
Requires-Dist: openai<4,>=3; extra == 'openai'
Description-Content-Type: text/markdown

# agentdevlabs

Python SDK for Agent Dev Labs Capture & Replay. `wrap(client)` records the calls your app makes through an OpenAI or
Anthropic client. Your provider key stays with your app.

```sh
pip install agentdevlabs
```

```py
import openai
from agentdevlabs import wrap

client = wrap(openai.OpenAI())
```

## Set up with a coding agent

1. Check that `AGENT_DEV_LABS_TOKEN` is set in `.env`. If it isn't, stop and ask the user for it. Never create a token or write one into code, and never commit `.env`. The SDK reads the process environment, not `.env` itself, so make sure the app loads it. In Python call `load_dotenv()` from python-dotenv before wrapping the client, or export the variable.
2. Install `agentdevlabs` and the provider SDK (`openai` or `anthropic`) with the project's own package manager.
3. Wrap the provider client where it is created: `wrap(openai.OpenAI())` or `wrap(anthropic.Anthropic())`. Leave `AGENT_DEV_LABS_MODE` unset unless the user asks, because it outranks the devkit toggle.
4. Run the app twice. The first call shows as captured and the second as replayed in the console's Logs; ask the user to look there, since you can't sign in.

Settings are environment variables only:

| Variable | Meaning |
| --- | --- |
| `AGENT_DEV_LABS_TOKEN` | Your workspace token. Without it the client runs unwrapped. |
| `AGENT_DEV_LABS_MODE` | `auto`, `capture`, `replay` or `off`, in any case. Overrides the server's mode. Any other value runs as `auto`, with one warning naming it. |
| `AGENT_DEV_LABS_DISABLED` | `1`, `true`, `yes` or `on` turns the SDK off; `0`, `false`, `no`, `off` or empty leaves it on. Any other value turns it off, with one warning naming it. Beats every other setting. |
| `AGENT_DEV_LABS_API_URL` | The API to talk to. |
| `AGENT_DEV_LABS_REPLAY_SPEED` | How fast a replayed stream plays: `realtime` (the default), `fast` (10x), `instant`, or a number to divide the recorded pace by. |
| `AGENT_DEV_LABS_GROUP` | Names a trace group: calls are captured into it and replays use only its recordings. Letters, digits, `.`, `_`, `/` and `-`, up to 100. |
| `AGENT_DEV_LABS_CACHE_DIR` | Where replayed captures are cached, encrypted. Defaults to your OS cache directory. |

## Replay in CI

Record a group on your machine, then replay only that group in CI. A call with no recording in the group fails with an error naming the cache key and the group (or saying the group doesn't exist), so CI never reaches the provider.

The group name uses letters, digits, `.`, `_`, `/` and `-`, up to 100 characters; anything else fails at startup. `AGENT_DEV_LABS_TOKEN` in CI must be a `replay-only` service token, which an owner or admin creates in the console's Access tokens page.

```sh
AGENT_DEV_LABS_GROUP=checkout-flow AGENT_DEV_LABS_MODE=capture pytest   # once, locally
```

```yaml
# .github/workflows/test.yml
name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv sync
      - run: uv run pytest
        env:
          AGENT_DEV_LABS_TOKEN: ${{ secrets.AGENT_DEV_LABS_TOKEN }}
          AGENT_DEV_LABS_GROUP: checkout-flow
          AGENT_DEV_LABS_MODE: replay
```

## Project rules: a worked example

A travel agent's system prompt carries today's date, a session UUID and a request id, so Monday's recording never matches on Tuesday. In the console's Project rules page, three masks make the calls match:

- `[0-9]{4}-[0-9]{2}-[0-9]{2}` masks the date.
- `[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}` masks the session UUID.
- `req_[A-Za-z0-9]+` masks the request id.

A mask changes only what matching reads, so the recording still holds the original text. To see which mask a pair of calls needs, open a trace, choose "Why didn't this replay?" on step 1 and "Try this rule" on a suggestion.

A card number the user typed should never be uploaded, so add a redact pattern such as `[0-9]{4} [0-9]{4} [0-9]{4} [0-9]{4}`. The SDK replaces it with `[redacted]` before upload; matching still uses the original, so redacting doesn't stop replays. The page's "Try it" box shows both results on a sample request that never leaves the browser.

Calls already recorded keep the rules they were captured with: after saving a rule, capture them again.

## License and privacy

Apache-2.0. The SDK sends nothing beyond the capture and replay events described above: no usage analytics or telemetry.

## Versions

Versions follow semantic versioning. Before 1.0, a minor release (0.1 to 0.2) may break your code; the changelog says how, and the API supports only the latest 0.x minor. From 1.0, the API supports the previous major version for 12 months after a new major ships. See `CHANGELOG.md`.
