XaviGuardia/oa2-agent

🤖 OA2 Agent - Intelligent Codebase Analysis Tool

<!-- Force HF rebuild: 2025-01-16-19:00 -->

Privacy-first LLM integration with local inference, conversation history, and vector search.

🚀 Live Demo

🌐 Try it now: [OA2 Agent on Hugging Face Spaces](https://huggingface.co/spaces/XaviGuardia/oa2-agent)

Upload your codebase ZIP files and start chatting with AI about your code - all inference happens locally for complete privacy!

🎯 Features

• —🔒 Privacy-First: Local LLM inference (no external API calls)
• —📤 Upload ZIP files of your codebase for analysis
• —🔍 Semantic search using Qdrant vector database server
• —💬 Interactive chat with conversation memory and context
• —📋 Context-aware responses using retrieved code snippets
• —⚡ GPU Acceleration in HF Spaces for fast inference
• —🎯 Token management for efficient LLM interactions

🔒 Local LLM Support

Privacy-First Design

• —✅ All inference happens locally - your code never leaves your environment
• —✅ No API keys required - no external service dependencies
• —✅ GPU acceleration when available (HF Spaces auto-detects)
• —✅ Dual environment support - works in both local dev and HF Spaces

Supported Providers

• —Ollama (recommended for local development)
• —Hugging Face Transformers (for both local and HF Spaces)

Quick Configuration

# Local development with Ollama (default)
llm:
  provider: ollama
  model: llama3

# Local development with Hugging Face
llm:
  provider: huggingface
  model: microsoft/DialoGPT-medium
  device: auto  # auto-detects GPU/CPU

📖 See [LOCAL_LLM_GUIDE.md](LOCAL_LLM_GUIDE.md) for complete setup instructions and configuration options.

💡 How to Use

1. 1.Upload a codebase ZIP file in the sidebar
2. 2.Give it a collection name for organization
3. 3.Start a chat session to explore your code
4. 4.Ask questions about your codebase - all processed locally!

💭 Example Questions

• —"How does authentication work in this codebase?"
• —"Show me the main classes and their relationships"
• —"What are the database connection patterns?"
• —"Explain the API endpoints and their functionality"

🛠️ Architecture

This deployment runs in a single Docker container with:

• —OA2 Agent: Core analysis engine with local LLM inference
• —Qdrant Server: Vector database for semantic search
• —Streamlit UI: Interactive web interface
• —ChatSession: Persistent conversation management
• —Local LLM: Privacy-first inference (Ollama/HuggingFace)

Powered by: OA2 Agent + Local LLMs + Qdrant Server + Streamlit

   

OA2 Agent transforms how you explore and understand codebases using AI-powered semantic search and interactive analysis with complete privacy through local LLM inference.

🚀 Core Features

• —📦 ZIP Import: Import entire codebases from ZIP files into Qdrant vector database
• —🔍 Semantic Search: Natural language search across your codebase using embeddings
• —🤖 Interactive Chat: Local LLM-powered conversations about your code with context-aware responses
• —🔒 Privacy-First: All LLM inference happens locally - your code never leaves your environment
• —⚡ Fast Setup: One-command Docker deployment with persistent storage

📋 Quick Start

1. Prerequisites

# Python 3.12+ and Docker required
python --version  # Should be 3.12+
docker --version

# For local LLM support (optional)
# Install Ollama for easy model management
brew install ollama  # macOS
# OR curl -fsSL https://ollama.ai/install.sh | sh  # Linux

2. Installation

git clone https://github.com/xaviguardia/oa2.git
cd oa2
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt  # Includes transformers and torch for local LLM
pip install -e .

3. Start Services

# Start Qdrant vector database
docker-compose -f tests/docker-compose.yml up -d

# For Ollama users: Pull a model
ollama pull llama3

# Verify Qdrant is running
curl http://localhost:6333/health

4. Usage Examples

Import Codebase

# Import a ZIP file into Qdrant
oa2 import-zip /path/to/your-project.zip --collection my-project

Search Code

# Natural language search
oa2 search "authentication functions" --collection my-project

# Get JSON output for programmatic use
oa2 search "database connections" --collection my-project --format json

Interactive Analysis (Local LLM)

# Start interactive chat session with local LLM
oa2 chat --collection my-project
# Now ask questions like:
# "How does authentication work in this codebase?"
# "Show me all database-related functions"
# "What security patterns are used?"
# All processed locally for complete privacy!

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Layer     │    │  Service Layer  │    │  Vector Store   │
│                 │    │                 │    │                 │
│ • import-zip    │───▶│ • IndexerService│───▶│  Qdrant Server  │
│ • search        │    │ • Retriever     │    │                 │
│ • chat          │    │ • AgentService  │    │ Collections:    │
│                 │    │                 │    │ - codebase-docs │
│                 │    │ Config & LLM    │    │ - file-chunks   │
│                 │    │ (Local/Private) │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🔧 Development and Testing

⚠️ MANDATORY: Local Testing Before Deployment

NEVER deploy without running the full local test suite first.

# Run complete validation pipeline
./scripts/local_test.sh

This script validates:

• —✅ Code linting and formatting
• —✅ Unit tests with 89% coverage requirement
• —✅ Streamlit app integration tests
• —✅ Docker build validation
• —✅ Container startup and health checks
• —✅ Local LLM functionality

Development Workflow

1. 1.Make changes to code
2. 2.Run local tests: ./scripts/local_test.sh
3. 3.Fix any failures before committing
4. 4.Commit and push (triggers CI)
5. 5.Deploy only after CI passes

Manual Testing

# Test locally with Docker (includes local LLM)
docker build -t oa2-local .
docker run -p 7860:7860 oa2-local
# Open http://localhost:7860

# Test with development server
cd src && streamlit run ../app.py

# Test local LLM functionality
python -c "
from oa2_agent.config import get_config
from oa2_agent.services.llm_service import get_llm_service
service = get_llm_service(get_config().llm)
print('LLM Available:', service.is_available())
"

Debugging Failed Deployments

# Check container logs
docker logs <container-name>

# Test specific components
python -m pytest tests/integration/test_streamlit_integration.py -v

# Validate configuration
python -c "from oa2_agent.config import get_config; print(get_config())"

# Test LLM service
python -c "
from oa2_agent.services.llm_service import get_llm_service
from oa2_agent.config import get_config
service = get_llm_service(get_config().llm)
print(f'Provider: {get_config().llm.provider}')
print(f'Available: {service.is_available()}')
"

📁 Project Structure