Examples๏ƒ

Working code examples demonstrating Pravalโ€™s capabilities.

Overview๏ƒ

The Praval examples showcase progressively complex agent patterns, from simple single agents to sophisticated multi-agent systems.

Beginner Examples๏ƒ

Simple Calculator๏ƒ

A basic calculator agent demonstrating tool integration.

File: examples/calculator.py

#!/usr/bin/env python3
"""
Agentic Calculator - A CLI Mathematical Assistant

An intelligent calculator agent built with Praval's new tool system.
Tools are defined using the @tool decorator and automatically registered
with the calculator agent. The agent performs various mathematical operations
through natural language commands using registered tools for precise calculations.

Usage:
    python examples/calculator.py
    
Examples:
    - "What is 15 + 27?"
    - "Calculate the square root of 144"
    - "What's 5 factorial?"
    - "Convert 100 degrees Celsius to Fahrenheit"
    - "Find the area of a circle with radius 5"
"""

import logging
import math
import sys
import os

# Add the src directory to the path to import praval
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))

from praval import agent, tool

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.StreamHandler(),
        logging.FileHandler('calculator.log')
    ]
)
logger = logging.getLogger(__name__)


# ==========================================
# MATHEMATICAL TOOLS DEFINITION
# ==========================================
# Tools are defined first and automatically registered with the calculator agent

# Basic Arithmetic Tools
@tool("add", owned_by="calculator", category="arithmetic", description="Add two numbers together")
def add(x: float, y: float) -> float:

What it demonstrates:

  • Single agent with tools

  • Basic @tool decorator usage

  • Simple request-response pattern

Run it:

python examples/calculator.py

Core Pattern Examples๏ƒ

001 - Single Agent Identity๏ƒ

The simplest possible agent.

File: examples/001_single_agent_identity.py

Demonstrates:

  • @agent decorator

  • Basic agent creation

  • Identity and system messages

002 - Agent Communication๏ƒ

Agents communicating through broadcasts.

File: examples/002_agent_communication.py

Demonstrates:

  • broadcast() messaging

  • responds_to filtering

  • Multi-agent coordination

003 - Specialist Collaboration๏ƒ

Multiple specialized agents working together.

File: examples/003_specialist_collaboration.py

Demonstrates:

  • Specialized agent roles

  • Workflow emergence

  • Knowledge sharing

004 - Registry Discovery๏ƒ

Dynamic agent discovery and coordination.

File: examples/004_registry_discovery.py

Demonstrates:

  • Agent registry usage

  • Dynamic agent lookup

  • Runtime coordination

005 - Memory-Enabled Agents๏ƒ

Agents with persistent memory.

File: examples/005_memory_enabled_agents.py

Demonstrates:

  • memory=True configuration

  • remember() and recall() API

  • Persistent agent memory

006 - Resilient Agents๏ƒ

Error handling and resilience patterns.

File: examples/006_resilient_agents.py

Demonstrates:

  • Error handling

  • Graceful degradation

  • Fault tolerance

Advanced Examples๏ƒ

007 - Adaptive Agent Systems๏ƒ

Agents that adapt based on feedback.

File: examples/007_adaptive_agent_systems.py

Demonstrates:

  • Learning from results

  • Dynamic behavior adjustment

  • Feedback loops

008 - Self-Organizing Networks๏ƒ

Agents that organize themselves into networks.

File: examples/008_self_organizing_networks.py

Demonstrates:

  • Emergent organization

  • Network topology formation

  • Distributed coordination

009 - Emergent Collective Intelligence๏ƒ

Complex intelligence from simple agents.

File: examples/009_emergent_collective_intelligence.py

Demonstrates:

  • Collective decision making

  • Consensus algorithms

  • Swarm intelligence patterns

010 - Unified Storage Demo๏ƒ

Multi-provider storage system.

File: examples/010_unified_storage_demo.py

Demonstrates:

  • Storage providers (FileSystem, PostgreSQL, Redis, S3, Qdrant)

  • Data persistence patterns

  • Multi-backend coordination

011 - Secure Spore Demo๏ƒ

Enterprise secure messaging.

File: examples/011_secure_spore_demo.py

Demonstrates:

  • Encrypted communication

  • Message authentication

  • Secure transport protocols

Docker Examples๏ƒ

Containerized Praval applications.

Directory: examples/docker-examples/

See the Docker Examples README for:

  • Dockerized agent deployments

  • Multi-container coordination

  • Production deployment patterns

Running Examples๏ƒ

Prerequisites๏ƒ

# Install Praval with all features
pip install praval[all]

# Set API key
export OPENAI_API_KEY="sk-..."

Run an Example๏ƒ

# Simple examples
python examples/001_single_agent_identity.py

# Advanced examples
python examples/009_emergent_collective_intelligence.py

# With Docker
cd examples/docker-examples
docker-compose up

Example Output๏ƒ

Most examples print their progress:

Starting agent system...
Agent 'researcher' registered
Agent 'analyst' registered
Broadcasting task...
Researcher: Processing topic 'AI trends'
Analyst: Analyzing results from researcher
Complete!

Troubleshooting๏ƒ

Example Doesnโ€™t Run๏ƒ

Check dependencies:

pip install praval[all]

Verify API key:

echo $OPENAI_API_KEY

Check Python version:

python --version  # Should be 3.9+

No Output๏ƒ

Some examples run asynchronously. Add a sleep at the end:

import time
time.sleep(3)  # Give agents time to complete

Memory Examples Fail๏ƒ

Install memory dependencies:

pip install praval[memory]

Storage Examples Fail๏ƒ

Some examples require external services:

# Start with Docker
docker-compose up -d postgres redis qdrant

# Or install locally
# PostgreSQL, Redis, etc.

Next Steps๏ƒ

After exploring examples:

  • Modify examples - Experiment with the code

  • Combine patterns - Mix different example patterns

  • Build your own - Create custom agent systems

  • Read guides - Deep dive into specific features

Additional Resources๏ƒ