Praval Logo

User Guide

  • Getting started
    • Install
    • First path: call a model through Agent
    • Structured output
    • Second path: collaborate through Reef
    • When to use each layer
    • Local models
    • Learn by inspecting execution
  • Core concepts and API layers
    • Mental model
    • Direct Agent API
    • Decorated agents
    • Spores
    • Reef delivery
    • Tools and human approval
    • Memory, embeddings, and storage
    • Lifecycle
    • What to read next
  • Application lifecycle
    • Ownership boundary in 0.8
    • Errors
  • Model Runtime
    • Request Options
    • Public Inspection
    • Runtime Events
    • Client Tool Orchestration
  • Providers
    • Provider Names
    • Capability Matrix
    • Provider-Hosted Tools and MCP Descriptors
    • Registry Inspection
    • Provider Profile Fields
  • Local LLMs
    • Presets
    • Conservative Defaults
    • Base URL Safety
  • Streaming
  • Structured Outputs
  • Multimodal Input
    • Request-Based Voice
    • Multimodal Spores
  • Embeddings
  • Tools
  • MCP Tool Clients
    • Local stdio server
    • Remote Streamable HTTP server
    • Approval and async execution
    • Result handling
    • Lifecycle and security
    • MCP clients and provider-hosted descriptors
    • Explicitly unsupported in 0.8
  • Exact-wheel demo certification
    • Offline and service checks
    • Optional real OpenAI checks
    • Optional all-provider workflow
  • HITL Troubleshooting
    • HITLConfigurationError
    • InterventionRequired during Agent.chat()
    • Pending queue never clears
    • praval hitl resume cannot find agent
    • Resume fails after restart
  • Reef and Spores
  • Memory
    • Provider-Neutral Embeddings
    • Re-indexing Safety
  • Storage
    • Minimal filesystem example
    • DataManager contract
    • Registering providers
    • Provider roles
    • Data references
    • Smart selection and fallback
    • Storage-aware handlers
    • Custom provider contract
    • Failure and cleanup checklist
  • Observability
  • Runtime Migration
    • Agent.chat() to Agent.generate()
    • Provider Strings to Provider and Model
    • Tool Behavior
    • Spore.knowledge to V2 Payload Fields
    • Embedding Configuration
    • Local LLMs
  • Troubleshooting
    • Capability Errors
    • Local Provider Connection Errors
    • Streaming Errors
    • Documentation Quality Gates
  • Documentation Quality
    • Release Gates
    • API Coverage
    • Example Policy

Tutorials

  • Tutorial: Creating Your First Agent
    • What You’ll Build
    • Prerequisites
    • Step 1: Basic Agent
    • Step 2: Understanding the Code
      • The @agent Decorator
      • The Spore Parameter
      • The chat() Function
    • Step 3: Add a System Message
    • Step 4: Add Error Handling
    • Step 5: Add Broadcasting
    • Step 6: Create a Listener
    • Complete Example
    • Running the Example
    • Key Concepts Learned
    • Next Steps
    • Troubleshooting
  • Recipe: agent communication
    • Message contract
    • Implement the handlers
    • What to inspect
  • Recipe: a memory-enabled agent
    • Collection compatibility
  • Tutorial: Tool Integration
    • Prerequisites
    • 1) Minimal Tool + Agent
    • 2) Shared Tool Across Agents
    • 3) Direct Agent tools
    • See Also
  • Tutorial: human approval for a tool call
    • Define an approval-gated tool
    • Enable HITL and run
    • CLI review
  • Recipe: a bounded multi-agent workflow
    • Example flow

Architecture

  • Emergent Coordination Architecture
    • Architectural Thesis
    • Coordination Model
    • Framework Positioning
    • Operational Components
    • Design Rules
    • Benchmarks And Claims
    • Documentation Policy
  • ADR: Model Runtime Hardening
    • Status
    • Context
    • Decision
    • Capability Resolution
    • Streaming Semantics
    • Multimodal Normalization
    • Local Provider Policy
    • Async Execution
    • Agent Communication and Realtime Scope
    • Consequences

Examples

  • Examples
    • Overview
    • Model Runtime Examples
      • Offline Runtime Contract
      • Local OpenAI-Compatible LLM
      • Structured Output
      • Streaming Events
      • Multimodal Input
      • Gemini Multimodal File Input
      • Request-Based Voice Agent
      • Gemini Client Tools
      • Configurable Embeddings
    • Beginner Examples
      • Simple Calculator
    • Core Pattern Examples
      • 001 - Single Agent Identity
      • 002 - Agent Communication
      • 003 - Specialist Collaboration
      • 004 - Registry Discovery
      • 005 - Memory-Enabled Agents
      • 006 - Resilient Agents
    • Advanced Examples
      • 007 - Adaptive Agent Systems
      • 008 - Self-Organizing Networks
      • 009 - Emergent Collective Intelligence
      • 010 - Unified Storage Demo
      • 011 - Secure Spore Demo
    • Docker Examples
    • Running Examples
      • Prerequisites
      • Run an Example
      • Example Output
    • Troubleshooting
      • Example Doesn’t Run
      • No Output
      • Memory Examples Fail
      • Storage Examples Fail
    • Next Steps
    • Additional Resources

