<div align="center">

# 🤖 AgenticAI Framework

### *Enterprise-Grade Multi-Agent AI Orchestration Platform*

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://isathish.github.io/agenticaiframework/)
[![PyPI version](https://badge.fury.io/py/agenticaiframework.svg)](https://badge.fury.io/py/agenticaiframework)
[![Coverage](https://img.shields.io/badge/coverage-66%25-green.svg)](https://github.com/isathish/agenticaiframework)
[![Tests](https://img.shields.io/badge/tests-1036%20passing-success.svg)](https://github.com/isathish/agenticaiframework)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**The most comprehensive Python SDK for building production-ready AI agent systems with advanced orchestration, intelligent memory management, speech processing, state management, and enterprise-grade monitoring.**

[📚 Documentation](https://isathish.github.io/agenticaiframework/) • [🚀 Quick Start](#-quick-start) • [💡 Examples](#-examples) • [🤝 Contributing](#-contributing)

---

<img src="https://img.shields.io/badge/Features-50%2B%20Modules-blue?style=for-the-badge" alt="50+ Modules"/>
<img src="https://img.shields.io/badge/Tools-35%2B%20Built--in-green?style=for-the-badge" alt="35+ Tools"/>
<img src="https://img.shields.io/badge/Enterprise-21%20Features-purple?style=for-the-badge" alt="21 Enterprise Features"/>
<img src="https://img.shields.io/badge/Protocols-6%20Supported-orange?style=for-the-badge" alt="6 Protocols"/>

</div>

---

## 📋 Table of Contents

- [✨ Key Features](#-key-features)
- [🏗️ Architecture](#️-architecture)
- [📦 Installation](#-installation)
- [🚀 Quick Start](#-quick-start)
- [🧠 Core Modules](#-core-modules)
- [🔧 Advanced Features](#-advanced-features)
- [🏢 Enterprise Features](#-enterprise-features)
- [📊 Evaluation Framework](#-evaluation-framework)
- [🔄 Framework Comparison](#-framework-comparison)
- [📚 Documentation](#-documentation)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)

---

## ✨ Key Features

<table>
<tr>
<td width="50%">

### 🚀 **Production-First Design**
- Enterprise-grade reliability with **66% test coverage**
- **1036+ tests** ensuring stability
- Circuit breaker patterns & automatic retry
- Comprehensive error handling

### 🧩 **Modular Architecture**
- **50+ independently composable modules**
- Plug-and-play component system
- Clean separation of concerns
- Easy customization & extension

### 🧠 **Intelligent Memory**
- **7 specialized memory managers**
- Multi-tier storage with TTL
- Context compression & windowing
- Automatic memory consolidation

</td>
<td width="50%">

### 🎯 **Multi-Agent Orchestration**
- Team-based coordination
- Supervisor & peer patterns
- Task handoff & delegation
- Shared context management

### 🔊 **Speech Processing**
- STT/TTS integration
- Voice profile management
- Multi-language support
- Audio caching & optimization

### 📊 **12-Tier Evaluation**
- Model quality assessment
- RAG evaluation
- Security risk scoring
- Business outcome tracking

</td>
</tr>
</table>

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         AgenticAI Framework                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Agents    │  │  Workflows  │  │Orchestration│  │   Speech    │        │
│  │  • Context  │  │  • Steps    │  │  • Teams    │  │  • STT/TTS  │        │
│  │  • Memory   │  │  • Routing  │  │  • Handoffs │  │  • Profiles │        │
│  │  • Tools    │  │  • State    │  │  • Messages │  │  • Cache    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Memory    │  │    State    │  │Communication│  │  Knowledge  │        │
│  │ • Agent     │  │ • Agent     │  │ • HTTP/WS   │  │ • Retrieval │        │
│  │ • Workflow  │  │ • Workflow  │  │ • MQTT/SSE  │  │ • Embedding │        │
│  │ • Orch.     │  │ • Orch.     │  │ • gRPC      │  │ • RAG       │        │
│  │ • Knowledge │  │ • Tools     │  │ • STDIO     │  │ • Search    │        │
│  │ • Tools     │  │ • Speech    │  │ • Remote    │  │ • Indexing  │        │
│  │ • Speech    │  │ • Knowledge │  │   Agents    │  │             │        │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Guardrails │  │  Security   │  │  Evaluation │  │  Monitoring │        │
│  │ • Content   │  │ • Injection │  │ • 12-Tier   │  │ • Metrics   │        │
│  │ • Policy    │  │ • PII       │  │ • A/B Test  │  │ • Tracing   │        │
│  │ • Semantic  │  │ • Rate Lim  │  │ • Canary    │  │ • Events    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │    LLMs     │  │    Tools    │  │   Prompts   │  │ Compliance  │        │
│  │ • Routing   │  │ • 35+ Built │  │ • Versioning│  │ • Audit     │        │
│  │ • Caching   │  │ • Registry  │  │ • Templates │  │ • Masking   │        │
│  │ • Fallback  │  │ • MCP       │  │ • Security  │  │ • Policy    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 📦 Installation

### Quick Install

```bash
pip install agenticaiframework
```

### Development Install

```bash
git clone https://github.com/isathish/agenticaiframework.git
cd agenticaiframework
pip install -e ".[dev]"
```

### Optional Dependencies

```bash
# Full installation with all features
pip install "agenticaiframework[all]"

# Specific feature sets
pip install "agenticaiframework[monitoring]"  # Enhanced observability
pip install "agenticaiframework[memory]"      # Advanced memory features
pip install "agenticaiframework[speech]"      # Speech processing
pip install "agenticaiframework[docs]"        # Documentation building
```

---

## 🚀 Quick Start

### 1. Create an Agent

```python
from agenticaiframework import Agent, AgentManager

# Create a specialized agent
agent = Agent(
    name="ResearchAssistant",
    role="Research Specialist",
    capabilities=["web_search", "document_analysis", "summarization"],
    config={"model": "gpt-4", "temperature": 0.7}
)

# Start the agent
agent.start()
print(f"Agent {agent.name} is {agent.status}")
```

### 2. Multi-Agent Orchestration

```python
from agenticaiframework.orchestration import OrchestrationEngine, AgentTeam

# Create a team of agents
team = AgentTeam(
    name="ResearchTeam",
    agents=[researcher, analyst, writer],
    coordination_strategy="supervisor"
)

# Create orchestration engine
engine = OrchestrationEngine()
engine.register_team(team)

# Execute coordinated task
result = engine.execute_task(
    task="Research AI trends and write a comprehensive report",
    team_id="ResearchTeam"
)
```

### 3. Intelligent Memory Management

```python
from agenticaiframework.memory import (
    AgentMemoryManager,
    WorkflowMemoryManager,
    OrchestrationMemoryManager,
    KnowledgeMemoryManager,
    ToolMemoryManager,
    SpeechMemoryManager
)

# Agent-specific memory with 4 memory types
agent_memory = AgentMemoryManager("agent_001")
agent_memory.add_turn("user", "What's the weather like?")
agent_memory.add_turn("assistant", "It's sunny and 72°F.")
agent_memory.set_working("current_task", "weather_query", ttl_seconds=300)
agent_memory.learn_fact("User prefers Fahrenheit", "preference")
agent_memory.record_episode("weather_query", {"temp": 72}, "Successful query")

# Workflow memory with step tracking & checkpoints
workflow_memory = WorkflowMemoryManager()
ctx = workflow_memory.create_context("workflow_001", {"input": "data"})
workflow_memory.set_variable("workflow_001", "status", "processing")
workflow_memory.record_step_result("workflow_001", "step1", "Process", {"result": "ok"})
workflow_memory.create_checkpoint("workflow_001", "Before critical operation")

# Team shared memory with messaging
team_memory = OrchestrationMemoryManager()
team_memory.create_team_context("team_001", "Complete analysis task")
team_memory.send_message("agent_a", "agent_b", "Task completed", priority="high")
team_memory.record_contribution("team_001", "agent_a", {"output": "analysis"})

# Knowledge memory with embedding cache
knowledge_memory = KnowledgeMemoryManager()
knowledge_memory.cache_embedding("sample text", [0.1, 0.2, 0.3], "text-embedding-3")
knowledge_memory.cache_query_result("What is AI?", "kb_001", [{"doc": "AI is..."}], 5)

# Tool memory with result caching
tool_memory = ToolMemoryManager()
tool_memory.cache_result("calculator", {"x": 1, "y": 2}, {"sum": 3})
tool_memory.record_execution("calculator", {"x": 1}, {"sum": 3}, 50, True)

# Speech memory with voice profiles
speech_memory = SpeechMemoryManager()
speech_memory.store_transcription(audio_data, "Hello world", "en", 0.95)
speech_memory.store_synthesis("Hello world", audio_output, "voice_001", 120)
speech_memory.create_voice_profile("user_001", "User One", [0.1, 0.2], {"lang": "en"})
```

### 4. State Management

```python
from agenticaiframework.state import (
    AgentStateManager,
    WorkflowStateManager,
    OrchestrationStateManager,
    KnowledgeStateManager,
    ToolStateManager,
    SpeechStateManager
)

# Agent state with persistence & checkpoints
agent_state = AgentStateManager("agent_001", persist=True)
agent_state.transition("idle", "processing")
agent_state.update_context({"current_task": "analysis"})
agent_state.create_checkpoint("Before critical decision")

# Workflow state with step tracking
workflow_state = WorkflowStateManager("workflow_001")
workflow_state.set_current_step("data_processing")
workflow_state.record_step_completion("validation", {"passed": True})

# Orchestration state for team coordination
orch_state = OrchestrationStateManager("team_001")
orch_state.update_team_status("active")
orch_state.record_agent_contribution("agent_a", {"output": "analysis_result"})

# Knowledge state for index management
knowledge_state = KnowledgeStateManager("kb_001")
knowledge_state.set_index_status("ready")
knowledge_state.record_retrieval("query_001", ["doc1", "doc2"])

# Tool state with circuit breaker
tool_state = ToolStateManager("calculator")
tool_state.set_availability(True)
tool_state.record_execution(success=True, duration_ms=50)

# Speech state for session management
speech_state = SpeechStateManager("session_001")
speech_state.set_mode("listening")
speech_state.update_voice_context({"language": "en", "speaker": "user_001"})
```

### 5. Speech Processing

```python
from agenticaiframework.speech import SpeechProcessor

# Initialize speech processor
speech = SpeechProcessor(
    stt_provider="whisper",
    tts_provider="elevenlabs",
    default_language="en"
)

# Speech-to-Text
transcription = speech.transcribe(audio_data, language="en")
print(f"Transcribed: {transcription.text} (confidence: {transcription.confidence})")

# Text-to-Speech
audio = speech.synthesize("Hello, how can I help you today?", voice="professional")
speech.play(audio)

# Voice profile management
speech.register_voice("user_001", voice_sample, metadata={"language": "en"})
identified = speech.identify_speaker(audio_data)
```

### 6. Comprehensive Monitoring

```python
from agenticaiframework import MonitoringSystem

# Initialize monitoring
monitoring = MonitoringSystem()

# Record metrics
monitoring.record_metric("agent_response_time", 1.2)
monitoring.record_metric("agent_success_rate", 0.95)
monitoring.record_metric("memory_usage_mb", 128)

# Log events with context
monitoring.log_event("task_completed", {
    "task_name": "data_processing",
    "duration": 2.5,
    "status": "success"
})

# Distributed tracing
with monitoring.trace("process_request") as span:
    span.set_attribute("user_id", "user_001")
    # Your processing logic
    span.add_event("processing_complete")
```

---

## 🧠 Core Modules

### Memory Management (7 Specialized Managers)

| Manager | Purpose | Key Features |
|---------|---------|--------------|
| **MemoryManager** | Core multi-tier memory | Short/long-term, TTL, LRU eviction, consolidation |
| **AgentMemoryManager** | Agent-specific memory | Conversation, working, episodic, semantic memory |
| **WorkflowMemoryManager** | Workflow execution memory | Step results, context passing, checkpoints |
| **OrchestrationMemoryManager** | Multi-agent shared memory | Team context, messaging, task handoffs |
| **KnowledgeMemoryManager** | Knowledge base memory | Embedding cache, query results, retrieval history |
| **ToolMemoryManager** | Tool execution memory | Result caching, patterns, performance stats |
| **SpeechMemoryManager** | Speech processing memory | Transcription/synthesis history, voice profiles |

### State Management (7 State Managers)

| Manager | Purpose | Key Features |
|---------|---------|--------------|
| **StateManager** | Core state management | State transitions, history, persistence |
| **AgentStateManager** | Agent lifecycle state | Status, context, checkpoints, metrics |
| **WorkflowStateManager** | Workflow execution state | Step tracking, routing, error handling |
| **OrchestrationStateManager** | Team coordination state | Team status, agent states, coordination |
| **KnowledgeStateManager** | Knowledge base state | Index status, sync state, retrieval state |
| **ToolStateManager** | Tool execution state | Availability, execution, circuit breakers |
| **SpeechStateManager** | Speech processing state | Session, voice, processing state |

### Communication Protocols (6 Protocols)

| Protocol | Use Case | Features |
|----------|----------|----------|
| **HTTP** | REST APIs | Request/response, webhooks |
| **WebSocket** | Real-time | Bidirectional, low-latency |
| **SSE** | Event streaming | Server-push, one-way |
| **MQTT** | IoT/Messaging | Pub/sub, lightweight |
| **gRPC** | High-performance | Streaming, strong typing |
| **STDIO** | Local processes | MCP compatibility |

### Context Management

```python
from agenticaiframework.context import (
    ContextManager,
    ContextWindow,
    ContextCompressor
)

# Manage context windows
context = ContextManager(max_tokens=8000)
context.add_message("user", "Hello!")
context.add_message("assistant", "Hi there!")

# Automatic compression when needed
compressor = ContextCompressor(strategy="summarize")
compressed = compressor.compress(context.messages, target_tokens=4000)

# Sliding window management
window = ContextWindow(size=10, overlap=2)
window.add(message)
recent = window.get_recent(5)
```

---

## 🔧 Advanced Features

### Tools Framework (35+ Built-in Tools)

```python
from agenticaiframework.tools import (
    ToolRegistry,
    ToolExecutor,
    BaseTool,
    register_tool
)

# Register custom tool
@register_tool(category="analysis", version="1.0")
class DataAnalysisTool(BaseTool):
    name = "data_analysis"
    description = "Analyze data and generate insights"
    
    def execute(self, data: dict) -> dict:
        # Your analysis logic
        return {"insights": [...], "metrics": {...}}

# Use tool executor with caching
executor = ToolExecutor()
result = executor.execute("data_analysis", {"data": dataset})
```

**Tool Categories:**
| Category | Tools |
|----------|-------|
| **File & Document** | FileRead, FileWrite, PDF, DOCX, OCR, RAG Search |
| **Web Scraping** | Selenium, Firecrawl, BrightData, Oxylabs |
| **Database** | MySQL, PostgreSQL, Snowflake, MongoDB, Vector Search |
| **AI/ML** | DALL-E, Vision, Code Interpreter, LangChain, LlamaIndex |

### Guardrails & Safety

```python
from agenticaiframework.guardrails import GuardrailManager, ContentGuardrail

# Setup guardrails
guardrails = GuardrailManager()

# Add content filtering
guardrails.add(ContentGuardrail(
    blocked_topics=["violence", "hate_speech"],
    pii_detection=True,
    max_token_limit=4000
))

# Validate input/output
result = guardrails.validate(user_input)
if not result.passed:
    print(f"Blocked: {result.violations}")
```

### Human-in-the-Loop (HITL)

```python
from agenticaiframework.hitl import HITLManager

# Setup HITL manager
hitl = HITLManager(
    approval_required=["high_risk_actions"],
    timeout=300,  # 5 minutes
    escalation_policy="notify_admin"
)

# Request human approval
approval = await hitl.request_approval(
    action="delete_records",
    context={"count": 1000, "table": "users"},
    urgency="high"
)

if approval.granted:
    execute_action()
```

### Conversation Management

```python
from agenticaiframework.conversations import ConversationManager

# Manage multi-turn conversations
conversation = ConversationManager(
    session_id="session_001",
    max_turns=50,
    context_strategy="sliding_window"
)

# Add turns with metadata
conversation.add_turn(
    role="user",
    content="Analyze this data",
    metadata={"intent": "analysis", "entities": ["data"]}
)

# Get conversation summary
summary = conversation.summarize()
```

### Response Formatting

```python
from agenticaiframework.formatting import ResponseFormatter

# Format responses consistently
formatter = ResponseFormatter(
    style="professional",
    format="markdown",
    max_length=2000
)

# Format agent response
formatted = formatter.format(
    response=raw_response,
    include_sources=True,
    add_disclaimer=True
)
```

---

## 🏢 Enterprise Features

### 21 Enterprise-Grade Capabilities

<table>
<tr>
<td width="50%">

**Observability & Metrics**
- ✅ Distributed tracing with span hierarchy
- ✅ Latency percentiles (P50, P95, P99)
- ✅ Custom metrics & dashboards
- ✅ Event logging & alerting

**Security & Compliance**
- ✅ Prompt injection detection (15+ patterns)
- ✅ PII detection & masking
- ✅ Rate limiting & throttling
- ✅ Audit trails with hash chain integrity
- ✅ Policy enforcement

</td>
<td width="50%">

**Infrastructure**
- ✅ Multi-region deployment
- ✅ Tenant isolation
- ✅ Auto-scaling
- ✅ Serverless execution

**Integrations**
- ✅ ServiceNow (ITSM)
- ✅ GitHub/Azure DevOps
- ✅ Snowflake/Databricks
- ✅ Webhooks (in/out)

</td>
</tr>
</table>

### Compliance & Audit

```python
from agenticaiframework.compliance import (
    AuditLogger,
    PolicyEnforcer,
    DataMasker
)

# Audit logging with integrity
audit = AuditLogger(storage="database", integrity="hash_chain")
audit.log_action("data_access", user="admin", resource="customer_data")

# Policy enforcement
policy = PolicyEnforcer()
policy.add_rule("no_pii_in_logs", pattern=r"\b\d{3}-\d{2}-\d{4}\b")
policy.enforce(log_message)

# Data masking
masker = DataMasker(strategies=["pii", "credit_card", "email"])
masked = masker.mask("Contact: john@example.com, SSN: 123-45-6789")
# Output: "Contact: [EMAIL], SSN: [SSN]"
```

---

## 📊 Evaluation Framework

### 12-Tier Comprehensive Evaluation

```python
from agenticaiframework.evaluation import EvaluationSystem

# Initialize evaluation system
evaluator = EvaluationSystem()

# Run comprehensive evaluation
results = evaluator.evaluate(
    agent=my_agent,
    test_cases=test_suite,
    tiers=[
        "model_quality",      # Hallucination, reasoning, coherence
        "task_skill",         # Success rates, completion
        "tool_api",           # Tool usage, latency
        "workflow",           # Orchestration, handoffs
        "memory_context",     # Context quality, retrieval
        "rag",                # Faithfulness, groundedness
        "autonomy_planning",  # Plan optimality
        "performance",        # Latency P50/P95/P99
        "cost_finops",        # Token usage, cost
        "human_loop",         # Acceptance rates
        "business_outcomes",  # ROI, impact
        "security_risk"       # Risk scoring
    ]
)

# A/B Testing
from agenticaiframework.evaluation import ABTestFramework

ab_test = ABTestFramework()
experiment = ab_test.create_experiment(
    name="prompt_optimization",
    variants=["control", "variant_a", "variant_b"],
    metrics=["success_rate", "latency", "cost"]
)
ab_test.run(experiment, sample_size=1000)
results = ab_test.analyze(experiment)

# Canary Deployments
from agenticaiframework.evaluation import CanaryDeployment

canary = CanaryDeployment()
canary.deploy(
    new_version="v2.0",
    initial_traffic=5,
    increment=10,
    rollback_threshold={"error_rate": 0.05}
)
```

---

## 🔄 Framework Comparison

| Feature | AgenticAI | LangChain | CrewAI | AutoGen |
|:--------|:---------:|:---------:|:------:|:-------:|
| **Production Ready** | ✅ Enterprise | ⚠️ Experimental | ⚠️ Limited | ⚠️ Research |
| **Test Coverage** | ✅ 66% (1036 tests) | ⚠️ Variable | ❌ Limited | ⚠️ Basic |
| **Built-in Tools** | ✅ 35+ | ⚠️ Community | ❌ Limited | ⚠️ Basic |
| **Memory Managers** | ✅ 7 Specialized | ⚠️ 1 Basic | ❌ None | ⚠️ Simple |
| **State Managers** | ✅ 7 Specialized | ❌ None | ❌ None | ❌ None |
| **Speech Processing** | ✅ Full STT/TTS | ❌ None | ❌ None | ❌ None |
| **Communication Protocols** | ✅ 6 Protocols | ⚠️ HTTP only | ❌ None | ⚠️ Basic |
| **12-Tier Evaluation** | ✅ Built-in | ❌ None | ❌ None | ❌ None |
| **Multi-Agent Orchestration** | ✅ Advanced | ⚠️ Simple | ✅ Team-based | ✅ Group chat |
| **Enterprise Features** | ✅ 21 Features | ⚠️ Limited | ❌ None | ❌ None |
| **HITL Support** | ✅ Built-in | ⚠️ Manual | ❌ None | ⚠️ Basic |
| **Compliance/Audit** | ✅ Full | ❌ None | ❌ None | ❌ None |
| **Conversation Management** | ✅ Advanced | ⚠️ Basic | ❌ None | ⚠️ Basic |
| **Context Compression** | ✅ Built-in | ⚠️ Manual | ❌ None | ❌ None |

---

## 📚 Documentation

### 📖 Core Documentation
- **[Complete Documentation](https://isathish.github.io/agenticaiframework/)** - Full framework docs
- **[API Reference](https://isathish.github.io/agenticaiframework/API_REFERENCE/)** - Detailed API docs
- **[Quick Start Guide](https://isathish.github.io/agenticaiframework/quick-start/)** - Get started fast
- **[Best Practices](https://isathish.github.io/agenticaiframework/best-practices/)** - Production patterns

### 🎯 Module Guides

| Module | Description | Link |
|--------|-------------|------|
| Agents | Creating intelligent agents | [📚 Docs](https://isathish.github.io/agenticaiframework/agents/) |
| Memory | 7 specialized memory systems | [📚 Docs](https://isathish.github.io/agenticaiframework/memory/) |
| State | 7 state management systems | [📚 Docs](https://isathish.github.io/agenticaiframework/state/) |
| Orchestration | Multi-agent coordination | [📚 Docs](https://isathish.github.io/agenticaiframework/orchestration/) |
| Speech | STT/TTS processing | [📚 Docs](https://isathish.github.io/agenticaiframework/speech/) |
| Tools | 35+ built-in tools | [📚 Docs](https://isathish.github.io/agenticaiframework/tools/) |
| Evaluation | 12-tier assessment | [📚 Docs](https://isathish.github.io/agenticaiframework/evaluation/) |
| Guardrails | Safety & compliance | [📚 Docs](https://isathish.github.io/agenticaiframework/guardrails/) |
| Monitoring | Observability & tracing | [📚 Docs](https://isathish.github.io/agenticaiframework/monitoring/) |
| Communication | 6 protocol support | [📚 Docs](https://isathish.github.io/agenticaiframework/communication/) |
| HITL | Human-in-the-loop | [📚 Docs](https://isathish.github.io/agenticaiframework/hitl/) |
| Compliance | Audit & policy | [📚 Docs](https://isathish.github.io/agenticaiframework/compliance/) |

---

## 🧪 Testing

```bash
# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=agenticaiframework --cov-report=html

# Run specific test suites
pytest tests/unit/ -v                         # Unit tests
pytest tests/integration/ -v                  # Integration tests
pytest tests/test_memory_coverage.py -v       # Memory tests
pytest tests/test_all_evaluation_types.py -v  # Evaluation tests
```

### Test Coverage Summary

| Module | Coverage | Status |
|--------|----------|--------|
| Communication | 100% | 🟢 Excellent |
| Processes | 100% | 🟢 Excellent |
| Configurations | 100% | 🟢 Excellent |
| Evaluation (Basic) | 100% | 🟢 Excellent |
| Knowledge | 94% | 🟢 Excellent |
| Integrations | 95% | 🟢 Excellent |
| Monitoring | 86% | 🟢 Good |
| Hub | 85% | 🟢 Good |
| Agents | 83% | 🟢 Good |
| Memory | 82% | 🟢 Good |
| Evaluation (Advanced) | 81% | 🟢 Good |
| Tasks | 80% | 🟢 Good |
| MCP Tools | 79% | 🟡 Fair |
| Guardrails | 75% | 🟡 Fair |
| Security | 74% | 🟡 Fair |
| Prompts | 71% | 🟡 Fair |

---

## 🤝 Contributing

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.

```bash
# Setup development environment
git clone https://github.com/isathish/agenticaiframework.git
cd agenticaiframework
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Run tests before submitting
pytest tests/

# Build documentation locally
mkdocs serve
```

### Ways to Contribute

| Type | Description |
|------|-------------|
| 🐛 Bug Reports | [Report issues](https://github.com/isathish/agenticaiframework/issues) |
| ✨ Feature Requests | [Request features](https://github.com/isathish/agenticaiframework/issues/new) |
| 📝 Documentation | [Improve docs](https://github.com/isathish/agenticaiframework) |
| 💻 Code | [Submit PRs](https://github.com/isathish/agenticaiframework/pulls) |
| 💡 Examples | [Add examples](https://github.com/isathish/agenticaiframework/tree/main/examples) |

---

## 📅 Roadmap

| Quarter | Focus Areas |
|---------|-------------|
| **Q1 2026** | Enhanced multi-modal capabilities, advanced evaluation metrics |
| **Q2 2026** | Distributed agent coordination, multi-region deployment |
| **Q3 2026** | Advanced ML/AI integrations, self-healing capabilities |
| **Q4 2026** | Enterprise security enhancements, plugin marketplace |

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

<div align="center">

**Built with ❤️ by the AgenticAI Framework Team**

*Making AI agents accessible, reliable, and production-ready*

---

[![GitHub Stars](https://img.shields.io/github/stars/isathish/agenticaiframework?style=social)](https://github.com/isathish/agenticaiframework)
[![GitHub Forks](https://img.shields.io/github/forks/isathish/agenticaiframework?style=social)](https://github.com/isathish/agenticaiframework/fork)
[![Twitter Follow](https://img.shields.io/twitter/follow/agenticai?style=social)](https://twitter.com/agenticai)

**[⬆ Back to Top](#-agenticai-framework)**

</div>

---

<div align="center">
<sub>© 2026 AgenticAI Framework. All rights reserved.</sub>
<br>
<sub>
<a href="https://isathish.github.io/agenticaiframework/">Documentation</a> •
<a href="https://github.com/isathish/agenticaiframework">GitHub</a> •
<a href="https://pypi.org/project/agenticaiframework/">PyPI</a>
</sub>
</div>
