Changelog

Changelog

All notable changes to the Praval project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.8.1 - 2026-07-18

Release overview

This release gives Praval one provider-neutral execution path for model-backed agents while keeping Reef and Spores as its native collaboration system. It also adds a direct MCP tools client, expands media and embedding support, uses one human approval flow across provider tool loops, and hardens lifecycle, storage, observability, tests, packaging, and release automation.

Version 0.8.0 was briefly uploaded during release preparation and then withdrawn before a matching Git tag and GitHub release existed. PyPI does not allow deleted release filenames to be reused. Version 0.8.1 is therefore the first supported 0.8 release. It keeps the planned 0.8 runtime behavior and adds release diagnostics, wheel-only publication, and clearer validation guidance.

Existing applications can continue to use Agent.chat(), decorated agents, Reef, Spores, and established top-level imports. New applications should use generate(), agenerate(), stream(), or astream() when they need normalized responses, usage, tool events, structured output, or provider-neutral errors.

The detailed release scope is in the release notes. Volatile evidence such as test results, coverage, artifact hashes, live provider results, and voice artifacts is generated by CI instead of being copied into this file.

Highlights

  • One model runtime. OpenAI, Anthropic, Cohere, Gemini, and OpenAI-compatible servers share request, response, streaming, tool, usage, media, and error contracts.

  • Native collaboration stays focused. Reef remains the agent-to-agent substrate. Spores carry structured, correlated knowledge between decorated agents without adding another agent-to-agent layer.

  • Approval can survive a process boundary. HITL can suspend an approval-protected tool call, persist it, accept approval, edits, or rejection, and resume the stored continuation.

  • MCP is a first-class optional client. Praval can discover and call tools from stdio and Streamable HTTP servers through the normal agent tool path.

  • Learning resources are executable. The visual course, four agent-team capstones, and runnable examples are registered for exact-wheel certification.

Added

Model execution and providers

  • Provider-neutral ModelRuntime contracts for sync, async, streaming, structured output, reasoning, multimodal messages, usage, and tool events.

  • Runtime-owned client/function tool loops for OpenAI, Anthropic, Cohere, and Gemini, including provider-neutral HITL suspend/resume state.

  • Native Gemini adapter with function calling, streaming, structured output, and image/file/audio/video inputs.

  • Request-based OpenAI transcription and speech APIs through Agent.transcribe() and Agent.speak().

  • Provider-neutral EmbeddingRuntime for SentenceTransformers, OpenAI, OpenAI-compatible servers, and Gemini.

  • JSON-safe Spore V2 fields for content_parts, knowledge_references, and data_references, while preserving the legacy knowledge-only wire body.

  • First-class OpenAI-compatible presets for Ollama, vLLM, LM Studio, and llama.cpp.

Tools, approval, and MCP

  • Agent.add_tool_spec() for registering an external JSON Schema tool and its handler without creating a second tool registry.

  • Tools-only MCP clients for local stdio and remote Streamable HTTP servers, including discovery, async execution, default HITL approval, tracing, bounded results, secret redaction, and lifecycle cleanup.

  • MCP tool namespacing, timeout and result-size limits, structured result metadata, duplicate rejection, secure URL rules, sanitized errors, and deterministic close behavior.

Collaboration, data, and lifecycle

  • Explicit PravalApp lifecycle ownership and expanded runtime examples.

  • Async Spore handlers as a supported Reef execution path.

  • Completion tracking for tests, demos, and applications that need to wait for Reef work without timing sleeps.

Platform and learning resources

  • praval --version, praval doctor, and praval doctor --json for safe, scriptable installation and environment diagnostics.

  • Python 3.13 support while retaining Python 3.9 through 3.12 for the core framework. The official MCP SDK requires Python 3.10 or newer.

  • A manifest-driven demo runner that installs the exact wheel in an isolated environment, clears source-tree imports, checks package identity, and writes sanitized machine-readable reports.

  • A 13-part visual Jupyter course covering architecture, collaboration, tools, memory, production services, ModelRuntime, HITL, MCP, voice, and multimodal input.

  • Four substantial agent-team showcase capstones: a deterministic Research Intelligence Desk, Customer Support Resolution Center, Software Release Readiness Team, and protected-live OpenAI Marketing Studio. Their committed evidence fixtures, correlated Spore trails, tools, state, recovery paths, final artifacts, provenance, and exact-wheel certification are maintained as release assets.

Changed

Runtime behavior

  • OpenAI model profiles use the Responses API by default where declared.

  • Chat and embedding configuration are independent; Chroma and Qdrant both use the configured embedding runtime.

  • Default OpenAI embedding model is text-embedding-3-small; default Cohere chat model is command-a-03-2025.

  • Provider-hosted tools, provider-hosted MCP descriptors, and computer-use descriptors are experimental explicit pass-through options rather than stable capability claims. Direct MCP clients are a separate capability.

  • ModelResponse.content remains the carrier for provider-constrained JSON text. Applications still parse and validate this text when required.

  • Local OpenAI-compatible presets use conservative capability declarations. Applications opt in to tools, media, structured output, or embeddings only when the configured endpoint supports them.

