Praval Logo

User Guide

  • Getting Started with Praval
    • What is Praval?
    • Installation
      • Minimal Installation
      • With Memory System
      • With All Features
      • For Development
    • Prerequisites
      • Python Version
      • API Keys
    • Your First Agent
    • Understanding the Code
      • 1. The @agent Decorator
      • 2. The chat() Function
      • 3. The Spore Object
      • 4. Starting Agents
    • Multi-Agent Communication
    • Adding Memory
    • Next Steps
      • Recommended Learning Path
    • Common Patterns
      • Pattern 1: Request-Response
      • Pattern 2: Pipeline
      • Pattern 3: Fan-Out/Fan-In
    • Troubleshooting
      • No API Key Found
      • Import Errors
      • Agents Not Responding
    • Configuration
      • Environment Variables
      • Programmatic Configuration
    • Getting Help
  • Core Concepts
    • The Coral Reef Metaphor
    • Design Principles
      • 1. Specialization Over Generalization
      • 2. Declarative Design
      • 3. Emergent Intelligence
      • 4. Zero Configuration
      • 5. Composability
    • Core Components
      • Agents
      • Spores
      • The Reef
      • Registry
    • Communication Patterns
      • Pattern 1: Broadcast & Filter
      • Pattern 2: Request-Response
      • Pattern 3: Pipeline
      • Pattern 4: Coordinator
    • Memory System
      • Memory Types
      • Enabling Memory
      • Knowledge Base
    • Tool System
      • Defining Tools
      • Using Tools in Agents
    • Storage System
      • Supported Providers
      • Using Storage
    • LLM Provider System
      • Supported Providers
      • Provider Selection
      • Configuration
    • Agent Lifecycle
      • 1. Definition
      • 2. Activation
      • 3. Execution
      • 4. Communication
    • Error Handling
      • Agent Resilience
      • Reef Guarantees
    • Performance Considerations
      • Concurrency
      • Memory Usage
      • Scaling
    • Best Practices
      • 1. Keep Agents Small
      • 2. Use Descriptive Names
      • 3. Document System Messages
      • 4. Filter Messages Specifically
      • 5. Handle Errors Gracefully
    • Next Steps
  • Praval Memory System
    • 🧠 Overview
    • 🏗️ Architecture
      • Memory Layers
      • 1. Short-term Memory
      • 2. Long-term Memory
      • 3. Episodic Memory
      • 4. Semantic Memory
    • 🚀 Quick Start
      • Basic Setup
      • With Docker Compose
    • 🎯 Agent Integration
      • Memory-Enabled Agents
    • 📊 Memory Types
      • MemoryType Enum
      • Memory Entry Structure
    • 🔍 Search and Retrieval
      • Advanced Search
      • Conversation Context
      • Knowledge Search
    • 🐳 Docker Deployment
      • Simple Deployment
      • Full Development Stack
    • 📈 Performance and Scaling
      • Memory Optimization
      • Vector Database Scaling
      • Memory Cleanup
    • 🔧 Configuration
      • Environment Variables
      • Programmatic Configuration
    • 🚨 Troubleshooting
      • Common Issues
      • Debug Mode
    • 🎯 Best Practices
      • Memory Design Patterns
      • Agent Patterns
    • 🔮 Advanced Features
      • Memory Analytics
      • Knowledge Validation
      • Memory Relationships
  • Reef Communication System Specification
    • Overview
    • Design Philosophy
    • Core Requirements
      • 1. Knowledge-First Communication
      • 2. Agent Discovery Integration
      • 3. Multiple Communication Patterns
      • 4. Reliability and Performance
      • 5. Simple API Surface
    • API Specification
      • Core Classes
        • Spore
        • ReefChannel
        • Reef
      • Agent Integration
        • Enhanced Agent Class
    • Usage Examples
      • Basic Knowledge Sharing
      • Request-Response Pattern
      • Broadcast Knowledge Discovery
      • Multi-Channel Communication
    • Implementation Requirements
      • 1. Thread Safety
      • 2. Performance Characteristics
      • 3. Error Handling
      • 4. Testing Requirements
      • 5. Configuration
    • Non-Requirements (Out of Scope)
    • Success Criteria
    • Migration Strategy
  • Praval Tool System Specification
    • Overview
    • Key Features
      • 1. Declarative Tool Definition
      • 2. Tool Registry
      • 3. Agent-Tool Association
      • 4. Type Safety and Validation
    • Architecture
      • Core Components
      • Tool Metadata Structure
      • Tool Registry Interface
    • Usage Patterns
      • Pattern 1: Agent-Specific Tools
      • Pattern 2: Shared Tools
      • Pattern 3: Category-Based Tools
      • Pattern 4: Dynamic Tool Assignment
    • Integration with Existing Agent System
      • Enhanced @agent Decorator
      • Tool Method Exposure
    • Error Handling and Validation
      • Tool Validation
      • Runtime Error Handling
    • Tool Discovery and Introspection
      • Tool Discovery
      • Tool Introspection
    • Backward Compatibility
    • Testing Requirements
      • Unit Tests
      • Integration Tests
      • Performance Tests
    • Implementation Phases
      • Phase 1: Core Infrastructure
      • Phase 2: Advanced Features
      • Phase 3: Developer Experience
    • Migration Guide
      • For Existing Code
      • Benefits of Migration
  • Storage System Guide
    • Overview
    • Quick Start
      • Basic Storage
      • Storage with Agents
    • Storage Providers
      • FileSystem Provider
      • PostgreSQL Provider
      • Redis Provider
      • S3 Provider
      • Qdrant Provider
    • Data Manager API
      • Storing Data
      • Retrieving Data
      • Deleting Data
      • Querying Data
      • Searching (Vector Databases)
    • Storage Decorators
      • @storage_enabled
      • @requires_storage
    • Configuration
      • Environment Variables
      • Programmatic Configuration
    • Advanced Patterns
      • Multi-Provider Storage
      • Storage with Memory Integration
      • Transaction-like Operations
    • Custom Storage Providers
    • Best Practices
      • 1. Choose the Right Provider
      • 2. Use Metadata
      • 3. Handle Failures Gracefully
      • 4. Clean Up Temporary Data
      • 5. Version Your Data
    • Troubleshooting
      • Provider Not Available
      • Connection Errors
      • Serialization Errors
    • See Also

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
  • Tutorial: Agent Communication
    • Coming Soon
  • Tutorial: Memory-Enabled Agents
    • Coming Soon
  • Tutorial: Tool Integration
    • Coming Soon
  • Tutorial: Multi-Agent Systems
    • Coming Soon

