👁️ Oxeye

Codebase Q&A with Context-Aware RAG

Oxeye is an intelligent code assistant that answers questions about your codebase using Retrieval-Augmented Generation (RAG). It parses code into semantic chunks, understands relationships, and provides accurate answers with file references.

---

✨ Features

Feature	Description
🌳 AST Parsing	Uses Tree-sitter for accurate code parsing across languages
� Semantic Chunking	Preserves function/class boundaries instead of arbitrary splits
� Hybrid Search	Combines dense (embedding) + sparse (BM25) retrieval
⚡ Cross-Encoder Reranking	Improves precision with contextual re-scoring
🤖 Free LLM	Uses Groq's free API (Llama 3.3 70B) - no cost!
💬 Streaming Chat	Real-time responses with file citations
🐙 GitHub Support	Clone and index repos directly from URL
🎨 Modern UI	Dark theme with glassmorphism effects

---

🚀 Quick Start

1. Clone & Setup

git clone https://github.com/yourusername/oxeye.git
cd oxeye

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

2. Configure API Key

Get a free Groq API key at console.groq.com

# Copy the example config
copy .env.example .env

# Edit .env and add your key
GROQ_API_KEY=your_api_key_here

3. Run Oxeye

streamlit run oxeye/ui/streamlit_app.py

Open http://localhost:8502 and start asking questions!

---

📁 Project Structure

oxeye/
├── oxeye/
│   ├── __init__.py          # Package init
│   ├── config.py             # Settings management
│   │
│   ├── core/
│   │   ├── parser/
│   │   │   ├── ast_parser.py # Tree-sitter AST parsing
│   │   │   └── chunker.py    # Semantic code chunking
│   │   │
│   │   ├── embeddings/
│   │   │   └── encoder.py    # Sentence-transformers embeddings
│   │   │
│   │   ├── retrieval/
│   │   │   ├── hybrid.py     # Dense + BM25 fusion
│   │   │   ├── reranker.py   # Cross-encoder reranking
│   │   │   └── context.py    # Context builder for LLM
│   │   │
│   │   └── llm/
│   │       ├── client.py     # Groq API client
│   │       └── chains.py     # RAG chain orchestration
│   │
│   ├── ingestion/
│   │   ├── crawler.py        # File discovery
│   │   └── pipeline.py       # End-to-end ingestion
│   │
│   ├── storage/
│   │   └── vector_store.py   # FAISS vector storage
│   │
│   └── ui/
│       └── streamlit_app.py  # Chat interface
│
├── requirements.txt          # Dependencies
├── pyproject.toml           # Package config
├── .env.example             # Environment template
└── README.md

---

🔧 How It Works

graph LR
    A[📂 Codebase] --> B[🌳 AST Parser]
    B --> C[🧩 Chunker]
    C --> D[🔢 Embedder]
    D --> E[(💾 FAISS)]
    
    F[❓ Question] --> G[🔍 Hybrid Search]
    E --> G
    G --> H[⚡ Reranker]
    H --> I[📝 Context Builder]
    I --> J[🤖 LLM]
    J --> K[💬 Answer]

Loading

Pipeline Steps

1. Crawl - Find source files (Python, JS, etc.)
2. Parse - Extract functions, classes, docstrings via AST
3. Chunk - Split into semantic units preserving context
4. Embed - Generate vectors via sentence-transformers (local)
5. Store - Save to FAISS for fast similarity search
6. Search - Combine dense + BM25 with RRF fusion
7. Rerank - Boost precision with cross-encoder
8. Generate - Stream answer from Groq LLM

---

⚙️ Configuration

All settings in .env:

Variable	Default	Description
GROQ_API_KEY	Required	Your Groq API key
LLM_MODEL	llama-3.3-70b-versatile	Groq model to use
EMBEDDING_MODEL	all-MiniLM-L6-v2	Local embedding model
TOP_K_RETRIEVAL	10	Chunks to retrieve
TOP_K_RERANK	5	Chunks after reranking
GITHUB_TOKEN	Optional	For private repos

---

🛠️ Tech Stack

Component	Technology
LLM	Groq (Llama 3.3 70B)
Embeddings	sentence-transformers (local)
Vector Store	FAISS
AST Parsing	Tree-sitter
Sparse Search	BM25 (rank-bm25)
Reranking	Cross-encoders
UI	Streamlit
Config	Pydantic Settings

---

📝 Usage Examples

Ingest a Local Codebase

from oxeye.ingestion.pipeline import IngestionPipeline

pipeline = IngestionPipeline(collection_name="my_project")
stats = pipeline.ingest("./path/to/codebase")
print(f"Indexed {stats.chunks_created} chunks")

Ask Questions

from oxeye.core.llm.chains import RAGChain

chain = RAGChain(collection_name="my_project")
answer = chain.ask("How does authentication work?")
print(answer)

Streaming Responses

for chunk in chain.stream("Explain the database models"):
    print(chunk, end="", flush=True)

---

🎯 Best Practices

• ✅ Be specific - "How does UserService.create_user validate email?" works better than "how does it work?"
• ✅ Reference files - "What does auth.py do?" helps narrow context
• ✅ Ask about patterns - "What design patterns are used in the API layer?"
• ✅ Debug with context - "Why might login fail in auth_controller.py?"

---

🤝 Contributing

Contributions welcome! Feel free to:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

📄 License

MIT License - see LICENSE for details.

---

Made with ❤️ by Shaan