CLAUDE.md

# Code Generation Assistant — Claude Context

RAG-based Python code generation assistant using CodeSearchNet.
Compares baseline, RAG, fine-tuned, and agentic approaches.

## Environment

- macOS, no NVIDIA GPU. All local runs must stay small and CPU-friendly.
- Python 3.9; virtual environment at `.venv/` (never touch system Python).
- Always activate with `.venv/bin/python` (or `.venv/bin/<tool>`); don't use bare `python`.

## Pipeline run order

```bash
# 1. Install (one-time)
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 2. Smoke test (synthetic data, fast)
#    Set use_sample: true in config.yaml first.
.venv/bin/python scripts/01_prepare_data.py
.venv/bin/python scripts/02_run_eda.py

# 3. Real subset (set use_sample: false, keep max_rows: 5000 in config.yaml)
.venv/bin/python scripts/01_prepare_data.py   # downloads CodeSearchNet ~457k rows, caps at max_rows
.venv/bin/python scripts/03_build_index.py    # downloads all-MiniLM-L6-v2, embeds corpus, writes FAISS index

# 4. Launch UI (downloads Qwen2.5-Coder-1.5B-Instruct ~3 GB on first run)
.venv/bin/python app/gradio_app.py            # serves at http://127.0.0.1:7860
```

## config.yaml key settings

| Key | Default | Notes |
|-----|---------|-------|
| `data.use_sample` | `false` | Set `true` for offline/CI smoke tests |
| `data.sample_size` | 200 | Rows generated when `use_sample: true` |
| `data.max_rows` | 5000 | Caps real HF data for local runs (0 = no cap) |
| `models.embed_model` | `sentence-transformers/all-MiniLM-L6-v2` | Retrieval embedder |
| `models.gen_model` | `Qwen/Qwen2.5-Coder-1.5B-Instruct` | Code LLM |
| `models.top_k` | 3 | Retrieved examples per query |

## What each script does

- `scripts/01_prepare_data.py` — load raw dataset (HF or synthetic) → clean → train/val/test split → `data/processed/`
- `scripts/02_run_eda.py` — compute stats + plots from training split → `data/eda/`
- `scripts/03_build_index.py` — embed training corpus with MiniLM → FAISS index → `data/index/`
- `scripts/04_run_eval.py` — retrieval metrics (recall@k, MRR) + pass@1 baseline vs RAG
- `scripts/05_finetune.py` — fine-tune CodeT5+ on docstring→code (Colab only; too slow locally)

## Source layout

```
src/config.py          loads config.yaml into a SimpleNamespace
src/data/load.py       HF dataset fetch + max_rows cap
src/data/clean.py      filtering funnel (word count, tokens, dedup, etc.)
src/data/make_sample.py synthetic 200-row sample for smoke tests
src/eda/analyze.py     stats + matplotlib/seaborn plots
src/rag/embedder.py    CodeIndex: SentenceTransformer + FAISS (build/save/load/retrieve)
src/rag/generator.py   CodeAssistant: Qwen LLM wrapper, baseline + RAG prompt builders
src/eval/             functional_eval.py, retrieval_eval.py, sandbox.py
src/agent/repair_loop.py  generate → run → self-repair loop
src/finetune/train_codet5.py  (Colab only)
app/gradio_app.py      Gradio chat UI (main local + HF Spaces deploy target)
app/api.py             FastAPI REST service (uvicorn)
app/streamlit_app.py   Streamlit UI
```

## HuggingFace downloads (one-time, cached in ~/.cache/huggingface/)

| Asset | Size | When |
|-------|------|------|
| `code_search_net` dataset | ~2 GB | `01_prepare_data.py` with `use_sample: false` |
| `sentence-transformers/all-MiniLM-L6-v2` | ~90 MB | `03_build_index.py` (first run) |
| `Qwen/Qwen2.5-Coder-1.5B-Instruct` | ~3 GB | `app/gradio_app.py` (first run) |

## Data directories (excluded from git)

```
data/raw/          raw parquet from HF
data/processed/    train/val/test.parquet + cleaning_funnel.csv
data/eda/          PNG plots + eda_stats.json
data/index/        code.index (FAISS) + corpus.parquet + embed_model.txt
```

## Deployment options

```bash
# Gradio (local or push to HF Spaces as app.py)
.venv/bin/python app/gradio_app.py

# FastAPI
.venv/bin/uvicorn app.api:app --host 0.0.0.0 --port 8000

# Streamlit
.venv/bin/streamlit run app/streamlit_app.py

# Docker
docker build -t cga . && docker run -p 8000:8000 cga
```

## Full-dataset training / eval

Do NOT run locally — use Colab:
- `scripts/04_run_eval.py` on full CodeSearchNet is slow; fine for small subsets.
- `scripts/05_finetune.py` (CodeT5+) requires a GPU.
- The notebook (`notebooks/`) is for Colab EDA, training, and reporting eval numbers.

## Known warnings (non-fatal)

- `urllib3 NotOpenSSLWarning` — macOS LibreSSL vs OpenSSL; safe to ignore.
- `Some parameters are on the meta device` — CPU offload of Qwen weights; expected on macOS without GPU.