Existing installations and stored data¶
Version 0.2.0 adds the guided improve init, capture, start and finish
workflow. Python 3.11 remains the minimum. Existing explicit --tasks FILE
commands and runner argv remain valid; agentloop.toml is optional data-only
configuration. Native trace 1.1, task/session 1.0, API v1 and database migration
IDs remain unchanged. No stored-data rewrite or numbering reset is required.
Retain old captures and sessions. New attempts use fresh output directories. Guided results now apply execution, independent quality and positive measured improvement checks to linked native intervention gates as well as the report. Previously rejected attempts must not be interpreted as accepted because of an older intervention gate field. Frozen existing sessions remain readable.
The 0.2.0 Hermes observer accepts >=0.21.6,<0.24. Real-host checks are pinned to 0.22.7 and 0.23.1, and 0.21.6 has contract coverage. Re-export the plugin from the upgraded package into the intended Hermes profile. See guided onboarding and release readiness.
Schema-repair rule 1.2 requires retry_reason: invalid_output_schema or
reason: schema_validation_failed. All retry spans stay in the metrics. Existing
traces without a declared structured-output cause can produce fewer schema-repair
recommendations. The rule's estimate applies only to the qualifying spans.
Version 0.1.1 requires Python 3.11 or newer so supported installations can
use patched dependencies. It adds Hermes tracing and fixes CLI output collisions,
retry/error reporting, and API client credential handling. Native trace schema
1.1, API v1, and database migration IDs continue unchanged; retain existing data.
The TypeScript SDK remains a separately versioned source package, with npm
publication pending.
Version 0.1.0 includes the evidence workflow: canonical findings and estimator
provenance, intervention records, paired studies, offline HTML reports, telemetry
conformance, API v1, graph fixes and explicitly opt-in runtime harness adapters.
The distribution remains agentloop-profiler; imports and the
CLI remain agentloop.
Upgrade order¶
- Back up the database and retain the previous package/deployment configuration. Test restoration before upgrading a production store.
- After the release is published, install the exact
agentloop-profiler==0.2.0version for server/dashboard first. Package numbering resets independently of data schemas; refresh version pins and explicitly reinstall when moving an existing higher-numbered installation. Initialize the configured store withagentloop init-store, then check/readyzand read an existing project trace before resuming writes. - Upgrade Python clients and CLI installations. The new client sends
/v1requests and needs the upgraded server. Configure the server origin or mount path; the client normalizes an optional trailing/v1. Old clients can continue using unversioned routes throughout 0.x. - Update scorer configurations and explicit diagnosis writes as described below. Re-run your task-specific quality fixtures and CI gates on retained traces.
See API v1 for the route mapping. /health and /readyz
remain supported. Unversioned application routes are deprecated; their earliest
removal is 1.0 with a release notice.
Repeat the optional extras you use when upgrading so pip applies their patched dependency requirements. For example, upgrade a dashboard/API installation with:
Installing only the base package does not upgrade optional dependencies left in an existing environment. Source development and standalone dependency groups also declare their security floors for installers that do not read uv constraints.
Diagnosis GET requests now compute without persisting or superseding findings.
Use POST /v1/traces/{run_id}/diagnosis,
AgentLoopClient.save_diagnosis(run_id), or agentloop remote-diagnose to save
recomputed findings. The legacy GET /diagnose alias is also read-only.
Trace and token compatibility¶
Native traces now use schema 1.1. Model events can record token_provenance
as provider, tokenizer, user_supplied, estimated_words, or unavailable.
Reports expose token_status independently of pricing completeness. Existing
schema 1.0 JSON remains readable without rewriting artifacts; missing provenance
is reported as unspecified, not promoted to provider usage.
For compatibility, cost gates continue evaluating legacy unspecified counts when
pricing is known. Counts explicitly marked estimated or unavailable make cost
gates indeterminate. They are non-failing by default, but fail a required positive
minimum cost improvement. Review pricing_known, token_basis_evaluable, and
cost/token status before interpreting a dollar delta as measured savings.
See trace schema and pricing.
Operation kinds are additive metadata; old event categories remain readable. Estimator predictions now carry versioned inputs, coefficients, and assumptions, and remain uncalibrated. An intervention gate pass is evidence only for its configured checks and supplied pair, not proof of general recommendation quality.
Quality scorer names¶
The misleading regex and json_schema scorer names are no longer accepted:
| Previous configuration | Replacement |
|---|---|
regex |
glob, contains, or exact_match, chosen for the intended comparison |
json_schema |
required_fields or json_subset |
These are semantic changes, not automatic renames. glob is bounded wildcard
matching, not a regular-expression engine. required_fields checks field presence,
not full JSON Schema validation. Rewrite and test fixtures accordingly; callers
needing a richer evaluator must supply and validate their own offline scorer.
Database migration and recovery¶
The trace schema, database migrations and package versions are separate. Migration
5, intervention_ledger, creates the project-scoped interventions table in
SQLite and Postgres. The package numbering reset does not reset migration IDs.
Existing trace, finding, usage, and credential records are retained. Store
initialization applies pending migrations; repeated initialization does not
duplicate records.
For SQLite, use its backup API/.backup command or copy the database only after
stopping all writers. For Postgres, take a consistent pg_dump and verify that it
can be restored. Keep backups outside the active database path. Detailed commands
and deployment settings are in production setup.
There is no automatic down migration. If initialization fails, stop the rollout, inspect the migration error locally, correct the reported cause, and retry store initialization. Do not mark an unapplied migration as completed or drop evidence tables to force startup. For rollback, stop writers, restore the pre-upgrade backup, and redeploy the previous server/dashboard/client versions together. Restoration discards post-backup writes; preserve those artifacts separately before rollback when necessary.
Verify the installation¶
In a fresh environment outside the source checkout, install the release and run:
python -m pip install --force-reinstall agentloop-profiler==0.1.1
agentloop quickstart --out quickstart.json
agentloop analyze quickstart.json --html report.html --json-out analysis.json
The synthetic trace should yield findings and a self-contained HTML report. Follow the evidence workflow for a reproducible study and ledger example that retains a rejected quality outcome and unknown cost. These fixtures test artifact behavior, not real-world performance improvements.
Release CI also runs the installed-wheel study and intervention smoke documented
in the release guide. A merged release-preparation PR is not proof
of publication: verify the exact tag's validation, GitHub assets and SHA256SUMS,
and PyPI publication separately. The pypi environment approval remains required.