Merge pull request #167 from 2-Coatl/feature/implement-hamilton-framework-with-sdlc-11-28-51

Refactor Hamilton workspace tests into infrastructure tree

Author: 2-Coatl

docs/EXECPLAN_hamilton_llm_dataflow_example.md

@@ -9,7 +9,8 @@ Queremos que cualquier integrante del proyecto pueda ejecutar un ejemplo mínimo
 ## Progress
 
 - [x] (2025-11-19 10:00Z) ExecPlan creado y alcance documentado.
-- [x] (2025-11-19 10:25Z) Pruebas unitarias que describen el dataflow Hamilton deseado creadas en scripts/coding/tests/ai/examples/test_hamilton_llm_example.py.
+- [x] (2025-11-19 10:25Z) Pruebas unitarias que describen el dataflow Hamilton deseado creadas en `scripts/coding/tests/ai/examples/test_hamilton_llm_example.py` (ahora residiendo en `infrastructure/workspace/tests/hamilton_llm/test_driver.py`).
+- [x] (2025-11-19 12:20Z) Registro de suites de prueba en `infrastructure.workspace.TEST_SUITES` y reubicación del paquete de pruebas a `infrastructure/workspace/tests/hamilton_llm/`.
 - [x] (2025-11-19 11:05Z) Implementación del ejemplo Hamilton (driver, dataflow y cliente LLM) con pruebas pasando.
 - [x] (2025-11-19 11:20Z) Documentación actualizada (guía Hamilton e índice general) y validaciones ejecutadas.
 - [x] (2025-11-13 11:05Z) Refactor del driver para exponer Builder/Driver/DictResult estilo apache/hamilton y ampliación de pruebas.
@@ -33,6 +34,9 @@ Queremos que cualquier integrante del proyecto pueda ejecutar un ejemplo mínimo
 - Decision: Trasladar el ejemplo Hamilton al árbol `infrastructure/workspace` para alinearlo con la organización de entornos ejecutables y facilitar su descubrimiento desde infraestructura.
   Rationale: El ejemplo sirve como workspace autocontenible; ubicarlo junto al resto de utilidades de infraestructura responde a la retroalimentación del stakeholder y mantiene la separación documentación/código.
   Date/Author: 2025-11-19 / coding-agent
+- Decision: Registrar las suites de prueba del workspace en `infrastructure.workspace.TEST_SUITES` para que automatizaciones y documentación puedan descubrirlas sin depender de rutas históricas.
+  Rationale: La reubicación desde `scripts/coding/tests/` rompía la convención previa; proveer un registro explícito evita referencias obsoletas en guías y herramientas.
+  Date/Author: 2025-11-19 / coding-agent
 
 ## Outcomes & Retrospective
 
@@ -42,7 +46,7 @@ Las pruebas de documentación existentes siguen fallando por deuda histórica; s
 
 ## Context and Orientation
 
-El repositorio organiza scripts de agentes en `scripts/coding/ai/` y pruebas correspondientes en `scripts/coding/tests/`. La guía `docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md` solicita como siguiente paso incorporar ejemplos de código Hamilton usando TDD. Actualmente no existe un paquete que demuestre un dataflow Hamilton; tampoco tenemos dependencias a `sf-hamilton`. Implementaremos un micro-driver declarativo interno inspirado en Hamilton, suficiente para ejecutar funciones nombradas según los nodos del grafo y resolver dependencias mediante introspección. Las pruebas se ubicarán en `scripts/coding/tests/ai/examples/` para mantener la correspondencia.
+El repositorio organiza scripts de agentes en `scripts/coding/ai/` y pruebas correspondientes en `scripts/coding/tests/`. La guía `docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md` solicita como siguiente paso incorporar ejemplos de código Hamilton usando TDD. Actualmente no existe un paquete que demuestre un dataflow Hamilton; tampoco tenemos dependencias a `sf-hamilton`. Implementaremos un micro-driver declarativo interno inspirado en Hamilton, suficiente para ejecutar funciones nombradas según los nodos del grafo y resolver dependencias mediante introspección. Las pruebas residirán en `infrastructure/workspace/tests/hamilton_llm/` para mantenerlas junto al workspace correspondiente.
 
 El ejemplo debe incluir:
 1. Una representación explícita de la diferencia entre flujos de desarrollo ML tradicional y LLM, ya sea en docstrings o constantes que puedan inspeccionarse desde las pruebas.
