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

AGENTS.md — Contexto operativo del monorepo VAAET

Este archivo es la entrada de trabajo para agentes de código. Explica dónde realizar cada cambio, qué contratos no pueden alterarse silenciosamente y qué evidencia se necesita antes de cerrar una tarea. No reemplaza la presentación humana del README.md, el resumen técnico de llms.txt ni la documentación normativa de docs/.

VAAET de un vistazo

Aspecto	Estado vigente
Propósito	Convertir videos de tránsito en telemetría por minuto, estados de circulación y evidencia revisable por una persona.
Producto actual	Laboratorio ML y procesamiento batch; los workflows principales se ejecutan en Google Colab.
Runtime	Python 3.10–3.13.
Componentes activos	`vaaet-core/` portable, `vaaet-persistence/` compartido y `vaaet-ml/` como laboratorio.
Componente reservado	`vaaet-app/`; todavía no existe API ni Web App ejecutable.
Modelo de estados	El MLP aprende `Normal`, `Reduced` y `Congested`; `Accident` requiere confirmación humana.
Licencia	AGPL-3.0-only, con condiciones adicionales para serving que utilice Ultralytics YOLO.
Límite operativo	No es un sistema autónomo de seguridad ni de respuesta ante emergencias.

La arquitectura vigente está definida por ADR-0021. Los ADRs, contratos y reglas de seguridad prevalecen sobre resúmenes y guías introductorias.

Mapa de contexto y orden de lectura

Antes de editar:

Leé este archivo y revisá el estado actual de Git sin descartar cambios ajenos.
Consultá llms.txt y el índice documental para localizar el contrato o ADR vigente.
Leé las instrucciones del componente propietario: vaaet-core/AGENTS.md o vaaet-ml/AGENTS.md.
Inspeccioná las pruebas y el código existente antes de proponer una nueva abstracción.

Fuente	Responsabilidad
`README.md`	Presentación y primer recorrido para personas.
`AGENTS.md`	Límites y reglas operativas compartidas para agentes.
`llms.txt`	Resumen portable y compacto para herramientas.
`docs/index.md`	Navegación hacia arquitectura, contratos, operación, calidad y gobernanza.
`vaaet-core/AGENTS.md`	Reglas de percepción, telemetría, features, bundle e inferencia portable.
`vaaet-persistence/AGENTS.md`	Reglas de conexión, SQL, transacciones, seguridad y migraciones PostgreSQL.
`vaaet-ml/AGENTS.md`	Reglas de notebooks, entrenamiento, evaluación, datasets, adaptadores Colab y DVC.

No crees raíces de contexto paralelas ni dupliques ADRs completos en archivos introductorios. Si dos fuentes se contradicen, detené el cambio y señalá las fuentes concretas antes de elegir una interpretación.

Enrutamiento de cambios

Si la tarea afecta...	Propietario	Regla principal
Percepción, tracking, velocidad, telemetría, timestamps, 19 features, política de estados, HUD o bundle	`vaaet-core/`	Implementar con import `vaaet`; no incorporar dependencias del laboratorio.
Conexión, consultas, escrituras, linaje, roles, auditoría o Alembic PostgreSQL	`vaaet-persistence/`	Implementar con import `vaaet_persistence`; no depender del laboratorio ni de la futura aplicación.
Notebooks, ingestión, datasets, entrenamiento, evaluación, UI HITL, backups o registro DVC	`vaaet-ml/`	Implementar con import `vaaet_ml` y consumir core/persistencia mediante sus APIs públicas.
API, frontend, workers o aplicación desplegable	`vaaet-app/`	Está reservado: requiere alcance aprobado y contrato HTTP versionado antes de agregar código o dependencias.
Documentación, CI, configuración Git/DVC o políticas compartidas	Raíz	Mantener un único workspace y comprobar el impacto sobre los componentes.

No existe un paquete Python instalable en la raíz. En desarrollo, CI y Colab se instala vaaet-core, luego vaaet-persistence y finalmente vaaet-ml.

