chore: centralizzare path artifact in unico source of truth

[Gabrymi93]

Obiettivo

Sostituire i path sparsi in so_mcp/_paths.py e hardcoded in test/script con risoluzione centralizzata via lab-connectors/gcs/paths.py + paths.json.

Stato attuale

Oggi i path SO sono definiti in:

Dove	Come	Problema
so_mcp/_paths.py	Path costanti Pathlib	Duplicati rispetto a paths.json, non usa lab-connectors
scripts/_constants.py	Altre costanti Path	Stesso problema, in piu' sourcing
tests/test_*.py	Hardcoded nei test	Se un path cambia, tocca aggiornare N test
.github/workflows/*.yml	Hardcoded nella CI	Non risolvibile via codice, ma worth documenting
so_mcp/*.py	import da _paths.py	Dipendenza locale non centralizzata

Cosa fare

1. Aggiornare _paths.py per delegare a lab_connectors.gcs.paths:

   • local_path(pattern_key) → risolve path locale relativo a SO_ROOT
   • gcs_uri(pattern_key) → già esiste via gs_url()
   • resolve_artifact(pattern_key, prefer="local") → locale se esiste, altrimenti GCS

2. Eliminare duplicazione:

   • Sostituire INVENTORY_PARQUET_PATH etc. con chiamate a local_path("catalog_inventory_latest")
   • Mantenere _paths.py come facade (non rompere import esistenti), ma delegare a lab-connectors

3. Aggiornare test per usare _paths.py invece di hardcoded path

4. Vincoli:

   • _paths.py resta come interfaccia pubblica per tutti i consumer SO (non importano lab-connectors direttamente)
   • I workflow YAML restano hardcoded (non risolvibili via Python)
   • scripts/_constants.py da unificare con _paths.py (o viceversa)

Dipende da

• lab-connectors #?? (aggiunta local_path() a paths.py + nuovi pattern in paths.json)

Tasks

• Aggiungere local_path() in so_mcp/_paths.py (delega a lab-connectors con SO_ROOT)
• Sostituire tutte le costanti Path in _paths.py con risoluzione via pattern
• Identificare e sostituire path hardcoded in scripts/
• Identificare e sostituire path hardcoded in tests/
• Identificare e sostituire path hardcoded in notebooks/
• Verificare che agent-context-builder funzioni ancora
• Documentare in CONTRIBUTING.md come aggiungere un nuovo path

[Gabrymi93]

Aggiornamento stato — 2026-06-17

Buona notizia: la parte principale dell'unificazione è già fatta. scripts/_constants.py importa già tutti i path condivisi da so_mcp._paths (righe 17-43). Commento in testa: "Le costanti di path sono importate da so_mcp._paths (unica fonte)."

Cosa resta

Solo 2 path in _constants.py non ancora in _paths.py:

Path	Dove sta ora	Da aggiungere a _paths.py
CATALOG_WATCH_REPORT_PATH	data/catalog/CATALOG_WATCH_REPORT.md	sì
SCHEMA_DIR_PATH	schemas/	sì

Una volta spostati questi 2, _constants.py potrà importarli tutti da _paths.py e la fonte unica sarà completa.

Cosa è stato scartato (dopo analisi)

• lab-connectors/gcs/paths.py — dominio GCS, non locale. I path SO sono locali al repo. Aggiungere local_path() a lab-connectors sarebbe overengineering.
• schema/ — in altri repo del Lab contiene schemi JSON di artifact pubblici, non path di routing interno. Non è il posto giusto.

Prossimo passo (minimo)

Aggiungere i 2 path mancanti a so_mcp/_paths.py:

CATALOG_WATCH_REPORT_PATH = _REPO_ROOT / "data" / "catalog" / "CATALOG_WATCH_REPORT.md"
SCHEMA_DIR_PATH = _REPO_ROOT / "schemas"

Poi chiudere l'issue.