A production-ready Retrieval-Augmented Generation (RAG) system implementing the Adaptive Cognitive Evolution (ACE) framework from the AlphaAgent research paper, with support for multiple LLM providers through a clean, SOLID-based interface architecture.

ACE RAG combines advanced language models with an innovative learning framework that continuously improves retrieval quality through:

• Generator: Creates diverse query trajectories using evolving strategies
• Reflector: Analyzes trajectory effectiveness and extracts insights
• Curator: Integrates insights into a versioned playbook through delta updates

The system supports multiple LLM providers through a clean, SOLID-based interface:

• Gemini: Google's state-of-the-art language models
• Claude: Anthropic's powerful reasoning models (ready for implementation)
• OpenAI: GPT models and embeddings (ready for implementation)
• Custom Providers: Easy to add new providers through interfaces

The system learns from every query, adapting its retrieval strategies to improve performance over time without manual tuning.

• ✅ Document Ingestion: Support for TXT, MD, and PDF formats
• ✅ Semantic Chunking: Intelligent text splitting with overlap
• ✅ Vector Storage: FAISS-based efficient similarity search
• ✅ Query Processing: Multi-trajectory retrieval with ACE framework
• ✅ Answer Generation: Context-aware responses using Gemini
• ✅ Continuous Learning: Automatic strategy evolution through insights

• ✅ Diverse Trajectories: Multiple retrieval strategies per query
• ✅ Quality Assessment: Automated trajectory scoring
• ✅ Insight Extraction: Pattern detection and strategy optimization
• ✅ Playbook Evolution: Delta-based strategy updates with versioning
• ✅ Strategy Pruning: Automatic removal of low-performing approaches

• ✅ Rate Limiting: Token bucket algorithm for API calls
• ✅ Circuit Breaker: Fault tolerance for service failures
• ✅ Retry Logic: Exponential backoff with configurable retries
• ✅ Type Safety: Full Pydantic model validation
• ✅ Logging: Comprehensive structured logging

• Python 3.9 or higher
• Google Gemini API key (Get one here)

1. Clone the repository:

git clone https://github.com/SourceShift/alphaagent-ace.git
cd alphaagent-ace

2. Create virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment:

cp .env.example .env
# Edit .env and add your Gemini API key

5. Install package (optional):

pip install -e .

from ace_rag import Config
from ace_rag.rag_engine import RAGEngine

# Initialize
config = Config.from_env()
rag = RAGEngine(config)
rag.initialize_default_strategies()

# Ingest documents
rag.ingest_text("""
Machine learning is a subset of artificial intelligence that enables
systems to learn and improve from experience without being explicitly
programmed.
""")

# Query without ACE (simple retrieval)
response = rag.query("What is machine learning?", enable_ace=False)
print(response.answer)

# Query with ACE (learning enabled)
response = rag.query("What is machine learning?", enable_ace=True)
print(f"Answer: {response.answer}")
print(f"Insights: {len(response.insights)}")
print(f"Quality: {response.metadata}")

Basic usage example:

python examples/basic_usage.py

ACE evolution demo:

python examples/ace_evolution_demo.py

┌─────────────────────────────────────────────────────────────┐
│                        RAG Engine                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   Document   │  │    Vector    │  │    Gemini    │       │
│  │  Processor   │→ │    Store     │  │    Client    │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │              ACE Framework                         │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐          │     │
│  │  │Generator │→ │Reflector │→ │ Curator  │          │     │
│  │  └──────────┘  └──────────┘  └──────────┘          │     │
│  │       ↓             ↓              ↓               │     │
│  │  ┌────────────────────────────────────┐            │     │
│  │  │         Playbook (Strategies)      │            │     │
│  │  └────────────────────────────────────┘            │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘

Query → Generator (3 trajectories) → Retrieval Results
                                          ↓
                                    Reflector
                                          ↓
                                    Insights
                                          ↓
                                     Curator
                                          ↓
                                Playbook Update (Δ)
                                          ↓
                              Improved Strategies

from ace_rag.config import Config, GeminiConfig, ACEConfig

config = Config(
    gemini=GeminiConfig(
        api_key="your-key",
        max_retries=5,
        timeout=60
    ),
    ace=ACEConfig(
        num_trajectories=5,
        insight_similarity_threshold=0.9
    )
)