Quality and packaging

  • Release gates now enforce at least 90% complete-package statement coverage, focused module floors, strict typing/format/lint/docs checks, package integrity, and reproducible distributions.

  • The PDF extra now uses maintained pypdf instead of deprecated PyPDF2.

  • The release bundle contains one universal wheel. The build rejects source distributions, JSON files, and any other extra item in dist/. Checksums, manifests, coverage, demo reports, and certification records belong in evidence/.

  • Documentation is built against the installed exact wheel, with source-tree imports disabled and warnings treated as errors.

  • Paid provider, real HITL, multimodal, STT, and TTS certification is optional, protected, and manually dispatched. It does not run on a push or pull request. Developers can also run the OpenAI checks with their own keys.

Fixed

Model and media behavior

  • GPT-5/o-series Chat Completions parameters and empty-response retry behavior.

  • OpenAI Responses tools now use the API’s required top-level function schema instead of the nested Chat Completions schema.

  • Gemini functionCall/functionResponse round trips.

  • Embedding model/dimension mismatch detection with re-index guidance.

  • Live voice certification now uses a complete committed speech fixture and validates the decoded WAV frame count instead of trusting a streaming WAV header sentinel.

Persistence, cleanup, and safety

  • Reef and ReefChannel shutdown are idempotent, so explicit cleanup is not repeated by interpreter finalization.

  • SQLite HITL connection leaks and deprecated naive UTC timestamps.

  • OpenAI-compatible initialization secret redaction.

  • DataReference URI parsing and round trips, including provider names with underscores and praval:// compatibility references.

  • Short-term memory cleanup workers now stop immediately during shutdown and no longer retain abandoned agent memory instances.

  • StorageRegistry.execute_query() no longer forwards duplicate positional query or data values as keywords.

Observability and tests

  • Observability finalizes spans before one-time storage, handles sync and async wrappers consistently, and initializes and resets idempotently.

  • Async Spore handlers are formally supported, and tests wait for Reef completion instead of sleeping or mocking private callbacks.

  • Every prior expected-failure cause is fixed; strict xfail mode now rejects both XFAIL and XPASS results.

  • Agent communication examples 002 and 003 now use bounded correlated flows, wait for Reef completion, collect worker results, and print them in order.

Compatibility

  • Core Praval supports Python 3.9 through 3.13. The optional official MCP SDK requires Python 3.10 or newer.

  • Agent.chat() remains available for applications that expect a plain string.

  • Decorated agent helpers, Reef delivery, and established top-level imports remain available.

  • Spore V2 adds JSON-safe content and reference fields while preserving the legacy knowledge-only wire body.

  • RabbitMQ is the distributed Reef backend. Redis remains a storage provider. AMQP, MQTT, and STOMP adapters remain part of optional secure transport.

  • PravalApp owns cleanup. It is not a dependency-injection container and does not isolate the process-wide provider registry.

Migration guidance

  • No migration is required for ordinary Agent.chat() or decorated-agent applications.

  • Prefer generate() and agenerate() when code needs ModelResponse, usage, structured output, or tool metadata. Prefer stream() and astream() for normalized events.

  • MCP tools are async-only in this release. Register them inside an MCPClient async context and call them through Agent.agenerate() or Agent.astream().

  • Re-index a vector collection when the configured embedding model or dimension changes. Praval now reports the mismatch instead of allowing incompatible vectors to mix.

  • Replace application-side PyPDF2 imports with pypdf when sharing the PDF extra’s dependency.

  • Replace timing sleeps in Reef workflows with completion waits and always close the Reef, agent, MCP client, storage provider, and exporter that your application owns.

  • Review the runtime migration guide for provider-neutral request and response examples.

Learning resources

Validation and publication

  • Normal CI covers the supported Python versions, complete-package coverage, focused coverage floors, formatting, lint, typing, documentation, package metadata, reproducibility, wheel smoke tests, and exact-wheel offline and service demos.

  • Optional live certification uses real provider APIs. Its voice path performs real STT, agent generation, TTS, and a second STT check. A fake provider or successful early skip cannot satisfy that gate.

  • Release evidence records the commit, exact wheel hash, models, demo results, artifact hashes, and sanitized failures. A source change invalidates prior evidence.

  • CI produces one exact wheel. The maintainer uploads that named wheel with Twine. The tag workflow then checks PyPI’s SHA-256 against the CI manifest and attaches the same wheel to the GitHub release. It does not rebuild or upload.

Known limitations

  • Provider capabilities depend on both the adapter and the selected model. Applications should choose an explicit model and verify its profile.

  • Direct MCP support is limited to tools, text, and structured results. It does not yet consume resources, prompts, or rich binary content.

  • Structured output is provider-constrained output. Local JSON Schema validation remains an application responsibility.

  • Request-based STT and TTS do not provide a persistent realtime session.

  • Retries are explicit and provider-specific. There is no universal hidden circuit breaker, automatic storage fallback, or MCP reconnect layer.

Deferred

  • Realtime WebRTC/WebSocket voice sessions and raw binary Spore attachments remain 0.9 work.

  • MCP resources/prompts, server hosting, OAuth negotiation, rich binary/image results, automatic reconnect, and optional sync bridging remain 0.9 work.

  • Broader provider contract suites, scheduled real-service tests, branch coverage ratchets, and further typing-exemption reductions remain follow-up work for the 0.8 line.

0.7.22 - 2026-02-21