@@ -54,7 +58,7 @@ El ejemplo debe incluir:
 
 1. Crear paquete `infrastructure/workspace/hamilton_llm/` con archivos `__init__.py`, `dataflow.py` y `llm_client.py`. `dataflow.py` contendrá funciones declarativas (topic, prompt_template, prompt, llm_response, business_value, cost_estimate). `llm_client.py` expondrá una clase `MockLLMClient` parametrizable. Documentar en docstrings las diferencias de ritmo de desarrollo.
 2. Implementar micro driver en `infrastructure/workspace/hamilton_llm/driver.py` que resuelva dependencias mediante inspección de firmas, exponiendo además un `Builder` y adaptadores `DictResult` compatibles con la API oficial. La ejecución debe aceptar configuración base (`with_config`) y adaptadores encadenables.
-3. Escribir pruebas TDD en `scripts/coding/tests/ai/examples/test_hamilton_llm_example.py` que:
+3. Escribir pruebas TDD en `infrastructure/workspace/tests/hamilton_llm/test_driver.py` que:
    - Construyan el driver con el módulo `dataflow`.
    - Injecten entradas (por ejemplo, `idea`, `domain_data`, `pricing_policy`).
    - Verifiquen que `llm_response` y `business_value` devuelvan valores esperados.
@@ -63,12 +67,12 @@ El ejemplo debe incluir:
 5. Implementar código real en los módulos descritos, asegurando cobertura >80 % mediante pruebas que ejerciten rutas principales, errores controlados (por ejemplo, dependencia faltante) y adaptadores personalizados.
 6. Re-ejecutar pytest (Green) y refactorizar si procede.
 7. Actualizar `docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md` en la sección de próximos pasos para referenciar el nuevo ejemplo y añadir entrada en `docs/index.md` si corresponde.
-8. Documentar en el ExecPlan las decisiones, sorpresas y resultados. Incluir instrucciones de validación (`python3 -m pytest scripts/coding/tests/ai/examples/test_hamilton_llm_example.py`).
+8. Documentar en el ExecPlan las decisiones, sorpresas y resultados. Incluir instrucciones de validación (`python3 -m pytest infrastructure/workspace/tests/hamilton_llm/test_driver.py`).
 9. Mantener el shim alineado con apache/hamilton agregando pruebas de Builder y adaptadores para evitar regresiones.
 
 ## Concrete Steps
 
-1. Añadir pruebas fallidas: crear archivo de test y ejecutar `python3 -m pytest scripts/coding/tests/ai/examples/test_hamilton_llm_example.py` desde la raíz del repo.
+1. Añadir pruebas fallidas: crear archivo de test y ejecutar `python3 -m pytest infrastructure/workspace/tests/hamilton_llm/test_driver.py` desde la raíz del repo.
 2. Implementar paquetes y funciones según el plan, escribir docstrings que recojan la narrativa de ritmo de desarrollo y habilidades SWE.
 3. Añadir pruebas de Builder/adaptadores (`test_custom_adapter_transforms_execution_result`, `test_builder_requires_modules_before_building`) antes de implementar el shim.
 4. Ejecutar pytest nuevamente hasta que pase y revisar cobertura si se añade reporte.
@@ -77,7 +81,7 @@ El ejemplo debe incluir:
 
 ## Validation and Acceptance
 
-- `python3 -m pytest scripts/coding/tests/ai/examples/test_hamilton_llm_example.py` debe pasar, mostrando que el driver ejecuta correctamente el dataflow y que la metadata esperada está disponible.
+- `python3 -m pytest infrastructure/workspace/tests/hamilton_llm/test_driver.py` debe pasar, mostrando que el driver ejecuta correctamente el dataflow y que la metadata esperada está disponible.
 - `python3 -m pytest docs/qa/testing/test_documentation_alignment.py` debe continuar pasando, confirmando integridad documental.
 - La documentación Hamilton debe mencionar explícitamente el nuevo ejemplo.
 
