Consolidate vision finetune files under finetune/vision/

Move all vision-specific finetune assets into finetune/vision/ so the
vision fine-tuning work lives in one place, separate from the text-gen
work: the synthetic generator, dataset builders, schema/contract/prompts,
configs/, patches/, fixtures/, the model + dataset cards, the vision
reports, and the repo-root vision runlog all relocate. Update every
importer (modal/, evals/, tests/, intra-package) to finetune.vision.* and
the moved path strings (configs, patches, fixtures, cards, reports) in the
Modal scripts and Makefile.

Kept at finetune/ root: the text-gen files (minicpm5/qa/whatsapp) and
redact.py, which is shared — the text distill pipeline copies it too, so
it is not vision-specific. modal/ and evals/ stay top-level shared infra.

make check green: 626 passed, 1 skipped; ruff + format clean.

Makefile

@@ -27,9 +27,9 @@ modal-profile:
 	modal profile activate $(MODAL_PROFILE)
 
 modal-train-v2:
-	MODAL_PROFILE=$(MODAL_PROFILE) uv run python finetune/train.py --modal --detach \
+	MODAL_PROFILE=$(MODAL_PROFILE) uv run python finetune/vision/train.py --modal --detach \
 		--train-json finetune/labeled/v2/all_train.json \
-		--config finetune/configs/minicpmv4_6_lora_sft_v2.yaml \
+		--config finetune/vision/configs/minicpmv4_6_lora_sft_v2.yaml \
 		--hf-repo marinarosa/vivamais-vision-lora-v2
 
 modal-merge-v2:

evals/stage1_adapter.py

@@ -6,7 +6,7 @@ import json
 import re
 from pathlib import Path
 
-from finetune.prompts import STAGE1_PROMPT
+from finetune.vision.prompts import STAGE1_PROMPT
 
 DEFAULT_BASE_MODEL = "openbmb/MiniCPM-V-4.6"
 DEFAULT_TUNED_MODEL = "marinarosa/vivamais-vision-merged-v2"

evals/stage2_adapter.py

@@ -6,7 +6,7 @@ import json
 import re
 from pathlib import Path
 
-from finetune.prompts import stage2_vision_prompt
+from finetune.vision.prompts import stage2_vision_prompt
 from vivamais.domain.artifacts import ArtifactKind
 
 DEFAULT_BASE_MODEL = "openbmb/MiniCPM-V-4.6"

evals/stage2_scoring.py

@@ -7,7 +7,7 @@ from collections import defaultdict
 from typing import Any
 
 from evals.metrics import normalize_text