Added

  • Agent-gated HITL support via @agent(..., hitl=False|True) (default False).

  • Durable SQLite-backed intervention queue and suspended run state.

  • New HITL package exports: models, runtime, store, and service APIs.

  • CLI commands for intervention operations:

    • praval hitl pending

    • praval hitl show <intervention_id>

    • praval hitl approve <intervention_id>

    • praval hitl reject <intervention_id>

    • praval hitl resume <run_id>

  • Tool metadata fields:

    • requires_approval

    • risk_level

    • approval_reason

  • HITL examples:

    • examples/015_hitl_tool_approval.py

    • examples/016_hitl_mixed_agents.py

  • Release notes: docs/releases/RELEASE_NOTES_0.7.22.md

Changed

  • OpenAI, Anthropic, and Cohere providers now route tool calls through unified HITL runtime when context is supplied.

  • Agent.chat() now forwards HITL run context to providers and propagates InterventionRequired.

  • tests/test_all_examples.py now discovers executable Python examples recursively under examples/.

  • Sphinx docs include HITL tutorial and troubleshooting guidance.

Fixed

  • Prevents silent policy bypass: if a tool requires approval but agent has hitl=False, Praval raises HITLConfigurationError.

Migration Notes

  • Handle InterventionRequired in callers for HITL-enabled agents.

  • Keep non-HITL agents unchanged by leaving hitl=False (default).

  • For approval-gated tools, set hitl=True on the owning/executing agent.

Validation Evidence

  • make test passed: 1272 passed, 15 skipped, 28 xfailed, 1 xpassed.

  • make test-cov test execution passed, but coverage gate failed at 82.14% (target >=90%).

  • make lint and make type-check remain blocked by pre-existing repo-wide lint/mypy backlog.

  • Example sweep (python tests/test_all_examples.py) status: 30 passed, 0 failed.

  • HITL examples pass:

    • examples/015_hitl_tool_approval.py

    • examples/016_hitl_mixed_agents.py

  • Docker example validation script passed:

    • scripts/test-docker-examples.sh

0.7.21 - 2026-02-09

Added

  • Reef performance options: shared thread pool (use_shared_pool) and handler batching (batch_size).

  • Reef authorization hook (auth_provider) for per-action checks.

  • Agent conversation history cap via max_history (default 100, None = unbounded).

  • Unit tests covering transport backends (AMQP/MQTT/STOMP), agent runner, reef backend, observability exporters, and optional storage providers.

Changed

  • Spore payload size estimation uses JSON-based byte estimation (faster, less memory).

  • Async backend calls use a persistent event loop instead of per-call loops.

  • Async handlers run on per-channel shared event loop.

  • Embedded vector store uses an isolated default storage subdirectory and cleans up on shutdown.

Fixed

  • SQLite trace store handles unwritable paths without crashing.

  • Observability context handles non-mapping metadata; span duration now enforces a minimum positive duration.

  • Agent coroutine handlers are awaited in on_spore_received.

  • Reef shutdown now resets shared backend state and avoids descriptor leaks.

  • Secure reef configuration now propagates auth_provider.

Security

  • Optional broadcast rate limiting (per-agent, per-second).

  • Provider error messages redact API keys when present.

[0.7.18] - 2025-12-08

Added

  • 🎯 Deterministic Multi-Agent Synchronization - wait_for_completion() method for reliable agent coordination

    • reef.wait_for_completion(timeout=30.0) - Block until all agents finish processing

    • Replaces error-prone time.sleep() patterns with deterministic completion tracking

    • Uses future tracking with _active_futures and thread-safe _futures_lock

    • Supports both ReefChannel and Reef levels

Fixed

  • 🔧 broadcast() Channel Resolution - Fixed silent failures in agent chaining

    • broadcast() now correctly uses the startup channel set by start_agents()

    • Stores _startup_channel on agents during start_agents() for proper channel propagation

    • Prevents messages from being sent to wrong channels in multi-agent workflows

    • Maintains backward compatibility with explicit channel parameter

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • 📝 Updated All Examples - 13 examples updated to use new synchronization pattern

    • Replaced time.sleep() with get_reef().wait_for_completion()

    • Added proper get_reef().shutdown() calls for clean termination

    • Examples now demonstrate production-ready patterns

Technical Details

  • Modified: src/praval/core/reef.py - Added wait_for_completion() method with future tracking

  • Modified: src/praval/decorators.py - Fixed broadcast() channel resolution

  • Modified: src/praval/composition.py - Store _startup_channel on agents

  • Updated: Examples 001-010, blog demos, website sidebar example

Migration Path (v0.7.17 → v0.7.18)

# Old way (v0.7.17) - unreliable timing
start_agents(agent1, agent2, initial_data={...})
time.sleep(3)  # Hope agents finish in time

# New way (v0.7.18) - deterministic completion
from praval import get_reef

start_agents(agent1, agent2, initial_data={...})
get_reef().wait_for_completion()  # Block until all agents done
get_reef().shutdown()  # Clean termination

[0.7.17] - 2025-12-07

Added

  • 🧪 Comprehensive Storage System Tests - 340+ new test cases for storage providers

    • Tests for FileSystem, PostgreSQL, Redis, S3, Qdrant providers

    • Tests for StorageRegistry, DataManager, and exception handling

    • Testcontainers integration for real database testing

    • Added testcontainers[postgres,redis,qdrant] and moto[s3] dev dependencies

  • 🔧 Test Isolation Infrastructure

    • Added tests/conftest.py with autouse fixture for global state reset

    • Added reset_tracer() function in observability tracer module

    • Added reset_trace_store() function in SQLite store module

    • Comprehensive reset of Reef, Registry, ToolRegistry, Agent context

  • 📖 New Examples

    • blog_multi_agent_demo.py - Multi-agent collaboration example

    • blog_tools_and_observability_demo.py - Tools and tracing example

