CLAUDE.md for Python ML

# CLAUDE.md

Project memory for Claude Code in this Python ML repository. Read it before editing. Other agents can follow the same rules.

## Stack

This repository is a Python data or machine-learning project. Training code does not see the test split. Notebooks are for exploration. Reusable logic lives in importable modules.

## Layout

- Importable code lives in a package. Notebooks live in a notebooks folder and stay thin.
- Data paths come from config. Do not hard-code a laptop path.
- Experiment outputs go to a gitignored directory.

## Commands

- Tests: `pytest`
- Lint: `ruff check .`
- Train: `Run the project's training entry point, not a notebook cell`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Fit scalers, vocabularies, and feature selection on training data only.
- Pin seeds where the library supports it, and record them.
- Keep a single source of metric computation. Do not reimplement accuracy in a notebook.
- Type the public functions. Validate dataframe assumptions at the boundary.
- Do not commit large data files or credentials.
- Prefer the project's config format for hyperparameters.

## Testing

Add or update tests when behavior changes.

Test the split and the metric with a tiny synthetic frame. Do not download a dataset in the test.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Raise a clear error when a required column is missing or a split is empty. Do not fill target values to hide it.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not tune on the test set.
- Do not leak the label through an id, a timestamp, or a target-encoded feature fit on all rows.
- Do not call the network or a paid API from an import.
- Do not leave a GPU tensor on the wrong device and catch the error with a bare except.

## Done when

- The requested behavior works.
- `pytest` passes and the training entry point still runs the unchanged path, or you say why it cannot.
- The diff stays inside the task.
- You list anything you could not run.