rbtrace==1.3.1 helper and native Bedrock integration.
Version 1.3.0 and existing generated helpers remain compatible. Version 1.3.1
adds dispatch diagnostics without requiring new URLs, keys or client setup.
Connection(source_id, api_key=None)
Resolve a source’s authenticated endpoints without assembling provider URLs.
By default, the server credential comes from REASONBLOCKS_API_KEY.
serving=False keeps native Bedrock in capture-only mode. Streaming operations
always stay upstream. An unknown candidate outcome is not silently replayed
against Bedrock. See Bedrock and fallback.
Dispatch diagnostics (1.3.1)
Native Bedrock dispatch failures raiseDispatchError, available from rbtrace.
Its diagnostic fields contain no credentials, request bodies, server response
bodies or raw exception text:
rb.diagnostics()["last_dispatch"] is None before a dispatch completes.
Afterwards it holds the most recently completed dispatch’s dispatch_id,
elapsed_ms, route, category, status_code, outcome_unknown and retry_safe.
A confirmed route is upstream or candidate; on failure it is None and
category explains the failure. Only one record is retained. For concurrent
calls, use the caught error’s dispatch_id to identify that call.
elapsed_ms measures the dispatch request, including endpoint discovery if needed.
It excludes the subsequent AWS operation and capture upload. rb.status() reads
remote recording status separately.
Reconcile an unknown outcome before retrying model work. Do not automatically
replay through AWS, create another dispatch ID, or treat an HTTP error as proof
that no candidate run exists. Only an explicit upstream decision permits the
SDK to invoke the original Bedrock operation.
Server credentials
Use API Keys or Data → Manage connection to issue anrb_live_ key.
Choose Capture, Inference, or both permissions; optional source binding applies
to both capabilities. Leave expiration empty for no scheduled expiration.
Existing keys retain their original permissions and expiry. An rb_live_ prefix
alone does not guarantee Capture permission.
Legacy rbcap_ source credentials retain source capture and existing proxy
rollout access until their configured expiry or revocation. Newly generated source credentials are persistent by default.
Rotation accepts the old source key for up to 24 hours, never beyond its expiry.
Revocation removes source-key access without waiting for that overlap.
Source status
GET /capture/SOURCE_ID/status authenticates with x-reasonblocks-key.
The dashboard uses the signed-in session at
GET /api/data-sources/SOURCE_ID/connection-status; it does not store your server key.
The response reports status (waiting, connected, or attention),
recorded_requests, training_examples, excluded_requests, failed_requests,
last_recorded_at, last_error, exclusions, key_expires_at and expires_soon.
An exclusion describes training eligibility separately from recording and provider
success. The dashboard refreshes these fields automatically while the panel is open.
connected is a capture status, not a trained-model or approval status. Training
preparation, budget approval, training and evaluation are separate steps.
The SDK status checks the credential used for that request. The dashboard shows
the last recorded connection credential’s expiration; before the first recording,
it uses the legacy source key’s expiration when one exists. Check API Keys
for every server key’s current expiration and revocation status.
Recorded exchanges
Use your signed-in session for these management endpoints. A server capture key does not grant access to browse the source’s stored exchanges.GET /api/data-sources/SOURCE_ID/recordings?offset=0 returns up to 50 recent
completed recordings, newest first. The recent index holds at most 256 entries.
The response has this structure:
total counts the recent entries available to paginate. recorded_requests is
the cumulative number of recorded exchanges and can exceed total. Pass a new
offset to read the next page; this endpoint does not enumerate the full archive.
GET /api/data-sources/SOURCE_ID/recordings/RECORDING_ID returns a completed
exchange by its stable ID. It can retrieve an older stored exchange after that
entry leaves the recent index. Index eviction does not delete the exchange or
stop new capture. These endpoints do not promise unlimited retention.
Each serialized backend exchange has a 4 MiB limit. The native SDK and public
HTTP gateway apply a smaller 2 MiB request limit. Privacy filtering and response
completeness also determine whether an exchange can be stored. Native partial
streams do not upload a complete event; inspect rb.diagnostics() for local
delivery failures even when remote status has no new recording.
The existing limit of 512 normalized training examples per source still applies.
Continuous exchange recording is separate from training admission: recording more
exchanges does not increase that training limit.
Recording IDs have durable private receipts so a completed upload can be
recognized after it leaves the recent index. A pending or uncertain ID requires
reconciliation. Do not create another ID or repeat a provider call merely because
an upload timed out or the ID is absent from the recent list.
Existing generated helper
Source configuration
The CLI records the exact dashboard-issued capture URL and provider in.reasonblocks/config.json and generates an adjacent reasonblocks_setup.py.
The application imports that helper. See Endpoint compatibility
for provider paths and native SDK support.
Environment variables
Keys do not belong in generated files or CLI arguments. New keys are persistent
unless an expiration is selected. Existing keys retain their expiration. Source-key
rotation provides a 24-hour overlap, bounded by the previous key’s expiry.
client_kwargs()
Returns client settings containing the configured base_url, default_headers
with x-reasonblocks-key, and max_retries=0. Pass them to the existing OpenAI
or Anthropic Python client constructor. Async clients accept the same settings.
Preserve other application settings and merge headers deliberately.
max_retries=0 disables the SDK’s automatic retries. A timeout can leave paid
work with an unknown outcome, because the provider may already have accepted the
request; a silent retry would repeat it. Reconcile that outcome before retrying.
An application with its own reconciliation policy can override max_retries
explicitly in the returned dictionary.
Run labelling (automatic)
Importing the generated helper installs run labelling for the process: every model call the provider client makes carriesx-rb-run (which task) and x-rb-seq (call number
within the task). The dashboard groups a task’s calls by x-rb-run and, with
x-rb-snapshot-id, uses that group for full-agent training. The sequence number is
carried on every call so a task’s calls stay in order; the dashboard does not
currently read it and groups solely by x-rb-run. The labelling
patches only the HTTP transport the SDK uses, reads no bodies and sends nothing of its
own. It applies to allowlisted hosts; the helper adds the configured capture hostname
to the allowlist, and RBTRACE_HOSTS extends it as described above.
RBTRACE_DISABLE=1 turns it off; python -m rbtrace doctor reports whether calls
from an environment will be labelled.
Without a named task the helper uses one process-wide run ID. That is correct for a
process that handles exactly one task; any process that handles more than one task
must name each task with run_headers() or an explicit rbtrace.client.run() scope.
run_headers(snapshot_id=None, run_id=None)
Returns headers naming one task; if run_id is omitted, generates a new ID. Call once
per task and reuse the result as extra_headers on every model call of that task.
Required for any long-lived or multi-task process (queue worker, web server, batch
loop); unnecessary only when a process runs a single task. Sequence numbers are still
added automatically, keyed by the run ID.
Legacy response headers may describe preliminary training admission. Prefer
rb.status() or Manage connection for completed recording and eligibility,
including streams that fail after their response headers have been sent.
IDs use 1–128 letters, numbers, underscores, periods, colons or hyphens. Header names
are case-insensitive: X-RB-Run / X-RB-Seq (as the shim writes them) and
x-rb-run / x-rb-seq are the same headers. The helper attaches identifiers; it does
not reset tools or create snapshots.
CLI checks and migration
python -m rbtrace doctor --path . --json inspects local configuration, the Python
version, SDK availability, whether the selected SDK’s HTTP transport can be
labelled, capture-key presence and the task-header contract. It makes no network
calls and does not validate provider credentials or prove capture delivery. Use
the helper’s actual directory for --path.
python -m rbtrace migrate converts an older generated gateway connection when
given a real dashboard capture URL, and upgrades an unmodified generated 1.1.0
connection to the current helper when given its existing URL. It backs up the
original files under .reasonblocks/backups/ first. See
migration for backup
behavior, customized helpers and the required application changes.