@@ -89,9 +93,9 @@ El driver declarativo resolverá dependencias determinísticamente, por lo que e
 
 Salida relevante de validaciones más recientes:
 
-- `python3 -m pytest scripts/coding/tests/ai/examples/test_hamilton_llm_example.py`
+- `python3 -m pytest infrastructure/workspace/tests/hamilton_llm/test_driver.py`
 
-      scripts/coding/tests/ai/examples/test_hamilton_llm_example.py .....
+      infrastructure/workspace/tests/hamilton_llm/test_driver.py .....
 
 - `python3 -m pytest docs/qa/testing/test_documentation_alignment.py` (sigue fallando por deuda documental heredada)
 

docs/gobernanza/ai/HAMILTON_FRAMEWORK_INTEGRACION_SDLC.md

@@ -132,7 +132,7 @@ Cada subsección resume objetivos, acciones Hamilton y validaciones alineadas co
 
 ## 6. Próximos pasos
 
-1. Ejemplo base publicado en `infrastructure/workspace/hamilton_llm/`: driver declarativo + pruebas `scripts/coding/tests/ai/examples/test_hamilton_llm_example.py`. A partir de este flujo se pueden derivar variantes (e.g. adaptadores FastAPI) conservando el enfoque TDD.
+1. Ejemplo base publicado en `infrastructure/workspace/hamilton_llm/`: driver declarativo + pruebas `infrastructure/workspace/tests/hamilton_llm/test_driver.py`. A partir de este flujo se pueden derivar variantes (e.g. adaptadores FastAPI) conservando el enfoque TDD.
 2. Evaluar integración con `TASK-024-ai-telemetry-system.md` para recolectar métricas de ejecución.
 3. Registrar aprendizajes en `docs/qa/registros/` una vez ejecutados pilotos.
 

docs/index.md

@@ -87,7 +87,7 @@ Este índice combina lo implementado con la visión futura del proyecto, clarame
 - **Métricas DORA**: [`scripts/dora_metrics.py`](../scripts/dora_metrics.py)
 - **Templates**: [`scripts/templates/`](../scripts/templates/)
 - **Gestión de contexto multi-LLM**: [`ai_capabilities/orchestration/CONTEXT_MANAGEMENT_PLAYBOOK.md`](ai_capabilities/orchestration/CONTEXT_MANAGEMENT_PLAYBOOK.md) y módulo reutilizable [`scripts/coding/ai/shared/context_sessions.py`](../scripts/coding/ai/shared/context_sessions.py).
-- **Hamilton Data→Prompt→LLM ejemplo**: [`infrastructure/workspace/hamilton_llm/`](../infrastructure/workspace/hamilton_llm/) con pruebas [`scripts/coding/tests/ai/examples/test_hamilton_llm_example.py`](../scripts/coding/tests/ai/examples/test_hamilton_llm_example.py).
+- **Hamilton Data→Prompt→LLM ejemplo**: [`infrastructure/workspace/hamilton_llm/`](../infrastructure/workspace/hamilton_llm/) con pruebas [`infrastructure/workspace/tests/hamilton_llm/test_driver.py`](../infrastructure/workspace/tests/hamilton_llm/test_driver.py).
 
 #### [PLANIFICADO] Planificados (ver [`docs/scripts/README.md`](scripts/README.md))
 - `scripts/sdlc_agent.py` - CLI SDLC

docs/infraestructura/README.md

@@ -23,4 +23,4 @@ Cada carpeta ofrece un README inicial listo para documentar los artefactos corre
 ## Recursos destacados recientes
 - **CPython precompilado**: consulta el [pipeline y guía de DevContainer](cpython_precompilado/pipeline_devcontainer.md) para entender cómo se construye, publica y consume el intérprete optimizado.【F:docs/infrastructure/cpython_precompilado/pipeline_devcontainer.md†L1-L99】
 - **Scripts oficiales**: `build_cpython.sh`, `validate_build.sh` e `install_prebuilt_cpython.sh` viven en `infrastructure/cpython/scripts/` y cuentan con pruebas en `infrastructure/cpython/tests/`.