Fixed

  • 🐛 Test Suite Reliability - Fixed test pollution causing failures in full suite run

    • Tests now properly isolated with global singleton reset between tests

    • Improved test pass rate from 906 to 964 tests

Technical Details

  • Modified: src/praval/observability/tracing/tracer.py - Added reset function

  • Modified: src/praval/observability/storage/sqlite_store.py - Added reset function

  • Added: tests/conftest.py - Pytest fixtures for test isolation

  • Added: tests/storage/ - Complete storage provider test suite

[0.7.16] - 2025-11-08

Fixed

  • 🔧 broadcast() Now Works for Agent Chaining - Fixed silent failure where broadcast() messages weren’t reaching other agents

    • broadcast() now defaults to reef’s default channel (“main”) instead of agent’s own channel

    • Enables simple agent-to-agent communication patterns (researcher → analyst → writer)

    • Prevents silent failures - messages now reach intended recipients

    • Maintains backward compatibility - explicit channel specification still works

Added

  • 🎯 Broadcast Channel Options

    • Simple mode (default): broadcast() reaches all agents on default channel

    • Advanced mode: explicit channel parameter for separation of concerns

    • Examples in docstring showing both approaches

  • 🧪 Comprehensive Broadcast Tests (tests/test_broadcast_chaining.py)

    • 5 new tests covering: simple broadcasts, multi-stage chains, explicit channels, filtering, isolation

    • Tests verify agent chaining works correctly

    • Validates agents don’t receive their own broadcasts

  • 📖 Website Sidebar Example (examples/website_sidebar_example.py)

    • Demonstrates three-agent collaboration pattern

    • Shows broadcast-based message passing with responds_to filtering

    • Ready-to-run example for documentation

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • 📝 Updated broadcast() Docstring

    • Clarified that channel parameter is optional

    • Added examples of default and explicit usage

    • Documented design philosophy: simple by default, explicit when needed

Technical Details

  • Modified: src/praval/decorators.py

    • broadcast() function now gets reef’s default_channel when channel=None

    • Updated docstring with clear examples

    • Added comments explaining design decisions

[0.7.15] - 2025-11-08

Fixed

  • 🔧 RabbitMQ Queue Consumption with Pre-configured Queues - Agents can now consume from pre-configured RabbitMQ queues instead of only topic-based subscriptions

    • Added channel_queue_map parameter to run_agents() and AgentRunner

    • Enables agents to work with existing RabbitMQ setups with queue bindings

    • Solves issue where messages on different exchanges weren’t reaching agents

Added

  • 📚 Queue-Based Consumption Support

    • RabbitMQBackend now supports both topic-based (default) and queue-based consumption modes

    • Channel-to-queue mapping allows direct consumption from pre-configured queues

    • Example: {"data_received": "agent.data_analyzer"} maps channel to queue

  • 🚀 Enhanced run_agents() Function

    • New channel_queue_map parameter for queue-based routing

    • Documentation with examples for both topic-based and queue-based approaches

    • Hybrid mode support (some channels use queues, others use topics)

  • 🏗️ Enhanced AgentRunner Class

    • Accepts channel_queue_map in constructor

    • Automatically creates RabbitMQBackend with queue mappings

    • Full documentation and examples

  • 📖 Documentation: docs/rabbitmq-queue-consumption.md

    • Explains topic-based vs queue-based routing

    • Real-world examples with pre-configured RabbitMQ setups

    • Hybrid approach examples

    • Troubleshooting guide

Technical Details

  • Modified: src/praval/core/reef_backend.py

    • RabbitMQBackend.init() now accepts channel_queue_map

    • subscribe() method supports both modes based on mapping

    • Enhanced documentation with mode explanations

  • Modified: src/praval/core/agent_runner.py

    • AgentRunner.init() accepts channel_queue_map

    • _create_backend() passes mapping to RabbitMQBackend

    • run_agents() function supports channel_queue_map parameter

  • Modified: src/praval/composition.py

    • run_agents() function updated with channel_queue_map parameter

    • Enhanced documentation with dual-mode examples

Breaking Changes

  • None - Fully backward compatible

Migration Path (v0.7.14 → v0.7.15)

No changes needed. All v0.7.14 code works unchanged.

To use pre-configured queues:

# Old way (still works - topic-based)
run_agents(agent1, agent2, backend_config={...})

# New way (queue-based for existing RabbitMQ setups)
run_agents(
    agent1, agent2,
    backend_config={...},
    channel_queue_map={
        "channel1": "existing.queue.1",
        "channel2": "existing.queue.2"
    }
)

Backward Compatibility

✅ All v0.7.14 code continues to work ✅ Default behavior (topic-based) unchanged ✅ No breaking API changes ✅ Can mix topic and queue-based consumption in same runner

[0.7.14] - 2025-11-08

Fixed

  • 🔧 Critical: RabbitMQ Distributed Agent Message Consumption - Fixed issue where distributed agents weren’t consuming messages from RabbitMQ broker

    • Root cause: No async event loop running to handle RabbitMQ subscription and message delivery

    • Solution: AgentRunner class manages proper async lifecycle for distributed agents

    • Agents now properly initialize backend, subscribe to queues, and consume messages

