Metadata-Version: 2.4
Name: siare
Version: 1.0.0
Summary: Self-Improving Agentic RAG Engine - Evolve multi-agent RAG pipelines using Quality-Diversity optimization
Author-email: Daniel Bentes <daniel@synapti.ai>
Maintainer-email: Daniel Bentes <daniel@synapti.ai>
License-Expression: MIT
Project-URL: Homepage, https://siare.dev
Project-URL: Documentation, https://github.com/synaptiai/siare#readme
Project-URL: Repository, https://github.com/synaptiai/siare
Project-URL: Issues, https://github.com/synaptiai/siare/issues
Project-URL: Changelog, https://github.com/synaptiai/siare/blob/main/CHANGELOG.md
Keywords: rag,retrieval-augmented-generation,evolutionary-algorithms,quality-diversity,map-elites,llm,agents,multi-agent,prompt-optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: questionary>=2.0.0
Provides-Extra: llm
Requires-Dist: openai>=1.0.0; extra == "llm"
Requires-Dist: anthropic>=0.18.0; extra == "llm"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Provides-Extra: full
Requires-Dist: siare[embeddings,llm]; extra == "full"
Requires-Dist: scikit-learn>=1.3.0; extra == "full"
Provides-Extra: benchmarks
Requires-Dist: datasets>=2.14.0; extra == "benchmarks"
Requires-Dist: beir>=2.0.0; extra == "benchmarks"
Requires-Dist: plotly>=5.18.0; extra == "benchmarks"
Requires-Dist: matplotlib>=3.7.0; extra == "benchmarks"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pyright>=1.1.0; extra == "dev"
Dynamic: license-file

# SIARE - Self-Improving Agentic RAG Engine

[![PyPI version](https://badge.fury.io/py/siare.svg)](https://badge.fury.io/py/siare)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

**Stop tuning RAG pipelines. Let them evolve.**

SIARE is the first self-improving RAG engine that treats pipeline configuration as evolvable genetic material. Instead of manually tuning prompts, retrieval strategies, and agent topologies, SIARE uses **Quality-Diversity optimization** to automatically discover and maintain diverse high-performing multi-agent RAG strategies.

## The Problem

Building RAG systems today means endless iteration:
- Tweak prompts → benchmark → repeat
- Try different chunking strategies → benchmark → repeat
- Adjust retrieval parameters → benchmark → repeat
- Add more agents → debug interactions → repeat

This process is **expensive**, **brittle**, and **never-ending** as your data and requirements change.

## The Solution

SIARE treats your RAG pipeline as a **living system that evolves**:

1. **Define your goals** - accuracy, latency, cost, or custom metrics
2. **Let evolution work** - SIARE mutates prompts, tools, and even agent topology
3. **Get diverse solutions** - Quality-Diversity ensures you have multiple good options
4. **Adapt continuously** - As your data changes, your pipeline evolves

## Quick Start

```bash
pip install siare

# Initialize a new project
siare init

# Run evolution (10 generations)
siare evolve

# Query your evolved pipeline
siare run "How do I reset my password?"
```

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                      SIARE Evolution Loop                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
│  │  Execute │───▶│ Evaluate │───▶│ Diagnose │───▶│  Mutate  │  │
│  │   SOP    │    │  Metrics │    │ Weakness │    │   SOP    │  │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │
│       ▲                                                │         │
│       │                                                │         │
│       └────────────────────────────────────────────────┘         │
│                                                                  │
│  Mutation Types:                                                 │
│  • PROMPT_CHANGE  - Evolve prompts based on failure patterns    │
│  • PARAM_TWEAK    - Adjust model parameters (temp, tokens)      │
│  • ADD_ROLE       - Add new agents to the pipeline              │
│  • REMOVE_ROLE    - Simplify by removing agents                 │
│  • REWIRE_GRAPH   - Change how agents connect and communicate   │
│  • CROSSOVER      - Combine successful strategies               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Key Features

### 🧬 Topology Evolution
Unlike prompt-only optimizers, SIARE can evolve the **structure** of your pipeline - adding, removing, and rewiring agents to find optimal architectures.

### 🎯 Quality-Diversity Optimization
Using MAP-Elites, SIARE maintains a diverse population of high-performing solutions. You don't just get one answer - you get a range of options trading off different metrics.

### 🔌 Extensible Hooks
Enterprise features integrate cleanly via hooks without modifying core code:
- Audit logging
- Usage billing
- Approval gates
- Custom metrics

### 📊 Built-in Benchmarks
Evaluate your pipelines against standard datasets:
- HotpotQA (multi-hop reasoning)
- Natural Questions
- Custom evaluation suites

## Installation

```bash
# Core package
pip install siare

# With LLM providers
pip install siare[llm]

# With embeddings support
pip install siare[embeddings]

# Everything
pip install siare[full]
```

## Programmatic Usage

```python
from siare import ProcessConfig, Role, GraphEdge
from siare.services import DirectorService, ExecutionEngine, GenePool

# Define your pipeline
config = ProcessConfig(
    name="customer-support",
    version="1.0.0",
    roles=[
        Role(
            name="retriever",
            model="gpt-4o-mini",
            system_prompt="Find relevant documents...",
            tools=["vector_search"],
        ),
        Role(
            name="answerer",
            model="gpt-4o-mini",
            system_prompt="Answer based on retrieved context...",
        ),
    ],
    graph=[
        GraphEdge(source="retriever", target="answerer"),
    ],
)

# Run evolution
director = DirectorService(llm_provider)
gene_pool = GenePool()

for generation in range(10):
    # Execute and evaluate
    trace = await engine.execute(config, task)
    evaluation = await evaluator.evaluate(trace)

    # Diagnose and mutate
    diagnosis = await director.diagnose(evaluation)
    mutated = await director.mutate_sop(config, diagnosis)

    # Track in gene pool
    gene_pool.add(mutated, evaluation)

# Get best solution
best = gene_pool.get_pareto_frontier()[0]
```

## Why SIARE?

| Feature | SIARE | DSPy | AutoRAG | LangChain |
|---------|-------|------|---------|-----------|
| Prompt optimization | ✅ | ✅ | ✅ | ❌ |
| Parameter tuning | ✅ | ❌ | ✅ | ❌ |
| **Topology evolution** | ✅ | ❌ | ❌ | ❌ |
| **Quality-Diversity** | ✅ | ❌ | ❌ | ❌ |
| Multi-agent support | ✅ | Limited | ❌ | ✅ |
| Extensible hooks | ✅ | ❌ | ❌ | ✅ |

## Examples

- [Customer Support](examples/quickstart/) - Simple Q&A over documents
- [Clinical Trials](examples/clinical_trials/) - Complex multi-agent research assistant

## Documentation

- [Getting Started](docs/getting-started.md)
- [CLI Reference](docs/cli-reference.md)
- [Architecture](docs/architecture.md)
- [API Reference](docs/api-reference.md)

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

---

Built with ❤️ by [Synapti.ai](https://synapti.ai)
