Metadata-Version: 2.4
Name: rbtrace
Version: 1.2.0
Summary: Self-serve ReasonBlocks dashboard capture setup for OpenAI, Anthropic, Gemini and Bedrock, with safe migration and local verification.
Author: ReasonBlocks
License: Proprietary
Project-URL: Documentation, https://docs.reasonblocks.com
Project-URL: Homepage, https://reasonblocks.com
Keywords: llm,agents,observability,tracing,anthropic,openai
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# rbtrace

Connect Python agents to the [ReasonBlocks](https://reasonblocks.com) dashboard.
Python 3.10+, no required dependencies.

The package provides a setup CLI and small Python helpers. It works with the
OpenAI and Anthropic Python client libraries your application already uses.

## Set up with your coding agent

Give your coding agent the setup guide after publishing the matching package and documentation:

```text
Read https://docs.reasonblocks.com/agent-setup.md and integrate ReasonBlocks into this project.
```

Add `rbtrace==1.1.1` with your project's existing package manager, then generate the
connection using the exact source URL copied from **Data**:

```bash
python -m rbtrace init --capture-url "$REASONBLOCKS_CAPTURE_URL" --provider openai --json
```

Use `--provider anthropic` for Anthropic Messages. Add `--dry-run` to inspect the
planned files. Repeating `init` preserves identical files and refuses to overwrite
customized files. It writes `.reasonblocks/config.json`, `.reasonblocks/SETUP.md`
and `reasonblocks_setup.py`; your coding agent connects the helper to the application.

Choose an importable helper directory with `--path`. For a packaged application,
this may be `--path src/my_agent`, with `from my_agent import reasonblocks_setup`.
Include the adjacent `.reasonblocks/config.json` in package data or your deployment
image. Test the actual launch command outside the source directory.

Set `REASONBLOCKS_CAPTURE_KEY` in the application's secret environment (the existing
`RB_CAPTURE_KEY` name is also accepted). Keep your existing provider API key. The
capture key is read at runtime and never written into generated files.

The generated client options set `max_retries=0`. This prevents an SDK from
silently repeating a paid request after a timeout. Your application can explicitly
change that option in the returned dictionary if it has its own reconciliation
policy. Keep existing provider credentials; the capture key is a separate,
source-scoped key, not a normal ReasonBlocks organization API key.

```python
from openai import OpenAI
import reasonblocks_setup

client = OpenAI(**reasonblocks_setup.client_kwargs())

# Once per task:
headers = reasonblocks_setup.run_headers()
# Reuse headers on EVERY model call in this task:
response = client.chat.completions.create(
    model=model,
    messages=messages,
    extra_headers=headers,
)
```

Basic capture needs no training sandbox or snapshot. The supported model APIs are
OpenAI Chat Completions and Anthropic Messages. Keep executing tools in your existing
application and carrying the conversation forward as before.

The same options and per-task headers work with `AsyncOpenAI` and `AsyncAnthropic`.
For concurrent jobs, create a fresh header dictionary inside each job and reuse
only that dictionary throughout its tool loop. Streaming calls still receive
`extra_headers=headers`; consume the complete stream before checking collection.
Importing the generated helper installs request labeling for the configured capture
host, including current SDKs that use `httpx2`. Each run receives `x-rb-run` and
incrementing `x-rb-seq` headers. Installation sends no requests and does not change
model payloads, credentials, or retry settings. `RBTRACE_DISABLE=1` disables labeling
at startup; `doctor` reports that condition. You do not need to patch a transport
yourself. Keep explicit task boundaries: unscoped tasks share a process-wide run.

For older integrations, `rbtrace.client.install()` and `with rbtrace.client.run():`
remain available. They only label requests; they do not configure the capture URL
or capture authentication. Unscoped jobs share a process-wide default run. Use
the explicit helper above for new dashboard integrations. Basic capture groups
by run ID; successful local setup alone does not prove complete sequence capture.

In 1.1.1, `RBTRACE_HOSTS=capture.example.com` authorizes only that exact host.
Use a leading-dot entry such as `.example.com` to include subdomains explicitly;
use `example.com,.example.com` for both the apex and its subdomains. The generated
helper adds only its configured capture host. Existing `*` and leading-dot choices
remain unchanged.

```bash
python -m rbtrace doctor --json
```

Run `doctor` in the application's Python environment with the same `--path` used
for initialization. It checks local configuration, the selected provider library
capture-key presence, and whether the selected SDK transport can be labeled. It
makes no network requests, verifies no remote key or
captures, and explicitly reports cloud authentication and application wiring as
unverified. Running a CLI with `uvx` does not install the dependency in your app.

## Move an earlier generated connection to the dashboard

Create a source in **Data**, obtain its capture URL and key, then run:

```bash
python -m rbtrace migrate --capture-url "$REASONBLOCKS_CAPTURE_URL" --provider anthropic --path . --json
```

Add `--dry-run` to preview. Migration backs up the original generated files and
replaces them with dashboard configuration and helpers. It refuses to overwrite
a customized helper. Exact generated 1.1.0 files are recognized and backed up
before upgrading their import-time labeling. Repeating a completed migration makes
no changes.

Your coding agent must use `client_kwargs()` at client construction and
`run_headers()` once per task, passed on every model call. Existing explicit
`rbtrace.client.run()` scopes may be retained. Remove obsolete
`reasonblocks_setup.install()` calls; importing the helper installs labeling. Remove old gateway base-URL settings from
application/deployment configuration and restart the application. Migration of
configuration alone does not change existing application call sites.

Use the application's existing supported provider. An application using a different
provider or OpenAI Responses needs an explicitly chosen compatible integration;
the migration command does not switch its model API automatically.

## Training later

Full-agent training lets a smaller model try new actions through your agent's tools.
It needs a resettable sandbox: for example, test support tickets and a test database
that can be restored for every attempt, plus a checker that decides whether the
task succeeded. The sandbox can be hosted wherever your deployment supports; it
must expose the application's actual tool behavior.

Once that environment exists, attach its real starting snapshot to each task:

```python
headers = reasonblocks_setup.run_headers(snapshot_id=starting_snapshot_id)
```

This ID refers to a saved state; the helper does not create it. Ordinary capture
alone does not preserve tool/database state for later replay. See
[full-agent training](https://docs.reasonblocks.com/full-agent-training) for the
sandbox connection and preparation steps.

## Reusable agent skill

After documentation publication:

```bash
npx skills add https://docs.reasonblocks.com
```

Select `reasonblocks-setup`. The [setup guide](https://docs.reasonblocks.com/agent-setup)
covers task boundaries, async clients and deployment layout. Python helpers must
be wired where requests actually occur; they do not reach JavaScript clients or
model calls made by a separate child process.
