Examples

Working code examples demonstrating Praval’s capabilities.

Examples that contact model providers are offline by default. Set PRAVAL_RUN_LIVE_EXAMPLES=1 and the relevant provider credentials to execute live requests. The full example smoke sweep removes ambient provider keys unless that opt-in is present.

Overview

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

Model Runtime Examples

Offline Runtime Contract

File: examples/model_runtime_fake_provider.py

This example needs no provider credentials. It demonstrates a fake provider adapter, propagation of a structured-output request, and normalized streaming events. It does not represent a provider constraint or local schema validation.

Run it:

python examples/model_runtime_fake_provider.py

Local OpenAI-Compatible LLM

File: examples/local_llm_openai_compatible.py

Connects to an already-running Ollama, vLLM, LM Studio, llama.cpp, or generic OpenAI-compatible server.

Run it:

PRAVAL_LOCAL_PROVIDER=ollama PRAVAL_LOCAL_MODEL=llama3 \
  python examples/local_llm_openai_compatible.py

Structured Output

File: examples/structured_output_runtime.py

Shows Agent.generate(..., response_schema=...) with a live provider. Use examples/model_runtime_fake_provider.py as the offline alternative.

Streaming Events

File: examples/streaming_events.py

Shows normalized start, delta, usage, and final event handling for live provider streaming.

Multimodal Input

File: examples/multimodal_input_runtime.py

Shows ContentPart lists for text plus image URL input. The runtime validates that the selected provider/model profile supports image input before execution.

Gemini Multimodal File Input

File: examples/gemini_multimodal_file.py

Shows how to pass a URI returned by the Gemini Files API as a ContentPart.file_url. The example accepts PDF, audio, video, and other MIME types supported by the selected Gemini model. Uploading local files is outside the Praval 0.8 adapter.

Run it:

python examples/gemini_multimodal_file.py \
  https://generativelanguage.googleapis.com/v1beta/files/FILE_ID \
  --mime-type application/pdf

Request-Based Voice Agent

File: examples/request_based_voice_agent.py

Shows the 0.8 voice flow: transcribe a local audio file, send the transcript to an agent, and synthesize the reply. It requires OPENAI_API_KEY and an audio file path. Realtime voice sessions are not part of this example.

Run it:

python examples/request_based_voice_agent.py question.wav --output reply.mp3

Gemini Client Tools

File: examples/gemini_tool_runtime.py

Shows a Gemini functionCall round trip executed by ModelRuntime. It requires GEMINI_API_KEY or GOOGLE_API_KEY.

Run it:

python examples/gemini_tool_runtime.py

Configurable Embeddings

File: examples/configurable_embeddings.py

Shows chat model and memory embedding configuration as independent choices, using local Chroma storage and text-embedding-3-small.

Run it:

python examples/configurable_embeddings.py

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, chat, tool, start_agents, get_reef, get_tool_registry

# 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

Make sure you wait for agents to complete:

from praval import get_reef

# After start_agents(), wait for completion
get_reef().wait_for_completion()
get_reef().shutdown()

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

Getting started - Setup and basics
Core concepts and API layers - Architecture understanding
API Reference - API reference
GitHub Examples - Latest code