An intelligent repository analysis system that gives repositories the ability to understand and explain themselves.

RepoMind transforms static code repositories into queryable knowledge bases by combining GitHub API data with local LLM capabilities (Ollama) through a type-safe, spec-driven architecture.

• Type-Safe: Every API interaction validated against specifications
• Local-First: Uses Ollama for privacy-preserving LLM analysis
• Composable: Build complex analysis workflows from simple parts
• Scheme-Based: Leverages Guile Scheme for powerful metaprogramming
• Spec-Driven: Heavy focus on formal specifications and contracts

RepoMind follows an experiment-driven development approach where each capability is validated through systematic experiments before implementation.

graph TD
    %% Core Specifications & Contracts
    A[Spec System<br/>003] --> B[Unit Tests<br/>071]
    A --> C[Validation<br/>005]
    
    %% LLM Integration Core
    D[Ollama Integration<br/>001-002] --> E[Pipeline<br/>007]
    C --> E
    E --> F[Query Interface<br/>013]
    
    %% Integration & Testing
    B --> G[Integration Tests<br/>034]
    E --> G
    G --> H[Monitoring<br/>074]
    H --> I[Telemetry<br/>014]
    I --> J[Logging<br/>036]
    
    %% Storage & Data
    K[Caching<br/>010] --> L[Storage Layer<br/>026-030]
    E --> K
    L --> M[Analytics DB<br/>037]
    
    %% User Interfaces
    F --> N[CLI<br/>021]
    F --> O[Web API<br/>022]
    N --> P[Web UI<br/>023]
    O --> P
    
    %% Production Systems
    G --> Q[CI/CD<br/>033]
    H --> Q
    Q --> R[Deployment<br/>059-063]
    
    %% Security & Performance
    S[Security<br/>043] --> T[Performance<br/>044]
    R --> S
    T --> U[Enterprise<br/>045]
    
    %% Development Methodology
    B --> V[TDD/BDD<br/>070-071]
    V --> W[DDD/CQRS<br/>069,073]
    
    %% Visualization & Mapping (Future)
    X[Development Visualization<br/>TBD] -.-> A
    X -.-> E
    X -.-> G
    
    classDef core fill:#e1f5fe
    classDef test fill:#f3e5f5
    classDef integration fill:#e8f5e8
    classDef ui fill:#fff3e0
    classDef production fill:#fce4ec
    
    class A,C,D,E core
    class B,G,V,W test
    class H,I,J,M integration
    class F,N,O,P ui
    class Q,R,S,T,U production

Specification-Driven Core (Blue)

• Formal contracts and validation at every boundary
• Spec-to-code generation and bidirectional validation
• Type safety through systematic specification

Testing Foundation (Purple)

• Unit tests drive core module design
• Integration tests validate system behavior
• TDD/BDD methodology experiments

System Integration (Green)

• Monitoring and telemetry as first-class concerns
• Analytics and logging infrastructure
• Observability-driven development

User Experience (Orange)

• CLI and web interfaces built on solid foundation
• Query interface enabling natural language interaction
• Design systems for consistent experience

Production Systems (Pink)

• CI/CD and deployment automation
• Security and performance optimization
• Enterprise-grade capabilities

• Operating System: FreeBSD 14.3-RELEASE
• Language: GNU Guile 2.2.7
• LLM Runtime: Ollama 0.9.6
• OpenAPI: Version 3.1.0 (for API specifications)

• Databases: PostgreSQL 15+, SQLite 3.40+
• Containers: Docker 24+, Docker Compose
• Cloud Simulation: LocalStack
• Testing: Expect, QuickCheck for Scheme
• CI/CD: GitHub Actions
• Monitoring: OpenTelemetry, Prometheus

• Static Analysis:
  • guild compile with -W flags for warnings
  • Custom spec validation tools (to be developed)
• Testing: SRFI-64 test framework
• Documentation: Texinfo
• Package Management: Guix (optional)

• Contract System: Design by Contract patterns
• Spec Languages: S-expressions for DSLs
• Validation: JSON Schema validation
• API Specs: OpenAPI 3.1.0
• Type Systems: Gradual typing experiments

⚠️ Early Development - This project is in early experimental stages.

• 12 Working Experiments (009-020): Demonstrating error handling, caching, rate limiting, and other concepts
• Experiment Framework: Run with gmake -C experiments/XXX-name run
• Basic Documentation: Architecture and development philosophy documented

• Core Library: The src/ directory is empty - no production code exists yet
• Experiments 001-008: Core Ollama integration not implemented
• Tests: No actual test suite beyond experiment demos
• CLI/API: No user-facing interfaces
• Build System: Makefile targets incomplete

• ✅ Phase 1 experiments (009-020) have working demonstrations
• ⚠️ Core foundations (001-008) are scaffolded but not implemented
• ❌ No production-ready code or modules
• ❌ Integration between experiments not done

Each experiment follows: gmake -C experiments/XXX-name run

Benefits of this approach:

• Rapid prototyping - Test ideas quickly without full integration
• Risk reduction - Discover issues early in isolated contexts
• Knowledge capture - Document discoveries for future implementers
• Parallel development - Multiple agents can work on different experiments
• Incremental progress - Each experiment builds system understanding

# Clone the repository  
git clone https://github.com/aygp-dr/repomind.git
cd repomind

# Check dependencies
make validate-deps

# Run working experiments
gmake -C experiments/009-error-handling run
gmake -C experiments/010-caching-layer run
gmake -C experiments/011-rate-limiting run
gmake -C experiments/012-concurrent-requests run

# Run all phase 1 experiments (when ready)
make phase-1

GitHub API → Validation → Transformation → Ollama LLM → Validation → Output
     ↓            ↓             ↓              ↓            ↓          ↓
   [Spec]      [Spec]        [Spec]         [Spec]      [Spec]    [Spec]

repomind/
├── experiments/          # Incremental validation experiments
├── src/                 # Core library code (future)
├── specs/               # Formal specifications
├── tests/               # Test suites
├── docs/                # Documentation
└── tools/               # Development tools

This is an experimental project exploring spec-driven LLM integration. Contributions focusing on formal specifications, contract design, and type safety are especially welcome.

MIT