Skip to content

Migration Plan

Hokage Vision Agent Migration

Hokage Vision Agent will replace the current root-level YOLOv5 + PySide6 layout with a modern Python package, Docker-first developer workflow, documented data governance, a safe rule-based agent layer, a FastAPI service, and a redesigned PySide6 desktop GUI.

Legacy Repository Shape

The original repository was mostly a YOLOv5-style tree at the repository root:

  • Upstream-like YOLOv5 entrypoints: detect.py, train.py, val.py, export.py, benchmarks.py, hubconf.py.
  • Upstream-like YOLOv5 packages and configs: models/, utils/, classify/, segment/, data/*.yaml, data/hyps/, data/scripts/.
  • Project-specific GUI code: base_ui.py, main_window.py, main_window.ui, test_open_image.py.
  • Project-specific dataset labels/classes: datasets/classes.txt, datasets/labels/.
  • Demo/readme assets: readme_images.png, readme_images/.

The legacy tree was previously isolated under legacy/old_project/. It has since been removed from the working tree (see commit chore: remove vendored legacy yolo toolchain (unused)); the full snapshot remains retrievable from git history for license audit. The new project must not import YOLOv5 legacy modules directly into src/hokage_vision. A compatibility backend may call legacy code only through an explicit boundary.

Migration Strategy

  1. Preserve old code during the first audit phase.
  2. Create a new package under src/hokage_vision with shared types, configuration, and mock-first inference.
  3. Build CLI, API, GUI, agent, dataset, training, and model-management features against the new package.
  4. Legacy YOLOv5 code was isolated under legacy/old_project/ once the new mock workflow was runnable, and later removed from the working tree once no runtime, CI, or build references remained.
  5. Keep the legacy backend optional and documented as a compatibility path, not the default runtime.
  6. Keep data, model weights, generated runs, API keys, and private datasets out of git.

Known Legacy Risks

  • base_ui.py hardcodes QT_QPA_PLATFORM_PLUGIN_PATH to a local Anaconda path.
  • base_ui.py and hub_detect.ipynb hardcode runs/train/exp/weights/best.pt.
  • Legacy YOLOv5 scripts include webcam examples and download helpers; Hokage Vision Agent must not expose camera support and must not auto-download copyrighted data.
  • No root LICENSE file was found during the initial audit.
  • Git history indicates a GPL-3.0 LICENSE existed in the first commit and was later deleted; legacy YOLOv5 provenance must be preserved before choosing a final main project license.
  • The repository contains dataset label files and caches, but no dataset manifest or license provenance.
  • The old GUI/runtime previously depended on local Qt/OpenGL binary components. Undocumented binary artifacts such as libEGL.dll are no longer redistributed in the current tree.

Acceptance Criteria

  • Legacy code is no longer present in the working tree; git history preserves the full snapshot for reference, license audit, and compatibility.
  • New code lives under src/hokage_vision.
  • Root-level data/ and models/ now contain only the new project workspace and registry metadata; old YOLOv5 assets were previously moved to legacy/old_project/ and that tree has since been removed from the working tree (git history retains it).
  • The default backend is mock.
  • CI, GUI smoke tests, API tests, and agent tests do not depend on GPU, private data, real YOLO weights, or external LLM APIs.
  • Documentation clearly separates source code, legacy code, documentation, model weights, dataset images, and annotations.