Imported from camilomarino/craft_v2027 (AGENTS.md). Install upstream with npx skills add camilomarino/craft_v2027. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

This repository has four main training surfaces:

• training/craft/: phase-1 frozen CRAFT-family baseline implementation.
• training/phase2/: VGG/CRAFT-compatible training line.
• training/phase3/: ConvNeXt CRAFT training line.
• training/common/: shared interfaces, model loading, and evaluation contracts. training/docs/ holds general roadmaps.

Datasets must stay outside git. The expected local layout is a repo-level data symlink pointing to an external dataset root, with canonical dataset paths such as data/raw/synthtext/SynthText/ and data/raw/icdar2015/. Provenance manifests are written to data/manifests/.

Build, Test, and Development Commands

Run all commands from the repository root unless noted otherwise.

• make dataset-list: list registered datasets managed by the CLI.
• make prepare-baseline-data: download and normalize SynthText and ICDAR2015 into data/raw/.
• make import-existing-layout: import datasets from an existing local layout into data/raw/.
• make check-layout: validate that required dataset paths and files exist.
• make smoke: run the smoke_baseline experiment plan.
• make train-baseline: launch the baseline_v1 experiment plan.
• make eval-baseline: run the eval stage for baseline_v1.
• PYTHONPATH=training/craft/src python3 -m craftlab train list: inspect available experiments directly through the CLI.
• python -m training.phase2.train --yaml=synth_smoke: quick phase-2 smoke entrypoint.
• python -m training.phase3.train --yaml=synth_smoke: quick phase-3 smoke entrypoint.
• make PYTHON=/path/to/python train-baseline: use a specific interpreter, for example the project Conda env.

Coding Style & Naming Conventions

Python is the primary language. Follow existing style: 4-space indentation, snake_case for functions and variables, PascalCase for classes, and concise module names. Keep config names descriptive and stage-specific, for example baseline/icdar2015_baseline.yaml. There is no configured formatter in the repo, so match surrounding code closely and keep imports and file layout tidy.

When adding a new detector family, prefer placing generic contracts in training/common/ and the concrete implementation in a phase-specific subtree. Do not add broad shared training abstractions until two phases clearly need the same behavior.

Testing Guidelines

There is no standalone pytest suite yet. Use workflow checks as the test surface:

• make check-layout before any training-related change.
• make smoke for fast regression coverage.
• make eval-baseline when changing phase-1 model, metric, or evaluation behavior.
• python -m unittest discover -s training/tests -p 'test*.py' for the current lightweight unit-test surface.

If you add tests later, place them near the affected module or under a dedicated tests/ tree and name files test_*.py.

Commit & Pull Request Guidelines

Recent history uses short, imperative commit subjects, often focused on one change, for example Add baseline CRAFT training scaffold. Prefer that style and keep commits narrow.

Pull requests should include:

• a short summary of user-visible or training-impacting changes,
• commands run (make check-layout, make smoke, etc.),
• dataset or environment assumptions,
• screenshots or sample outputs only when UI or visual inference output changes.