Convención de código y documentación interna

Mantené identificadores, nombres de archivos y código en inglés. Redactá los comentarios y docstrings propios en español rioplatense formal: usá forma declarativa para contratos (por ejemplo, «Valida…» o «Representa…») y voseo formal para instrucciones operativas («Ejecutá…», «Editá…»). Documentá sólo contratos, efectos laterales, invariantes, decisiones y algoritmos no evidentes; no narres una línea obvia ni repitas el nombre de un símbolo.

Límites de componentes

`vaaet-core/`

Contiene la lógica portable de percepción, telemetría, clasificación y carga segura del bundle. No puede depender de vaaet_ml, PostgreSQL, Alembic, DVC, Google Drive ni APIs de notebooks. Recibe archivos y contratos locales ya resueltos por el consumidor; no decide de dónde provienen.

`vaaet-ml/`

Contiene el laboratorio: notebooks, fuentes de datos, entrenamiento, evaluación, adaptadores Colab y artefactos ML. Puede consumir core y persistencia, pero nunca debe convertirse en dependencia de serving. El notebook de evaluación es read-only y no promociona modelos ni persiste resultados operacionales.

`vaaet-persistence/`

Contiene el acceso compartido a PostgreSQL, contratos de configuración, consultas y escrituras concretas, auditoría y la única cadena Alembic. Puede depender del core base, pero no de ML, Colab, DVC, Drive o la aplicación.

`vaaet-app/`

Permanece reservado. Una futura Web App sólo podrá consumir una API HTTP versionada; el navegador no accederá directamente a módulos Python, PostgreSQL, DVC, Google Drive ni rutas de artefactos. El backend podrá consumir vaaet-core y vaaet-persistence, nunca vaaet-ml, y validará el manifiesto antes de deserializar un bundle.

Invariantes no negociables

Las 19 FEATURE_COLS conservan nombre, orden y semántica contractual salvo una decisión explícita con migración y compatibilidad definidas.
El MLP tiene tres salidas aprendidas: Normal, Reduced y Congested. Los cuatro estados públicos se conservan, pero Accident nunca se publica de forma automática.
El manifiesto del bundle v3 y sus checksums se validan antes de deserializar .keras o .joblib. Consultá el contrato del bundle.
Git identifica versiones; DVC almacena el bundle atómico. Existe una sola raíz Git/DVC y un único remoto lógico vaaet-registry, configurado por entorno en .dvc/config.local. ADR-0023 gobierna esta operación.
PostgreSQL pertenece a la capa compartida vaaet-persistence. Alembic es la única autoridad DDL y los perfiles aplican TLS y mínimo privilegio. No ejecutes migraciones administrativas desde notebooks. Consultá ADR-0024.
La extracción compartida y la frontera con el futuro backend están gobernadas por ADR-0028.
La fidelidad float64, el linaje idempotente y las cadenas HITL efectivas están gobernados por ADR-0029.
La idempotencia de decisiones, los aliases portables verificables y la recuperación pending-sync están gobernados por ADR-0030.
La asociación estricta de identidades, el estado vigente de inferencia y el publicador único del catálogo HITL están gobernados por ADR-0031.
El orden determinista de consolidación, los modos PostgreSQL explícitos, la reconciliación sin reinserciones y la validación compartida de probabilidades están gobernados por ADR-0032.
Videos, datasets privados, validaciones sensibles, credenciales, DSN, certificados, calibraciones reales y binarios ML no se versionan con Git ni se exponen en logs o ejemplos.
VideoViewPlan es opcional y sólo admite segmentos offline declarados y calibrados. Cada transición reinicia el estado temporal y descarta el minuto mixto; no se inventan perfiles ni se reidentifican vehículos entre vistas. Consultá ADR-0025.
continuity_id separa tramos físicos continuos y model_revision identifica un bundle exacto. Ningún estado, incidente o revisión puede atravesar esos límites o sobrescribir historia. Consultá ADR-0026.
La identidad vigente incluye input_policy; las identidades anteriores son sólo históricas. La publicación recuperable y la resolución HITL uniforme están gobernadas por ADR-0027.
La visión mantiene un pipeline Pipe-and-Filter síncrono y ordenado. No introduzcas threads, procesos, colas o Producer--Consumer sin mediciones comparables en Colab y aprobación explícita.

