Migrate from v0.8.2 to v0.8.3

v0.8.3 adds an explicit OpenTelemetry foundation and a provider-neutral evaluation system. Agent, ModelRuntime, Reef, Spore, tool, storage, memory, HITL, and MCP application contracts remain compatible unless noted here.

Runtime support

Python 3.9 support ends with v0.8.2. v0.8.3 supports Python 3.10 through 3.14. Upgrade the application interpreter and rebuild environments before installing the wheel. The MCP extra no longer needs a separate Python-version caveat.

Observability

Observability is disabled by default. Importing Praval no longer implies a local trace database or SDK lifecycle.

  1. Install praval[observability] only when Praval should construct SDK providers and OTLP exporters.

  2. Call configure_observability() once at process startup.

  3. Give each deployable service a stable name and send OTLP to a Collector.

  4. Enable local SQLite explicitly for single-process diagnosis only.

  5. Call bounded force_flush()/shutdown_observability() during graceful termination.

The old flat sample_rate, otlp_endpoint, and storage_path inputs map to sample_ratio, otlp, and local with deprecation warnings. Compatibility Tracer, local viewer, and export helpers remain, but new code should use the official APIs described in API reference and v0.8.2 migration.

Do not move prompts, responses, tool payloads, or exception messages into span or metric attributes. The default ExecutionObservation is metadata-only and aggregates bounded facts into one record per agent/workflow.

Evaluation

Evaluation is additive and disabled until configured or explicitly constructed. Core datasets, SQLite, deterministic metrics, judges, runners, gates, baselines, CLI, and online contracts are in the base wheel. Install eval-ragas only for the optional RAGAS adapter and storage for shared PostgreSQL deployments.

Start with an offline deterministic suite:

praval eval run <suite> --module <agent-registration-module> --json

Targets must be registered as agent:<name> for the v0.8.3 CLI. AgentEvaluationTarget rejects persistent conversation state and requires one agent observation per case. Model and agent judges use separate versioned profiles and strict outputs. Baseline promotion is explicit.

Online evaluation remains disabled by default and requires PostgreSQL. It samples by trace, enqueues bounded observations without storage/judge work on the request path, and runs judges from explicitly owned durable workers.

Configuration

The complete schema is version 1. Configuration precedence is defaults, nearest/explicit praval.toml, supported environment variables, then explicit API overrides. Unknown fields and bad cross-references now fail rather than being ignored. Keep DSNs, provider keys, and OTLP headers in named environment variables.

Run after migration:

praval doctor --json

The report includes core/SQLite evaluation availability plus installed PostgreSQL, RAGAS, and OpenTelemetry components. It reports secret presence, never secret values.

Removed or nonexistent claims

v0.8.3 does not provide praval.explainability, praval.security, or a get_metrics() convenience API. Use praval.observability for signals, praval.eval for quality records/gates, and the existing secure Spore/transport modules for message security.

Validation checklist

  • Run application tests on Python 3.10 through 3.14.

  • Run praval doctor --json and check optional extras.

  • Execute observability quickstarts against a Collector and bounded shutdown.

  • Run offline suites from the exact wheel; explicitly promote an approved baseline and verify CI exit codes.

  • Validate privacy with content capture off.

  • If using online eval, test saturation, database outage, restart, duplicate delivery, timeout, dead letter, and shutdown before enabling sampling.

See Evaluation and Observability for complete operational guidance.