rag = RAGEngine(config)

from pathlib import Path

# Ingest file
rag.ingest_document(Path("document.pdf"))

# Ingest text
rag.ingest_text("Your text here", doc_id="custom_id")

# Batch ingestion
for file in Path("docs/").glob("*.md"):
    rag.ingest_document(file)

# Enable ACE for learning
response = rag.query(
    "What are neural networks?",
    enable_ace=True
)

# Access trajectories
for traj in response.trajectories:
    print(f"Trajectory {traj.id}:")
    print(f"  Temperature: {traj.temperature}")
    print(f"  Quality: {traj.quality_score}")
    print(f"  Results: {len(traj.results)}")

# Access insights
for insight in response.insights:
    print(f"{insight.insight_type}: {insight.description}")

# View strategies
strategies = rag.playbook.get_all_strategies()
for s in strategies:
    print(f"{s.name}: success={s.success_rate:.3f}, uses={s.usage_count}")

# Get top performers
top = rag.playbook.get_top_strategies(5)

# Manual strategy addition
rag.playbook.add_strategy(
    name="Custom Strategy",
    description="My custom retrieval approach",
    parameters={
        "temperature": 0.4,
        "fusion_method": "weighted",
        "top_k": 7
    }
)

# Record usage
rag.playbook.record_usage(
    strategy_id="strategy_123",
    success=True,
    metrics={"latency": 0.5}
)

# Prune low performers
removed = rag.playbook.prune_strategies()

# System statistics
stats = rag.get_stats()
print(f"Total chunks: {stats['vector_store']['total_chunks']}")
print(f"Strategies: {stats['playbook']['total_strategies']}")
print(f"Avg success: {stats['playbook']['avg_success_rate']:.3f}")

# Vector store stats
vs_stats = rag.vector_store.get_stats()

# Playbook stats
pb_stats = rag.playbook.get_stats()

# Run all tests
pytest

# Run with coverage
pytest --cov=ace_rag --cov-report=html

# Run specific test file
pytest tests/test_models.py -v

Based on the ACE paper, typical improvements after 100 queries:

• Baseline RAG: 65% accuracy
• ACE RAG: 75-85% accuracy
• Improvement: 15-30% relative gain

• Without ACE: ~200-500ms per query
• With ACE (3 trajectories): ~800-1500ms per query
• Trade-off: Higher latency for better quality and continuous learning

• Memory: ~500MB base + ~100MB per 10K chunks
• Storage: ~1KB per chunk + playbook (~10MB max)
• API Calls: 1 embedding + 3 trajectory embeddings + 1 generation per query

1. API Key Error

ConfigurationException: Invalid Gemini API key

Solution: Ensure GEMINI_API_KEY is set in .env file

2. Rate Limit Exceeded

GeminiAPIException: Rate limit exceeded

Solution: Reduce GEMINI_RATE_LIMIT or add delays between queries

3. Vector Store Not Found

VectorStoreException: Index not found

Solution: Ingest documents before querying or load existing index

4. Out of Memory

MemoryError: Cannot allocate vector

Solution: Reduce CHUNK_SIZE or process documents in batches

import logging
logging.basicConfig(level=logging.DEBUG)

ace_rag_gemini/
├── ace_rag/                  # Main package
│   ├── __init__.py
│   ├── config.py            # Configuration management
│   ├── models.py            # Data models
│   ├── exceptions.py        # Custom exceptions
│   ├── gemini_client.py     # Gemini API client
│   ├── vector_store.py      # FAISS vector store
│   ├── document_processor.py # Document processing
│   ├── playbook.py          # Strategy storage
│   ├── ace_generator.py     # ACE Generator
│   ├── ace_reflector.py     # ACE Reflector
│   ├── ace_curator.py       # ACE Curator
│   └── rag_engine.py        # Main orchestrator
├── examples/                 # Example scripts
│   ├── basic_usage.py
│   └── ace_evolution_demo.py
├── tests/                    # Test suite
│   ├── test_models.py
│   └── test_config.py
├── requirements.txt          # Dependencies
├── setup.py                  # Package setup
├── .env.example             # Environment template
└── README.md                # Documentation

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

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

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Built with ❤️ by the SourceShift.io