Serving y licencias

Una ejecución que incorpore vaaet-core[vision] y Ultralytics YOLO sólo puede seguir una de estas vías:

demo pública AGPL-3.0, con código y activos aprobados y el checklist de publicación completo;
aplicación privada o comercial con licencia Ultralytics Enterprise vigente, verificada fuera de Git.

ADR-0022 gobierna esta frontera. No interpretes la licencia del repositorio como autorización para publicar videos, pesos, datasets o activos sin procedencia y permiso de redistribución.

Gobernanza: Always / Ask / Never

Nivel	Conducta esperada
Always	Leer las fuentes aplicables; inspeccionar código, pruebas y estado Git; preservar cambios ajenos; mantener el cambio acotado; validar en proporción al riesgo; documentar el resultado real.
Ask	Cambiar contratos, 19 features, estados, umbrales, MLP, dependencias, schema o permisos PostgreSQL, migraciones, remotos DVC, serving, límites core--persistencia--ML--app o iniciar una refactorización arquitectónica.
Never	Versionar secretos, datos privados, videos, calibraciones o binarios ML; saltar la validación manifest-first; eliminar o debilitar pruebas para obtener un resultado verde; introducir dependencias ML/infraestructura en el core; agregar silenciosamente API, frontend o framework en `vaaet-app/`.

Los cambios arquitectónicos, de contratos, seguridad, datos persistidos, dependencias, permisos o remotos requieren un plan gobernado en docs/governance/plans/, el ADR aplicable y aprobación humana antes de ejecutar la fase de riesgo. No hagas commits, tags, promociones DVC ni publicaciones remotas salvo solicitud explícita.

Calidad y validación

Usá los comandos completos definidos por el componente propietario y ejecutá sólo los extras necesarios.

Alcance	Evidencia mínima
`vaaet-core/`	Ruff, Pyright, pytest y `compileall` según `vaaet-core/AGENTS.md`.
`vaaet-persistence/`	Ruff, Pyright, pytest, `compileall` e integración PostgreSQL 17 según `vaaet-persistence/AGENTS.md`.
`vaaet-ml/`	Ruff, Pyright, pytest, `compileall`, AST y auditoría de notebooks según `vaaet-ml/AGENTS.md`.
Documentación o contexto	Enlaces Markdown internos, coherencia con ADRs y contratos, y `git diff --check`.
PostgreSQL	Pruebas unitarias más integración PostgreSQL 17 cuando corresponda; la validación real de TLS y proveedor es manual.
DVC, Drive, GPU o YOLO	Pruebas sin red cuando existan y validación manual explícita en el entorno real.
Cambio transversal	Validaciones de todos los componentes afectados y controles de integración del workspace.

No presentes una comprobación manual pendiente como si hubiera pasado. Si una prueba no puede ejecutarse, indicá el motivo, el riesgo que queda abierto y el comando o entorno necesario para completarla.

Cierre y handoff

Antes de finalizar una tarea:

Confirmá que el resultado solicitado existe y respeta los límites del componente.
Revisá el diff para detectar cambios accidentales, secretos, binarios o archivos ajenos al alcance.
Informá archivos modificados y decisiones relevantes sin copiar logs extensos.
Enumerá las validaciones ejecutadas y sus resultados.
Señalá comprobaciones manuales pendientes, limitaciones y riesgos restantes.
Proponé un commit Conventional Commits sólo cuando ayude al handoff; no lo crees sin autorización explícita.

Para contribuir, seguí CONTRIBUTING.md. Los problemas de seguridad se reportan mediante SECURITY.md, nunca mediante issues públicos con información sensible.

vaaet

About