Added

  • ✨ AgentRunner Class - Proper lifecycle management for distributed agents

    • Manages asyncio event loop creation and cleanup

    • Handles RabbitMQ backend initialization before agent subscription

    • Graceful shutdown on SIGTERM/SIGINT signals

    • Signal handler for Ctrl+C interrupts

    • Methods: run(), run_async(), initialize(), shutdown()

    • Async context manager: async with runner.context():

  • 🚀 run_agents() Function - Convenience function for distributed agent deployment

    • Replaces need for manual event loop management

    • Recommended for simple distributed setups

    • Handles all lifecycle automatically

    • Usage: run_agents(agent1, agent2, backend_config={...})

  • 📚 Documentation - Comprehensive agent lifecycle documentation

    • docs/agent-lifecycle.md - Complete lifecycle management guide

    • Explains local vs distributed agent execution

    • Troubleshooting guide for common issues

    • Migration guide from v0.7.13 to v0.7.14

  • 💡 Working Example - examples/distributed_agents_bootstrap.py

    • Demonstrates proper use of run_agents() with RabbitMQ

    • Shows multi-agent workflows (processor → analyzer → reporter)

    • Includes proper error handling and signal handling

    • Clear documentation of the v0.7.13 issue and solution

Testing

  • New Tests: tests/test_distributed_agent_startup.py

    • AgentRunner initialization tests

    • Backend compatibility tests

    • Lifecycle management tests

    • Signal handling tests

    • Multi-agent coordination tests

  • New Integration Tests: tests/integration/test_rabbitmq_distributed_workflow.py

    • End-to-end distributed workflow tests

    • Message delivery verification

    • Broadcast delivery tests

    • Multi-agent coordination tests

    • Requires RabbitMQ (marked with @pytest.mark.skipif)

Technical Details

  • New File: src/praval/core/agent_runner.py (350+ lines)

    • AgentRunner class with full async lifecycle

    • run_agents() convenience function

    • Comprehensive docstrings and examples

  • Modified: src/praval/composition.py

    • Added run_agents() function for distributed agents

    • Updated docstrings to clarify local vs distributed usage

    • Imported AgentRunner for distribution

  • No Breaking Changes: All v0.7.13 code remains compatible

    • InMemoryBackend works unchanged

    • start_agents() for local agents still works

    • Existing distributed code can migrate gradually

Breaking Changes

  • None - Fully backward compatible with v0.7.13

Migration Path (v0.7.13 → v0.7.14)

If you were using RabbitMQ in v0.7.13:

# Old way (didn't work - agents didn't consume messages)
@agent("processor")
def process(spore):
    return {}

# New way (v0.7.14 - works correctly)
from praval.composition import run_agents

run_agents(
    process,
    backend_config={'url': 'amqp://localhost:5672/'}
)

Performance

  • Startup time: <100ms (backend initialization)

  • Message consumption: Immediate (event loop polling)

  • No performance regression vs v0.7.13

Known Limitations

  • RabbitMQ agent processes cannot be nested/spawned from other agent processes

  • Event loop must be created at top-level (can’t run run_agents() from async code)

  • Use AgentRunner.context() if inside async code

[0.7.13] - 2025-11-07

Added

  • 🔄 Native Spore AMQP Serialization - Spore is now the canonical wire format for RabbitMQ

    • Spore.to_amqp_message() - Serialize Spore to AMQP message (metadata in headers, knowledge in body)

    • Spore.from_amqp_message() - Deserialize AMQP message directly to Spore

    • Eliminates 4-5 conversion layers → 1 clean conversion

    • Foundation for single wire protocol across all transports

  • 🔌 Pluggable Reef Backends - Support multiple transport backends without agent code changes

    • ReefBackend abstract interface for pluggable backends

    • InMemoryBackend - Local agent communication (new, default for backward compatibility)

    • RabbitMQBackend - Distributed agent communication via RabbitMQ

    • Agents work unchanged whether using local or distributed backends

    • Foundation for future backends (HTTP, gRPC, Kafka, etc.)

Features

  • Distributed Agents: Deploy agents across multiple processes/machines with RabbitMQ

  • Transparent Transport: Same agent code works locally or distributed

  • Production Ready: Full RabbitMQ integration with TLS support

  • Zero Code Changes: Existing agents work without modification

Example

# Same agent code, different backend!
from praval.core.reef import Reef
from praval.core.reef_backend import RabbitMQBackend

backend = RabbitMQBackend()
reef = Reef(backend=backend)
await reef.initialize_backend({'url': 'amqp://localhost:5672/'})
# Now agents communicate via RabbitMQ!

Testing

  • 24 new tests for Spore AMQP serialization (roundtrip, edge cases, all spore types)

  • 27 new tests for backend implementations (InMemory, RabbitMQ, abstraction)

  • 100% backward compatibility - All 24 existing tests pass

  • Total: 75 tests passing

Documentation

  • Comprehensive v0.7.13 release guide: docs/v0.7.13-native-spore-amqp.md

  • Distributed agents example: examples/distributed_agents_with_rabbitmq.py

  • Configuration guide and troubleshooting

Technical Details

  • Modified: src/praval/core/reef.py (+42 lines, 2 new async methods)

  • Added: src/praval/core/reef_backend.py (420 lines, 3 backend implementations)

  • Enhanced: src/praval/core/transport.py (improved AMQP serialization)

  • Tests Added: tests/test_spore_amqp_serialization.py (545 lines, 24 tests)

  • Tests Added: tests/test_reef_backends.py (539 lines, 27 tests)

  • Breaking Changes: None - fully backward compatible