-- **Workspace Hamilton LLM**: la carpeta [`workspace`](workspace/README.md) concentra el ejemplo `Data → Prompt → LLM → $` situado en `infrastructure/workspace/hamilton_llm/`, con pruebas asociadas en `scripts/coding/tests/ai/examples/test_hamilton_llm_example.py`.
+- **Workspace Hamilton LLM**: la carpeta [`workspace`](workspace/README.md) concentra el ejemplo `Data → Prompt → LLM → $` situado en `infrastructure/workspace/hamilton_llm/`, con pruebas asociadas en `infrastructure/workspace/tests/hamilton_llm/test_driver.py`.

docs/infraestructura/workspace/README.md

@@ -5,7 +5,7 @@ Este workspace agrupa los artefactos ejecutables que acompañan la guía de inte
 ## Ubicación del código
 
 - **Paquete principal**: `infrastructure/workspace/hamilton_llm/`
-- **Pruebas asociadas**: `scripts/coding/tests/ai/examples/test_hamilton_llm_example.py`
+- **Pruebas asociadas**: `infrastructure/workspace/tests/hamilton_llm/test_driver.py`
 
 El paquete contiene el driver declarativo (`driver.py`), el dataflow (`dataflow.py`) y el cliente LLM determinista (`llm_client.py`).
 
