I2P Meta-Reasoning System

Strategic Technical Advisory for AI Agents - A comprehensive meta-reasoning system that transforms issue descriptions into structured strategic analysis for complex software development projects.

🎯 What is I2P?

I2P (Issue to Prompt) is an AI-powered meta-reasoning system designed to provide strategic technical advisory for complex software development projects. It analyzes issues across multiple dimensions and generates comprehensive strategic guidance with specific code navigation paths.

Key Capabilities

🏗️ System Boundary Analysis - Maps issue scope and dependencies across system components
🎯 Strategic Gap Analysis - Identifies what you have, what you need, and what's missing
🗺️ Code Navigation Index - Provides specific file references and implementation pathways
🔍 Multi-Language Vector Search - Searches across Rust, TypeScript, Solidity, and Documentation
📚 Knowledge Base Integration - Semantic search across organizational knowledge repositories
📋 PRD-Style Requirements - Structures complex issues into actionable requirements
🤖 Trained Query Generation - GEPA module learns to generate optimized search queries from training data
🔄 Continuous Model Training - Automated training pipeline with GitHub Actions integration

🚀 Quick Start

Prerequisites

Python 3.11+
uv (installed automatically if missing)
OpenRouter API Key (for LLM access)
Qdrant Vector Database (local or cloud)
Modal Account (for embedding services)

Installation

# Clone the repository
git clone [email protected]:ardaglobal/i2p.git
cd i2p

# Complete setup with virtual environment (uv-based)
make setup

# Or step-by-step:
make venv      # Create virtual environment
make install   # Install dependencies

# Set up environment variables
cp .env.example .env
# Edit .env with your API keys:
# OPENROUTER_API_KEY=your_openrouter_key
# QDRANT_URL=your_qdrant_url
# QDRANT_API_KEY=your_qdrant_key

# Activate virtual environment
source .venv/bin/activate

# Verify setup
make check-env

Basic Usage

# Ingest your codebase for vector search
make ingest

# (Optional) Train GEPA search query model
make train

# Analyze an issue
make i2p ISSUE='Implement privacy-preserving credit score verification using zero-knowledge proofs'

# Run demo with sample issues
make demo

# Check system health
make health

📁 Project Structure

i2p/
├── 📖 Makefile                  # Comprehensive command interface
├── 📝 CLAUDE.md                 # Development guidelines & best practices
├──
├── modules/                     # Core I2P processing modules
│   ├── cli/                     # Command-line interface
│   │   └── 🧠 i2p_cli.py        # Main CLI entry point
│   ├── core/                    # Core processing pipeline
│   │   ├── 🔄 pipeline.py       # Main processing pipeline orchestrator
│   │   ├── 🎯 classifier.py     # System boundary analysis
│   │   ├── 📊 analyzer.py       # Strategic gap analysis
│   │   ├── 📝 generator.py      # Code navigation & output generation
│   │   ├── ✅ validation.py     # Input validation & error handling
│   │   ├── 🔍 vector_search.py  # Vector similarity search
│   │   └── 🤖 gepa.py           # GEPA search query generation module
│   ├── training/                # Training & model optimization
│   │   ├── 🎓 train_gepa.py         # GEPA model training script
│   │   ├── 🤖 gepa_trainer.py       # DSPy BootstrapFewShot trainer
│   │   ├── 📊 dataset_generator.py  # Automated dataset generation
│   │   ├── 📁 dataset_manager.py    # Dataset loading & splitting
│   │   ├── 📈 dataset_statistics.py # Dataset analysis & metrics
│   │   ├── 🔧 dataset_loader.py     # Dataset I/O operations
│   │   └── 🖥️ generate_dataset_cli.py # CLI for dataset generation
│   └── ingest/                  # Ingestion & embedding services
│       ├── core/
│       │   ├── 🔄 pipeline.py        # Multi-language ingestion pipeline
│       │   ├── ⚙️ config.py          # Ingestion configuration
│       │   ├── 🔗 embedding_service.py # Embedding generation
│       │   └── 📦 batch_processor.py  # Batch processing
│       ├── parsers/
│       │   ├── 🦀 rust_parser.py         # Rust code parsing & analysis
│       │   ├── 📘 typescript_parser.py   # TypeScript code parsing
│       │   ├── ⚡ solidity_parser.py     # Solidity contract parsing
│       │   └── 📄 documentation_parser.py # Documentation extraction
│       ├── services/
│       │   ├── 🔗 vector_client.py       # Qdrant vector database client
│       │   ├── 🚀 tei_service.py         # TEI embedding service (Modal L4 GPU)
│       │   ├── 🤖 modal_client.py        # Modal service client
│       │   ├── 🔍 enhanced_ranking.py    # Advanced search ranking
│       │   └── ✅ quality_validator.py   # Code quality validation
│       └── deploy/
│           └── 🚀 modal_deploy.py    # Modal deployment orchestrator
│
└── repos/                       # Target codebases for analysis
    ├── arda-credit/             # Rust blockchain infrastructure
    ├── arda-platform/           # TypeScript monorepo (Platform, Credit App, IDR)
    ├── arda-knowledge-hub/      # Documentation and knowledge base (Obsidian vault)
    ├── aig/                     # Arda Investment Group markdown documentation
    ├── arda-chat-agent/         # JavaScript/TypeScript chat agent implementation
    └── ari-ui/                  # JavaScript/TypeScript chat bot implementation

