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

# 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

# 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.