claraity-code 0.11.0__tar.gz

claraity_code-0.11.0/PKG-INFO

@@ -0,0 +1,816 @@
+Metadata-Version: 2.4
+Name: claraity-code
+Version: 0.11.0
+Summary: ClarAIty Code - An AI-powered coding agent with TUI interface, tool execution, multi-layered memory, prompt caching, and intelligent context management
+Author: Vijay Jayanandan
+License: MIT
+Keywords: ai,coding-agent,llm,tui,context-management,prompt-caching,tool-use
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: transformers>=4.40.0
+Requires-Dist: sentence-transformers>=2.7.0
+Requires-Dist: chromadb>=0.4.24
+Requires-Dist: langchain>=0.2.0
+Requires-Dist: langchain-community>=0.2.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: tree-sitter>=0.21.0
+Requires-Dist: tree-sitter-languages>=1.10.2
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pydantic-settings>=2.2.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn>=0.29.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: aiofiles>=23.2.1
+Requires-Dist: redis>=5.0.0
+Requires-Dist: sqlalchemy>=2.0.30
+Requires-Dist: alembic>=1.13.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: jinja2>=3.1.4
+Requires-Dist: gitpython>=3.1.43
+Requires-Dist: watchdog>=4.0.0
+Requires-Dist: psutil>=5.9.8
+Requires-Dist: textual>=0.47.0
+Requires-Dist: structlog>=24.1.0
+Requires-Dist: openai>=1.12.0
+Requires-Dist: pyperclip>=1.8.0
+Requires-Dist: Pillow>=10.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
+Requires-Dist: black>=24.4.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+Requires-Dist: pre-commit>=3.7.0; extra == "dev"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.2.0; extra == "ollama"
+Provides-Extra: vllm
+Requires-Dist: vllm>=0.4.0; extra == "vllm"
+Provides-Extra: all
+Requires-Dist: ai-coding-agent[dev,ollama,vllm]; extra == "all"
+
+# AI Coding Agent
+
+An advanced AI coding agent optimized for small open-source LLMs, featuring state-of-the-art memory management, RAG-powered code understanding, and intelligent prompt engineering. Designed for organizations with strict data residency requirements that need self-hosted AI solutions.
+
+**🚀 GPU-Accelerated | 🔒 Privacy-First | 🎯 Production-Ready**
+
+## ✨ Key Features
+
+### Core Capabilities
+- **Intelligent Workflow Orchestration**: Plan-Execute-Verify system that automatically decides when to use structured workflows vs direct execution
+- **Multi-Layered Memory System**: Hierarchical memory architecture (working, episodic, semantic) to overcome context window limitations
+- **File-Based Hierarchical Memory**: Team-shareable, version-controlled memory system with 4-level hierarchy (enterprise → user → project → imports) for persistent coding standards and preferences
+- **RAG-Powered Code Understanding**: Hybrid search combining semantic and keyword-based retrieval with AST-based code parsing
+- **Advanced Context Management**: Dynamic context assembly with intelligent prioritization and compression
+- **Optimized Prompt Engineering**: Task-specific templates with few-shot examples and chain-of-thought reasoning
+- **Multi-LLM Backend Support**: Compatible with OpenAI, Alibaba Cloud, Ollama, and any OpenAI-compatible API
+- **Privacy-First Design**: Complete local execution option with zero external data transmission
+
+### Workflow Features (NEW!)
+- **Task Analysis**: Automatically classifies tasks (9 types, 5 complexity levels) and estimates resource requirements
+- **Intelligent Planning**: LLM-powered execution plan generation with dependency validation
+- **Step-by-Step Execution**: Direct tool execution with real-time progress tracking and error recovery
+- **Decision Logic**: Smart routing between workflow and direct execution based on task type and complexity
+- **User Approval Gates**: Interactive approval for high-risk operations with detailed risk assessment
+- **Progress Transparency**: Real-time callbacks showing what the agent is doing at each step
+
+### Advanced Features
+- **AST-Based Code Analysis**: Deep understanding of code structure using Tree-sitter parsers for 10+ languages
+- **Incremental Codebase Learning**: Progressive understanding without overwhelming small context windows
+- **Token Budget Management**: Dynamic allocation of context budget based on task requirements
+- **Session Persistence**: Save and restore conversation state across sessions
+- **Checkpoints for Long-Running Projects**: Create save points during multi-day development with full context preservation
+- **Tool Execution Engine**: Read, write, edit, search, and analyze code intelligently
+
+### Language Support
+- **Python** ✅ (fully tested)
+- **Java / Spring Boot** ✅ (parser verified)
+- **TypeScript / React / TSX** ✅ (parser verified)
+- Plus: JavaScript, Go, Rust, C/C++, C#, Ruby, PHP
+
+## 🏗️ Architecture
+
+The agent uses a sophisticated multi-component architecture:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Coding Agent                          │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
+│  │   Memory    │  │     RAG     │  │   Prompts   │    │
+│  │  Manager    │  │   System    │  │  Optimizer  │    │
+│  └─────────────┘  └─────────────┘  └─────────────┘    │
+│         │                │                 │            │
+│         └────────────────┴─────────────────┘            │
+│                          │                               │
+│                  ┌───────▼────────┐                     │
+│                  │  LLM Backend   │                     │
+│                  │ (Ollama/vLLM)  │                     │
+│                  └────────────────┘                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+**See [ARCHITECTURE.md](ARCHITECTURE.md)** for detailed system design.
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.10+ (3.11 recommended)
+- 8GB+ RAM (16GB+ recommended)
+- GPU optional but highly recommended (10-30x performance improvement)
+- Local LLM backend (Ollama recommended)
+
+### Installation
+
+1. **Clone the repository**
+```bash
+git clone https://github.com/vijayjayanandan/ai-coding-agent.git
+cd ai-coding-agent
+```
+
+2. **Create virtual environment**
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. **Install dependencies**
+```bash
+pip install -r requirements.txt
+```
+
+4. **Set up environment variables**
+```bash
+cp .env.example .env
+# Edit .env with your configuration
+```
+
+### Setting Up LLM Backend
+
+#### Option 1: Ollama (Recommended)
+```bash
+# Install Ollama from https://ollama.ai
+# Pull a code-optimized model
+ollama pull deepseek-coder:6.7b-instruct
+# Or try: codellama:7b-instruct, qwen2.5-coder:7b
+```
+
+#### Option 2: GPU-Accelerated with RunPod (Production)
+For 10-30x faster performance, deploy on RunPod with GPU:
+
+```bash
+# See RUNPOD_QUICKSTART.md for detailed setup
+# Quick summary:
+# 1. Create RunPod account + SSH key
+# 2. Deploy RTX 4090 pod (~$0.69/hour)
+# 3. Run automated setup script
+# 4. Get 1-3 second responses instead of 30-60 seconds!
+```
+
+**Performance Comparison:**
+- CPU (local): 30-60 seconds per query
+- GPU (RunPod RTX 4090): 1-5 seconds per query
+
+See [RUNPOD_QUICKSTART.md](RUNPOD_QUICKSTART.md) for step-by-step GPU deployment.
+
+### Usage
+
+#### Command Line Interface
+
+```bash
+# Interactive chat mode
+python -m src.cli chat
+
+# Execute a single task
+python -m src.cli task "Explain the memory system" --type explain
+
+# Index a codebase
+python -m src.cli index ./src
+
+# Run demo
+python demo.py
+
+# Run capability tests
+python test_agent_capabilities.py
+```
+
+**Memory Management Commands (in chat mode):**
+```bash
+# Show current file-based memories
+> memory
+
+# Initialize project memory template
+> memory-init
+
+# Quick add a memory (e.g., coding standard)
+> memory-add "Always use 2-space indentation"
+
+# Reload memories after editing the file
+> memory-reload
+```
+
+**File-Based Memory Hierarchy:**
+- **Enterprise** (`/etc/opencodeagent/memory.md` or `C:/ProgramData/opencodeagent/`): Organization-wide policies
+- **User** (`~/.opencodeagent/memory.md`): Personal preferences across all projects
+- **Project** (`./.opencodeagent/memory.md`): Project-specific standards (version controlled)
+- **Imports** (`@path/to/file.md`): Modular memory files with circular detection
+
+**Session Persistence Commands (in chat mode):**
+```bash
+# Save current session with metadata
+> session-save
+Session name: feature-auth
+Task description: Implementing JWT authentication
+Tags: feature,auth,backend
+
+# List all saved sessions
+> sessions
+╭─ Saved Sessions (5 total) ───────────────────────────╮
+│ ID       │ Name        │ Description    │ Msgs │ ... │
+├──────────┼─────────────┼────────────────┼──────┼─────┤
+│ abc12345 │ feature-auth│ JWT auth...    │ 42   │ 2h  │
+╰───────────────────────────────────────────────────────╯
+
+# Load a saved session (by ID, short ID, or name)
+> session-load abc12345
+✓ Session loaded! 42 messages restored
+
+# Show detailed session info
+> session-info feature-auth
+
+# Delete old sessions
+> session-delete old-test-session
+```
+
+**Session Persistence Features:**
+- **Complete State Preservation**: Saves all messages, task context, episodic memory, and file memories
+- **Fast Session Listing**: Instant listing even with 100+ sessions using manifest-based indexing
+- **Flexible Loading**: Load by full UUID, 8-char short ID, or human-readable name
+- **Tag-Based Organization**: Organize sessions with tags (e.g., `feature`, `bugfix`, `auth`)
+- **Interactive Prompts**: User-friendly CLI guides you through save process
+- **Safe Operations**: Confirmation prompts prevent accidental data loss
+
+**Common Use Cases:**
+- Pause work on a feature and resume later with full context
+- Save before switching between multiple projects
+- Archive completed sessions for future reference
+- Share session IDs with team members for collaboration
+- Organize work by tags (project, feature type, etc.)
+
+**Session Storage:**
+Sessions are stored in `.opencodeagent/sessions/` with the following structure:
+```
+.opencodeagent/
+  sessions/
+    manifest.json              # Fast index for listing
+    <uuid>/
+      metadata.json            # Session info (name, tags, timestamps)
+      working_memory.json      # All messages and context
+      episodic_memory.json     # Conversation history
+      task_context.json        # Current task details
+      file_memories.txt        # Loaded CLAUDE.md content
+```
+
+### Checkpoints for Long-Running Projects
+
+**Checkpoints** are work-in-progress snapshots designed for multi-day/multi-session development. Unlike session persistence (which saves complete conversations), checkpoints create save points you can return to later.
+
+**Think of it like save games:** Resume development exactly where you left off, with full context of architecture decisions, pending tasks, and conversation history.
+
+**CLI Commands (in chat mode):**
+```bash
+# Create a checkpoint during development
+> checkpoint-save
+Description: Backend API complete, frontend pending
+Phase: Phase 1 - API Development
+Pending tasks:
+  - Create React dashboard
+  - Add authentication UI
+  - Implement real-time updates
+✓ Checkpoint created: abc12345
+
+# List all checkpoints for current project
+> checkpoints
+╭─ Project Checkpoints (3 total) ──────────────────────╮
+│ ID       │ Description        │ Files │ Phase      │
+├──────────┼────────────────────┼───────┼────────────┤
+│ abc12345 │ Backend API comp...│ 12    │ Phase 1    │
+│ def67890 │ User auth added    │ 15    │ Phase 2    │
+╰───────────────────────────────────────────────────────╯
+
+# Restore from a checkpoint (rollback)
+> checkpoint-restore abc12345
+✓ Restored to: Backend API complete, frontend pending
+✓ Restored 24 messages, 8 tool calls
+✓ Working directory: ./my-project
+✓ Pending tasks: 3
+
+# Delete all checkpoints (WARNING: irreversible!)
+> checkpoint-clear-all
+⚠ Delete ALL checkpoints? (yes/no): yes
+✓ Deleted 3 checkpoint(s)
+```
+
+**Python API (for automation/testing):**
+```python
+from src.orchestration import AgentOrchestrator
+
+# Start a multi-session project
+orchestrator = AgentOrchestrator(
+    working_directory="./music-academy"
+)
+session = orchestrator.start_conversation(
+    task_description="Build online music learning academy"
+)
+
+# === Day 1: Build backend ===
+session.send_message("Create database models for User, Course, Lesson")
+session.send_message("Create FastAPI endpoints for course catalog")
+
+# Create checkpoint before ending day
+checkpoint_id = session.save_checkpoint(
+    description="Backend foundation complete",
+    phase="Phase 1 - Backend",
+    pending_tasks=[
+        "Create React frontend",
+        "Add authentication",
+        "Implement video player"
+    ]
+)
+print(f"Checkpoint saved: {checkpoint_id}")
+
+# End day 1
+orchestrator.end_conversation(session.conversation_id)
+
+# === Day 2: Resume work ===
+# Start fresh session (simulates new day/terminal)
+new_session = orchestrator.start_conversation(
+    task_description="Continue music academy"
+)
+
+# Restore checkpoint
+new_session.restore_checkpoint(checkpoint_id)
+# Agent now has full context from day 1!
+
+# Continue building
+new_session.send_message("Create the React student dashboard")
+```
+
+**Checkpoint Features:**
+- **Full Context Preservation**: Saves conversation history, files created, tool calls, and pending tasks
+- **Cross-Session Resume**: Start new terminal/session and pick up exactly where you left off
+- **Architecture Memory**: Agent remembers database schemas, API endpoints, and design decisions
+- **Pending Task Tracking**: Checkpoint stores what's left to do (frontend, tests, deployment, etc.)
+- **Project-Scoped**: Checkpoints stored in `.checkpoints/` directory within project workspace
+- **Automatic Cleanup**: Configure `max_checkpoints` to auto-delete old checkpoints
+
+**Common Use Cases:**
+- **Multi-day development**: Build complex apps over several days with full context
+- **Experiment safety**: Create checkpoint before trying risky changes, restore if needed
+- **Team handoffs**: Share checkpoint ID so teammates can resume your work
+- **Milestone tracking**: Save checkpoints after completing each project phase
+- **Testing/QA**: Restore to specific states for bug reproduction
+
+**Checkpoint vs Session Persistence:**
+| Feature | Checkpoints | Session Persistence |
+|---------|-------------|---------------------|
+| **Purpose** | Work-in-progress snapshots | Complete conversation archives |
+| **Scope** | Project-specific | Global across all projects |
+| **Use Case** | Resume multi-day development | Pause/resume conversations |
+| **Storage** | `.checkpoints/` in project | `.opencodeagent/sessions/` |
+| **Restore Behavior** | Rolls back to checkpoint state | Loads full conversation |
+| **Pending Tasks** | Yes, explicitly tracked | No, use tags instead |
+
+**Checkpoint Storage:**
+Checkpoints are stored in your project's `.checkpoints/` directory:
+```
+my-project/
+  .checkpoints/
+    checkpoint_abc12345.json   # Includes working memory, tool history, pending tasks
+    checkpoint_def67890.json
+```
+
+Each checkpoint contains:
+- **Conversation history**: All messages exchanged with agent
+- **Tool execution history**: Files created/modified, commands run
+- **Task context**: Current phase, pending tasks, file count
+- **Metadata**: Timestamp, description, working directory
+
+#### Python API
+
+**Basic Usage:**
+```python
+from src.core import CodingAgent
+
+# Initialize agent with OpenAI-compatible API (Alibaba Cloud example)
+agent = CodingAgent(
+    backend="openai",
+    model_name="qwen3-coder-plus",
+    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
+    api_key_env="DASHSCOPE_API_KEY",
+    context_window=32768,
+)
+
+# Or use local Ollama for complete data residency
+agent = CodingAgent(
+    backend="ollama",
+    model_name="deepseek-coder:6.7b-instruct",
+    context_window=16384,
+)
+
+# Index your codebase
+stats = agent.index_codebase(directory="./src")
+print(f"Indexed {stats['total_files']} files")
+
+# Execute a task - agent automatically decides workflow vs direct
+response = agent.execute_task(
+    task_description="Explain how the RAG system works",
+    task_type="explain",
+    use_rag=True,
+)
+print(response.content)
+
+# Interactive chat
+response = agent.chat("What is the MemoryManager class?")
+print(response)
+```
+
+**Workflow Features (Advanced):**
+```python
+# Implementation tasks automatically use workflow (analyze → plan → execute)
+response = agent.execute_task(
+    task_description="Add a new tool for running shell commands",
+    task_type="implement",
+)
+# Output:
+# 📊 TASK ANALYSIS
+# Task Type: feature
+# Complexity: MODERATE
+# Risk Level: MEDIUM
+# ... (detailed analysis)
+#
+# 📋 EXECUTION PLAN
+# Step 1: Read existing tool implementations
+# Step 2: Design new RunCommandTool class
+# Step 3: Implement the tool
+# ...
+#
+# ▶️  Step 1: starting...
+# ✅ Step 1: completed
+# ... (real-time progress)
+
+# Explanation queries use fast direct execution
+response = agent.execute_task(
+    task_description="How does the workflow system work?",
+    task_type="explain",
+)
+# → Fast response, no planning overhead
+
+# Force specific execution mode if needed
+response = agent.execute_task(
+    task_description="Some task",
+    force_workflow=True,  # Always use workflow
+    # force_direct=True,   # Always use direct
+)
+
+# Check execution mode in response metadata
+print(response.metadata["execution_mode"])  # "workflow" or "direct"
+```
+
+**Session Persistence (Python API):**
+```python
+# Interactive work session
+agent.chat("Implement JWT authentication")
+agent.chat("Add login endpoint")
+agent.chat("Add password hashing")
+
+# Save session with metadata
+session_id = agent.memory.save_session(
+    session_name="jwt-auth-feature",
+    task_description="Implementing JWT authentication for REST API",
+    tags=["feature", "auth", "backend"],
+)
+print(f"Session saved: {session_id[:8]}")  # abc12345
+
+# Later - create new agent and load session
+new_agent = CodingAgent(backend="openai", model_name="qwen3-coder-plus")
+new_agent.memory.load_session("abc12345")  # Load by short ID
+# Or: new_agent.memory.load_session("jwt-auth-feature")  # Load by name
+
+# Continue from where you left off with full context
+new_agent.chat("Now add token refresh logic")
+
+# List all saved sessions programmatically
+from src.core.session_manager import SessionManager
+session_mgr = SessionManager()
+sessions = session_mgr.list_sessions()
+for session in sessions:
+    print(f"{session.short_id}: {session.name} ({session.message_count} messages)")
+
+# Filter sessions by tags
+auth_sessions = session_mgr.list_sessions(tags=["auth"])
+
+# Get detailed session info
+metadata = session_mgr.get_session_metadata("abc12345")
+print(f"Created: {metadata.created_at}")
+print(f"Duration: {metadata.duration_minutes} minutes")
+print(f"Tags: {', '.join(metadata.tags)}")
+
+# Delete old sessions
+session_mgr.delete_session("old-test-id")
+```
+
+## 📊 Performance & Testing
+
+### Verified Capabilities ✅
+- **RAG System**: 242 intelligent chunks from 28 files with AST-based parsing
+- **Memory Management**: Multi-turn conversations with full context retention
+- **Code Understanding**: Deep comprehension of complex architectures
+- **Fast Inference**: 1-5 second responses with GPU acceleration
+
+### Test Results (RunPod RTX 4090)
+```
+Response Times:
+├─ Simple Query: 1.5s
+├─ Code Generation: 1.5s
+├─ Complex Explanation: 3-5s
+└─ RAG Retrieval + Response: 4-6s
+
+GPU Utilization:
+├─ GPU Usage: 96% during inference
+├─ Memory Bandwidth: 88%
+└─ VRAM: 6.5GB / 24GB
+```
+
+**See [RUNPOD_TEST_RESULTS.md](RUNPOD_TEST_RESULTS.md)** for complete test report.
+
+## 📁 Project Structure
+
+```
+ai-coding-agent/
+├── src/
+│   ├── core/              # Agent orchestration & context building
+│   ├── memory/            # Hierarchical memory system
+│   ├── rag/               # RAG system with AST parsing
+│   ├── prompts/           # Prompt templates & optimization
+│   ├── llm/               # LLM backend integrations
+│   ├── tools/             # Tool execution engine
+│   └── cli.py             # Command-line interface
+├── demo.py                # Demo script
+├── test_agent_capabilities.py  # Comprehensive tests
+├── requirements.txt       # Python dependencies
+└── Documentation/
+    ├── ARCHITECTURE.md    # System design
+    ├── GETTING_STARTED.md # Detailed setup guide
+    ├── RUNPOD_QUICKSTART.md  # GPU deployment
+    └── RUNPOD_TEST_RESULTS.md # Test results
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+```bash
+# LLM Backend
+OLLAMA_URL=http://localhost:11434
+MODEL_NAME=deepseek-coder:6.7b-instruct
+
+# Memory Configuration
+MAX_WORKING_MEMORY_TOKENS=2048
+MAX_EPISODIC_MEMORY_TOKENS=10240
+
+# RAG Configuration
+EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
+CHUNK_SIZE=512
+CHUNK_OVERLAP=50
+```
+
+### Supported Models
+- **DeepSeek Coder** (6.7B, 33B) - Excellent for code understanding
+- **CodeLlama** (7B, 13B, 34B) - General code generation
+- **Qwen2.5-Coder** (7B, 14B, 32B) - Strong code intelligence
+- **StarCoder2** (7B, 15B) - Code-specific training
+- Any Ollama-compatible model
+
+## 🎯 Use Cases
+
+### Validated Use Cases
+1. **Intelligent Code Implementation**: Plan-execute-verify workflow for feature development
+2. **Code Explanation**: Understand complex architectures and patterns
+3. **Bug Fixing**: Systematic debugging with step-by-step execution
+4. **Code Refactoring**: Safe refactoring with dependency analysis
+5. **Code Search**: Find relevant code using natural language queries
+6. **Conversational Coding**: Multi-turn context-aware dialogue
+7. **Knowledge Retrieval**: RAG-powered code knowledge base
+
+### Example Workflows
+
+**Scenario 1: Feature Implementation (Uses Workflow)**
+```
+User: "Add a new tool for listing directories"
+
+Agent:
+1. 📊 Analyzes: feature, moderate complexity, 3 files, 5 iterations
+2. 📋 Creates Plan:
+   - Read existing tools
+   - Design new tool class
+   - Implement with error handling
+   - Write tests
+   - Integrate with agent
+3. ⚙️  Executes: Step-by-step with real-time progress
+4. ✅ Verifies: All steps completed successfully
+```
+
+**Scenario 2: Code Explanation (Uses Direct)**
+```
+User: "Explain how the memory system works"
+
+Agent:
+→ Fast direct execution (2-5 seconds)
+→ Uses RAG to retrieve relevant code
+→ Provides detailed explanation
+```
+
+**Scenario 3: Complex Refactoring (Uses Workflow + Approval)**
+```
+User: "Refactor the entire memory system to use Redis"
+
+Agent:
+1. 📊 Analyzes: refactor, very complex, HIGH RISK
+2. 📋 Creates Plan: 12 steps with rollback strategy
+3. ⏸️  Asks for Approval: Shows risk assessment
+4. ⚙️  Executes: Only after user confirmation
+```
+
+### Ideal For
+- Organizations with data residency requirements
+- Teams needing self-hosted AI solutions
+- Privacy-sensitive development environments
+- Regulated industries (finance, healthcare, government)
+- Developers who want transparent, explainable AI assistance
+
+## 🛠️ Development
+
+### Running Tests
+```bash
+# Install dev dependencies
+pip install -r requirements-dev.txt
+
+# Run comprehensive tests
+python test_agent_capabilities.py
+
+# Run demo
+python demo.py
+```
+
+### Key Dependencies
+- `transformers>=4.40.0` - HuggingFace models
+- `sentence-transformers>=2.7.0` - Embeddings
+- `chromadb>=0.4.24` - Vector database
+- `tree-sitter==0.21.3` - AST parsing (specific version required)
+- `tree-sitter-languages>=1.10.2` - Language parsers
+- `pysqlite3-binary` - SQLite upgrade for ChromaDB
+- `rich>=13.7.0` - Beautiful CLI output
+
+## 🤝 Contributing
+
+Contributions are welcome! Areas for improvement:
+- Additional language parsers (JSX, Vue, etc.)
+- More LLM backend integrations
+- Enhanced tool system
+- Web UI (FastAPI + React)
+- Multi-agent coordination
+
+## 📄 License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+Built with:
+- [Ollama](https://ollama.ai/) - Local LLM runtime
+- [ChromaDB](https://www.trychroma.com/) - Vector database
+- [Tree-sitter](https://tree-sitter.github.io/) - AST parsing
+- [Sentence Transformers](https://www.sbert.net/) - Embeddings
+- [Rich](https://rich.readthedocs.io/) - Beautiful terminal output
+
+## 📚 Documentation
+
+### 🌟 Start Here (For Developers & AI Assistants)
+
+**Essential Reading:**
+1. **[CODEBASE_CONTEXT.md](CODEBASE_CONTEXT.md)** ⭐ - **Master project documentation**
+   - Complete codebase overview (85+ files)
+   - Architecture decisions and rationale
+   - File-by-file breakdown with purpose and key concepts
+   - Common development patterns
+   - Known issues and technical debt
+   - **Purpose:** Get full project context in < 2 minutes
+
+2. **[README.md](README.md)** (this file) - User-facing documentation
+   - Quick start guide
+   - Usage examples
+   - Feature overview
+
+3. **[CLAUDE.md](CLAUDE.md)** - Session handoff for AI assistants
+   - Current task status
+   - Recent changes (last session only)
+   - Immediate next steps
+   - **Purpose:** Quick session continuation
+
+### Core System Documentation
+
+**Setup & Deployment:**
+- [GETTING_STARTED.md](GETTING_STARTED.md) - Detailed setup guide
+- [RUNPOD_QUICKSTART.md](RUNPOD_QUICKSTART.md) - GPU deployment (5 minutes)
+- [RUNPOD_DEPLOYMENT.md](RUNPOD_DEPLOYMENT.md) - Comprehensive GPU guide
+- [RUNPOD_TEST_RESULTS.md](RUNPOD_TEST_RESULTS.md) - Performance benchmarks
+
+**Architecture & Design:**
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Original system design
+- [WORKFLOW_ARCHITECTURE.md](WORKFLOW_ARCHITECTURE.md) - Workflow system design (1,100+ lines)
+
+### Workflow System Implementation (Week 1-2)
+
+**Summaries:**
+- [WORKFLOW_WEEK1_COMPLETE.md](WORKFLOW_WEEK1_COMPLETE.md) - Week 1 complete (400 lines)
+- [WORKFLOW_WEEK2_DAY1_COMPLETE.md](WORKFLOW_WEEK2_DAY1_COMPLETE.md) - Bug fixes (29/29 tests passing!)
+
+**Daily Implementation Details:**
+- [WORKFLOW_DAY1_COMPLETE.md](WORKFLOW_DAY1_COMPLETE.md) - TaskAnalyzer implementation
+- [WORKFLOW_DAY3-4_COMPLETE.md](WORKFLOW_DAY3-4_COMPLETE.md) - TaskPlanner implementation
+- [WORKFLOW_DAY5_COMPLETE.md](WORKFLOW_DAY5_COMPLETE.md) - ExecutionEngine implementation
+- [WORKFLOW_DAY6_COMPLETE.md](WORKFLOW_DAY6_COMPLETE.md) - Integration with CodingAgent
+
+### Documentation Navigation Guide
+
+**I'm a new developer, where do I start?**
+→ Read [CODEBASE_CONTEXT.md](CODEBASE_CONTEXT.md) for complete project understanding, then [GETTING_STARTED.md](GETTING_STARTED.md) for setup
+
+**I'm an AI assistant joining a session:**
+→ Read [CODEBASE_CONTEXT.md](CODEBASE_CONTEXT.md) first (< 2 min), then [CLAUDE.md](CLAUDE.md) for current status
+
+**I want to understand the workflow system:**
+→ [WORKFLOW_ARCHITECTURE.md](WORKFLOW_ARCHITECTURE.md) for design, [WORKFLOW_WEEK1_COMPLETE.md](WORKFLOW_WEEK1_COMPLETE.md) for implementation summary
+
+**I need to deploy on GPU:**
+→ [RUNPOD_QUICKSTART.md](RUNPOD_QUICKSTART.md) for fast setup
+
+**I want to understand a specific file:**
+→ [CODEBASE_CONTEXT.md](CODEBASE_CONTEXT.md) has file-by-file breakdown with purpose and key concepts
+
+## 🚀 What's Next?
+
+**Workflow System - Week 1 Complete (✅ DONE):**
+- [x] Intelligent workflow orchestration (2,000+ lines)
+- [x] Task analysis and planning system
+- [x] Step-by-step execution engine
+- [x] Comprehensive testing (75+ tests)
+
+**Workflow System - Week 2 Days 1-7 Complete (✅ DONE):**
+- [x] Fixed callback signature mismatch (4 tests)
+- [x] Fixed response generation data type issues
+- [x] Fixed WorkingMemory len() access (2 tests)
+- [x] All 29 integration tests passing ✅
+- [x] Essential tools integrated (10 production tools)
+- [x] Three-tier verification layer (always works, tool-enhanced, git-based)
+- [x] E2E testing (8 comprehensive scenarios, 143/143 tests passing)
+
+**Claude Code Integration - Phase 1 (In Progress):**
+- [x] **File-Based Hierarchical Memory** (✅ COMPLETE)
+  - 4-level hierarchy (enterprise → user → project → imports)
+  - CLI commands (memory, memory-init, memory-add, memory-reload)
+  - Auto-loading on agent initialization
+  - 61 tests passing, 89% coverage on file_loader
+- [ ] Permission Modes (Plan/Normal/Auto) - Week 1 remaining days
+- [ ] Enhanced Prompts Integration - Week 2
+
+**Near-Term Roadmap:**
+- [ ] Automated Rollback System (Week 3: FileStateTracker + RollbackEngine)
+- [ ] Multiple Tool Calls (Week 4: Parallel execution + batch operations)
+
+**Future Enhancements:**
+- [ ] Web UI (FastAPI + React)
+- [ ] Multi-agent system
+- [ ] Code execution sandbox
+- [ ] Plugin system
+- [ ] More language support (JSX, Vue, Kotlin, Swift)
+
+---
+
+**⭐ Star this repo if you find it useful!**
+
+**💬 Questions?** Open an issue or discussion.
+
+**📧 Contact:** [vijayjayanandan](https://github.com/vijayjayanandan)
+
+**Made with ❤️ for the AI & open-source community**