🛠️ Available Commands

🏗️ Setup & Installation

make venv             # Create virtual environment using uv
make install          # Install Python dependencies (creates venv if needed)
make sync             # Sync dependencies with uv (faster than install)
make setup            # Complete system setup (venv + install + check environment)
make check-env        # Verify environment variables and credentials

🗄️ Vector Database & Ingestion

make ingest           # Full ingestion pipeline (Rust + TypeScript + Solidity + Documentation)
make ingest-warmup    # Warm up Modal embedding service before ingestion
make ingest-search QUERY='text'  # Test vector search functionality
make vector-status    # Check Qdrant collections and vector counts

🧠 I2P Meta-Reasoning

make i2p ISSUE='your issue description'    # Run I2P analysis
make demo             # Run demo with sample Arda Credit issues
make examples         # Generate example analyses for common issues

🚀 Modal & Embedding Services

make modal-deploy     # Deploy Qwen3-Embedding-8B service to Modal (L4 GPU)
make modal-health     # Check Modal embedding service health
make modal-monitor    # Monitor GPU distribution across containers

🤖 Training & Model Management

make train                    # Train GEPA search query model with DSPy optimization
make train-eval               # Evaluate trained model on test set
make generate-dataset         # Generate training dataset from codebase
make train-clean              # Clean training cache and artifacts

⚙️ System Management

make health           # System health check (pipeline + vector search)
make test             # Run all tests
make clean            # Clean up generated files and caches

💡 Example Analyses

Zero-Knowledge Proof Implementation

make i2p ISSUE='Implement privacy-preserving credit score verification using zero-knowledge proofs in the Arda Credit loan approval process'

Output includes:

System boundary analysis identifying affected components
Strategic gap analysis of current ZK infrastructure vs requirements
Specific file references for implementation (contracts/src/, program/src/main.rs)
Step-by-step implementation roadmap

API Error Handling

make i2p ISSUE='Implement comprehensive error handling for API timeouts in the Arda Credit authentication service'

Output includes:

Code navigation to auth handlers (api/src/authentication_handlers.rs:45)
Strategic analysis of current error handling vs robust patterns
Implementation suggestions with middleware integration

🏗️ Architecture

Processing Pipeline

graph LR
    A[Issue Input] --> B[Boundary Analysis]
    B --> C[Strategic Gap Analysis]
    C --> D[Vector Search]
    D --> E[Code Navigation Index]
    E --> F[Structured Output]