-from finetune.v2_schema import STAGE2_FIELDS
+from finetune.vision.v2_schema import STAGE2_FIELDS
 from vivamais.adapters.models.dspy_payloads import (
     EXTRACTION_PROGRAMS,
     LineItemFields,

finetune/{build_auxiliary_dataset.py → vision/build_auxiliary_dataset.py}

@@ -12,9 +12,9 @@ _ROOT = Path(__file__).resolve().parents[1]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.prompts import stage2_assistant, stage2_vision_prompt
+from finetune.vision.prompts import stage2_assistant, stage2_vision_prompt
 from finetune.redact import redact_v2_row
-from finetune.v2_schema import EXTRACTABLE_KINDS
+from finetune.vision.v2_schema import EXTRACTABLE_KINDS
 from vivamais.domain.artifacts import ArtifactKind
 
 

finetune/{build_mixed_dataset.py → vision/build_mixed_dataset.py}

@@ -13,8 +13,8 @@ _ROOT = Path(__file__).resolve().parents[1]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.build_auxiliary_dataset import to_training_row as auxiliary_row
-from finetune.build_stage1_dataset import to_training_row as stage1_row
+from finetune.vision.build_auxiliary_dataset import to_training_row as auxiliary_row
+from finetune.vision.build_stage1_dataset import to_training_row as stage1_row
 
 
 def load_labels(path: Path) -> list[dict[str, Any]]:

finetune/{build_real_corpus.py → vision/build_real_corpus.py}

@@ -34,8 +34,8 @@ if str(_ROOT / "src") not in sys.path:
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.catalog import extract_all
-from finetune.synthetic_vision_dataset import normalize_text
+from finetune.vision.catalog import extract_all
+from finetune.vision.synthetic_vision_dataset import normalize_text
 
 SOURCE_SUFFIXES = (".jpg", ".jpeg", ".png", ".pdf")
 IGNORED_SUFFIXES = (".webp",)

finetune/{build_stage1_dataset.py → vision/build_stage1_dataset.py}

@@ -12,7 +12,7 @@ _ROOT = Path(__file__).resolve().parents[1]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.prompts import STAGE1_PROMPT, stage1_assistant
+from finetune.vision.prompts import STAGE1_PROMPT, stage1_assistant
 from finetune.redact import redact_v2_row
 
 

finetune/{build_v3_dataset.py → vision/build_v3_dataset.py}

@@ -5,7 +5,7 @@ labels (teacher_labels.jsonl), after carving a stratified real eval holdout that
 is NEVER in train. Emits one shuffled all_train.json that package_modal_dataset
 turns into the Modal/LLaMA-Factory package.
 
-    python -m finetune.build_v3_dataset \
+    python -m finetune.vision.build_v3_dataset \
         --teacher finetune/labeled/v2/teacher_labels.jsonl \
         --synthetic finetune/workspace/synthetic_vision \
         --workspace finetune/workspace \
@@ -29,8 +29,8 @@ if str(_ROOT / "src") not in sys.path:
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.build_auxiliary_dataset import to_training_row as stage2_row
-from finetune.build_stage1_dataset import to_training_row as stage1_row
+from finetune.vision.build_auxiliary_dataset import to_training_row as stage2_row
+from finetune.vision.build_stage1_dataset import to_training_row as stage1_row
 
 DEFAULT_EVAL_FRACTION = 0.15
 DEFAULT_SEED = 42

finetune/{convert_v1_to_v2.py → vision/convert_v1_to_v2.py}

@@ -13,8 +13,8 @@ _ROOT = Path(__file__).resolve().parents[1]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.audit_transcriptions import transcription_path
-from finetune.v2_schema import STAGE2_FIELDS, validate_v2_row
+from finetune.vision.audit_transcriptions import transcription_path
+from finetune.vision.v2_schema import STAGE2_FIELDS, validate_v2_row
 from vivamais.domain.artifacts import ArtifactKind
 
 _BOARDING_CUES = (

finetune/{fix_v2_coercion.py → vision/fix_v2_coercion.py}

@@ -14,8 +14,8 @@ if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
     sys.path.insert(0, str(_ROOT / "src"))
 
-from finetune.validate_v2_labels import _coerce_row, validate_v2_row
-from finetune.v2_schema import STAGE2_FIELDS, validate_v2_row as _validate
+from finetune.vision.validate_v2_labels import _coerce_row, validate_v2_row
+from finetune.vision.v2_schema import STAGE2_FIELDS, validate_v2_row as _validate
 from vivamais.domain.artifacts import ArtifactKind
 
 

finetune/{merge_export.py → vision/merge_export.py}

@@ -13,9 +13,9 @@ _ROOT = Path(__file__).resolve().parents[1]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.train_schema import TrainValidationError, validate_export_config
+from finetune.vision.train_schema import TrainValidationError, validate_export_config
 
-DEFAULT_EXPORT_CONFIG = Path("finetune/configs/minicpmv4_6_lora_export.yaml")
+DEFAULT_EXPORT_CONFIG = Path("finetune/vision/configs/minicpmv4_6_lora_export.yaml")
 HF_VISION_REPO = "marinarosa/vivamais-vision"
 HF_LORA_REPO = "marinarosa/vivamais-vision-lora"
 HF_MERGED_REPO = "marinarosa/vivamais-vision-merged"

finetune/{package_modal_dataset.py → vision/package_modal_dataset.py}

@@ -14,7 +14,7 @@ _ROOT = Path(__file__).resolve().parents[1]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.train_schema import TrainValidationError, validate_training_rows
+from finetune.vision.train_schema import TrainValidationError, validate_training_rows
 
 CONVERT_TO_JPEG_SUFFIXES = frozenset({".webp", ".gif", ".bmp", ".tiff", ".tif"})
 # PDFs (real e-tickets) are rendered to JPEG from their first page.

finetune/{stage2_contract.py → vision/stage2_contract.py}

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from finetune.v2_schema import EXTRACTABLE_KINDS, STAGE2_FIELDS
+from finetune.vision.v2_schema import EXTRACTABLE_KINDS, STAGE2_FIELDS
 from vivamais.domain.artifacts import ArtifactKind
 
 # Fields whose v2 value is a list (everything else is a scalar string).

finetune/{synthetic_example_export.py → vision/synthetic_example_export.py}

@@ -21,7 +21,7 @@ if str(_ROOT / "src") not in sys.path:
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.synthetic_vision_dataset import (
+from finetune.vision.synthetic_vision_dataset import (
     Fonts,
     RENDERERS,
     finish_image,

finetune/{synthetic_vision_dataset.py → vision/synthetic_vision_dataset.py}

@@ -35,8 +35,8 @@ if str(_ROOT / "src") not in sys.path:
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.prompts import STAGE1_PROMPT, stage1_assistant, stage2_assistant, stage2_vision_prompt
-from finetune.v2_schema import validate_v2_row
+from finetune.vision.prompts import STAGE1_PROMPT, stage1_assistant, stage2_assistant, stage2_vision_prompt
+from finetune.vision.v2_schema import validate_v2_row
 from vivamais.domain.artifacts import ArtifactKind
 
 REFERENCE_SUFFIXES = {".jpg", ".jpeg", ".pdf"}

finetune/{train.py → vision/train.py}

@@ -14,9 +14,9 @@ _ROOT = Path(__file__).resolve().parents[1]
 if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
 
-from finetune.build_mixed_dataset import build_mixed
-from finetune.package_modal_dataset import package_modal_dataset
-from finetune.train_schema import (
+from finetune.vision.build_mixed_dataset import build_mixed
+from finetune.vision.package_modal_dataset import package_modal_dataset
+from finetune.vision.train_schema import (
     TrainValidationError,
     validate_image_paths,
     validate_lora_config,
@@ -25,14 +25,14 @@ from finetune.train_schema import (
 
 MODAL_PROFILE = "marinaleitecabrera"
 
-DEFAULT_CONFIG = Path("finetune/configs/minicpmv4_6_lora_sft_v2.yaml")
+DEFAULT_CONFIG = Path("finetune/vision/configs/minicpmv4_6_lora_sft_v2.yaml")
 DEFAULT_PACKAGE = Path("finetune/modal_package")
 DEFAULT_WORKSPACE = Path("finetune/workspace")
 DEFAULT_LABELS = Path("finetune/labeled/v2/all.jsonl")
 DEFAULT_TRAIN_JSON = Path("finetune/labeled/v2/all_train.json")
-FIXTURE_LABELS = Path("finetune/fixtures/labels.jsonl")
-FIXTURE_TRAIN_JSON = Path("finetune/fixtures/fixture_train.json")
-FIXTURE_IMAGES = Path("finetune/fixtures/images")
+FIXTURE_LABELS = Path("finetune/vision/fixtures/labels.jsonl")
+FIXTURE_TRAIN_JSON = Path("finetune/vision/fixtures/fixture_train.json")
+FIXTURE_IMAGES = Path("finetune/vision/fixtures/images")
 
 
 def prepare_fixture_workspace(workspace: Path) -> None:

finetune/{validate_v2_labels.py → vision/validate_v2_labels.py}

@@ -14,7 +14,7 @@ if str(_ROOT) not in sys.path:
     sys.path.insert(0, str(_ROOT))
     sys.path.insert(0, str(_ROOT / "src"))
 
-from finetune.v2_schema import EXTRACTABLE_KINDS, validate_v2_row
+from finetune.vision.v2_schema import EXTRACTABLE_KINDS, validate_v2_row
 from vivamais.adapters.models.dspy_payloads import (
     EXTRACTION_PROGRAMS,
     LineItemFields,

modal/judge_pipeline.py

@@ -107,7 +107,7 @@ def judge_corpus(limit: int = 0) -> str:
     teacher_volume.reload()
 
     from evals.judge_scoring import build_judge_prompt, is_accepted, parse_judge_verdict
-    from finetune.v2_schema import validate_v2_row
+    from finetune.vision.v2_schema import validate_v2_row
 
     root = Path("/data")
     rows = [

modal/merge_export.py

@@ -80,23 +80,23 @@ export_image = (
         "pip install 'transformers>=5.7.0,<6.0.0'",
     )
     .add_local_file(
-        local_path="finetune/patches/apply_llamafactory_loader_patch.py",
+        local_path="finetune/vision/patches/apply_llamafactory_loader_patch.py",
         remote_path=f"{VIVAMAIS_REMOTE}/apply_llamafactory_loader_patch.py",
         copy=True,
     )
     .run_commands(f"python {VIVAMAIS_REMOTE}/apply_llamafactory_loader_patch.py")
     .add_local_file(
-        local_path="finetune/configs/minicpmv4_6_lora_export_v2.yaml",
+        local_path="finetune/vision/configs/minicpmv4_6_lora_export_v2.yaml",
         remote_path=export_config_remote("v2"),
         copy=True,
     )
     .add_local_file(
-        local_path="finetune/configs/minicpmv4_6_lora_export_v3.yaml",
+        local_path="finetune/vision/configs/minicpmv4_6_lora_export_v3.yaml",
         remote_path=export_config_remote("v3"),
         copy=True,
     )
     .add_local_file(
-        local_path="finetune/configs/minicpmv4_6_lora_export_v4.yaml",
+        local_path="finetune/vision/configs/minicpmv4_6_lora_export_v4.yaml",
         remote_path=export_config_remote("v4"),
         copy=True,
     )
@@ -126,9 +126,7 @@ def _write_remote_export_config(version: str) -> Path:
     return config_path
 
 
-def _upload_from_container(
-    version: str, token: str, merged_repo: str, lora_repo: str
-) -> None:
+def _upload_from_container(version: str, token: str, merged_repo: str, lora_repo: str) -> None:
     from huggingface_hub import HfApi
 
     api = HfApi(token=token)
@@ -263,10 +261,7 @@ def main(
 
     token = ""
     if upload:
-        token = (
-            os.environ.get("HF_TOKEN", "").strip()
-            or os.environ.get("HF_API_KEY", "").strip()
-        )
+        token = os.environ.get("HF_TOKEN", "").strip() or os.environ.get("HF_API_KEY", "").strip()
         if not token:
             token = subprocess.run(
                 ["hf", "auth", "token"], capture_output=True, text=True, check=True

modal/publish_dataset.py

@@ -37,7 +37,7 @@ image = (
     modal.Image.debian_slim(python_version="3.11")
     .pip_install("huggingface_hub", "pillow")
     .add_local_file(
-        local_path="finetune/dataset_card_synthetic_ptbr.md",
+        local_path="finetune/vision/dataset_card_synthetic_ptbr.md",
         remote_path=CARD_REMOTE,
         copy=True,
     )