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
    • Design the first agent so it can be evaluated
  • Core concepts and API layers
    • Mental model
    • Direct Agent API
    • Decorated agents
    • Spores
    • Reef delivery
    • Tools and human approval
    • Memory, embeddings, and storage
    • Lifecycle
    • Design for evaluability
    • What to read next
  • Application lifecycle
    • Typed application configuration
    • Ownership boundary in 0.8
    • Errors
  • Application configuration reference
    • Root and application
    • Model profiles
    • Embedding profiles
    • Agent profiles
    • Observability and evaluation
    • Discovery and environment
  • 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 protocol and Spores
    • Send an existing Spore
    • Compatibility request and reply
    • Wait for one matched response
    • How Reef matches a response
    • Progress notifications
    • Forward a request
    • Cleanup and transport behavior
    • Application responsibilities
  • 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
  • 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
  • Migrate from v0.8.2 to v0.8.3
    • Runtime support
    • Observability
    • Evaluation
    • Configuration
    • Removed or nonexistent claims
    • Validation checklist
  • Troubleshooting
    • Capability Errors
    • Local Provider Connection Errors
    • Streaming Errors
    • Documentation Quality Gates
  • Documentation Quality
    • Release Gates
    • API Coverage
    • Example Policy

Observability

  • Observability
    • Install and five-minute quickstart
      • Base-package instrumentation
      • Local development
      • Host-owned SDK
      • Praval-owned SDK
    • Configuration reference
      • praval.toml
      • Fields and defaults
      • Environment variables
    • Instrumentation map
      • Root identity and completion
      • Instrumentation ownership
    • Distributed tracing
      • Propagation sequence
      • Sampling and trust
    • Traces, metrics, and logs
      • Traces
      • Metrics
      • Logs
      • Attribute policy
      • Backend queries
    • Collectors and deployment
      • Local Collector
      • Multiple containers
      • Headers and TLS
    • Sampling and performance
      • Choosing a ratio
      • Queue and batch tradeoffs
    • Privacy and security
      • Content enablement checklist
      • Threat boundaries
    • Local SQLite diagnostics
      • Inspecting traces
      • Retention behavior
    • Lifecycle and troubleshooting
      • Graceful shutdown
      • Diagnosis
      • Provider ownership
      • Failure sequence
      • Async and process boundaries
    • API reference and v0.8.2 migration
      • Lifecycle API
      • Complete public surface
      • Observation API
      • Compatibility surface
      • Migration from v0.8.2
    • Ownership model
    • Executed tutorial matrix