API Reference

  • API Reference
    • Core API
      • praval.app
        • PravalApp
        • get_default_app()
        • reset_default_app()
      • praval.core.agent
        • AgentConfig
        • Agent
      • praval.core.reef
        • SporeValidationError
        • SporeType
        • Spore
        • SubscriptionManager
        • ReefChannel
        • ReefCore
        • Reef
        • get_reef()
        • reset_reef()
      • praval.core.registry
        • PravalRegistry
        • register_agent()
        • get_registry()
        • reset_registry()
      • praval.core.exceptions
        • PravalError
        • ProviderError
        • ConfigurationError
        • EmbeddingConfigurationError
        • ToolError
        • StateError
        • InterventionRequired
        • HITLConfigurationError
    • Model Runtime
      • praval.models
        • AudioResponse
        • ContentPart
        • EmbeddingRequest
        • EmbeddingResponse
        • ModelEvent
        • ModelMessage
        • ModelRequest
        • ModelResponse
        • ProviderAdapter
        • ProviderCapabilities
        • ProviderProfile
        • ReasoningConfig
        • SpeechRequest
        • StructuredOutputConfig
        • ToolCall
        • ToolResult
        • ToolSpec
        • TranscriptionRequest
        • Usage
      • praval.model_runtime
        • normalize_structured_output_config()
        • normalize_reasoning_config()
        • normalize_content_parts()
        • legacy_tool_to_spec()
        • execute_legacy_tool_call()
        • execute_legacy_tool_call_async()
        • ModelRuntime
      • praval.providers.registry
        • ProviderRegistration
        • ProviderRegistry
        • get_provider_registry()
        • reset_provider_registry()
        • register_default_providers()
      • praval.embeddings
        • EmbeddingRuntime
    • Decorators And Composition
      • praval.decorators
        • chat()
        • achat()
        • broadcast()
        • get_agent_info()
      • praval.composition
        • agent_pipeline()
        • conditional_agent()
        • throttled_agent()
        • AgentSession
        • start_agents()
        • run_agents()
    • Providers
      • praval.providers.factory
        • ProviderFactory
      • praval.providers.openai
        • OpenAIProvider
      • praval.providers.anthropic
        • AnthropicProvider
      • praval.providers.cohere
        • CohereProvider
      • praval.providers.gemini
        • GeminiProvider
      • praval.providers.openai_compatible
        • OpenAICompatibleProvider
    • Tool System
      • praval.tools
        • tool()
        • get_tool_info()
        • is_tool()
        • discover_tools()
        • list_tools()
        • register_tool_with_agent()
        • unregister_tool_from_agent()
        • ToolCollection
      • praval.core.tool_registry
        • ToolMetadata
        • Tool
        • ToolRegistry
        • get_tool_registry()
        • reset_tool_registry()
    • Human-in-the-Loop And MCP
      • praval.hitl.models
        • InterventionStatus
        • InterventionDecision
        • InterventionPolicy
        • InterventionRequest
        • SuspendedRunState
      • praval.hitl.policy
        • requires_approval()
        • risk_level()
        • approval_reason()
      • praval.hitl.service
        • HITLService
      • praval.hitl.store
        • HITLStore
        • get_hitl_store()
        • reset_hitl_stores()
      • praval.hitl.runtime
        • HITLRuntime
      • praval.mcp.client
        • MCPClient
        • MCPClientClosedError
        • MCPConnectionError
        • MCPError
        • MCPServerConfig
        • MCPToolError
    • Memory System
      • praval.memory.memory_manager
        • MemoryManager
      • praval.memory.short_term_memory
        • ShortTermMemory
      • praval.memory.long_term_memory
        • LongTermMemory
      • praval.memory.episodic_memory
        • EpisodicMemory
      • praval.memory.semantic_memory
        • SemanticMemory
      • praval.memory.memory_types
        • MemoryType
        • MemoryEntry
        • MemoryQuery
        • MemorySearchResult
    • Storage System
      • praval.storage.data_manager
        • DataManager
        • get_data_manager()
        • store_data()
        • get_data()
        • query_data()
        • delete_data()
      • praval.storage.base_provider
        • StorageType
        • DataReference
        • StorageQuery
        • StorageResult
        • StorageMetadata
        • BaseStorageProvider
        • create_storage_provider()
      • praval.storage.storage_registry
        • StorageRegistry
        • get_storage_registry()
        • register_storage_provider()
        • get_storage_provider()
        • list_storage_providers()
      • praval.storage.decorators
        • storage_enabled()
        • requires_storage()
      • praval.storage.providers.filesystem
        • FileSystemProvider
      • praval.storage.providers.postgresql
        • PostgreSQLProvider
      • praval.storage.providers.qdrant_provider
        • QdrantProvider
      • praval.storage.providers.redis_provider
        • RedisProvider
      • praval.storage.providers.s3_provider
        • S3Provider
    • Observability
      • praval.observability.config
        • ObservabilityConfig
        • get_config()
        • reset_config()
      • praval.observability.tracing.context
        • TraceContext
        • get_current_span()
        • set_current_span()
        • clear_current_span()
      • praval.observability.tracing.tracer
        • generate_trace_id()
        • generate_span_id()
        • Tracer
        • get_tracer()
        • reset_tracer()
      • praval.observability.storage.sqlite_store
        • SQLiteTraceStore
        • get_trace_store()
        • reset_trace_store()
      • praval.observability.export.console_viewer
        • ConsoleViewer
        • print_traces()
        • show_recent_traces()
      • praval.observability.export.otlp_exporter
        • OTLPExporter
        • export_traces_to_otlp()
      • praval.observability.instrumentation.manager
        • initialize_instrumentation()
        • is_instrumented()
        • reset_instrumentation()