@@ -17,7 +17,9 @@ El paquete contiene el driver declarativo (`driver.py`), el dataflow (`dataflow.
 ## Cómo ejecutarlo
 
 ```bash
-python3 -m pytest scripts/coding/tests/ai/examples/test_hamilton_llm_example.py
+python3 -m pytest infrastructure/workspace/tests/hamilton_llm/test_driver.py
 ```
 
 La prueba valida tanto el linaje del dataflow como el manejo de dependencias ausentes, permitiendo extender el workspace mediante TDD.
+
+Para verificar la alineación estructural del workspace, se expone además `infrastructure/workspace/tests/test_registry.py`, que afirma la presencia de `TEST_SUITES` en el paquete raíz y que el workspace Hamilton queda registrado para futuras automatizaciones.

infrastructure/workspace/__init__.py

@@ -1 +1,12 @@
 """Workspace automation modules, including Hamilton examples."""
+
+from pathlib import Path
+
+from . import hamilton_llm
+
+__all__ = ("hamilton_llm",)
+
+TEST_SUITES = {
+    "hamilton_llm": Path("infrastructure/workspace/tests/hamilton_llm"),
+}
+"""Mapping from workspace identifier to the directory containing its tests."""

infrastructure/workspace/tests/__init__.py

@@ -0,0 +1,119 @@
+"""Tests for the Hamilton-style LLM dataflow example located in the workspace tree."""
+
+import pytest
+
+from infrastructure.workspace.hamilton_llm import dataflow
+from infrastructure.workspace.hamilton_llm import driver as mini_driver
+from infrastructure.workspace.hamilton_llm.driver import MissingDependencyError
+from infrastructure.workspace.hamilton_llm.llm_client import MockLLMClient
+
+
+@pytest.fixture()
+def hamilton_driver():
+    return (
+        mini_driver.Builder()
+        .with_modules(dataflow)
+        .with_config({"pricing_policy": {"price_per_1k_tokens": 0.4, "safety_multiplier": 1.15}})
+        .with_adapters(mini_driver.DictResult())
+        .build()
+    )
+
+
+def test_pace_of_development_metadata_matches_expected_sequence():
+    """Validate that the module exposes the canonical pacing differences described in the slides."""
+    assert dataflow.PACE_OF_DEVELOPMENT["traditional_ml"] == [
+        "Idea & Data/Resources",
+        "Design",
+        "Development/Prototype",
+        "Model Development",
+        "Getting to Production",
+        "Operations",
+        "Maintenance & Business Value",
+    ]
+    assert dataflow.PACE_OF_DEVELOPMENT["llm_apps"] == [
+        "Idea & Data/Resources",
+        "Design",
+        "Development/Prototype",
+        "Prompt / Model Development",
+        "Getting to Production",
+        "Operations",
+        "Maintenance & Business Value",
+    ]
+
+
+def test_hamilton_builder_executes_llm_business_flow(hamilton_driver):
+    """End-to-end execution should transform data into a business value package and cost estimate."""
+    mock_client = MockLLMClient(
+        price_per_1k_tokens=0.4,
+        response_catalog={
+            "Data → Prompt → LLM → $": "Use Hamilton declarative functions to keep prompts versioned and guarded against injection.",
+        },
+    )
+
+    inputs = {
+        "idea": "AI copilots for compliance analysts",
+        "domain_data": {
+            "data": "archived compliance tickets",
+            "ui": "browser extension",
+            "business_process": "regulatory audit",
+        },
+        "edge_cases": [
+            "Input state space",
+            "Guard against prompt injection",
+            "Domain expertise",
+            "Evaluation",
+            "Cost/GPUs",
+        ],
+        "llm_client": mock_client,
+    }
+
+    result = hamilton_driver.execute(["business_value", "cost_estimate"], inputs)
+
+    assert result["business_value"]["llm_plan"].startswith("Use Hamilton declarative functions")
+    assert result["business_value"]["next_step"] == "Prototype with guarded prompts"
+    assert pytest.approx(result["cost_estimate"], rel=1e-3) == 0.0552
+
+    executed = hamilton_driver.execution_log
+    assert executed[-1] == "cost_estimate"
+    assert "llm_response" in executed
+    assert executed.index("business_value") < executed.index("cost_estimate")
+
+
+def test_driver_reports_missing_inputs():
+    driver = mini_driver.Builder().with_modules(dataflow).build()
+    mock_client = MockLLMClient(price_per_1k_tokens=0.5, response_catalog={})
+
+    with pytest.raises(MissingDependencyError) as exc:
+        driver.execute(
+            ["cost_estimate"],
+            {
+                "idea": "Guardrails demo",
+                "domain_data": {"data": "logs", "ui": "cli", "business_process": "ops"},
+                "edge_cases": ["Injection"],
+                "llm_client": mock_client,
+            },
+        )
+
+    assert "pricing_policy" in str(exc.value)
+
+
+def test_builder_requires_modules_before_building():
+    with pytest.raises(ValueError) as exc:
+        mini_driver.Builder().build()
+
+    assert "modules" in str(exc.value).lower()
+
+
+def test_custom_adapter_transforms_execution_result():
+    class KeysAdapter:
+        def __call__(self, results):
+            return tuple(sorted(results))
+
+    driver = (
+        mini_driver.Builder()
+        .with_modules(dataflow)
+        .with_adapters(KeysAdapter())
+        .build()
+    )
+
+    assert driver.execute(["pace_of_development"], {}) == ("pace_of_development",)

infrastructure/workspace/tests/hamilton_llm/__init__.py

@@ -0,0 +1,33 @@
+"""Structural tests ensuring workspace modules expose their test locations."""
+
+from importlib import import_module
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture(scope="module")
+def workspace_pkg():
+    return import_module("infrastructure.workspace")
+
+
+def test_workspace_exposes_hamilton_llm_suite(workspace_pkg):
+    """The workspace package should document the canonical location of its tests."""
+    suites = getattr(workspace_pkg, "TEST_SUITES")
+    assert "hamilton_llm" in suites
+
+    suite_path = Path(suites["hamilton_llm"])
+    assert suite_path.parts[:3] == ("infrastructure", "workspace", "tests")
+    assert suite_path.name == "hamilton_llm"
+
+
+def test_suite_path_points_to_existing_directory(workspace_pkg):
+    suites = workspace_pkg.TEST_SUITES
+    suite_path = Path(suites["hamilton_llm"])
+    assert suite_path.exists(), "El workspace debe registrar un directorio real de pruebas"
+
+
+def test_workspace_exports_documented_modules(workspace_pkg):
+    """Ensure __all__ helps discovery tools locate available workspaces."""
+    exported = set(getattr(workspace_pkg, "__all__", ()))
+    assert "hamilton_llm" in exported, "El workspace Hamilton debe exponerse en __all__"