Performance

  • Spore → AMQP roundtrip: < 2ms

  • RabbitMQ p99 latency: < 100ms

  • Throughput: 10,000+ spores/sec

  • No performance regressions

Migration

  • No migration needed for existing code

  • Opt-in: Use RabbitMQBackend for distributed deployments

  • Default: InMemoryBackend for backward compatibility

Impact

  • ✅ Production-ready microservices architecture

  • ✅ Single wire protocol (Spore in AMQP)

  • ✅ Foundation for additional backends

  • ✅ 100% backward compatible

  • ✅ Zero breaking changes

[0.7.12] - 2025-11-06

Fixed

  • 🐛 Critical: Reef Broadcast Agent Invocation - Fixed issue where @agent decorated functions were not being invoked when reef.broadcast() was called

    • Agents now subscribe to both their own channel AND the default broadcast channel

    • Prevents duplicate invocations through handler delegation

    • Unblocks Phase 3B agent processing pipeline

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • Enhanced agent subscription mechanism in @agent decorator

  • ReefChannel handler invocation already supported both scenarios

Testing

  • Added comprehensive test suite: tests/test_reef_broadcast_fix.py (12 tests)

  • Tests cover: basic invocation, multiple agents, no duplicates, custom channels, concurrency, regressions

  • All 89 tests passing (12 new + 53 decorator + 24 reef)

Technical Details

  • Modified: src/praval/decorators.py (~10 lines)

  • Added: tests/test_reef_broadcast_fix.py (445 lines)

  • Breaking Changes: None - fully backward compatible

Impact

  • ✅ Agents now correctly receive broadcasts from reef.broadcast()

  • ✅ Unblocks entire Phase 3B agent processing pipeline

  • ✅ Enables proper spore-based communication patterns

  • ✅ No regressions to existing functionality

[0.7.11] - 2025-11-05

Added

  • 📊 Built-in Observability Framework - Comprehensive, zero-configuration distributed tracing for multi-agent systems

    • Automatic Instrumentation: All agents, reef communication, memory operations, storage I/O, and LLM calls automatically traced

    • OpenTelemetry Export: OTLP compliance with support for Jaeger, Zipkin, Honeycomb, DataDog, New Relic

    • Console Viewer: Rich terminal output with tree hierarchy, ANSI colors, timing, and statistics

    • Local Storage: SQLite backend with query interface and trace retrieval

    • <5% Overhead: Minimal performance impact with configurable sampling (0.0-1.0)

Features

  • Zero Configuration: Auto-detection based on environment (dev vs production)

  • Trace Context Propagation: Automatic parent-child span relationships across agents via Spore metadata

  • Four Span Kinds: SERVER (agent execution), CLIENT (LLM/storage), PRODUCER (reef comms), INTERNAL (memory ops)

  • Query Interface: Find spans by name, status, duration, trace ID with built-in analytics

Documentation

  • docs/observability/README.md: Comprehensive usage guide

  • docs/observability/quickstart.md: Quick start tutorial

  • 4 Examples: Quickstart, basic tracing, configuration, context propagation demos

Statistics

  • ~2,500 lines: Core implementation

  • ~1,300 lines: Tests (78 tests, 94% passing)

  • ~800 lines: Documentation

  • 33 new files: 10 implementation, 7 test, 4 example, 2 docs

Configuration

PRAVAL_OBSERVABILITY="on"  # on, off, or auto (default)
PRAVAL_OTLP_ENDPOINT="http://localhost:4318/v1/traces"
PRAVAL_SAMPLE_RATE="1.0"  # 0.0-1.0

Breaking Changes

None - Fully backward compatible, opt-in feature

[0.7.10] - 2025-10-28

Fixed

  • 🐛 Jupyter Duplicate Execution - Agents no longer execute multiple times when re-registering in notebooks

  • 🔧 Channel Subscription - Added replace parameter to subscribe() to prevent handler accumulation

Added

  • 🎓 Student Analytics AI Example - Interactive notebook with 6 AI-powered agents analyzing student performance

  • 🎨 AI Code Generation - Visualization agent dynamically generates matplotlib code (not templates!)

  • 📚 Documentation Infrastructure - Sphinx setup with 5 new make targets (docs-html, docs-serve, docs-clean, docs-check, docs-deploy)

  • 🧪 Interactive Environment Tests - Comprehensive test suite (165 lines) for notebook scenarios

  • 📖 Building Agents Tutorial - Step-by-step Jupyter notebook for learning Praval

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • 🎯 Default Subscribe Behavior - Now replaces handlers by default (set replace=False for append behavior)

Examples

  • student_analytics_ai.ipynb - 6 AI agents with parallel execution and code generation (198KB)

  • student_analytics.py - Python script version for CLI execution (16KB)

  • building_agents_tutorial.ipynb - Interactive tutorial (82KB)

Technical Details

  • Modified: src/praval/core/reef.py (~40 lines)

  • Added: tests/test_duplicate_agent_registration.py (165 lines)

  • Enhanced: Makefile with documentation targets

  • Updated: pyproject.toml with [docs] dependency group

Benefits

  • ✅ Seamless Jupyter notebook development

  • ✅ Showcase of true multi-agent AI collaboration

  • ✅ Demonstrates AI creativity through code generation

  • ✅ Production-ready documentation infrastructure