Examples

  • Examples
    • Overview
    • 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
    • Overview
      • Core API
        • praval.core.agent
        • praval.core.reef
        • praval.core.registry
        • praval.core.exceptions
      • Decorators
        • praval.decorators
        • praval.composition
      • Memory System
        • praval.memory.memory_manager
        • praval.memory.short_term_memory
        • praval.memory.long_term_memory
        • praval.memory.episodic_memory
        • praval.memory.semantic_memory
        • praval.memory.memory_types
      • Storage System
        • praval.storage.data_manager
        • praval.storage.base_provider
        • praval.storage.storage_registry
        • praval.storage.decorators
        • praval.storage.providers
      • Tool System
        • praval.tools
        • praval.core.tool_registry
      • LLM Providers
        • praval.providers.factory
        • praval.providers.openai
        • praval.providers.anthropic
        • praval.providers.cohere
    • Detailed Documentation
      • Core Module
        • AgentConfig
        • Agent
        • SporeType
        • Spore
        • ReefChannel
        • Reef
        • get_reef()
        • PravalRegistry
        • register_agent()
        • get_registry()
        • PravalError
        • ProviderError
        • ConfigurationError
        • ToolError
        • StateError
      • Decorators Module
        • agent()
        • chat()
        • achat()
        • broadcast()
        • get_agent_info()
        • agent_pipeline()
        • conditional_agent()
        • throttled_agent()
        • AgentSession
        • start_agents()
      • Memory Module
        • MemoryManager
        • ShortTermMemory
        • LongTermMemory
        • EpisodicMemory
        • SemanticMemory
        • MemoryType
        • MemoryEntry
        • MemoryQuery
        • MemorySearchResult
      • Storage Module
        • DataManager
        • get_data_manager()
        • store_data()
        • get_data()
        • query_data()
        • delete_data()
        • StorageType
        • DataReference
        • StorageQuery
        • StorageResult
        • StorageMetadata
        • BaseStorageProvider
        • create_storage_provider()
        • StorageRegistry
        • get_storage_registry()
        • register_storage_provider()
        • get_storage_provider()
        • list_storage_providers()
        • storage_enabled()
        • requires_storage()
        • Storage Providers
      • Tool Module
        • tool()
        • get_tool_info()
        • is_tool()
        • discover_tools()
        • list_tools()
        • register_tool_with_agent()
        • unregister_tool_from_agent()
        • ToolCollection
        • ToolMetadata
        • Tool
        • ToolRegistry
        • get_tool_registry()
        • reset_tool_registry()
      • Providers Module
        • ProviderFactory
        • OpenAIProvider
        • AnthropicProvider
        • CohereProvider

Additional Resources

  • Changelog
    • Changelog
      • Unreleased
      • [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
      • Version Bump Keywords
        • Major Version (Breaking Changes)
        • Minor Version (New Features)
        • Patch Version (Bug Fixes)
  • Contributing
    • Contributing to Praval
      • 🚀 Getting Started
        • Development Setup
      • 📝 Commit Message Convention
        • Version Bump Keywords
        • Examples
      • 🧪 Testing Guidelines
        • Running Tests
        • Test Coverage Expectations
        • Writing Tests
      • 🏗️ Development Workflow
        • 1. Create a Feature Branch
        • 2. Make Changes
        • 3. Test Your Changes
        • 4. Commit and Push
        • 5. Create Pull Request
      • 📦 Release Process
        • Manual Release (if needed)
      • 🎯 Areas for Contribution
        • High Priority
        • Documentation
        • Testing
      • 🔧 Code Style
        • Python Style
        • Documentation Style
        • Example Code Style
      • 📞 Getting Help
      • 📄 License
  • License
    • MIT License
Praval
  • Search

© Copyright 2025, Praval Team.

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