Evaluation

  • Evaluation
    • Install and five-minute quickstart
      • Install
      • Define a dataset
      • Run one deterministic suite
      • CLI configuration
    • Evaluation configuration reference
      • Core and stores
      • Judge profiles
      • Suites and gates
      • RAGAS
      • Online workers
    • Recommended agent and evaluator-agent patterns
      • Design an agent for evaluation
      • Pair target and evaluator
        • Single agent
        • Workflow
      • Least-privilege evaluator
      • Decision table
      • Anti-patterns
    • Defining evaluator agents
      • Configuration
      • Capability ownership
      • Errors
    • Evaluator flow and capability policy
      • Tools and side effects
      • Isolation and budgets
    • Direct model judges
    • Cases, datasets, and suites
    • Agent and workflow evaluation
      • Single agent
      • Correlated workflow
    • Metrics, plugins, and RAGAS
      • Built-in deterministic metrics
      • RAGAS
    • Gates, baselines, and CI
    • Sampled online evaluation
    • Stores and retention
    • Evaluation telemetry and trace correlation
    • Cost, privacy, and security
      • Safe defaults
    • Evaluation production recipes
      • 1. Local deterministic evaluation
      • 2. Paired target and evaluator agents
      • 3. Workflow judging
      • 4. CI regression gate and explicit baseline
      • 5. PostgreSQL shared store
      • 6. RAGAS through Praval runtimes
      • 7. Sampled online evaluation
      • 8. Metadata-only and redacted-content deployment
      • 9. Failure and graceful-shutdown exercise
      • 10. Correlate an evaluation result with its trace
    • Troubleshooting
      • Target agent is not registered
      • Unknown judge or metric
      • Invalid judge output
      • RAGAS metric reports missing input
      • Gate failed
      • Store conflict or outage
      • Online jobs retry or dead-letter
      • Shutdown hangs
    • Evaluation API reference
      • Datasets and immutable records
      • Execution and judges
      • Metrics, gates, and plugins
      • Stores
      • Online evaluation
    • Choose an evaluation mechanism
    • Record boundary
    • Executed evidence

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
    • Evaluation Examples
      • Deterministic Quickstart
      • Paired Target And Evaluator Agents
      • Workflow Evaluation
    • 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.config
        • AgentProfileConfig
        • AppConfig
        • EmbeddingProfileConfig
        • EvalConfig
        • EvalGateConfig
        • EvalJudgeConfig
        • EvalRagasConfig
        • EvalStoresConfig
        • EvalSuiteConfig
        • LocalObservabilityConfig
        • ModelProfileConfig
        • ObservabilityConfig
        • OnlineEvalConfig
        • OTLPConfig
        • PostgresEvalStoreConfig
        • PravalConfig
        • ResolvedAgentConfig
        • SQLiteEvalStoreConfig
        • discover_config_path()
        • load_config()
      • praval.core.agent
        • AgentConfig
        • Agent
      • praval.core.reef
        • SporeValidationError
        • ReefLifecycleError
        • 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
        • PravalConfigurationError
        • EmbeddingConfigurationError
        • ToolError
        • StateError
        • InterventionRequired
        • HITLConfigurationError
    • Model Runtime
      • praval.models
        • AudioResponse
        • ContentKind
        • ContentPart
        • ContentReference
        • EmbeddingRequest
        • EmbeddingResponse
        • ExecutionObservation
        • HITLDecisionObservation
        • ModelEvent
        • ModelMessage
        • ModelRequest
        • ModelResponse
        • NoOpObservationRecorder
        • ObservationFactStatus
        • ObservationKind
        • ObservationPrivacy
        • ObservationRecorder
        • ObservationStatus
        • PrivacyMode
        • ProviderAdapter
        • ProviderCapabilities
        • ProviderProfile
        • ReasoningConfig
        • ReefHandoffObservation
        • RetryObservation
        • SpeechRequest
        • StructuredOutputConfig
        • ToolCall
        • ToolResult
        • ToolSpec
        • TranscriptionRequest
        • TokenUsageObservation
        • Usage
        • ToolCallObservation
      • 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
        • agent()
        • 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.lifecycle
        • ObservabilityHandle
        • configure_observability()
        • configure_tracing()
        • force_flush()
        • get_logger()
        • get_meter()
        • get_tracer()
        • is_observability_configured()
        • shutdown_observability()
      • praval.observability.tracing.context
        • TraceContext
        • extract_trace_context()
        • get_current_span()
        • inject_trace_context()
      • praval.observability.tracing.tracer
        • Tracer
        • generate_span_id()
        • generate_trace_id()
        • get_tracer()
        • reset_tracer()
      • praval.observability.storage.sqlite_store
        • StorableSpan
        • SQLiteTraceStore
        • get_trace_store()
        • set_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()
    • Evaluation
      • praval.eval
        • AgentJudge
        • AgentEvaluationTarget
        • AttemptStatus
        • EvalDatasetError
        • EvalRunner
        • EvalCase
        • EvalSuite
        • EvaluationAttempt
        • EvaluationBaseline
        • EvaluationConflictError
        • EvaluationExecutionError
        • EvaluationJob
        • EvaluationMetadata
        • EvaluationResult
        • EvaluationRun
        • EvaluationRunStatus
        • EvaluationStore
        • EvaluationStoreError
        • EvaluationSubject
        • EvaluationTarget
        • ExactMatchMetric
        • Gate
        • GateAggregation
        • GateEvaluationError
        • GateOperator
        • GateResult
        • GateStatus
        • JobStatus
        • Judge
        • JudgeConfigurationError
        • JudgeContext
        • JudgeResult
        • JudgeResponseError
        • LoadedEvalCase
        • LoadedEvalSuite
        • MetricResult
        • MetricComparison
        • Metric
        • MetricPluginError
        • ModelJudge
        • OnlineContextLoader
        • OnlineEvaluationProcessor
        • OnlineEvaluationService
        • OnlineEvaluationStats
        • OnlineSubjectEvaluator
        • PostgresEvaluationStore
        • ResultStatus
        • RunComparison
        • SQLiteEvaluationStore
        • TargetResult
        • TerminalSuccessMetric
        • ToolCallMatchMetric
        • available_metrics()
        • builtin_metrics()
        • evaluation_call_scope()
        • compare_evaluation_runs()
        • discover_metric_plugins()
        • evaluate_gate()
        • is_evaluation_call()
        • load_jsonl_suite()
        • promote_evaluation_baseline()
        • trace_sampled()

Project

  • Changelog
    • Changelog
      • Unreleased
      • 0.8.3 - Unreleased
        • Added
        • Changed
        • Compatibility
      • 0.8.2 - 2026-07-31
        • Added
        • Changed
        • Fixed
      • 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.