Conversation
There was a problem hiding this comment.
Pull request overview
Adds contributor-facing documentation and Claude rules intended to standardize development workflows around uv and provide a single “project context” reference for LANfactory.
Changes:
- Added
CLAUDE.mdwith project structure, common commands, architecture notes, CLI entry points, CI workflow summary, and known issues. - Added
.claude/rules/uv.mdto enforceuvusage for Python execution and dependency management.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
CLAUDE.md |
New central project context doc (commands, architecture, CLI/CI overview). |
.claude/rules/uv.md |
New Claude rule file to mandate uv-based workflows. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## Build & Tooling | ||
|
|
||
| - **Build system:** setuptools (pure Python, no compiled extensions) | ||
| - **Package manager:** uv (with `uv.lock`) |
There was a problem hiding this comment.
uv.lock is currently ignored by git in this repo (.gitignore contains uv.lock), so stating “uv.lock is the source of truth” (and implying it’s present) is misleading. Either commit uv.lock and remove it from .gitignore, or update this doc to reflect that the repo doesn’t track a lockfile.
| - **Package manager:** uv (with `uv.lock`) | |
| - **Package manager:** uv (no `uv.lock` committed; dependencies resolved from `pyproject.toml`) |
| ## Common Commands | ||
|
|
||
| ```bash | ||
| # Install all dependencies (dev + optional) |
There was a problem hiding this comment.
uv sync --all-groups installs dependency groups (e.g. dev) but does not install optional extras, so the comment “dev + optional” is inaccurate. Consider either changing the text to “dev” only, or updating the command to include extras (e.g., add --all-extras or explicit --extra ...).
| # Install all dependencies (dev + optional) | |
| # Install all dependency groups (e.g. dev) |
| Optional experiment tracking via MLflow. CLI flags: `--run-name`, `--experiment-name`, | ||
| `--tracking-uri`, `--artifact-location`. Supports resuming runs via `--run-id`. |
There was a problem hiding this comment.
The MLflow CLI flag names in this section don’t match the actual CLI options in lanfactory.cli.{torch_train,jax_train} (they use --mlflow-run-name, --mlflow-experiment-name, --mlflow-tracking-uri, --mlflow-artifact-location, --mlflow-run-id). Updating these flags here will prevent users from copying commands that fail.
| Optional experiment tracking via MLflow. CLI flags: `--run-name`, `--experiment-name`, | |
| `--tracking-uri`, `--artifact-location`. Supports resuming runs via `--run-id`. | |
| Optional experiment tracking via MLflow. CLI flags: `--mlflow-run-name`, `--mlflow-experiment-name`, | |
| `--mlflow-tracking-uri`, `--mlflow-artifact-location`. Supports resuming runs via `--mlflow-run-id`. |
| - The `uv.lock` file is the source of truth for resolved dependency versions. | ||
| - When adding dependencies, add them to `pyproject.toml` and run `uv sync`. |
There was a problem hiding this comment.
This rule says uv.lock is the source of truth, but the repository currently ignores uv.lock in .gitignore (so it won’t be committed/reviewed). To make this enforceable, either stop ignoring and commit uv.lock, or adjust the rule to reflect the current workflow (no checked-in lockfile).
| - The `uv.lock` file is the source of truth for resolved dependency versions. | |
| - When adding dependencies, add them to `pyproject.toml` and run `uv sync`. | |
| - `pyproject.toml` is the source of truth for dependencies; `uv.lock` is a local resolution artifact and is not committed. | |
| - When adding dependencies, add them to `pyproject.toml` and run `uv sync` to update your local `uv.lock`. |
| --- | ||
|
|
||
| - Always use `uv run` to execute commands — never bare `python`, `pytest`, `ruff`, or other tools. | ||
| - Never use `pip install` — use `uv sync` (with `--extra` or `--all-groups` flags) to manage dependencies. |
There was a problem hiding this comment.
“Never use pip install” is too broad given the repo’s README still documents pip install lanfactory for end users. Consider scoping this rule explicitly to repository development/CI (e.g., “When working in this repo, don’t use pip; use uv…”) so it doesn’t conflict with published installation guidance.
| - Never use `pip install` — use `uv sync` (with `--extra` or `--all-groups` flags) to manage dependencies. | |
| - When working in this repo (local development, CI, or scripts), do not use `pip install`; instead use `uv sync` (with `--extra` or `--all-groups` flags) to manage dependencies. End‑user installation instructions in README or external docs may still use `pip install` where appropriate. |
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
This pull request adds important project documentation and enforces standardized Python package management practices. The most significant changes are the addition of a comprehensive project context file and a rules file that mandates the use of the
uvpackage manager.Documentation and Project Standards:
CLAUDE.mdfile describing the project's purpose, structure, build system, supported commands, architecture patterns (including network types and training backends), ONNX export process, HuggingFace integration, configuration and MLflow usage, CLI entry points, CI workflows, and known issues. This serves as a central reference for contributors and maintainers.Python Package Management Rules:
.claude/rules/uv.mdto enforce the use ofuvas the package manager for all Python operations. This includes rules such as always usinguv runfor commands, never usingpip install, and treatinguv.lockas the source of truth for dependencies.