Project

  • Changelog
    • Changelog
      • Unreleased
      • 0.8.1 - 2026-07-18
        • Release overview
        • Highlights
        • Added
        • Changed
        • Fixed
        • Compatibility
        • Migration guidance
        • Learning resources
        • Validation and publication
        • Known limitations
        • Deferred
      • 0.7.22 - 2026-02-21
        • Added
        • Changed
        • Fixed
        • Migration Notes
        • Validation Evidence
      • 0.7.21 - 2026-02-09
        • Added
        • Changed
        • Fixed
        • Security
      • [0.7.18] - 2025-12-08
        • Added
        • Fixed
        • Changed
        • Technical Details
        • Migration Path (v0.7.17 → v0.7.18)
      • [0.7.17] - 2025-12-07
        • Added
        • Fixed
        • Technical Details
      • [0.7.16] - 2025-11-08
        • Fixed
        • Added
        • Changed
        • Technical Details
      • [0.7.15] - 2025-11-08
        • Fixed
        • Added
        • Technical Details
        • Breaking Changes
        • Migration Path (v0.7.14 → v0.7.15)
        • Backward Compatibility
      • [0.7.14] - 2025-11-08
        • Fixed
        • Added
        • Testing
        • Technical Details
        • Breaking Changes
        • Migration Path (v0.7.13 → v0.7.14)
        • Performance
        • Known Limitations
      • [0.7.13] - 2025-11-07
        • Added
        • Features
        • Example
        • Testing
        • Documentation
        • Technical Details
        • Performance
        • Migration
        • Impact
      • [0.7.12] - 2025-11-06
        • Fixed
        • Changed
        • Testing
        • Technical Details
        • Impact
      • [0.7.11] - 2025-11-05
        • Added
        • Features
        • Documentation
        • Statistics
        • Configuration
        • Breaking Changes
      • [0.7.10] - 2025-10-28
        • Fixed
        • Added
        • Changed
        • Examples
        • Technical Details
        • Benefits
      • [0.7.9] - 2025-10-23
        • Changed
        • Added
        • Documentation
        • Benefits
      • [0.7.8] - 2025-10-23
        • Changed
        • Infrastructure
        • Note
      • [0.7.7] - 2025-10-23
        • Added
        • Changed
        • Fixed
        • Infrastructure
      • [0.7.6] - 2024-12-03
        • Added
        • Enhanced
        • Fixed
        • Technical
      • [0.7.5] - 2024-12-03
        • Fixed
        • Improved
      • [0.7.4] - 2024-12-03
        • Added
        • Fixed
        • Improved
      • [0.6.2] - 2025-08-21
        • Added
        • Fixed
        • Enhanced
      • [0.6.1] - 2025-08-20
        • Added
        • Enhanced
        • Examples
        • Changed
      • 0.5.0 - 2025-08-09
        • Added
        • Changed
        • Removed
  • Contributing
    • Contributing
      • Development Workflow
      • Release Workflow
        • 1. Stabilize release branch
        • 2. Run strict gates on final release candidate commit
        • 3. PR topology
        • 4. Build and publish artifacts
        • 5. Tag and GitHub release
        • 6. Post-release verification
      • Commit Convention
      • Pull Request Checklist
  • License
    • MIT License
Praval
  • Search

© Copyright 2026, Praval Team.

Built with Sphinx using a theme provided by Read the Docs.