[0.7.9] - 2025-10-23

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • 🚀 Flexible Installation Options - Choose your installation size!

    • Minimal (pip install praval): ~50MB - Core agents and LLM providers only

    • Memory (pip install praval[memory]): ~500MB - Adds vector storage and embeddings

    • Full (pip install praval[all]): ~1.5GB - All features including enterprise messaging

  • 📦 Restructured Dependencies:

    • Core: Only essential LLM providers and configuration (~50MB vs ~1.5GB)

    • Optional extras: [memory], [secure], [pdf], [storage], [all]

    • Faster installation for users who don’t need all features

    • Reduced barrier to entry for new users

Added

  • 🔧 New Installation Extras:

    • praval[memory] - ChromaDB, sentence-transformers, scikit-learn

    • praval[secure] - Secure Spores with AMQP, MQTT, STOMP, encryption

    • praval[pdf] - PDF knowledge base support

    • praval[storage] - PostgreSQL, Redis, S3, Qdrant providers

    • praval[all] - Everything combined

Documentation

  • Updated README with clear installation options and size comparisons

  • Updated requirements.txt with commented optional dependencies

  • Added feature-to-dependency mapping

Benefits

  • ⚡ 30x faster minimal installation (~2min vs ~10min)

  • 💾 30x smaller minimal package (~50MB vs ~1.5GB)

  • 🎯 Users only install what they need

  • 🚀 Lower barrier to entry for new users

[0.7.8] - 2025-10-23

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • 🔒 Distribution Strategy - Now distributing wheel-only packages to PyPI

    • Source code, examples, and documentation remain private

    • Only compiled wheel (.whl) available on PyPI

    • Users can install via pip install praval but cannot access source

    • Full source available on GitHub when project is open-sourced

Infrastructure

  • Updated release process to upload wheels only

  • Enhanced Makefile with interactive release wizard

  • Improved documentation organization

Note

This is a re-release to implement wheel-only distribution strategy. Versions 0.7.6 and 0.7.7 have been removed from PyPI.

[0.7.7] - 2025-10-23

Added

  • 📦 Manual Release Process Documentation - Comprehensive RELEASE.md guide

    • Step-by-step instructions for version bumping

    • PyPI publication workflow

    • Testing and verification procedures

    • Rollback and troubleshooting guides

  • 🔧 GitHub Actions Workflow - Automated release infrastructure (disabled by default)

    • Automatic version detection from commit messages

    • PyPI upload automation

    • GitHub release creation

    • Can be enabled when ready for automated releases

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • 🎯 Version Control Strategy - Moved to manual deliberate version bumps

    • Auto-versioning workflow disabled for more control

    • Prevents accidental major version jumps

    • Ensures version 1.0.0 is a deliberate milestone decision

  • 📚 Repository Organization - Comprehensive cleanup and documentation

    • Documentation organized in docs/ with archive/ subdirectory

    • Removed redundant files and build artifacts

    • Enhanced PyPI metadata with keywords and project URLs

    • Added UV installation support

Fixed

  • 🔒 Security - Removed exposed API keys from repository

    • Cleaned .env files from git history

    • Enhanced .gitignore patterns

    • Proper credential management documentation

  • 🧪 Test Suite - Fixed import errors in test files

    • Corrected module paths (src.praval → praval)

    • Added test environment setup for CI/CD

    • All core tests now passing

Infrastructure

  • ✅ PyPI publication ready (v0.7.6 successfully published)

  • ✅ UV package manager compatible

  • ✅ GitHub Actions infrastructure configured

  • ✅ Comprehensive release documentation

[0.7.6] - 2024-12-03

Added

  • 🏗️ Collection Separation Architecture - Separate ChromaDB collections for knowledge base vs conversational memory

    • Knowledge Collection: Immutable storage for semantic memories (knowledge base files, facts)

    • Memory Collection: Mutable storage for episodic and conversational memories

    • Smart Memory Routing: Automatic routing based on memory type (semantic → knowledge, others → memory)

    • Cross-Collection Operations: Search, retrieve, and stats work seamlessly across both collections

Enhanced

  • 🛡️ Data Integrity & Security

    • Immutable knowledge base - knowledge cannot be deleted, providing data protection

    • Selective deletion policy - only conversational memory can be deleted

    • Safe memory clearing - clear_agent_memories() preserves knowledge base, only clears conversations

  • 🔄 Migration & Compatibility

    • Automatic migration from legacy single collections to separated architecture

    • Zero-downtime migration - existing data is preserved and properly migrated

    • Backward compatibility - legacy single-collection mode still supported

  • 📊 Enhanced Features

    • Detailed statistics with separate metrics for knowledge vs conversational memories

    • Health monitoring across both collections

    • Memory manager integration with separated collections enabled by default

Fixed

  • ChromaDB API compatibility issues with get() vs query() result structures

  • Numpy array boolean evaluation errors in memory operations

  • Collection migration edge cases and error handling

  • Memory retrieval across separated collections

Technical

  • 17 comprehensive test cases covering initialization, storage, routing, migration

  • Production-ready implementation with proper error handling and logging

  • Enhanced documentation and code comments

[0.7.5] - 2024-12-03

Fixed

  • ChromaDB collection initialization error when collections don’t exist

  • Knowledge base auto-indexing now works correctly with memory-only fallback scenarios

  • Exception handling for ChromaDB NotFoundError instead of ValueError