Components

🎯 Issue Classifier - Categorizes issues by type, complexity, and domain
📊 Strategic Analyzer - Performs gap analysis using "have/need/missing" framework
🤖 GEPA Module - Trained DSPy module for generating optimized search queries from issue analysis
🔍 Vector Search - Semantic search across ingested codebases
📝 Output Generator - Creates structured markdown with code references
🚀 Modal Embedding Service - High-performance embedding generation (L4 GPU)

Supported Languages & Content Types

🦀 Rust - Complete parsing including macros, traits, and async code
📘 TypeScript - React components, hooks, utilities, and type definitions
⚡ Solidity - Smart contracts, interfaces, and deployment scripts
📚 Documentation - Markdown files, knowledge bases (Obsidian), technical documentation

🔧 Configuration

Environment Variables

# Required
OPENROUTER_API_KEY=your_openrouter_api_key
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_qdrant_api_key

# Optional
MODAL_TOKEN_ID=your_modal_token_id
MODAL_TOKEN_SECRET=your_modal_token_secret

Model Configuration

The system uses OpenRouter for LLM access with optimized model selection:

Grok-4-Fast: Primary model (8192 tokens)
Claude-3.5: Alternative model (4096 tokens)
GPT-4: Fallback option (4096 tokens)

Vector Database

Code Collections: arda_code_rust, arda_code_typescript, arda_code_solidity
Documentation Collection: arda_documentation (for knowledge bases and technical docs)
Embedding Model: Qwen3-Embedding-8B (4096 dimensions)
Chunk Size: 500 tokens with 50 token overlap (code), 6k-12k chars (documentation)

🤖 GEPA Training System

What is GEPA?

GEPA (Query Generation and Exploration for Prompt Augmentation) is a trained DSPy module that generates optimized search queries from issue descriptions. It uses DSPy BootstrapFewShot optimization to learn patterns from training data and produces domain-specific, codebase-aware queries.

Training Process

# Generate training dataset from codebase (optional)
make generate-dataset NUM_EXAMPLES=50 OUTPUT=custom_dataset.json

# Train the GEPA model
make train

# Evaluate model performance
make train-eval

Training Features

📊 Semantic Similarity Metrics - Uses embedding-based cosine similarity for evaluation
🔄 Vector Search Integration - Enriches training with real codebase context during optimization
📈 BootstrapFewShot Optimization - Automatically generates few-shot examples from training data
🎯 Domain-Specific Queries - Learns to generate queries using actual type/struct/function names
💾 Model Persistence - Saves trained models to trained_model.json for reuse

Training Configuration

Model: OpenRouter API (Claude Sonnet 4.5, GPT-4o-mini, or Grok-4-fast)
Dataset: 93 examples (74 train / 9 val / 10 test) across backend and frontend domains
Metric: Semantic similarity using Qwen3-Embedding-8B (4096-dim cosine similarity)
Optimizer: DSPy BootstrapFewShot with 8-40 bootstrapped demos
Cache: Training results cached in .cache/training/ for faster iteration

Automated Training Pipeline

The system includes a GitHub Actions workflow (.github/workflows/gepa-training.yml) that:

Triggers weekly or after vector ingestion completes
Trains GEPA model with latest codebase context
Evaluates accuracy and commits improved models
Provides comprehensive training reports with metrics

🔍 Vector Search Features

Enhanced Ranking

Semantic similarity using cosine distance
File type relevance boosting
Recency scoring for recently modified files
Dependency graph awareness for related components

Quality Validation

Syntax verification for all ingested code
Content filtering removing comments and empty files
Deduplication preventing redundant vector storage
Error handling with graceful fallbacks

📊 Performance & Monitoring

System Health Checks

make health         # Pipeline status & vector search connectivity
make vector-status  # Detailed vector database metrics

Health Check Coverage:

Pipeline component initialization status
Vector search connectivity and basic query test
Component readiness verification

Note: Health checks verify system readiness but do not include end-to-end DSPy module testing or embedding service response time measurement.

Key Metrics

Vector Collections: ~50K+ code chunks + documentation across all collections
Search Latency: <200ms for semantic queries
Embedding Generation: ~45 embeddings/sec via Modal TEI (L4 GPU)
Pipeline Processing: Varies by model (2-10s for boundary analysis, 5-30s for gap analysis, 3-15s for navigation index)
GEPA Training: ~5-15 minutes on 93 examples with vector context enrichment
Documentation Chunks: Intelligent section grouping (6k-12k chars per chunk)

🎯 Use Cases

For Development Teams

Feature Planning - Strategic analysis of complex feature requirements
Technical Debt - Identification of gaps and missing components
Code Navigation - Quick discovery of relevant implementation files
Architecture Decisions - Boundary analysis for system design choices

For AI Agents

Context Enhancement - Rich markdown output optimized for agent consumption
Code Discovery - Specific file paths and line references for implementation
Strategic Guidance - Structured requirements and implementation pathways
Multi-Language Support - Comprehensive codebase understanding

🛡️ Security & Best Practices

Code Quality Guidelines

Files must be under 500 lines (strict enforcement)
Single responsibility principle for all classes
Comprehensive error handling and validation
Security-first approach with no exposed secrets

Development Standards

OOP-First Design - Every functionality in dedicated classes
Modular Architecture - Lego-like component composition
DSPy Integration - Optimized LLM interactions with structured signatures
Vector Search - Semantic code discovery across languages

Pipeline Behavior Notes

Validation Strategy

Output validation is skipped - The system relies on vector search quality assurance rather than strict output validation
Confidence scores are provided as metadata but don't block pipeline execution
This enables faster processing while maintaining quality through context-aware LLM reasoning

Cross-System Search Protection

Vector search includes cross-system contamination prevention
When analyzing I2P system issues, search is automatically scoped to I2P codebase only
Documentation search is excluded by default from code searches to prevent pattern contamination
Use search_with_documentation_priority() for architectural context when needed

Collection Strategy

Code Collections: arda_code_rust, arda_code_typescript, arda_code_solidity
Documentation Collection: arda_documentation (knowledge bases, technical docs, architectural overviews)
Default searches exclude documentation to focus on implementation patterns
Gap analysis uses documentation-priority search for existing system understanding
Knowledge base integration provides organizational context and research findings

🤝 Contributing

Follow the guidelines in CLAUDE.md
Ensure all files remain under 500 lines
Use single responsibility principle
Add comprehensive tests for new features
Maintain security best practices

📚 Documentation

docs/architecture/ARCHITECTURE.md - 🆕 Comprehensive architecture guide and navigation hub
docs/ - Complete technical documentation (architecture, modules, guides)
CLAUDE.md - Development guidelines and coding standards
Makefile - Complete command reference with examples
Module docstrings - Detailed API documentation for each component
Example outputs - Run make examples to generate analyses in examples/ directory (not checked into repo)

🔗 Related Projects

Arda Credit - Privacy-preserving credit infrastructure (Rust)
Arda Platform - Monorepo with Platform, Credit App, and IDR (TypeScript)
Arda Knowledge Hub - Organizational knowledge base and documentation (Markdown/Obsidian)
Modal Platform - Serverless GPU infrastructure for embeddings
Qdrant - Vector database for semantic search

📄 License

MIT License - see LICENSE file for details.

I2P Meta-Reasoning System - Transforming complex issues into strategic technical guidance with AI-powered analysis and code navigation.

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.github/workflows		.github/workflows
docs		docs
modules		modules
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Makefile		Makefile
README.md		README.md
requirements.txt		requirements.txt
trained_model.json		trained_model.json

ardaglobal/i2p

Folders and files

Latest commit

History

Repository files navigation