CLAUDE.md

Project Conventions for Claude Code

CRITICAL: Commit & Attribution Rules

Claude Code MUST follow these rules without exception:

1. NEVER add Co-Authored-By: Claude or any AI co-author trailer to commit messages.
2. NEVER add 🤖 Generated with Claude Code footers or any AI attribution.
3. NEVER mention Claude, Anthropic, OpenAI, Copilot, AI, LLMs, or any model/assistant name in commit messages, code comments, file headers, documentation, PR descriptions, or changelogs.
4. All commits must be authored solely by:
   • Name: apoorvrajdev
   • Email: apoorvrajmgr@gmail.com
5. NEVER stage or commit changes on your own. Only suggest commit messages — the user runs git commit themselves.
6. NEVER push to remote. Only the user pushes.
7. NEVER create branches, tags, or releases on your own.

Commit Message Format

Use Conventional Commits. Examples:

• chore: initial repo scaffolding
• feat(backend): add /caption endpoint for image upload
• feat(inference): add beam search decoder
• fix(data): correct COCO split deduplication
• fix(training): stabilize loss scaling for mixed precision
• docs: update stabilized training runbook
• test(evaluation): add BLEU/CIDEr metric tests
• refactor(models): extract encoder CNN factory
• perf(inference): cache image features for batched predict

Keep subject under 72 characters. Body optional but explains why, not what.

Project Stack

• Core ML: Python 3.10+, TensorFlow / Keras, NumPy, Pillow
• Model: InceptionV3 encoder + Transformer decoder for image captioning
• Backend: FastAPI app under backend/app/ (routes, services, schemas, utils)
• Frontend: React 18 + Vite (JSX) under frontend/, ESLint configured
• Config: YAML configs under configs/ loaded via src/captioning/config/
• Data: MS COCO pipeline under src/captioning/data/
• Evaluation: BLEU, CIDEr, METEOR, ROUGE under src/captioning/evaluation/
• Tooling: pyproject.toml, Makefile, pytest, packaging as captioning

Repository Layout (authoritative)

• src/captioning/ — installable library (config, data, models, preprocessing, training, inference, evaluation, utils)
• backend/app/ — FastAPI service (api/routes.py, services/predictor_service.py, schemas/, core/, utils/)
• frontend/src/ — React UI (components/, services/api.js)
• scripts/ — CLI entrypoints (train.py, evaluate.py, predict.py, etc.)
• configs/ — YAML training/eval configs
• models/vX.Y.Z/ — versioned model artifacts (model.h5, vocab.json)
• tests/unit/ — pytest unit tests
• notebooks/ — exploratory notebooks (not part of runtime)
• docs/ — phase notes and runbooks

Code Standards

• Python: type hints on all new/edited public functions; prefer pathlib.Path over string paths
• Imports: absolute imports from captioning.*; no relative imports across top-level packages
• Determinism: seed NumPy / TF / Python random whenever introducing stochastic code paths in training or evaluation
• Configs: never hardcode hyperparameters in scripts — extend src/captioning/config/schema.py and update the relevant YAML in configs/
• Models / vocab: never modify files under models/vX.Y.Z/ in place; bump the version directory instead
• Backend layering: api/routes.py only orchestrates; inference logic stays in backend/app/services/ and src/captioning/inference/
• Schemas: all FastAPI request/response bodies go through Pydantic schemas in backend/app/schemas/
• Frontend: functional components + hooks; keep API calls inside frontend/src/services/api.js
• Tests: new behavior gets a unit test under tests/unit/; keep tests CPU-only and offline (no network, no real model downloads)

Working Style

• Plan before implementing for any non-trivial change (training loop, decoder, data pipeline, API contract)
• One module at a time, with tests
• Run pytest for touched areas before declaring a change done
• After making changes, summarize what you did so the user can review and commit
• If a change spans library + backend + frontend, list the affected files grouped by layer in the summary