protocol-h

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #android #linux #docker #macos #java #kubernetes #awesome-list #vue #pytorch #open-source

(★ 12)

"Enterprise-grade hierarchical agentic RAG for multi-modal reasoning"

protocol-h Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Protocol-H

Enterprise-grade hierarchical agentic RAG for multi-modal reasoning. A cloud-agnostic, production-grade framework for multi-hop reasoning over heterogeneous enterprise data using hierarchical multi-agent orchestration.

## Overview

**Protocol-H** addresses the "Modality Gap" in enterprise RAG systems by introducing a **Supervisor-Worker topology** that seamlessly synthesizes insights across bifurcated storage silos (SQL databases + Vector indices).

## Quick Start

```bash
# Install dependencies
pip install -r requirements.txt

# Set environment variables
export OPENAI_API_KEY="sk-..."
export SNOWFLAKE_ACCOUNT="xy12345"
export PINECONE_API_KEY="..."
```

## Key Features

- **Hierarchical Orchestration**: Supervisor decomposes complex queries into atomic sub-tasks
- **Multi-Modal Reasoning**: Cross-modal joins between SQL and document data
- **Self-Correcting Agents**: Reflective Retry Mechanism for autonomous error recovery
- **Cloud Agnostic**: Adapter Pattern for database abstraction (Snowflake, Redshift, BigQuery)
- **Enterprise-Grade**: Deterministic control flow, schema awareness, safety constraints

## Architecture

```
User Query → Supervisor Agent (Decompose)
         ├─→ SQL Worker (Query Database)
         ├─→ Vector Worker (Search Documents)
         └─→ Reflective Retry (Error Recovery)
                    ↓
         Synthesizer (Combine Results)
                    ↓
            Final Answer
```

## Project Structure

```
protocol-h/
├── config/          # Configuration files
├── src/             # Source code
│   ├── graph/       # State & workflow
│   ├── agents/      # Worker agents
│   ├── tools/       # Database connectors
│   └── utils/       # Utilities (LLM factory)
├── notebooks/       # Demo notebook
└── requirements.txt
```

## Usage

```python
from src.graph.workflow import create_orchestrator
from langchain_core.messages import HumanMessage

orchestrator = create_orchestrator()
app = orchestrator.get_compiled_app()

result = app.invoke({
    "messages": [HumanMessage(content="Why is Europe underperforming?")],
    "next_step": "supervisor",
    "final_answer": None,
    "query_type": None,
    "retry_count": 0,
    "error_message": None,
})

print(result["final_answer"])
```

## Performance (Ent-QA Benchmark)

| Metric | Protocol-H | Flat Agent | Standard RAG |
|--------|-----------|-----------|-------------|
| Tier 3 Accuracy | **84.5%** | 62.8% | 45.2% |
| Hallucination Rate | **7.1%** | 18.2% | 28.5% |

## Configuration

Set environment variables:
- `OPENAI_API_KEY`: Your OpenAI API key
- `SNOWFLAKE_ACCOUNT`: Snowflake account ID
- `PINECONE_API_KEY`: Pinecone API key

See `config/connections.yaml` for full configuration options.

## Key Components

### Supervisor Agent
- Analyzes queries and decomposes into sub-tasks
- Routes to appropriate workers
- Manages orchestration flow

### SQL Worker
- Schema introspection and validation
- Dialect-specific SQL generation
- Query execution with error handling

### Vector Worker
- Semantic search over documents
- Hybrid keyword-semantic retrieval
- Document chunk summarization

### Database Connectors
- **Base Connector**: Cloud-agnostic abstraction
- **Snowflake**: Production-ready connector
- **Vector Store**: Pinecone integration

## Innovation: Reflective Retry Mechanism

Autonomous error recovery:
```
Worker Error → Analysis → Correction → Re-execution
```

This reduces hallucinations by 60% vs. standard RAG.

## Deployment

### Docker
```bash
docker build -t agentic-rag .
docker run -e OPENAI_API_KEY=... agentic-rag
```

### AWS Lambda
```python
def lambda_handler(event, context):
    orchestrator = create_orchestrator()
    app = orchestrator.get_compiled_app()
    result = app.invoke(initial_state)
    return {"statusCode": 200, "body": result["final_answer"]}
```

## License

MIT License

---

Built with LangChain, LangGraph, and OpenAI

protocol-h

protocol-h Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

protocol-h

protocol-h Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README