To the infinity and beyond! 🚀

Fractal is a sophisticated CLI agent built with LangChain and LangGraph, providing comprehensive AI-driven assistance directly from your terminal. It features advanced RAG capabilities, multi-database support, intelligent memory management, and a beautiful interactive TUI.

• OpenAI GPT-4o - Advanced reasoning and code generation
• Anthropic Claude Opus - Excellent for complex analysis
• Google Gemini 2.0 Flash - Fast and efficient responses
• Runtime switching between providers with /llm command

• Hybrid Retrieval: Dense embeddings (Nomic) + Sparse BM25 + LLM reranking
• Real-time Codebase Indexing: Continuous delta re-indexing with change detection
• Background Re-embedding: Automatic updates every 10 minutes
• Smart Chunking: 800-character chunks with 150-character overlap for optimal code understanding

• Importance-based Storage: Automatic cleanup with 50KB default limit
• Context-aware Filtering: Smart message filtering for optimal performance
• Conversation History: Searchable memory with relevance scoring
• Automatic Summarization: Large tool results stored efficiently

• Multi-Database Support: PostgreSQL, MySQL, MongoDB
• Connection Management: Persistent connections with aliasing
• Full CRUD Operations: Query, insert, update, delete with async performance
• MCP Integration: Model Context Protocol for seamless database operations

• Streaming Responses: Real-time reasoning display with tool call transparency
• Command Completion: Intelligent autocomplete with suggestions
• Colored Output: Status indicators and syntax highlighting
• Configuration Management: Runtime settings adjustment

• Python 3.11+
• uv (recommended) or pip

# Clone the repository
git clone https://github.com/ReesavGupta/Fractal-CLI.git
cd Fractal-CLI

# Install dependencies with uv (recommended)
uv sync

# Or with pip
pip install -e .

Create a .env file in the project root:

# LLM API Keys
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
GEMINI_API_KEY=your_google_api_key

# Embedding API Keys (Required for RAG)
GOOGLE_EMBEDDING_API_KEY=your_google_api_key
NOMIC_EMBEDDING_API_KEY=your_nomic_api_key

# Vector Database (Required for RAG)
QDRANT_URL=your_qdrant_url
QDRANT_API_KEY=your_qdrant_api_key

# Start with interactive setup
python -m src.agent.main

# Start with specific LLM provider
python -m src.agent.main --llm openai
python -m src.agent.main --llm claude
python -m src.agent.main --llm gemini

# Enable verbose mode for debugging
python -m src.agent.main --verbose

# Show version
python -m src.agent.main --version

Once Fractal is running, use these commands:

# LLM Management
/llm openai          # Switch to OpenAI
/llm claude          # Switch to Claude
/llm gemini          # Switch to Gemini

# Database Operations
/dbtools             # Enable database tools
/dbconnect postgres postgresql://user:pass@localhost:5432/dbname prod
/dbconnect mysql mysql://user:pass@localhost:3306/dbname
/dbconnect mongodb mongodb://localhost:27017/mydb local
/dblist              # List saved connections
/dbdisconnect postgres prod

# Configuration
/config              # Show current settings
/verbose             # Toggle debug output
/apikey openai sk-... # Set API key
/embedkey google AI... # Set embedding key

# RAG Operations
/reembed             # Re-index codebase
/clear               # Clear screen
/help                # Show help
/quit                # Exit Fractal

Fractal/
├── src/
│   ├── agent/                    # Core agent implementation
│   │   ├── agent.py             # LangGraph-based CodingAgent
│   │   ├── main.py              # CLI entry point with async execution
│   │   ├── state.py             # Pydantic state management
│   │   ├── tools.py             # File system operations
│   │   ├── tui.py               # Interactive terminal interface
│   │   ├── utils.py             # Tool integration & coordination
│   │   ├── memory.py            # Conversation memory management
│   │   └── memory_filter.py     # Message filtering & optimization
│   ├── rag_service/             # Advanced RAG implementation
│   │   └── rag.py               # Hybrid retrieval with Qdrant + BM25
│   └── mcp/                     # Model Context Protocol
│       └── db_mcp.py            # Database operations (PostgreSQL, MySQL, MongoDB)
├── public/                      # Static assets
├── tests/                       # Test suite (structure ready)
├── pyproject.toml               # Dependencies & configuration
└── README.md                    # This file

