praval

Name	praval JSON
Version	0.7.9 JSON
	download
home_page	None
Summary	A composable Python framework for LLM-based agents inspired by coral ecosystems
upload_time	2025-10-24 07:29:00
maintainer	None
docs_url	None
author	Praval Team
requires_python	>=3.9
license	MIT
keywords	ai agents llm multi-agent framework openai anthropic cohere rag memory vector-database chromadb qdrant chatbot knowledge-graph semantic-search nlp
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            <div align="center">
  <img src="logo.png" alt="Praval Logo" width="200"/>
  
  # Praval
  
  **The Pythonic Multi-Agent AI Framework**
  
  Transform complex AI applications into simple, composable agent systems using decorator-based APIs, secure messaging, and distributed deployment.
  
  *Praval (प्रवाल) - Sanskrit for coral, representing how simple agents collaborate to create complex, intelligent ecosystems.*

  [![Version](https://img.shields.io/badge/version-0.7.6-blue.svg)](https://github.com/aiexplorations/praval/releases/tag/v0.7.6)
  [![Security](https://img.shields.io/badge/security-enterprise%20ready-green.svg)](#-secure-spores-messaging)
  [![Docker](https://img.shields.io/badge/docker-multi--service-blue.svg)](#-docker-deployment)
</div>

## Overview

**Praval is a revolutionary Python framework that transforms how we build AI applications.** Instead of monolithic systems, Praval enables you to create ecosystems of specialized agents that collaborate intelligently.

### 🚀 **Key Breakthrough: From Complexity to Simplicity**
- **489 lines → 50 lines**: Our decorator API dramatically reduces code complexity
- **Complex classes → Simple functions**: Agents become readable Python functions
- **Manual coordination → Self-organizing**: Agents coordinate through intelligent message passing
- **Imperative programming → Declarative agents**: Define what agents ARE, not what they DO

### ✨ **Core Capabilities**
- **🎯 Specialized Agents**: Each agent excels at one thing
- **🧠 Persistent Memory**: ChromaDB-powered semantic memory and knowledge search
- **🤝 Natural Collaboration**: Agents work together seamlessly
- **📡 Reef Communication**: Knowledge-first messaging between agents
- **🔄 Self-Organization**: Agents coordinate without central control
- **⚡ Pythonic API**: Clean, decorator-based agent definitions
- **🔒 Secure Messaging**: End-to-end encryption with enterprise-grade security
- **🐳 Distributed Deployment**: Multi-service Docker architecture with message queues
- **📡 Multi-Protocol Support**: AMQP, MQTT, STOMP for scalable messaging 

## ⭐ **The Praval Philosophy**

### **🧩 Simple Agents, Powerful Results**
```python
# Instead of complex monoliths...
complex_system = OneAgentDoesEverything()

# Praval encourages specialized collaboration
@agent("researcher", responds_to=["research_request"])
def research_specialist(spore):
    """I excel at finding and analyzing information."""
    return deep_research(spore.knowledge)

@agent("writer", responds_to=["write_request"])
def writing_specialist(spore):
    """I excel at creating compelling content."""
    return polished_writing(spore.knowledge)
```

### **🌊 Core Features**

#### **🎯 Decorator-Based Agent API**
- **@agent()**: Transform functions into intelligent agents
- **Automatic Registration**: Agents discover each other dynamically
- **Message Filtering**: Agents respond only to relevant communications
- **Thread-Safe Execution**: Concurrent processing with automatic resource management

#### **🏗️ Reef Communication System**
- **Knowledge-First Messaging**: All communication carries structured, semantic data
- **Spore Protocol**: JSON messages that agents broadcast and consume
- **Channel Management**: Organized communication streams
- **Self-Organization**: Agents coordinate without central orchestration

#### **🔧 Production-Ready Infrastructure**
- **Multi-LLM Support**: OpenAI, Anthropic, Cohere, and more
- **State Persistence**: Conversation memory and context management
- **Error Handling**: Graceful degradation and retry mechanisms
- **Resource Management**: Automatic cleanup and optimization

#### **🔒 Secure Spores Messaging** *(Enterprise Edition)*
- **End-to-End Encryption**: PyNaCl cryptography (Curve25519 + XSalsa20 + Poly1305)
- **Digital Signatures**: Ed25519 for message authenticity and integrity
- **Multi-Protocol Transport**: AMQP (RabbitMQ), MQTT (Mosquitto), STOMP (ActiveMQ)
- **TLS/SSL Security**: Certificate-based transport encryption
- **Key Management**: Automatic key rotation and forward secrecy
- **Distributed Architecture**: Horizontally scalable with message queue clustering

### **🏗️ Architecture Principles**

#### **🎯 Specialization Over Generalization**
```python
# ❌ Instead of one agent doing everything
general_agent = Agent("do_everything", "You can handle any task perfectly")

# ✅ Praval encourages focused specialists
@agent("researcher", responds_to=["research_query"])
def research_specialist(spore):
    """I excel at finding and analyzing information."""
    
@agent("writer", responds_to=["content_request"])
def writing_specialist(spore):
    """I excel at creating compelling content."""
```

#### **🌊 Reef Communication Philosophy**
- **Knowledge-First**: Every message carries structured, semantic data
- **Self-Organization**: Agents coordinate without central control
- **Emergent Intelligence**: Complex behaviors arise from simple interactions
- **Natural Flow**: Information flows like nutrients in a coral reef

#### **🛡️ Production-Ready Features**
- **Error Resilience**: Individual agent failures don't crash the system
- **Resource Management**: Automatic cleanup and thread pool optimization
- **Message Filtering**: Agents process only relevant communications
- **Graceful Degradation**: Systems adapt when agents are unavailable

## 📦 **Installation**

Praval offers flexible installation options based on your needs:

### **Minimal Installation** (Fastest - ~50MB)
Perfect for getting started with basic agents:
```bash
pip install praval

# Or with UV (faster)
uv pip install praval
```
**Includes**: LLM providers (OpenAI, Anthropic, Cohere), basic agent functionality

### **With Memory** (Recommended - ~500MB)
Adds vector storage and persistent memory:
```bash
pip install praval[memory]

# Or with UV
uv pip install praval[memory]
```
**Adds**: ChromaDB, sentence-transformers, semantic search

### **Full Installation** (~1.5GB)
All features including enterprise messaging and storage:
```bash
pip install praval[all]

# Or with UV
uv pip install praval[all]
```
**Adds**: Secure Spores, PDF support, storage providers (PostgreSQL, Redis, S3, Qdrant)

### **From Source**
```bash
git clone https://github.com/aiexplorations/praval.git
cd praval
pip install -e .[all]  # or [memory] for lighter install
```

### **Development Installation**

```bash
# Clone and install in development mode
git clone https://github.com/aiexplorations/praval.git
cd praval

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev]"
```

### **Environment Setup**
```bash
# Required: At least one LLM API key
OPENAI_API_KEY=your_openai_key        # Recommended
ANTHROPIC_API_KEY=your_anthropic_key  # Optional
COHERE_API_KEY=your_cohere_key        # Optional

# Memory System (Optional)
QDRANT_URL=http://localhost:6333      # For vector storage
PRAVAL_COLLECTION_NAME=praval_memories

# Framework Configuration (Optional)
PRAVAL_LOG_LEVEL=INFO
PRAVAL_MAX_THREADS=10
PRAVAL_DEFAULT_PROVIDER=openai
PRAVAL_DEFAULT_MODEL=gpt-4o-mini

# Secure Spores Configuration (Enterprise)
PRAVAL_TRANSPORT_PROTOCOL=amqp        # amqp, mqtt, or stomp
PRAVAL_AMQP_URL=amqps://user:pass@host:5671/vhost
PRAVAL_MQTT_HOST=localhost
PRAVAL_MQTT_PORT=8883
PRAVAL_TLS_CA_CERT=/path/to/ca.pem
PRAVAL_TLS_CLIENT_CERT=/path/to/client.pem
PRAVAL_TLS_CLIENT_KEY=/path/to/client.key
```
## ⚡ **Quick Start**

### **1. Simple Agent Creation**
```python
from praval import agent, chat, broadcast, start_agents

# Create a specialized agent with just a decorator
@agent("research_expert", responds_to=["research_query"])
def research_agent(spore):
    """I'm an expert at finding and analyzing information."""
    query = spore.knowledge.get("query")
    result = chat(f"Research this topic deeply: {query}")
    
    # Broadcast findings to other agents
    broadcast({
        "type": "research_complete",
        "findings": result,
        "confidence": 0.9
    })
    
    return {"research": result}

# Start the agent system
start_agents(research_agent, initial_data={
    "type": "research_query", 
    "query": "quantum computing applications"
})
```

### **2. Multi-Agent Collaboration**
```python
@agent("analyzer", responds_to=["research_complete"])
def analysis_agent(spore):
    """I analyze research findings for insights."""
    findings = spore.knowledge.get("findings")
    analysis = chat(f"Analyze these findings for key insights: {findings}")
    return {"analysis": analysis}

@agent("writer", responds_to=["analysis_complete"])
def writing_agent(spore):
    """I create polished reports from analysis."""
    analysis = spore.knowledge.get("analysis")
    report = chat(f"Write a professional report: {analysis}")
    return {"report": report}

# All agents coordinate automatically!
start_agents(research_agent, analysis_agent, writing_agent)
```

## 🏛️ **Architecture Overview**

### **🧠 The Praval Mental Model**

Think of Praval as creating **AI coral reefs** - ecosystems where:
- 🐠 **Agents are organisms** with specialized roles
- 🌊 **The Reef is the communication medium** enabling knowledge flow
- 🌿 **Spores are knowledge packets** that agents exchange
- 🏛️ **Emergent intelligence** arises from collective interaction

### **⚙️ Core Components**

#### **🎭 Agents - The Specialized Workers**
```python
@agent("name", responds_to=["message_types"], channel="optional")
def agent_function(spore):
    """Define what the agent IS, not what it DOES"""
    # Agent processes spore.knowledge
    # Returns results or broadcasts to others
```
- **Identity-Based Design**: Agents are defined by their role, not procedures
- **Message Filtering**: Only process relevant communications
- **Automatic Registration**: Self-discovery and coordination
- **Thread-Safe Execution**: Concurrent processing with resource management

#### **🌊 The Reef - Communication Substrate**
- **Spore Protocol**: JSON messages carrying structured knowledge
- **Channel System**: Organized communication streams
- **Broadcast/Unicast**: Flexible message routing patterns
- **Message Persistence**: Reliable delivery and replay capabilities

#### **📦 Spores - Knowledge Containers**
```python
spore = {
    "id": "unique_identifier",
    "type": "research_finding",
    "knowledge": {
        "topic": "quantum_computing",
        "insights": [...],
        "confidence": 0.89
    },
    "from_agent": "researcher",
    "timestamp": "2024-01-15T10:30:00Z"
}
```

#### **🔧 Built-in Capabilities**
- **Multi-LLM Support**: OpenAI, Anthropic, Cohere integration
- **State Persistence**: Conversation memory and context tracking
- **Error Handling**: Graceful failure recovery and retry logic
- **Resource Management**: Automatic thread pool and memory optimization
## 🚀 **Real-World Usage Patterns**

### **🎬 Complete Business Analysis Workflow**
*From VentureLens - see it in action:*

```python
from praval import agent, broadcast, start_agents

# Business analysis pipeline - each agent specializes
venture = {}  # Shared state

@agent("interviewer", responds_to=["start_interview", "answer_provided"])
def conduct_interview(spore):
    """I ask insightful questions about business ideas."""
    if venture.get("questions_asked", 0) < 8:
        # Generate contextual follow-up questions
        question = generate_smart_question(venture["responses"])
        print(f"💬 {question}")
        venture["current_question"] = question
    else:
        broadcast({"type": "interview_complete", "responses": venture["responses"]})

@agent("analyst", responds_to=["interview_complete"])
def analyze_viability(spore):
    """I evaluate business ideas across 6 dimensions."""
    responses = spore.knowledge["responses"]
    analysis = {
        "viability_score": 7.8,
        "problem_solution_fit": 8.5,
        "market_potential": 8.0,
        "strengths": ["Clear market need", "Strong differentiation"],
        "recommendations": ["Focus on MVP", "Validate with customers"]
    }
    broadcast({"type": "analysis_complete", "analysis": analysis})

@agent("reporter", responds_to=["analysis_complete"])
def generate_report(spore):
    """I create professional PDF reports."""
    analysis = spore.knowledge["analysis"]
    report = create_professional_pdf(analysis)
    broadcast({"type": "report_generated", "filename": report})

@agent("presenter", responds_to=["report_generated"], auto_broadcast=False)
def present_results(spore):
    """I present results and auto-open reports in browser."""
    filename = spore.knowledge["filename"]
    print(f"📄 Analysis complete: {filename}")
    open_in_browser(filename)  # Auto-open PDF and HTML

# Start the entire workflow with one command!
start_agents(
    conduct_interview, analyze_viability, generate_report, present_results,
    initial_data={"type": "start_interview", "idea": "AI-powered solopreneur toolkit"}
)
```

### **🧠 Knowledge Discovery Pipeline**
*From our knowledge graph miners:*

```python
@agent("domain_expert", responds_to=["explore_concept"])
def find_concepts(spore):
    """I identify core concepts and their relationships."""
    concept = spore.knowledge["concept"]
    related = chat(f"Find 10 concepts closely related to {concept}")
    
    broadcast({
        "type": "concepts_found",
        "base_concept": concept,
        "related_concepts": parse_concepts(related)
    })

@agent("relationship_analyst", responds_to=["concepts_found"])
def analyze_relationships(spore):
    """I determine how concepts connect to each other."""
    concepts = spore.knowledge["related_concepts"]
    relationships = []
    
    for concept_pair in combinations(concepts, 2):
        relationship = chat(f"How are {concept_pair[0]} and {concept_pair[1]} related?")
        relationships.append({
            "from": concept_pair[0],
            "to": concept_pair[1], 
            "relationship": relationship
        })
    
    broadcast({"type": "relationships_mapped", "relationships": relationships})

@agent("graph_builder", responds_to=["relationships_mapped"])
def build_knowledge_graph(spore):
    """I construct the final knowledge graph structure."""
    relationships = spore.knowledge["relationships"]
    graph = construct_graph(relationships)
    save_graph(graph, "knowledge_graph.json")
    print(f"🕸️ Knowledge graph built with {len(graph.nodes)} nodes!")

# Mine any topic automatically
start_agents(
    find_concepts, analyze_relationships, build_knowledge_graph,
    initial_data={"type": "explore_concept", "concept": "quantum computing"}
)
```

### **💬 Intelligent Conversation System**
*Multi-agent RAG chatbot pattern:*

```python
@agent("retriever", responds_to=["user_query"])
def find_relevant_context(spore):
    """I find relevant information from knowledge base."""
    query = spore.knowledge["query"]
    context = vector_search(query, top_k=5)
    
    broadcast({
        "type": "context_retrieved",
        "query": query,
        "context": context
    })

@agent("responder", responds_to=["context_retrieved"])
def generate_response(spore):
    """I craft responses using retrieved context."""
    query = spore.knowledge["query"]
    context = spore.knowledge["context"]
    
    response = chat(f"""
    Question: {query}
    Relevant Context: {context}
    
    Provide a comprehensive answer based on the context.
    """)
    
    return {"response": response}

# Each user query triggers the full RAG pipeline
start_agents(find_relevant_context, generate_response, 
    initial_data={"type": "user_query", "query": "How does quantum entanglement work?"})
```

### Reef Communication System

The **Reef** enables knowledge-first communication between agents through structured JSON messages called **spores**. Like coral reefs facilitate biological communication, the Reef connects all agents in a living communication network.

#### Core Concepts

- **Reef** - The message queue network connecting all agents
- **Spores** - JSON messages containing knowledge, data, or requests  
- **Channels** - Named communication channels within the reef
- **Knowledge-First** - All communication carries structured, semantic data

#### Basic Communication

```python
from praval import Agent, register_agent, get_reef

# Create and register agents
researcher = Agent("researcher", system_message="You research topics deeply")
analyzer = Agent("analyzer", system_message="You analyze data patterns")

register_agent(researcher)
register_agent(analyzer)

# Knowledge sharing between agents
researcher.send_knowledge("analyzer", {
    "topic": "quantum_computing",
    "findings": ["coherence_improved", "error_rates_reduced"],
    "confidence": 0.89,
    "source": "latest_research"
})

# Broadcasting discoveries to all agents
researcher.broadcast_knowledge({
    "breakthrough": "room_temperature_superconductor",
    "impact": "revolutionary",
    "verification_needed": True
})
```

#### Request-Response Pattern

```python
# Agent requests knowledge from another
analyzer.subscribe_to_channel("main")  # Subscribe to receive responses

def handle_requests(spore):
    if spore.spore_type == SporeType.REQUEST and spore.to_agent == "analyzer":
        # Process request and send response
        if spore.knowledge.get("query") == "analyze_data":
            response = {"result": "analysis_complete", "insights": [...]}
            get_reef().reply(
                from_agent="analyzer",
                to_agent=spore.from_agent, 
                response=response,
                reply_to_spore_id=spore.id
            )

# Override spore handler
analyzer.on_spore_received = handle_requests

# Request knowledge with timeout
response = researcher.request_knowledge("analyzer", {
    "query": "analyze_data",
    "dataset": "experiment_results",
    "priority": "high"
}, timeout=30)

if response:
    print(f"Analysis result: {response}")
```

#### Multi-Channel Communication

```python
reef = get_reef()

# Create specialized channels
reef.create_channel("research", max_capacity=500)  
reef.create_channel("alerts", max_capacity=100)
reef.create_channel("coordination", max_capacity=200)

# Agents subscribe to relevant channels
researcher.subscribe_to_channel("research")
researcher.subscribe_to_channel("coordination")

analyzer.subscribe_to_channel("alerts")
analyzer.subscribe_to_channel("coordination")

# Send to specific channels
researcher.send_knowledge("analyzer", {
    "paper": "quantum_error_correction",
    "significance": "breakthrough"
}, channel="research")

# Broadcast alerts
system_monitor = Agent("monitor")
system_monitor.broadcast_knowledge({
    "alert": "system_overload",
    "severity": "high",
    "action_required": True
}, channel="alerts")
```

#### Agent Coordination and Handoffs

```python
class CoordinatedAgent(Agent):
    def __init__(self, name, specialization):
        super().__init__(name)
        self.specialization = specialization
        self.active_tasks = {}
        
    def on_spore_received(self, spore):
        """Handle incoming spores with task coordination."""
        if spore.spore_type == SporeType.REQUEST:
            if self.can_handle_task(spore.knowledge):
                self.accept_task(spore)
            else:
                self.delegate_task(spore)
                
    def can_handle_task(self, task_data):
        """Check if this agent can handle the task."""
        return task_data.get("domain") == self.specialization
        
    def delegate_task(self, original_spore):
        """Hand off task to more suitable agent."""
        suitable_agent = self.find_suitable_agent(original_spore.knowledge)
        if suitable_agent:
            self.send_knowledge(suitable_agent, {
                "handoff": True,
                "original_request": original_spore.knowledge,
                "from_agent": original_spore.from_agent,
                "reason": f"Better handled by {suitable_agent}",
                "context": self.get_task_context()
            })

# Create coordinated multi-agent system
nlp_agent = CoordinatedAgent("nlp_specialist", "natural_language_processing")
cv_agent = CoordinatedAgent("cv_specialist", "computer_vision") 
coordinator = CoordinatedAgent("coordinator", "task_management")

for agent in [nlp_agent, cv_agent, coordinator]:
    register_agent(agent)
    agent.subscribe_to_channel("coordination")
```

### Simple Agent Creation

```python
from praval import Agent

# Create an agent with system message
agent = Agent(
    "assistant",
    system_message="You are a helpful assistant."
)

# Chat with the agent
response = agent.chat("Hello, how are you?")
print(response)
```

## ⚙️ **Configuration**

### **Environment Variables**
```bash
# LLM Provider Configuration
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
COHERE_API_KEY=your_cohere_key

# Praval Framework Settings
PRAVAL_DEFAULT_PROVIDER=openai     # Default LLM provider
PRAVAL_DEFAULT_MODEL=gpt-4-turbo    # Default model
PRAVAL_MAX_THREADS=10              # Thread pool size
PRAVAL_LOG_LEVEL=INFO              # Logging level
PRAVAL_REEF_CAPACITY=1000          # Message queue capacity
```

### **Runtime Configuration**
```python
from praval import configure

# Configure framework defaults
configure({
    "default_provider": "openai",
    "default_model": "gpt-4-turbo", 
    "max_concurrent_agents": 10,
    "reef_config": {
        "channel_capacity": 1000,
        "message_ttl": 3600  # seconds
    }
})
```

## 🛠️ **Development Guide**

### **Project Structure**
```
praval/
├── src/praval/
│   ├── __init__.py           # Main API exports
│   ├── decorators.py         # @agent decorator magic
│   ├── composition.py        # start_agents orchestration
│   └── core/
│       ├── agent.py          # Agent implementation
│       ├── reef.py           # Communication system
│       ├── registry.py       # Agent discovery
│       └── storage.py        # State persistence
├── examples/                 # Complete working examples
│   ├── venturelens.py        # Business analysis platform
│   ├── knowledge_graph_miner.py  # Advanced KG mining
│   ├── pythonic_knowledge_graph.py  # Simplified KG
│   ├── rag_chatbot.py        # RAG conversation system
│   └── arxiv_paper_downloader.py # Research automation
└── tests/                    # Comprehensive test suite
```

### **Testing & Validation**
```bash
# Run full test suite
pytest tests/ -v

# Test with coverage reporting
pytest --cov=praval --cov-report=html

# Test specific components
pytest tests/test_reef.py -v          # Communication system
pytest tests/test_agent.py -v         # Agent functionality
pytest tests/test_self_organizing_agents.py -v  # Multi-agent coordination

# Validate examples
python examples/pythonic_knowledge_graph.py
python examples/venturelens.py
```

### **Contributing Guidelines**
```python
# Follow Praval principles when adding new features:

# ✅ Good: Specialized, focused agents
@agent("validator", responds_to=["validation_request"])
def data_validator(spore):
    """I specialize in data quality validation."""
    
# ❌ Avoid: Monolithic, do-everything agents  
@agent("super_agent", responds_to=["everything"])
def handle_everything(spore):
    """I handle all possible tasks."""
```

## 🗺️ **Roadmap**

### **✅ Phase 1: Foundation Complete**
- **✓ Decorator API**: Clean `@agent()` decorator system
- **✓ Reef Communication**: Knowledge-first messaging protocol
- **✓ Multi-LLM Support**: OpenAI, Anthropic, Cohere integration
- **✓ Self-Organization**: Agents coordinate without central control
- **✓ Production Examples**: VentureLens business analyzer
- **✓ Concurrent Processing**: Thread-safe multi-agent execution
- **✓ Message Filtering**: Agents respond only to relevant communications

### **✅ Phase 2: Advanced Patterns Complete (v0.5.0)**
- **✓ Memory Integration**: ChromaDB embedded vector storage
- **✓ Comprehensive Testing**: 99% coverage on core decorators and composition
- **✓ Semantic Memory**: Persistent knowledge with semantic search
- **✓ Knowledge Base**: Auto-indexing of documents and files
- **✓ Multi-layered Memory**: Short-term, long-term, episodic, semantic memory
- **✓ Complex Workflows**: Multi-stage business analysis pipelines
- **✓ Dynamic Coordination**: Agents discover and delegate tasks

### **🚀 Phase 3: Enterprise Ready (Current)**
- **🚧 Streaming Responses**: Real-time token streaming from agents  
- **🚧 Tool Ecosystem**: External API and service integration
- **🚧 Visual Debugging**: Agent interaction visualization
- **📈 Observability Suite**: Comprehensive metrics and tracing
- **🔒 Security Framework**: Content filtering and access control
- **⚡ Performance Optimization**: Caching, rate limiting, cost management
- **🐝 Horizontal Scaling**: Distributed agent deployment

### **🎆 Phase 4: Advanced Intelligence**
- **🤖 Agent Evolution**: Self-improving agent capabilities
- **🌍 Multi-Modal Agents**: Vision, audio, and text integration
- **🎨 Creative Collaboration**: Agents for design, writing, and art
- **🔬 Scientific Discovery**: Agents for research and analysis
- **🏭 Industry Solutions**: Specialized agent packages for domains

## 🔄 **Versioning & Releases**

Praval follows [Semantic Versioning](https://semver.org/) with **automated version bumping**:

### **Current Status**: `v0.5.0` (Pre-1.0 Beta)

### **Automatic Release Process**
Every push to `main` triggers automatic version bumping based on commit messages:

#### 🔵 **Minor Release** (New features: `0.5.0 → 0.6.0`)
```bash
git commit -m "fix: Memory leak in agent cleanup"
git commit -m "docs: Update installation guide"  
git commit -m "test: Add coverage for edge cases"
```

#### 🟡 **Minor Release** (New features: `0.5.0 → 0.6.0`)
```bash
git commit -m "feat: Add streaming response capability"
git commit -m "add: New knowledge base integration"
git commit -m "enhance: Improve memory performance"
```

#### 🔴 **Major Release** (Breaking changes: `0.5.0 → 1.0.0`)
```bash
git commit -m "BREAKING CHANGE: Redesign agent decorator API"
git commit -m "major: Remove deprecated memory interface"
```

### **Installation from Releases**
```bash
# Latest development version
pip install git+https://github.com/aiexplorations/praval.git

# Specific version
pip install git+https://github.com/aiexplorations/praval.git@v0.5.0
```

### **Contributing**
See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines on contributing and triggering version bumps.

---

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🎯 **Complete Examples**

### **📚 Memory-Enabled Learning System**
*`examples/005_memory_enabled_agents.py`* - **Showcasing Praval's memory capabilities**

**What it demonstrates**: A learning system where agents build relationships and knowledge through persistent memory.

**Multi-Agent Architecture**:
- **🧠 Learning Agent**: Remembers past sessions and builds on previous knowledge
- **👨‍🏫 Teaching Agent**: Adapts teaching methods based on student history
- **🤔 Reflection Agent**: Analyzes patterns from memory to improve future interactions

### **🔗 Agent Communication & Collaboration**
*Complete example series demonstrating core Praval patterns*

#### **Core Example Series**:
- **`001_single_agent_identity.py`**: How agent identity drives behavior
- **`002_agent_communication.py`**: Basic agent-to-agent communication  
- **`003_specialist_collaboration.py`**: Specialized agents working together
- **`004_registry_discovery.py`**: Dynamic agent discovery and coordination
- **`005_memory_enabled_agents.py`**: Persistent memory and learning
- **`006_resilient_agents.py`**: Error handling and fault tolerance
- **`007_adaptive_agent_systems.py`**: Self-adapting agent behaviors
- **`008_self_organizing_networks.py`**: Emergent network behaviors
- **`009_emergent_collective_intelligence.py`**: Complex behaviors from simple agents

```python
# Simple agent identity example
@agent("philosopher", responds_to=["deep_question"])
def philosopher_agent(spore):
    """I ask insightful questions about business ideas."""
    # Dynamic question generation using AI
    next_question = generate_smart_question(previous_answers)
    return ask_user(next_question)

@agent("analyst", responds_to=["interview_complete"])
def analyze_business_viability(spore):
    """I evaluate business ideas across multiple dimensions."""
    # Comprehensive analysis with scoring
    analysis = evaluate_idea(interview_data)
    return {"viability_score": 8.2, "analysis": analysis}
```

**Key Features**:
- ✨ **489 lines → 50 lines**: Dramatic code simplification
- 🧠 **Dynamic Questioning**: AI generates contextual follow-ups
- 📊 **Multi-Dimensional Analysis**: SWOT, financial projections, market research
- 📄 **Professional Reports**: LaTeX-styled PDFs with auto-browser opening
- 🔄 **Self-Organizing Workflow**: Agents coordinate the entire process

### **🕸️ Knowledge Graph Mining Suite**

#### **Advanced Multi-Threading Version** 
*`examples/knowledge_graph_miner.py`* - Concurrent agent processing

- **🧠 Domain Expert**: Identifies core concepts and relationships
- **🔍 Relationship Analyst**: Maps connections between concepts
- **⚡ Concurrent Execution**: True parallel LLM processing
- **📡 Thread-Safe Communication**: Reef messaging across threads
- **🎯 Message Filtering**: Agents respond only to relevant messages

#### **Pythonic Simplified Version**
*`examples/pythonic_knowledge_graph.py`* - Clean decorator API showcase

- **📉 Complexity Reduction**: From complex classes to simple functions
- **🎨 Declarative Design**: Define agent identity, not procedures  
- **⚙️ Automatic Coordination**: No manual threading or state management
- **✨ Emergent Intelligence**: Complex graphs from simple agent collaboration

### **💬 RAG Chatbot**
*`examples/rag_chatbot.py`* - Retrieval-augmented conversation system

- **🔍 Document Processing**: Intelligent text chunking and embedding
- **🧠 Context Retrieval**: Semantic search for relevant information
- **💭 Conversational Memory**: Multi-turn dialogue management
- **📚 Knowledge Integration**: Combines retrieved context with AI generation

### **📚 ArXiv Paper Downloader**
*`examples/arxiv_paper_downloader.py`* - Automated research paper acquisition

- **🔍 Query Processing**: Intelligent search term optimization
- **📄 Batch Downloads**: Efficient paper retrieval and organization
- **📊 Metadata Extraction**: Author, abstract, and citation information
- **🗂️ File Management**: Organized storage with deduplication

### **🎯 API Pattern Examples**
*`examples/target_api_examples.py`* - Core framework demonstrations

- **🏗️ Foundation Patterns**: Basic agent creation and registration
- **🤝 Collaboration Examples**: Agent-to-agent communication
- **🔧 Tool Integration**: External API and service connections
- **📋 Best Practices**: Recommended implementation patterns

## 🔒 **Secure Spores Messaging** *(Enterprise Edition)*

Praval includes an enterprise-grade secure messaging system that transforms the framework from local agent coordination to distributed, encrypted, multi-agent platforms.

### **🛡️ Security Features**
- **🔐 End-to-End Encryption**: PyNaCl cryptography (Curve25519 + XSalsa20 + Poly1305)
- **✅ Digital Signatures**: Ed25519 for message authenticity and integrity
- **🔄 Key Rotation**: Automatic key management with forward secrecy
- **🛡️ TLS Transport**: Certificate-based transport layer security
- **🔒 Tamper-Proof**: Authenticated encryption prevents message modification

### **📡 Supported Protocols**
- **🐰 AMQP**: RabbitMQ with TLS support and management plugins
- **📡 MQTT**: Eclipse Mosquitto with WebSocket and TLS support  
- **🔌 STOMP**: ActiveMQ with SSL and enterprise features
- **⚡ Redis**: High-performance key-value messaging (planned)
- **🚀 NATS**: Cloud-native messaging (planned)

### **🐳 Quick Start with Docker**

```bash
# Clone and start secure infrastructure
git clone https://github.com/aiexplorations/praval.git
cd praval

# Start the full secure messaging stack
docker-compose -f docker/docker-compose.secure.yml up -d

# Run secure spore demo
docker-compose exec praval-secure python examples/secure_spore_demo.py

# Development with Jupyter (secure environment)
docker-compose --profile dev up jupyter-secure
# Access: http://localhost:8889 (token: praval_secure_2024)
```

### **🏗️ Infrastructure Services**

The secure deployment includes:

| Service | Port | Purpose | TLS |
|---------|------|---------|-----|
| **RabbitMQ** | 5671/5672 | AMQP message broker | ✅ |
| **Mosquitto** | 8883/8884 | MQTT message broker | ✅ |
| **ActiveMQ** | 61614/61613 | STOMP message broker | ✅ |
| **Qdrant** | 6333 | Vector database for memory | ✅ |
| **Redis** | 6379 | Key registry & caching | ✅ |
| **Jupyter** | 8889 | Secure development environment | ✅ |

### **💻 Example: Secure Agent Communication**

```python
from praval.core.secure_reef import SecureReef
from praval.core.secure_spore import SecureSporeFactory

# Initialize secure messaging
secure_reef = SecureReef(
    transport_protocol='amqp',
    amqp_url='amqps://user:pass@rabbitmq:5671/secure',
    tls_config={
        'ca_cert': '/certs/ca.pem',
        'client_cert': '/certs/client.pem', 
        'client_key': '/certs/client.key'
    }
)

# Create secure spore factory with encryption
spore_factory = SecureSporeFactory(
    signing_key=ed25519_private_key,
    encryption_key=curve25519_private_key
)

# Send encrypted message between agents
secure_spore = spore_factory.create_secure_spore(
    knowledge={"classified_data": "top_secret_analysis"},
    to_agent="analyst_agent",
    encryption_enabled=True
)

await secure_reef.send_secure_spore(secure_spore)
```

## 🐳 **Docker Deployment**

Praval supports both local development and production deployment through comprehensive Docker infrastructure.

### **📦 Available Configurations**

#### **Development Mode**
```bash
# Standard development with local services
docker-compose up -d

# With Jupyter Lab
docker-compose --profile dev up jupyter
# Access: http://localhost:8888
```

#### **Secure Production Mode**
```bash
# Enterprise secure messaging infrastructure  
docker-compose -f docker/docker-compose.secure.yml up -d

# Includes: RabbitMQ, MQTT, STOMP, Qdrant, Redis, TLS certificates
# All services configured with enterprise security
```

### **🔧 Service Configuration**

**Standard Services:**
- **Praval App**: Main application container
- **Qdrant**: Vector database for agent memory (http://localhost:6333)
- **Jupyter**: Development environment (http://localhost:8888)

**Secure Services:**
- **All standard services** plus:
- **RabbitMQ**: Message broker with AMQP/MQTT/STOMP
- **Mosquitto**: Dedicated MQTT broker
- **ActiveMQ**: Enterprise STOMP messaging
- **Redis**: Key registry and caching
- **TLS Certificates**: Automatic certificate management

### **⚙️ Environment Variables**

```bash
# Core configuration
OPENAI_API_KEY=your_key
PRAVAL_LOG_LEVEL=INFO

# Secure messaging
PRAVAL_TRANSPORT_PROTOCOL=amqp
PRAVAL_AMQP_URL=amqps://praval:secure_pass@rabbitmq:5671/praval
PRAVAL_TLS_CA_CERT=/app/certs/ca_certificate.pem

# Development
JUPYTER_TOKEN=your_secure_token
```

### **📋 Health Monitoring**

All services include health checks and monitoring:

```bash
# Check service health
docker-compose ps

# View logs
docker-compose logs praval-secure
docker-compose logs rabbitmq

# Access management interfaces
# RabbitMQ: http://localhost:15672 (admin/secure_praval_2024)
# ActiveMQ: http://localhost:8161 (admin/secure_activemq_2024)
```

## 📞 **Community & Support**

### **👥 Getting Help**
- **🐛 GitHub Issues**: Report bugs and request features
- **📚 Documentation**: Comprehensive guides in `/docs`  
- **🎯 Examples**: Complete working applications in `/examples`
- **🧠 Philosophy**: Deep dive into Praval principles in `praval.md`
- **💬 Discussions**: Community Q&A and best practices

### **🎆 Showcase Your Work**
**Built something amazing with Praval?** We'd love to feature it!

- **🏆 Agent Showcases**: Highlight innovative agent architectures
- **🚀 Success Stories**: Share your production implementations
- **📚 Tutorial Contributions**: Help others learn Praval patterns
- **🎆 Community Examples**: Expand the examples library

### **🕰️ Quick Links**
- **🚀 Get Started**: Follow the Quick Start guide above
- **📊 See Results**: Run VentureLens for a complete demo
- **🧠 Understand Philosophy**: Read `praval.md` for design principles
- **🔧 Contribute**: Check development guidelines above

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "praval",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "ai, agents, llm, multi-agent, framework, openai, anthropic, cohere, rag, memory, vector-database, chromadb, qdrant, chatbot, knowledge-graph, semantic-search, nlp",
    "author": "Praval Team",
    "author_email": null,
    "download_url": null,
    "platform": null,
    "description": "<div align=\"center\">\n  <img src=\"logo.png\" alt=\"Praval Logo\" width=\"200\"/>\n  \n  # Praval\n  \n  **The Pythonic Multi-Agent AI Framework**\n  \n  Transform complex AI applications into simple, composable agent systems using decorator-based APIs, secure messaging, and distributed deployment.\n  \n  *Praval (\u092a\u094d\u0930\u0935\u093e\u0932) - Sanskrit for coral, representing how simple agents collaborate to create complex, intelligent ecosystems.*\n\n  [![Version](https://img.shields.io/badge/version-0.7.6-blue.svg)](https://github.com/aiexplorations/praval/releases/tag/v0.7.6)\n  [![Security](https://img.shields.io/badge/security-enterprise%20ready-green.svg)](#-secure-spores-messaging)\n  [![Docker](https://img.shields.io/badge/docker-multi--service-blue.svg)](#-docker-deployment)\n</div>\n\n## Overview\n\n**Praval is a revolutionary Python framework that transforms how we build AI applications.** Instead of monolithic systems, Praval enables you to create ecosystems of specialized agents that collaborate intelligently.\n\n### \ud83d\ude80 **Key Breakthrough: From Complexity to Simplicity**\n- **489 lines \u2192 50 lines**: Our decorator API dramatically reduces code complexity\n- **Complex classes \u2192 Simple functions**: Agents become readable Python functions\n- **Manual coordination \u2192 Self-organizing**: Agents coordinate through intelligent message passing\n- **Imperative programming \u2192 Declarative agents**: Define what agents ARE, not what they DO\n\n### \u2728 **Core Capabilities**\n- **\ud83c\udfaf Specialized Agents**: Each agent excels at one thing\n- **\ud83e\udde0 Persistent Memory**: ChromaDB-powered semantic memory and knowledge search\n- **\ud83e\udd1d Natural Collaboration**: Agents work together seamlessly\n- **\ud83d\udce1 Reef Communication**: Knowledge-first messaging between agents\n- **\ud83d\udd04 Self-Organization**: Agents coordinate without central control\n- **\u26a1 Pythonic API**: Clean, decorator-based agent definitions\n- **\ud83d\udd12 Secure Messaging**: End-to-end encryption with enterprise-grade security\n- **\ud83d\udc33 Distributed Deployment**: Multi-service Docker architecture with message queues\n- **\ud83d\udce1 Multi-Protocol Support**: AMQP, MQTT, STOMP for scalable messaging \n\n## \u2b50 **The Praval Philosophy**\n\n### **\ud83e\udde9 Simple Agents, Powerful Results**\n```python\n# Instead of complex monoliths...\ncomplex_system = OneAgentDoesEverything()\n\n# Praval encourages specialized collaboration\n@agent(\"researcher\", responds_to=[\"research_request\"])\ndef research_specialist(spore):\n    \"\"\"I excel at finding and analyzing information.\"\"\"\n    return deep_research(spore.knowledge)\n\n@agent(\"writer\", responds_to=[\"write_request\"])\ndef writing_specialist(spore):\n    \"\"\"I excel at creating compelling content.\"\"\"\n    return polished_writing(spore.knowledge)\n```\n\n### **\ud83c\udf0a Core Features**\n\n#### **\ud83c\udfaf Decorator-Based Agent API**\n- **@agent()**: Transform functions into intelligent agents\n- **Automatic Registration**: Agents discover each other dynamically\n- **Message Filtering**: Agents respond only to relevant communications\n- **Thread-Safe Execution**: Concurrent processing with automatic resource management\n\n#### **\ud83c\udfd7\ufe0f Reef Communication System**\n- **Knowledge-First Messaging**: All communication carries structured, semantic data\n- **Spore Protocol**: JSON messages that agents broadcast and consume\n- **Channel Management**: Organized communication streams\n- **Self-Organization**: Agents coordinate without central orchestration\n\n#### **\ud83d\udd27 Production-Ready Infrastructure**\n- **Multi-LLM Support**: OpenAI, Anthropic, Cohere, and more\n- **State Persistence**: Conversation memory and context management\n- **Error Handling**: Graceful degradation and retry mechanisms\n- **Resource Management**: Automatic cleanup and optimization\n\n#### **\ud83d\udd12 Secure Spores Messaging** *(Enterprise Edition)*\n- **End-to-End Encryption**: PyNaCl cryptography (Curve25519 + XSalsa20 + Poly1305)\n- **Digital Signatures**: Ed25519 for message authenticity and integrity\n- **Multi-Protocol Transport**: AMQP (RabbitMQ), MQTT (Mosquitto), STOMP (ActiveMQ)\n- **TLS/SSL Security**: Certificate-based transport encryption\n- **Key Management**: Automatic key rotation and forward secrecy\n- **Distributed Architecture**: Horizontally scalable with message queue clustering\n\n### **\ud83c\udfd7\ufe0f Architecture Principles**\n\n#### **\ud83c\udfaf Specialization Over Generalization**\n```python\n# \u274c Instead of one agent doing everything\ngeneral_agent = Agent(\"do_everything\", \"You can handle any task perfectly\")\n\n# \u2705 Praval encourages focused specialists\n@agent(\"researcher\", responds_to=[\"research_query\"])\ndef research_specialist(spore):\n    \"\"\"I excel at finding and analyzing information.\"\"\"\n    \n@agent(\"writer\", responds_to=[\"content_request\"])\ndef writing_specialist(spore):\n    \"\"\"I excel at creating compelling content.\"\"\"\n```\n\n#### **\ud83c\udf0a Reef Communication Philosophy**\n- **Knowledge-First**: Every message carries structured, semantic data\n- **Self-Organization**: Agents coordinate without central control\n- **Emergent Intelligence**: Complex behaviors arise from simple interactions\n- **Natural Flow**: Information flows like nutrients in a coral reef\n\n#### **\ud83d\udee1\ufe0f Production-Ready Features**\n- **Error Resilience**: Individual agent failures don't crash the system\n- **Resource Management**: Automatic cleanup and thread pool optimization\n- **Message Filtering**: Agents process only relevant communications\n- **Graceful Degradation**: Systems adapt when agents are unavailable\n\n## \ud83d\udce6 **Installation**\n\nPraval offers flexible installation options based on your needs:\n\n### **Minimal Installation** (Fastest - ~50MB)\nPerfect for getting started with basic agents:\n```bash\npip install praval\n\n# Or with UV (faster)\nuv pip install praval\n```\n**Includes**: LLM providers (OpenAI, Anthropic, Cohere), basic agent functionality\n\n### **With Memory** (Recommended - ~500MB)\nAdds vector storage and persistent memory:\n```bash\npip install praval[memory]\n\n# Or with UV\nuv pip install praval[memory]\n```\n**Adds**: ChromaDB, sentence-transformers, semantic search\n\n### **Full Installation** (~1.5GB)\nAll features including enterprise messaging and storage:\n```bash\npip install praval[all]\n\n# Or with UV\nuv pip install praval[all]\n```\n**Adds**: Secure Spores, PDF support, storage providers (PostgreSQL, Redis, S3, Qdrant)\n\n### **From Source**\n```bash\ngit clone https://github.com/aiexplorations/praval.git\ncd praval\npip install -e .[all]  # or [memory] for lighter install\n```\n\n### **Development Installation**\n\n```bash\n# Clone and install in development mode\ngit clone https://github.com/aiexplorations/praval.git\ncd praval\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install with development dependencies\npip install -e \".[dev]\"\n```\n\n### **Environment Setup**\n```bash\n# Required: At least one LLM API key\nOPENAI_API_KEY=your_openai_key        # Recommended\nANTHROPIC_API_KEY=your_anthropic_key  # Optional\nCOHERE_API_KEY=your_cohere_key        # Optional\n\n# Memory System (Optional)\nQDRANT_URL=http://localhost:6333      # For vector storage\nPRAVAL_COLLECTION_NAME=praval_memories\n\n# Framework Configuration (Optional)\nPRAVAL_LOG_LEVEL=INFO\nPRAVAL_MAX_THREADS=10\nPRAVAL_DEFAULT_PROVIDER=openai\nPRAVAL_DEFAULT_MODEL=gpt-4o-mini\n\n# Secure Spores Configuration (Enterprise)\nPRAVAL_TRANSPORT_PROTOCOL=amqp        # amqp, mqtt, or stomp\nPRAVAL_AMQP_URL=amqps://user:pass@host:5671/vhost\nPRAVAL_MQTT_HOST=localhost\nPRAVAL_MQTT_PORT=8883\nPRAVAL_TLS_CA_CERT=/path/to/ca.pem\nPRAVAL_TLS_CLIENT_CERT=/path/to/client.pem\nPRAVAL_TLS_CLIENT_KEY=/path/to/client.key\n```\n## \u26a1 **Quick Start**\n\n### **1. Simple Agent Creation**\n```python\nfrom praval import agent, chat, broadcast, start_agents\n\n# Create a specialized agent with just a decorator\n@agent(\"research_expert\", responds_to=[\"research_query\"])\ndef research_agent(spore):\n    \"\"\"I'm an expert at finding and analyzing information.\"\"\"\n    query = spore.knowledge.get(\"query\")\n    result = chat(f\"Research this topic deeply: {query}\")\n    \n    # Broadcast findings to other agents\n    broadcast({\n        \"type\": \"research_complete\",\n        \"findings\": result,\n        \"confidence\": 0.9\n    })\n    \n    return {\"research\": result}\n\n# Start the agent system\nstart_agents(research_agent, initial_data={\n    \"type\": \"research_query\", \n    \"query\": \"quantum computing applications\"\n})\n```\n\n### **2. Multi-Agent Collaboration**\n```python\n@agent(\"analyzer\", responds_to=[\"research_complete\"])\ndef analysis_agent(spore):\n    \"\"\"I analyze research findings for insights.\"\"\"\n    findings = spore.knowledge.get(\"findings\")\n    analysis = chat(f\"Analyze these findings for key insights: {findings}\")\n    return {\"analysis\": analysis}\n\n@agent(\"writer\", responds_to=[\"analysis_complete\"])\ndef writing_agent(spore):\n    \"\"\"I create polished reports from analysis.\"\"\"\n    analysis = spore.knowledge.get(\"analysis\")\n    report = chat(f\"Write a professional report: {analysis}\")\n    return {\"report\": report}\n\n# All agents coordinate automatically!\nstart_agents(research_agent, analysis_agent, writing_agent)\n```\n\n## \ud83c\udfdb\ufe0f **Architecture Overview**\n\n### **\ud83e\udde0 The Praval Mental Model**\n\nThink of Praval as creating **AI coral reefs** - ecosystems where:\n- \ud83d\udc20 **Agents are organisms** with specialized roles\n- \ud83c\udf0a **The Reef is the communication medium** enabling knowledge flow\n- \ud83c\udf3f **Spores are knowledge packets** that agents exchange\n- \ud83c\udfdb\ufe0f **Emergent intelligence** arises from collective interaction\n\n### **\u2699\ufe0f Core Components**\n\n#### **\ud83c\udfad Agents - The Specialized Workers**\n```python\n@agent(\"name\", responds_to=[\"message_types\"], channel=\"optional\")\ndef agent_function(spore):\n    \"\"\"Define what the agent IS, not what it DOES\"\"\"\n    # Agent processes spore.knowledge\n    # Returns results or broadcasts to others\n```\n- **Identity-Based Design**: Agents are defined by their role, not procedures\n- **Message Filtering**: Only process relevant communications\n- **Automatic Registration**: Self-discovery and coordination\n- **Thread-Safe Execution**: Concurrent processing with resource management\n\n#### **\ud83c\udf0a The Reef - Communication Substrate**\n- **Spore Protocol**: JSON messages carrying structured knowledge\n- **Channel System**: Organized communication streams\n- **Broadcast/Unicast**: Flexible message routing patterns\n- **Message Persistence**: Reliable delivery and replay capabilities\n\n#### **\ud83d\udce6 Spores - Knowledge Containers**\n```python\nspore = {\n    \"id\": \"unique_identifier\",\n    \"type\": \"research_finding\",\n    \"knowledge\": {\n        \"topic\": \"quantum_computing\",\n        \"insights\": [...],\n        \"confidence\": 0.89\n    },\n    \"from_agent\": \"researcher\",\n    \"timestamp\": \"2024-01-15T10:30:00Z\"\n}\n```\n\n#### **\ud83d\udd27 Built-in Capabilities**\n- **Multi-LLM Support**: OpenAI, Anthropic, Cohere integration\n- **State Persistence**: Conversation memory and context tracking\n- **Error Handling**: Graceful failure recovery and retry logic\n- **Resource Management**: Automatic thread pool and memory optimization\n## \ud83d\ude80 **Real-World Usage Patterns**\n\n### **\ud83c\udfac Complete Business Analysis Workflow**\n*From VentureLens - see it in action:*\n\n```python\nfrom praval import agent, broadcast, start_agents\n\n# Business analysis pipeline - each agent specializes\nventure = {}  # Shared state\n\n@agent(\"interviewer\", responds_to=[\"start_interview\", \"answer_provided\"])\ndef conduct_interview(spore):\n    \"\"\"I ask insightful questions about business ideas.\"\"\"\n    if venture.get(\"questions_asked\", 0) < 8:\n        # Generate contextual follow-up questions\n        question = generate_smart_question(venture[\"responses\"])\n        print(f\"\ud83d\udcac {question}\")\n        venture[\"current_question\"] = question\n    else:\n        broadcast({\"type\": \"interview_complete\", \"responses\": venture[\"responses\"]})\n\n@agent(\"analyst\", responds_to=[\"interview_complete\"])\ndef analyze_viability(spore):\n    \"\"\"I evaluate business ideas across 6 dimensions.\"\"\"\n    responses = spore.knowledge[\"responses\"]\n    analysis = {\n        \"viability_score\": 7.8,\n        \"problem_solution_fit\": 8.5,\n        \"market_potential\": 8.0,\n        \"strengths\": [\"Clear market need\", \"Strong differentiation\"],\n        \"recommendations\": [\"Focus on MVP\", \"Validate with customers\"]\n    }\n    broadcast({\"type\": \"analysis_complete\", \"analysis\": analysis})\n\n@agent(\"reporter\", responds_to=[\"analysis_complete\"])\ndef generate_report(spore):\n    \"\"\"I create professional PDF reports.\"\"\"\n    analysis = spore.knowledge[\"analysis\"]\n    report = create_professional_pdf(analysis)\n    broadcast({\"type\": \"report_generated\", \"filename\": report})\n\n@agent(\"presenter\", responds_to=[\"report_generated\"], auto_broadcast=False)\ndef present_results(spore):\n    \"\"\"I present results and auto-open reports in browser.\"\"\"\n    filename = spore.knowledge[\"filename\"]\n    print(f\"\ud83d\udcc4 Analysis complete: {filename}\")\n    open_in_browser(filename)  # Auto-open PDF and HTML\n\n# Start the entire workflow with one command!\nstart_agents(\n    conduct_interview, analyze_viability, generate_report, present_results,\n    initial_data={\"type\": \"start_interview\", \"idea\": \"AI-powered solopreneur toolkit\"}\n)\n```\n\n### **\ud83e\udde0 Knowledge Discovery Pipeline**\n*From our knowledge graph miners:*\n\n```python\n@agent(\"domain_expert\", responds_to=[\"explore_concept\"])\ndef find_concepts(spore):\n    \"\"\"I identify core concepts and their relationships.\"\"\"\n    concept = spore.knowledge[\"concept\"]\n    related = chat(f\"Find 10 concepts closely related to {concept}\")\n    \n    broadcast({\n        \"type\": \"concepts_found\",\n        \"base_concept\": concept,\n        \"related_concepts\": parse_concepts(related)\n    })\n\n@agent(\"relationship_analyst\", responds_to=[\"concepts_found\"])\ndef analyze_relationships(spore):\n    \"\"\"I determine how concepts connect to each other.\"\"\"\n    concepts = spore.knowledge[\"related_concepts\"]\n    relationships = []\n    \n    for concept_pair in combinations(concepts, 2):\n        relationship = chat(f\"How are {concept_pair[0]} and {concept_pair[1]} related?\")\n        relationships.append({\n            \"from\": concept_pair[0],\n            \"to\": concept_pair[1], \n            \"relationship\": relationship\n        })\n    \n    broadcast({\"type\": \"relationships_mapped\", \"relationships\": relationships})\n\n@agent(\"graph_builder\", responds_to=[\"relationships_mapped\"])\ndef build_knowledge_graph(spore):\n    \"\"\"I construct the final knowledge graph structure.\"\"\"\n    relationships = spore.knowledge[\"relationships\"]\n    graph = construct_graph(relationships)\n    save_graph(graph, \"knowledge_graph.json\")\n    print(f\"\ud83d\udd78\ufe0f Knowledge graph built with {len(graph.nodes)} nodes!\")\n\n# Mine any topic automatically\nstart_agents(\n    find_concepts, analyze_relationships, build_knowledge_graph,\n    initial_data={\"type\": \"explore_concept\", \"concept\": \"quantum computing\"}\n)\n```\n\n### **\ud83d\udcac Intelligent Conversation System**\n*Multi-agent RAG chatbot pattern:*\n\n```python\n@agent(\"retriever\", responds_to=[\"user_query\"])\ndef find_relevant_context(spore):\n    \"\"\"I find relevant information from knowledge base.\"\"\"\n    query = spore.knowledge[\"query\"]\n    context = vector_search(query, top_k=5)\n    \n    broadcast({\n        \"type\": \"context_retrieved\",\n        \"query\": query,\n        \"context\": context\n    })\n\n@agent(\"responder\", responds_to=[\"context_retrieved\"])\ndef generate_response(spore):\n    \"\"\"I craft responses using retrieved context.\"\"\"\n    query = spore.knowledge[\"query\"]\n    context = spore.knowledge[\"context\"]\n    \n    response = chat(f\"\"\"\n    Question: {query}\n    Relevant Context: {context}\n    \n    Provide a comprehensive answer based on the context.\n    \"\"\")\n    \n    return {\"response\": response}\n\n# Each user query triggers the full RAG pipeline\nstart_agents(find_relevant_context, generate_response, \n    initial_data={\"type\": \"user_query\", \"query\": \"How does quantum entanglement work?\"})\n```\n\n### Reef Communication System\n\nThe **Reef** enables knowledge-first communication between agents through structured JSON messages called **spores**. Like coral reefs facilitate biological communication, the Reef connects all agents in a living communication network.\n\n#### Core Concepts\n\n- **Reef** - The message queue network connecting all agents\n- **Spores** - JSON messages containing knowledge, data, or requests  \n- **Channels** - Named communication channels within the reef\n- **Knowledge-First** - All communication carries structured, semantic data\n\n#### Basic Communication\n\n```python\nfrom praval import Agent, register_agent, get_reef\n\n# Create and register agents\nresearcher = Agent(\"researcher\", system_message=\"You research topics deeply\")\nanalyzer = Agent(\"analyzer\", system_message=\"You analyze data patterns\")\n\nregister_agent(researcher)\nregister_agent(analyzer)\n\n# Knowledge sharing between agents\nresearcher.send_knowledge(\"analyzer\", {\n    \"topic\": \"quantum_computing\",\n    \"findings\": [\"coherence_improved\", \"error_rates_reduced\"],\n    \"confidence\": 0.89,\n    \"source\": \"latest_research\"\n})\n\n# Broadcasting discoveries to all agents\nresearcher.broadcast_knowledge({\n    \"breakthrough\": \"room_temperature_superconductor\",\n    \"impact\": \"revolutionary\",\n    \"verification_needed\": True\n})\n```\n\n#### Request-Response Pattern\n\n```python\n# Agent requests knowledge from another\nanalyzer.subscribe_to_channel(\"main\")  # Subscribe to receive responses\n\ndef handle_requests(spore):\n    if spore.spore_type == SporeType.REQUEST and spore.to_agent == \"analyzer\":\n        # Process request and send response\n        if spore.knowledge.get(\"query\") == \"analyze_data\":\n            response = {\"result\": \"analysis_complete\", \"insights\": [...]}\n            get_reef().reply(\n                from_agent=\"analyzer\",\n                to_agent=spore.from_agent, \n                response=response,\n                reply_to_spore_id=spore.id\n            )\n\n# Override spore handler\nanalyzer.on_spore_received = handle_requests\n\n# Request knowledge with timeout\nresponse = researcher.request_knowledge(\"analyzer\", {\n    \"query\": \"analyze_data\",\n    \"dataset\": \"experiment_results\",\n    \"priority\": \"high\"\n}, timeout=30)\n\nif response:\n    print(f\"Analysis result: {response}\")\n```\n\n#### Multi-Channel Communication\n\n```python\nreef = get_reef()\n\n# Create specialized channels\nreef.create_channel(\"research\", max_capacity=500)  \nreef.create_channel(\"alerts\", max_capacity=100)\nreef.create_channel(\"coordination\", max_capacity=200)\n\n# Agents subscribe to relevant channels\nresearcher.subscribe_to_channel(\"research\")\nresearcher.subscribe_to_channel(\"coordination\")\n\nanalyzer.subscribe_to_channel(\"alerts\")\nanalyzer.subscribe_to_channel(\"coordination\")\n\n# Send to specific channels\nresearcher.send_knowledge(\"analyzer\", {\n    \"paper\": \"quantum_error_correction\",\n    \"significance\": \"breakthrough\"\n}, channel=\"research\")\n\n# Broadcast alerts\nsystem_monitor = Agent(\"monitor\")\nsystem_monitor.broadcast_knowledge({\n    \"alert\": \"system_overload\",\n    \"severity\": \"high\",\n    \"action_required\": True\n}, channel=\"alerts\")\n```\n\n#### Agent Coordination and Handoffs\n\n```python\nclass CoordinatedAgent(Agent):\n    def __init__(self, name, specialization):\n        super().__init__(name)\n        self.specialization = specialization\n        self.active_tasks = {}\n        \n    def on_spore_received(self, spore):\n        \"\"\"Handle incoming spores with task coordination.\"\"\"\n        if spore.spore_type == SporeType.REQUEST:\n            if self.can_handle_task(spore.knowledge):\n                self.accept_task(spore)\n            else:\n                self.delegate_task(spore)\n                \n    def can_handle_task(self, task_data):\n        \"\"\"Check if this agent can handle the task.\"\"\"\n        return task_data.get(\"domain\") == self.specialization\n        \n    def delegate_task(self, original_spore):\n        \"\"\"Hand off task to more suitable agent.\"\"\"\n        suitable_agent = self.find_suitable_agent(original_spore.knowledge)\n        if suitable_agent:\n            self.send_knowledge(suitable_agent, {\n                \"handoff\": True,\n                \"original_request\": original_spore.knowledge,\n                \"from_agent\": original_spore.from_agent,\n                \"reason\": f\"Better handled by {suitable_agent}\",\n                \"context\": self.get_task_context()\n            })\n\n# Create coordinated multi-agent system\nnlp_agent = CoordinatedAgent(\"nlp_specialist\", \"natural_language_processing\")\ncv_agent = CoordinatedAgent(\"cv_specialist\", \"computer_vision\") \ncoordinator = CoordinatedAgent(\"coordinator\", \"task_management\")\n\nfor agent in [nlp_agent, cv_agent, coordinator]:\n    register_agent(agent)\n    agent.subscribe_to_channel(\"coordination\")\n```\n\n### Simple Agent Creation\n\n```python\nfrom praval import Agent\n\n# Create an agent with system message\nagent = Agent(\n    \"assistant\",\n    system_message=\"You are a helpful assistant.\"\n)\n\n# Chat with the agent\nresponse = agent.chat(\"Hello, how are you?\")\nprint(response)\n```\n\n## \u2699\ufe0f **Configuration**\n\n### **Environment Variables**\n```bash\n# LLM Provider Configuration\nOPENAI_API_KEY=your_openai_key\nANTHROPIC_API_KEY=your_anthropic_key\nCOHERE_API_KEY=your_cohere_key\n\n# Praval Framework Settings\nPRAVAL_DEFAULT_PROVIDER=openai     # Default LLM provider\nPRAVAL_DEFAULT_MODEL=gpt-4-turbo    # Default model\nPRAVAL_MAX_THREADS=10              # Thread pool size\nPRAVAL_LOG_LEVEL=INFO              # Logging level\nPRAVAL_REEF_CAPACITY=1000          # Message queue capacity\n```\n\n### **Runtime Configuration**\n```python\nfrom praval import configure\n\n# Configure framework defaults\nconfigure({\n    \"default_provider\": \"openai\",\n    \"default_model\": \"gpt-4-turbo\", \n    \"max_concurrent_agents\": 10,\n    \"reef_config\": {\n        \"channel_capacity\": 1000,\n        \"message_ttl\": 3600  # seconds\n    }\n})\n```\n\n## \ud83d\udee0\ufe0f **Development Guide**\n\n### **Project Structure**\n```\npraval/\n\u251c\u2500\u2500 src/praval/\n\u2502   \u251c\u2500\u2500 __init__.py           # Main API exports\n\u2502   \u251c\u2500\u2500 decorators.py         # @agent decorator magic\n\u2502   \u251c\u2500\u2500 composition.py        # start_agents orchestration\n\u2502   \u2514\u2500\u2500 core/\n\u2502       \u251c\u2500\u2500 agent.py          # Agent implementation\n\u2502       \u251c\u2500\u2500 reef.py           # Communication system\n\u2502       \u251c\u2500\u2500 registry.py       # Agent discovery\n\u2502       \u2514\u2500\u2500 storage.py        # State persistence\n\u251c\u2500\u2500 examples/                 # Complete working examples\n\u2502   \u251c\u2500\u2500 venturelens.py        # Business analysis platform\n\u2502   \u251c\u2500\u2500 knowledge_graph_miner.py  # Advanced KG mining\n\u2502   \u251c\u2500\u2500 pythonic_knowledge_graph.py  # Simplified KG\n\u2502   \u251c\u2500\u2500 rag_chatbot.py        # RAG conversation system\n\u2502   \u2514\u2500\u2500 arxiv_paper_downloader.py # Research automation\n\u2514\u2500\u2500 tests/                    # Comprehensive test suite\n```\n\n### **Testing & Validation**\n```bash\n# Run full test suite\npytest tests/ -v\n\n# Test with coverage reporting\npytest --cov=praval --cov-report=html\n\n# Test specific components\npytest tests/test_reef.py -v          # Communication system\npytest tests/test_agent.py -v         # Agent functionality\npytest tests/test_self_organizing_agents.py -v  # Multi-agent coordination\n\n# Validate examples\npython examples/pythonic_knowledge_graph.py\npython examples/venturelens.py\n```\n\n### **Contributing Guidelines**\n```python\n# Follow Praval principles when adding new features:\n\n# \u2705 Good: Specialized, focused agents\n@agent(\"validator\", responds_to=[\"validation_request\"])\ndef data_validator(spore):\n    \"\"\"I specialize in data quality validation.\"\"\"\n    \n# \u274c Avoid: Monolithic, do-everything agents  \n@agent(\"super_agent\", responds_to=[\"everything\"])\ndef handle_everything(spore):\n    \"\"\"I handle all possible tasks.\"\"\"\n```\n\n## \ud83d\uddfa\ufe0f **Roadmap**\n\n### **\u2705 Phase 1: Foundation Complete**\n- **\u2713 Decorator API**: Clean `@agent()` decorator system\n- **\u2713 Reef Communication**: Knowledge-first messaging protocol\n- **\u2713 Multi-LLM Support**: OpenAI, Anthropic, Cohere integration\n- **\u2713 Self-Organization**: Agents coordinate without central control\n- **\u2713 Production Examples**: VentureLens business analyzer\n- **\u2713 Concurrent Processing**: Thread-safe multi-agent execution\n- **\u2713 Message Filtering**: Agents respond only to relevant communications\n\n### **\u2705 Phase 2: Advanced Patterns Complete (v0.5.0)**\n- **\u2713 Memory Integration**: ChromaDB embedded vector storage\n- **\u2713 Comprehensive Testing**: 99% coverage on core decorators and composition\n- **\u2713 Semantic Memory**: Persistent knowledge with semantic search\n- **\u2713 Knowledge Base**: Auto-indexing of documents and files\n- **\u2713 Multi-layered Memory**: Short-term, long-term, episodic, semantic memory\n- **\u2713 Complex Workflows**: Multi-stage business analysis pipelines\n- **\u2713 Dynamic Coordination**: Agents discover and delegate tasks\n\n### **\ud83d\ude80 Phase 3: Enterprise Ready (Current)**\n- **\ud83d\udea7 Streaming Responses**: Real-time token streaming from agents  \n- **\ud83d\udea7 Tool Ecosystem**: External API and service integration\n- **\ud83d\udea7 Visual Debugging**: Agent interaction visualization\n- **\ud83d\udcc8 Observability Suite**: Comprehensive metrics and tracing\n- **\ud83d\udd12 Security Framework**: Content filtering and access control\n- **\u26a1 Performance Optimization**: Caching, rate limiting, cost management\n- **\ud83d\udc1d Horizontal Scaling**: Distributed agent deployment\n\n### **\ud83c\udf86 Phase 4: Advanced Intelligence**\n- **\ud83e\udd16 Agent Evolution**: Self-improving agent capabilities\n- **\ud83c\udf0d Multi-Modal Agents**: Vision, audio, and text integration\n- **\ud83c\udfa8 Creative Collaboration**: Agents for design, writing, and art\n- **\ud83d\udd2c Scientific Discovery**: Agents for research and analysis\n- **\ud83c\udfed Industry Solutions**: Specialized agent packages for domains\n\n## \ud83d\udd04 **Versioning & Releases**\n\nPraval follows [Semantic Versioning](https://semver.org/) with **automated version bumping**:\n\n### **Current Status**: `v0.5.0` (Pre-1.0 Beta)\n\n### **Automatic Release Process**\nEvery push to `main` triggers automatic version bumping based on commit messages:\n\n#### \ud83d\udd35 **Minor Release** (New features: `0.5.0 \u2192 0.6.0`)\n```bash\ngit commit -m \"fix: Memory leak in agent cleanup\"\ngit commit -m \"docs: Update installation guide\"  \ngit commit -m \"test: Add coverage for edge cases\"\n```\n\n#### \ud83d\udfe1 **Minor Release** (New features: `0.5.0 \u2192 0.6.0`)\n```bash\ngit commit -m \"feat: Add streaming response capability\"\ngit commit -m \"add: New knowledge base integration\"\ngit commit -m \"enhance: Improve memory performance\"\n```\n\n#### \ud83d\udd34 **Major Release** (Breaking changes: `0.5.0 \u2192 1.0.0`)\n```bash\ngit commit -m \"BREAKING CHANGE: Redesign agent decorator API\"\ngit commit -m \"major: Remove deprecated memory interface\"\n```\n\n### **Installation from Releases**\n```bash\n# Latest development version\npip install git+https://github.com/aiexplorations/praval.git\n\n# Specific version\npip install git+https://github.com/aiexplorations/praval.git@v0.5.0\n```\n\n### **Contributing**\nSee [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines on contributing and triggering version bumps.\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## \ud83c\udfaf **Complete Examples**\n\n### **\ud83d\udcda Memory-Enabled Learning System**\n*`examples/005_memory_enabled_agents.py`* - **Showcasing Praval's memory capabilities**\n\n**What it demonstrates**: A learning system where agents build relationships and knowledge through persistent memory.\n\n**Multi-Agent Architecture**:\n- **\ud83e\udde0 Learning Agent**: Remembers past sessions and builds on previous knowledge\n- **\ud83d\udc68\u200d\ud83c\udfeb Teaching Agent**: Adapts teaching methods based on student history\n- **\ud83e\udd14 Reflection Agent**: Analyzes patterns from memory to improve future interactions\n\n### **\ud83d\udd17 Agent Communication & Collaboration**\n*Complete example series demonstrating core Praval patterns*\n\n#### **Core Example Series**:\n- **`001_single_agent_identity.py`**: How agent identity drives behavior\n- **`002_agent_communication.py`**: Basic agent-to-agent communication  \n- **`003_specialist_collaboration.py`**: Specialized agents working together\n- **`004_registry_discovery.py`**: Dynamic agent discovery and coordination\n- **`005_memory_enabled_agents.py`**: Persistent memory and learning\n- **`006_resilient_agents.py`**: Error handling and fault tolerance\n- **`007_adaptive_agent_systems.py`**: Self-adapting agent behaviors\n- **`008_self_organizing_networks.py`**: Emergent network behaviors\n- **`009_emergent_collective_intelligence.py`**: Complex behaviors from simple agents\n\n```python\n# Simple agent identity example\n@agent(\"philosopher\", responds_to=[\"deep_question\"])\ndef philosopher_agent(spore):\n    \"\"\"I ask insightful questions about business ideas.\"\"\"\n    # Dynamic question generation using AI\n    next_question = generate_smart_question(previous_answers)\n    return ask_user(next_question)\n\n@agent(\"analyst\", responds_to=[\"interview_complete\"])\ndef analyze_business_viability(spore):\n    \"\"\"I evaluate business ideas across multiple dimensions.\"\"\"\n    # Comprehensive analysis with scoring\n    analysis = evaluate_idea(interview_data)\n    return {\"viability_score\": 8.2, \"analysis\": analysis}\n```\n\n**Key Features**:\n- \u2728 **489 lines \u2192 50 lines**: Dramatic code simplification\n- \ud83e\udde0 **Dynamic Questioning**: AI generates contextual follow-ups\n- \ud83d\udcca **Multi-Dimensional Analysis**: SWOT, financial projections, market research\n- \ud83d\udcc4 **Professional Reports**: LaTeX-styled PDFs with auto-browser opening\n- \ud83d\udd04 **Self-Organizing Workflow**: Agents coordinate the entire process\n\n### **\ud83d\udd78\ufe0f Knowledge Graph Mining Suite**\n\n#### **Advanced Multi-Threading Version** \n*`examples/knowledge_graph_miner.py`* - Concurrent agent processing\n\n- **\ud83e\udde0 Domain Expert**: Identifies core concepts and relationships\n- **\ud83d\udd0d Relationship Analyst**: Maps connections between concepts\n- **\u26a1 Concurrent Execution**: True parallel LLM processing\n- **\ud83d\udce1 Thread-Safe Communication**: Reef messaging across threads\n- **\ud83c\udfaf Message Filtering**: Agents respond only to relevant messages\n\n#### **Pythonic Simplified Version**\n*`examples/pythonic_knowledge_graph.py`* - Clean decorator API showcase\n\n- **\ud83d\udcc9 Complexity Reduction**: From complex classes to simple functions\n- **\ud83c\udfa8 Declarative Design**: Define agent identity, not procedures  \n- **\u2699\ufe0f Automatic Coordination**: No manual threading or state management\n- **\u2728 Emergent Intelligence**: Complex graphs from simple agent collaboration\n\n### **\ud83d\udcac RAG Chatbot**\n*`examples/rag_chatbot.py`* - Retrieval-augmented conversation system\n\n- **\ud83d\udd0d Document Processing**: Intelligent text chunking and embedding\n- **\ud83e\udde0 Context Retrieval**: Semantic search for relevant information\n- **\ud83d\udcad Conversational Memory**: Multi-turn dialogue management\n- **\ud83d\udcda Knowledge Integration**: Combines retrieved context with AI generation\n\n### **\ud83d\udcda ArXiv Paper Downloader**\n*`examples/arxiv_paper_downloader.py`* - Automated research paper acquisition\n\n- **\ud83d\udd0d Query Processing**: Intelligent search term optimization\n- **\ud83d\udcc4 Batch Downloads**: Efficient paper retrieval and organization\n- **\ud83d\udcca Metadata Extraction**: Author, abstract, and citation information\n- **\ud83d\uddc2\ufe0f File Management**: Organized storage with deduplication\n\n### **\ud83c\udfaf API Pattern Examples**\n*`examples/target_api_examples.py`* - Core framework demonstrations\n\n- **\ud83c\udfd7\ufe0f Foundation Patterns**: Basic agent creation and registration\n- **\ud83e\udd1d Collaboration Examples**: Agent-to-agent communication\n- **\ud83d\udd27 Tool Integration**: External API and service connections\n- **\ud83d\udccb Best Practices**: Recommended implementation patterns\n\n## \ud83d\udd12 **Secure Spores Messaging** *(Enterprise Edition)*\n\nPraval includes an enterprise-grade secure messaging system that transforms the framework from local agent coordination to distributed, encrypted, multi-agent platforms.\n\n### **\ud83d\udee1\ufe0f Security Features**\n- **\ud83d\udd10 End-to-End Encryption**: PyNaCl cryptography (Curve25519 + XSalsa20 + Poly1305)\n- **\u2705 Digital Signatures**: Ed25519 for message authenticity and integrity\n- **\ud83d\udd04 Key Rotation**: Automatic key management with forward secrecy\n- **\ud83d\udee1\ufe0f TLS Transport**: Certificate-based transport layer security\n- **\ud83d\udd12 Tamper-Proof**: Authenticated encryption prevents message modification\n\n### **\ud83d\udce1 Supported Protocols**\n- **\ud83d\udc30 AMQP**: RabbitMQ with TLS support and management plugins\n- **\ud83d\udce1 MQTT**: Eclipse Mosquitto with WebSocket and TLS support  \n- **\ud83d\udd0c STOMP**: ActiveMQ with SSL and enterprise features\n- **\u26a1 Redis**: High-performance key-value messaging (planned)\n- **\ud83d\ude80 NATS**: Cloud-native messaging (planned)\n\n### **\ud83d\udc33 Quick Start with Docker**\n\n```bash\n# Clone and start secure infrastructure\ngit clone https://github.com/aiexplorations/praval.git\ncd praval\n\n# Start the full secure messaging stack\ndocker-compose -f docker/docker-compose.secure.yml up -d\n\n# Run secure spore demo\ndocker-compose exec praval-secure python examples/secure_spore_demo.py\n\n# Development with Jupyter (secure environment)\ndocker-compose --profile dev up jupyter-secure\n# Access: http://localhost:8889 (token: praval_secure_2024)\n```\n\n### **\ud83c\udfd7\ufe0f Infrastructure Services**\n\nThe secure deployment includes:\n\n| Service | Port | Purpose | TLS |\n|---------|------|---------|-----|\n| **RabbitMQ** | 5671/5672 | AMQP message broker | \u2705 |\n| **Mosquitto** | 8883/8884 | MQTT message broker | \u2705 |\n| **ActiveMQ** | 61614/61613 | STOMP message broker | \u2705 |\n| **Qdrant** | 6333 | Vector database for memory | \u2705 |\n| **Redis** | 6379 | Key registry & caching | \u2705 |\n| **Jupyter** | 8889 | Secure development environment | \u2705 |\n\n### **\ud83d\udcbb Example: Secure Agent Communication**\n\n```python\nfrom praval.core.secure_reef import SecureReef\nfrom praval.core.secure_spore import SecureSporeFactory\n\n# Initialize secure messaging\nsecure_reef = SecureReef(\n    transport_protocol='amqp',\n    amqp_url='amqps://user:pass@rabbitmq:5671/secure',\n    tls_config={\n        'ca_cert': '/certs/ca.pem',\n        'client_cert': '/certs/client.pem', \n        'client_key': '/certs/client.key'\n    }\n)\n\n# Create secure spore factory with encryption\nspore_factory = SecureSporeFactory(\n    signing_key=ed25519_private_key,\n    encryption_key=curve25519_private_key\n)\n\n# Send encrypted message between agents\nsecure_spore = spore_factory.create_secure_spore(\n    knowledge={\"classified_data\": \"top_secret_analysis\"},\n    to_agent=\"analyst_agent\",\n    encryption_enabled=True\n)\n\nawait secure_reef.send_secure_spore(secure_spore)\n```\n\n## \ud83d\udc33 **Docker Deployment**\n\nPraval supports both local development and production deployment through comprehensive Docker infrastructure.\n\n### **\ud83d\udce6 Available Configurations**\n\n#### **Development Mode**\n```bash\n# Standard development with local services\ndocker-compose up -d\n\n# With Jupyter Lab\ndocker-compose --profile dev up jupyter\n# Access: http://localhost:8888\n```\n\n#### **Secure Production Mode**\n```bash\n# Enterprise secure messaging infrastructure  \ndocker-compose -f docker/docker-compose.secure.yml up -d\n\n# Includes: RabbitMQ, MQTT, STOMP, Qdrant, Redis, TLS certificates\n# All services configured with enterprise security\n```\n\n### **\ud83d\udd27 Service Configuration**\n\n**Standard Services:**\n- **Praval App**: Main application container\n- **Qdrant**: Vector database for agent memory (http://localhost:6333)\n- **Jupyter**: Development environment (http://localhost:8888)\n\n**Secure Services:**\n- **All standard services** plus:\n- **RabbitMQ**: Message broker with AMQP/MQTT/STOMP\n- **Mosquitto**: Dedicated MQTT broker\n- **ActiveMQ**: Enterprise STOMP messaging\n- **Redis**: Key registry and caching\n- **TLS Certificates**: Automatic certificate management\n\n### **\u2699\ufe0f Environment Variables**\n\n```bash\n# Core configuration\nOPENAI_API_KEY=your_key\nPRAVAL_LOG_LEVEL=INFO\n\n# Secure messaging\nPRAVAL_TRANSPORT_PROTOCOL=amqp\nPRAVAL_AMQP_URL=amqps://praval:secure_pass@rabbitmq:5671/praval\nPRAVAL_TLS_CA_CERT=/app/certs/ca_certificate.pem\n\n# Development\nJUPYTER_TOKEN=your_secure_token\n```\n\n### **\ud83d\udccb Health Monitoring**\n\nAll services include health checks and monitoring:\n\n```bash\n# Check service health\ndocker-compose ps\n\n# View logs\ndocker-compose logs praval-secure\ndocker-compose logs rabbitmq\n\n# Access management interfaces\n# RabbitMQ: http://localhost:15672 (admin/secure_praval_2024)\n# ActiveMQ: http://localhost:8161 (admin/secure_activemq_2024)\n```\n\n## \ud83d\udcde **Community & Support**\n\n### **\ud83d\udc65 Getting Help**\n- **\ud83d\udc1b GitHub Issues**: Report bugs and request features\n- **\ud83d\udcda Documentation**: Comprehensive guides in `/docs`  \n- **\ud83c\udfaf Examples**: Complete working applications in `/examples`\n- **\ud83e\udde0 Philosophy**: Deep dive into Praval principles in `praval.md`\n- **\ud83d\udcac Discussions**: Community Q&A and best practices\n\n### **\ud83c\udf86 Showcase Your Work**\n**Built something amazing with Praval?** We'd love to feature it!\n\n- **\ud83c\udfc6 Agent Showcases**: Highlight innovative agent architectures\n- **\ud83d\ude80 Success Stories**: Share your production implementations\n- **\ud83d\udcda Tutorial Contributions**: Help others learn Praval patterns\n- **\ud83c\udf86 Community Examples**: Expand the examples library\n\n### **\ud83d\udd70\ufe0f Quick Links**\n- **\ud83d\ude80 Get Started**: Follow the Quick Start guide above\n- **\ud83d\udcca See Results**: Run VentureLens for a complete demo\n- **\ud83e\udde0 Understand Philosophy**: Read `praval.md` for design principles\n- **\ud83d\udd27 Contribute**: Check development guidelines above\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A composable Python framework for LLM-based agents inspired by coral ecosystems",
    "version": "0.7.9",
    "project_urls": {
        "Bug Tracker": "https://github.com/aiexplorations/praval/issues",
        "Changelog": "https://github.com/aiexplorations/praval/blob/main/CHANGELOG.md",
        "Documentation": "https://github.com/aiexplorations/praval/tree/main/docs",
        "Homepage": "https://github.com/aiexplorations/praval",
        "Repository": "https://github.com/aiexplorations/praval"
    },
    "split_keywords": [
        "ai",
        " agents",
        " llm",
        " multi-agent",
        " framework",
        " openai",
        " anthropic",
        " cohere",
        " rag",
        " memory",
        " vector-database",
        " chromadb",
        " qdrant",
        " chatbot",
        " knowledge-graph",
        " semantic-search",
        " nlp"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "8e1d139cfcf1c404e50026829835858eb6a8c5f7c21b8eff05f8031d1f8290f0",
                "md5": "0dcdcbeb35fd7d01faa7f9cb32e22a62",
                "sha256": "2bc8436d298f328fa27419d1538eeb1f962f917e8747018522f2c3a570201ccc"
            },
            "downloads": -1,
            "filename": "praval-0.7.9-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0dcdcbeb35fd7d01faa7f9cb32e22a62",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 127391,
            "upload_time": "2025-10-24T07:29:00",
            "upload_time_iso_8601": "2025-10-24T07:29:00.436966Z",
            "url": "https://files.pythonhosted.org/packages/8e/1d/139cfcf1c404e50026829835858eb6a8c5f7c21b8eff05f8031d1f8290f0/praval-0.7.9-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-24 07:29:00",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "aiexplorations",
    "github_project": "praval",
    "github_not_found": true,
    "lcname": "praval"
}