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.

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

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

streamlit run oxeye/ui/streamlit_app.py

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

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

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]

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

All settings in .env:

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")

from oxeye.core.llm.chains import RAGChain

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

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

• ✅ 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?"

Contributions welcome! Feel free to:

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

MIT License - see LICENSE for details.

Made with ❤️ by Shaan