Improved

  • More robust error handling during ChromaDB collection creation

  • Better integration between @agent decorator and knowledge base functionality

  • Automatic collection creation with proper metadata configuration

[0.7.4] - 2024-12-03

Added

  • Comprehensive knowledge base benchmark tests (test_knowledge_base_benchmark.py)

  • Pytest custom markers for better test organization (unit, integration, performance, edge_case, knowledge_base)

Fixed

  • Version discrepancy in __init__.py docstring

  • Pytest marker warnings by adding proper marker configuration in pyproject.toml

Improved

  • Test coverage for knowledge base functionality with performance benchmarks

  • Documentation accuracy for current version features

[0.6.2] - 2025-08-21

Added

  • 🐳 Containerized Examples Infrastructure - Production-ready Docker deployments

    • Memory Agents Container: Complete setup for memory-enabled agent demonstrations

    • Unified Storage Container: Full-stack demo with PostgreSQL, Redis, MinIO, Qdrant

    • Shell Script Orchestration: End-to-end automation with service health monitoring

    • Multi-Service Docker Compose: Professional development and testing environments

Fixed

  • 🔧 Qdrant Docker Health Check: Updated to use /readyz endpoint with bash networking

  • 📚 Example Organization: Properly renumbered examples and fixed import issues

  • 🔑 Environment Configuration: Added load_dotenv() support to all examples

  • 🧪 Testing Infrastructure: Comprehensive validation scripts for containerized examples

Enhanced

  • 🗄️ Cross-Storage Operations: Demonstrated filesystem + PostgreSQL integration

  • 📊 Production Logging: Enhanced monitoring and result reporting

  • 🚀 Developer Experience: One-command Docker setup with automatic cleanup

[0.6.1] - 2025-08-20

Added

  • 🗄️ Unified Data Storage & Retrieval System - Enterprise-grade data ecosystem

    • Base Provider Framework: Abstract base class for consistent storage interfaces

    • Storage Registry: Centralized provider discovery with permissions and health monitoring

    • Built-in Providers: Production-ready PostgreSQL, Redis, S3, Qdrant, and FileSystem providers

    • Storage Decorators: @storage_enabled() and @requires_storage() for declarative access

    • Data References: Lightweight sharing of large datasets through spore communication

    • Memory Integration: Unified interface combining memory system with external storage

    • Cross-Storage Operations: Query and manage data across multiple storage backends

  • 📊 Enhanced Data Management

    • Async connection pooling and health monitoring

    • Smart storage selection based on data characteristics

    • Batch operations for high-throughput scenarios

    • Security with permission-based access control per agent

    • Environment-based auto-registration of storage providers

  • 📖 Comprehensive Documentation

    • Complete PART VI section in praval.md (800+ lines)

    • Production examples demonstrating multi-storage workflows

    • Integration patterns and best practices

    • Storage provider development guide

Enhanced

  • 🔄 Spore Communication System

    • Enhanced spore protocol to support data references

    • Added data_references field for lightweight large data sharing

    • Methods: add_data_reference(), has_data_references(), has_any_references()

  • 🧠 Memory System Integration

    • Bridge between existing memory system and external storage

    • Unified memory-storage interface for agents

    • Cross-system data operations and retrieval

  • 📦 Framework Exports

    • Added comprehensive storage system exports with graceful fallbacks

    • New exports: BaseStorageProvider, StorageRegistry, DataManager, all providers

    • STORAGE_AVAILABLE flag for optional dependency handling

Examples

  • 📊 Unified Storage Demo (examples/unified_storage_demo.py)

    • Multi-agent workflow demonstrating PostgreSQL, Redis, and S3 integration

    • Data collection, analysis, and reporting across storage backends

    • Production-ready patterns for enterprise deployments

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • Updated version to 0.6.1 across all configuration files

  • Enhanced framework documentation to reflect new capabilities

  • Improved error handling throughout storage system

0.5.0 - 2025-08-09

Added

  • 🧠 Comprehensive multi-layered memory system

    • Short-term memory for working context

    • Long-term memory with ChromaDB vector storage

    • Episodic memory for conversation history

    • Semantic memory for knowledge and facts

  • 📊 Production-ready testing suite

    • 99% test coverage on decorators module

    • 100% test coverage on composition workflows

    • 4,750+ lines of comprehensive memory system tests

  • ✨ Enhanced agent capabilities

    • Memory-enabled agents with persistent knowledge

    • Dynamic knowledge reference creation and resolution

    • Advanced agent communication patterns

    • Knowledge base integration for document indexing

  • 📚 Complete documentation overhaul

    • Updated README.md with v0.5.0 features

    • Enhanced praval.md with comprehensive documentation

    • 1.5MB complete manual PDF

    • 9 progressive learning examples (001-009)

  • 🏗️ Production infrastructure

    • Docker support with development environment

    • Modern Python packaging with pyproject.toml

    • Pre-commit hooks and CI/CD configuration

    • Repository reorganization with proper structure

Changed

  • Spore is now immutable; mutation requires creating a new Spore (use add_* methods which return new instances).

  • Updated version numbering to follow semantic versioning

  • Reorganized repository structure for better maintainability

  • Enhanced error handling and resilience throughout framework

Removed

  • Legacy example files that were replaced with new progressive series

  • Deprecated API patterns in favor of cleaner decorator approach