• CodingAgent: LangGraph-based agent with tool binding and memory integration
• RAGService: Hybrid retrieval system with real-time indexing
• MemoryManager: Importance-based conversation memory with automatic cleanup
• DatabaseMCP: Multi-database support with connection management
• FractalAgent: Interactive TUI with streaming responses and command completion

• File System Tools: Complete CRUD operations, directory management, content editing
• RAG Tools: Semantic codebase search with hybrid retrieval and LLM reranking
• Memory Tools: Conversation history search with relevance scoring
• Database Tools: Full CRUD operations for PostgreSQL, MySQL, MongoDB
• Search Tools: Regex-based pattern matching and semantic code understanding

• Async Architecture: Full async/await support for optimal performance
• Memory Efficiency: Automatic cleanup with importance-based retention
• Background Processing: Non-blocking re-indexing and memory management
• Connection Pooling: Efficient database connection management
• Smart Caching: Optimized retrieval with hybrid search strategies

• Streaming Responses: Real-time reasoning display with tool call transparency
• Error Handling: Graceful degradation with comprehensive error messages
• Configuration Management: Runtime settings adjustment without restart
• Debug Mode: Verbose output for development and troubleshooting

• Hybrid RAG: Dense embeddings + Sparse BM25 + LLM reranking ✅
• Continuous Delta Re-indexing: Real-time codebase indexing ✅
• Multi-LLM Support: OpenAI, Claude, Gemini integration ✅
• Memory Management: Importance-based conversation memory ✅

• NoSQL Support: MongoDB integration ✅
• SQL Databases: MySQL, PostgreSQL support ✅
• MCP Integration: Model Context Protocol implementation ✅
• Direct Database Operations: Full CRUD with connection management ✅

• AWS MCP: Direct AWS resource management
• Vercel MCP: Deploy and manage Vercel projects
• Multi-Cloud Support: Unified interface for multiple cloud providers

• Plugin System: Extensible architecture for custom tools
• Workflow Automation: Complex multi-step task automation
• Team Collaboration: Shared workspaces and knowledge bases
• Advanced Analytics: Usage metrics and performance insights

• Python 3.11+ required
• uv (recommended) or pip for package management
• Qdrant vector database for RAG functionality
• API Keys for LLM providers and embedding services

langchain>=0.3.27          # Core AI framework
langgraph>=0.6.8           # Agent orchestration
fastembed>=0.7.3           # Embeddings
langchain-qdrant>=0.2.1    # Vector storage
asyncpg>=0.30.0            # PostgreSQL
aiomysql>=0.2.0            # MySQL
motor>=3.7.1               # MongoDB
prompt-toolkit>=3.0.52     # TUI
rank-bm25>=0.2.2           # Keyword search

# Run all tests (when implemented)
uv run pytest

# Run with coverage
uv run pytest --cov=src

# Format code
uv run black src/

# Lint code
uv run flake8 src/

# Type checking
uv run mypy src/

Current Version: 0.1.0
Development Status: Active development with core features complete
Architecture: Production-ready with comprehensive tool ecosystem
Testing: Basic structure in place, ready for test implementation

We welcome contributions! Please see our Contributing Guidelines for details.

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

• Testing: Implement comprehensive test suite
• Documentation: Improve examples and tutorials
• Cloud Integration: AWS, Vercel MCP implementations
• Plugin System: Extensible architecture development
• Performance: Optimization and benchmarking

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

• LangChain for the AI framework
• LangGraph for agent orchestration
• Prompt Toolkit for the TUI
• Qdrant for vector storage
• FastMCP for database integration

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

Fractal - To the infinity and beyond!

A sophisticated CLI agent demonstrating advanced AI engineering practices, modern Python development patterns, and thoughtful user experience design. Built with ❤️ for developers who want powerful AI assistance directly from their terminal.