Install and authenticate
braintrust Python package is not required to read traces.
Supply these environment variables securely through your secret manager:
Use a separate full Arga credential for task generation and review. Do not include keys in policy JSON, command arguments, traces or logs.
Choose the goal and tool mappings
Save a localtrace-policy.json:
goal_pointer is a JSON pointer selecting a string from the root span. For example, /input/task selects {"input":{"task":"Resolve the duplicate payment..."}}. Use /input when the input itself is a string.
Canonical executed tool names, such as stripe.charges.retrieve, work without a mapping. Each mapped span must contain provider-shaped arguments and responses: a charge retrieval uses input.id and a charge object in output; a list uses the provider’s normal page shape. V1 does not infer nested wrappers such as output.result. Normalize custom shapes on your host before calling project_trace.
LLM, score and eval spans are ignored, including tool suggestions inside model outputs. Unknown executed tool spans create a coverage gap. A tool suggestion is not evidence that an operation ran.
The CLI example selects only the goal and listed policies. Review those strings before export. Gmail subject/body remain excluded. The JSON CLI cannot run a custom text callback; use the Python worker below when selected text needs your own local filter.
Start the worker
Choose an initial timezone-aware timestamp for your project:--region eu for an EU Braintrust project; the default is us. The default destination is https://api.argalabs.com.
Without --watch, one bounded window runs and the process exits. The watcher processes five-minute windows, rereads two minutes of overlap, and waits 30 seconds once caught up. It fetches each selected trace’s full tree, including children outside the root’s discovery window.
Root and tool metrics.start/metrics.end must establish completed calls. End times before start times and ambiguous mutation ordering block generation. Parallel reads are accepted; overlapping reads/writes or writes remain coverage gaps.
Use a custom local text filter
filter_training_text is your existing local filtering function. This example selects Gmail subject/body as well as goal/policy and applies the callback before aliases and credential masking:
state_path and your intended start time. Pass operations={...} for custom tool names. You can also configure window and lookback as timedelta values for denser sources.
Check progress and retries
sync_once() returns content-free counters:
An unfinished root stays pending until it completes. A malformed tree or other projection failure stays pending while healthy roots continue. Fix source coverage rather than treating pending counts as a successful import.
An unacknowledged Arga upload prevents the watermark from advancing. Query failures, invalid responses and read limits also stop the window. Retrying uses the persisted aliases and acknowledgement hashes to suppress unchanged uploads. Revised evidence creates a new immutable collection.
Queries are capped at 2 MB and 1,000 records. Pending roots are bounded to 1,000. Reduce the window or intentionally backfill a dense source. Spans arriving beyond the lookback require an explicit backfill; this worker is not a lossless audit log.
Protect the checkpoint
The worker writes atomically with mode0600 and uses a lock to prevent concurrent workers sharing a checkpoint. The file contains an alias key, pending root references and acknowledgement hashes, not API keys or raw span payloads. Keep it private and out of version control.
Preserve the checkpoint across restarts. Use a new checkpoint when changing source, project, collection policy, mappings, start time, destination or account. Renewing an upload key for the same owner/source can reuse the checkpoint.
Accepted evidence appears under Training with the Braintrust sync source. Continue with task and verifier generation.
