v1.0.1 — Primer release estable (GA)

data-analytics-agents v1.0.1 — Primer release estable

Toolkit multi-CLI de personas y skills para flujos de trabajo de data analytics.

Esta es la primera versión GA (1.0.x) del toolkit. Cubre el ciclo end-to-end del data analyst: perfilado y limpieza de datos tabulares, exploración y validación de SQL sobre warehouses cloud, visualización y reporting ejecutivo, y modelado supervisado. Instalable con un solo comando en OpenCode, Claude Code, Codex y Antigravity CLI.

---

Highlights

• 5 personas + 20 skills distribuidas como markdown + snippets Python pre-aprobados. Auto-descubiertas por los 4 CLIs soportados via AGENTS.md + frontmatter.
• Multi-CLI install via npx data-analytics-agents install --all (symlinks idempotentes, sin copy-paste).
• Cloud warehouses: Snowflake, BigQuery, Redshift, Databricks (Spark SQL). Snippets dialecto-aware (DATE_TRUNC, IFF/IF/CASE, TRY_CAST/SAFE_CAST, backticks vs comillas).
• Guardrails de seguridad built-in: sql-write modo conservador bloquea DROP/UPDATE/DELETE/TRUNCATE/ALTER, audit-log redacta PII (emails, RUTs CL, teléfonos, tarjetas) automáticamente.
• 161 unit tests sobre los snippets de skills (make test-unit), más smoke tests de los examples (make test).

Instalación

npm install --save-dev data-analytics-agents
npx data-analytics-agents install --all

O vía clone directo:

git clone https://github.com/berriosb/data-analytics-agents.git
cd data-analytics-agents
make install-all

Cambios desde v0.9.0

Added

• docs/architecture.md — mapa mental de las 5 personas + 20 skills con diagramas Mermaid de triaje/handoffs y grafo de referencia de skills.
• Unit tests sobre snippets de skills (make test-unit) — 161 tests cubriendo api-builder, audit-log, excel-formulas, report-export, sql-cloud-warehouse, sql-write. Happy path + edge cases + guardrails de seguridad.
• identifier_quote() snippet en sql-cloud-warehouse — entrecomilla identificadores según dialecto (backticks para BigQuery/Databricks, comillas dobles para Snowflake/Redshift).
• docs/notes/databricks-coverage.md — review técnico del dialecto Databricks con cobertura actual + 7 gaps priorizados.
• CHANGELOG.md con release notes estructuradas (Keep a Changelog + SemVer) y roadmap a v1.0 marcado al día.
• prepublishOnly script en package.json que corre clean-cache + make test-unit + install --list antes de cualquier publish (guardrail contra publicar con caches stale o tests rojos).

Changed

• PRDs flippeados a Accepted — los 7 PRDs reflejan el estado real (las skills existen, los ADRs están aceptados).
• audit-log/redact.py — credit_card se matchea antes que phone_cl (un PAN de 16 dígitos se redactaba parcialmente como teléfono; ahora se redacta entero).
• sql-write/validate.py — SQL con solo comentarios ahora se detecta como vacío (antes pasaba silenciosamente como válido).

Fixed

• "4 personas" → "5 personas" en AGENTS.md y README.md (drift desde que se sumó using-data-analytics-agents).

Documentation

• Cross-link de docs/architecture.md desde AGENTS.md y README.md.
• docs/README.md agrega índice de arquitectura y sección de notes.
• README reorganiza la sección de "Tests" para distinguir smoke vs unit tests.
• README agrega badge npm version + GitHub.

Quickstart

# Después de instalar las personas/skills en tu proyecto, invoca un agente:
opencode -m <model> --agent data-explorer "Perfilá examples/ventas_sample.csv y pará."
codex -m <model> --agent sql-analyst exec "Top 5 clientes por revenue desde examples/notes_example.sqlite."
claude -m <model> --agent reporting-analyst "Tendencia mensual de revenue, salida a ./reports/."

# O vía "act as" en el prompt (funciona sin instalar agentes, lee AGENTS.md como contexto):
opencode -m <model> "act as data-explorer. Perfilá el CSV y pará."

Para el mapa completo de qué skill carga cada agente y cómo se conectan las personas, ver docs/architecture.md.

Out of scope para v1.0 (planeado para v1.x)

• data-engineer (ingesta APIs / S3 / scraping). ADR-003 cuando haya demanda.
• make doctor preflight (UX helper).
• QUALIFY clause snippet para Databricks (gap G2 del review).
• OAuth2 / service accounts para cloud warehouses.
• Modo "full" de sql-write (DROP/UPDATE/DELETE con rollback script).
• Unit tests sobre los 14 skills sin recetas/ (requiere extraer snippets de markdown a código).

El detalle completo de cada gap vive en CHANGELOG.md sección "Out of scope para v1.0".

Compatibilidad

• Node: >=18 (probado en 22.x).
• Python: >=3.10 (los snippets de skills; las peer-deps opcionales documentadas en requirements-dev.txt).
• CLIs soportados: OpenCode, Claude Code, Codex, Antigravity CLI (agy).

Créditos

• Schema de skill y template de 6 secciones inspirados en vaquarkhan/data-engineering-agent-skills.
• Workflow perfil → limpieza → gráfico adaptado de jenyss/DataAnalyticsAIAgent con fixes de seguridad.
• Patrón de instalador multi-CLI estilo npx inspirado en vercel-labs/skills.

—

Full Changelog: https://github.com/berriosb/data-analytics-agents/blob/v1.0.1/CHANGELOG.md

v0.8.0 — audit-log: ADR-002 cerrado

ADR-002 cerrado completamente

Este release cierra el ADR-002 que planeaba 4 skills. Las 4 entregadas:

• ✅ api-builder (v0.5.0)
• ✅ excel-formulas (v0.6.0)
• ✅ sql-write (v0.7.0)
• ✅ audit-log (v0.8.0) ← este release

Skill nueva (1)

**audit-log**\ — Log transversal: lo invocan automaticamente sql-analyst, sql-cloud-warehouse y sql-write para registrar cada operacion que toca una DB. NO es invocable directamente por el agente — se ejecuta como side effect.

Backends:

• JSONL (default): ~/.agents/audit/events.jsonl con rotacion automatica a 1MB, max 10 archivos historicos, permisos 0600.
• SQLite opcional: AUDIT_LOG_BACKEND=sqlite → tabla events con indices en actor, action, timestamp.

Redaction de PII automatica antes de cada write:

• email (user@domain.tld)
• rut_cl (12.345.678-9)
• phone_cl (+56 9 XXXX XXXX)
• credit_card (16 digitos)
• Custom patterns via AUDIT_LOG_REDACT_REGEX="nombre1:regex1|nombre2:regex2"

Los matches se reemplazan por ***REDACTED:<nombre>*** y el campo redacted_fields del evento guarda la lista.

Queries con filtros combinables:
```python
from audit_log.recetas import query_audit
eventos = query_audit(actor="sql-analyst", action="rejected", since="2026-09-13")
```

100% stdlib

Sin pandas, sin sqlalchemy, sin requests. La skill es la unica del toolkit que no agrega peerDeps.

Verificado

```bash
make test-audit-log

-> 10 eventos generados (4 SELECTs + 3 INSERTs + 1 CREATE + 2 rejected)

-> 0 PII en el JSONL (5 patrones verificados)

-> Permisos 0600

-> Queries con filtros funcionan

```

Workflow end-to-end final

El toolkit ahora cubre TODO el ciclo de trabajo de un data analyst, de lunes a viernes:

Dia	Skill
Lunes: Excel corporativo sucio	excel-profiler
Martes: limpieza + EDA	csv-profiler + pandas-cleaning
Miercoles: warehouse cloud	sql-cloud-warehouse
Jueves: insights	insight-synthesis
Viernes: reporte ejecutivo	report-export
Viernes (deploy): API REST	api-builder
Viernes (persistir): tabla con resultados	sql-write
Viernes (auditoria): quien corrio que query	audit-log
Auditoria de formulas (cuando aparece la pregunta)	excel-formulas

ADR-003 — follow-ups

Quedan para ADR-003 (futuro):

• sql-write modo full (DROP/UPDATE/DELETE con rollback scripts)
• audit-log forwarding a Datadog/OTEL
• audit-log tamper-evident (hash chaining)

v0.7.0 — sql-write: persistir resultados con guardrails

ADR-002 Nivel 3 cerrado: end-to-end-delivery

Este release agrega sql-write en modo conservador, que cierra el circulo: el data analyst ya no solo consulta y reporta — ahora puede persistir resultados de analisis en una DB de manera segura.

Skill nueva (1)

**sql-write**\ — Carga opcional de sql-analyst, SOLO si el usuario pide persistir resultados. Implementa el patron "dry-run + doble confirmacion + audit log" del ADR-002.

Operaciones permitidas:

• CREATE TABLE [IF NOT EXISTS] (incluido CREATE TEMPORARY TABLE)
• CREATE INDEX, CREATE UNIQUE INDEX
• CREATE VIEW, CREATE OR REPLACE VIEW
• INSERT INTO ... VALUES (...)
• INSERT INTO ... SELECT ...
• WITH cte AS (...) INSERT INTO ...

Operaciones BLOQUEADAS (BlockedOperationError con mensaje accionable):

• DROP TABLE/DATABASE/SCHEMA/INDEX/VIEW
• UPDATE, DELETE, TRUNCATE
• ALTER TABLE ... DROP COLUMN/RENAME
• GRANT, REVOKE

Guardrails obligatorios

1. Validacion estatica del SQL antes de ejecutar (regex sobre tokens).
2. Dry-run obligatorio: genera el DDL + muestra preview de las primeras 5 filas. El caller debe pedir confirmacion #1 al usuario.
3. Doble confirmacion: execute_insert requiere auto_confirm=True. Sin eso, levanta SqlWriteError.
4. Auditoria append-only en ~/.agents/audit/sql-write.log (formato JSONL). Cada escritura registra timestamp, action, engine, target, n_rows, duration_ms, sql_preview.
5. Rotacion automatica cuando el log supera 1MB (mantiene hasta 10 archivos historicos).
6. Rollback automatico si la transaccion SQLAlchemy falla.

Soporte de engines

Engine	Soporte	Dep
SQLite local	v1 ✅	stdlib
Snowflake	v1 ✅ (peerDep opcional)	snowflake-connector-python
BigQuery	v1 ✅ (peerDep opcional)	sqlalchemy-bigquery + google-cloud-bigquery
Redshift	v1 ✅ (peerDep opcional)	sqlalchemy-redshift + redshift-connector
Postgres / MySQL	follow-up (sin escribir en v1)	—

Inferencia de tipos

Mapeo automatico de pandas dtypes al dialecto:

Pandas	SQLite	Postgres	Snowflake	BigQuery
int64 / int32	INTEGER	BIGINT / INTEGER	NUMBER(38,0)	INT64
float64 / float32	REAL	DOUBLE PRECISION	FLOAT	FLOAT64
bool	BOOLEAN	BOOLEAN	BOOLEAN	BOOL
datetime64[ns]	TIMESTAMP	TIMESTAMP	TIMESTAMP_NTZ	TIMESTAMP
object (str)	TEXT	TEXT	TEXT	STRING

Verificado

```bash
make test-sql-write

-> 5 filas insertadas en SQLite

-> Audit log escrito correctamente

-> DROP/UPDATE/DELETE bloqueados con error accionable

-> 17/17 tests del validator (10 permitidas + 7 bloqueadas)

```

Workflow end-to-end completo para una pega de data analytics

Dia	Skill
Lunes: Excel corporativo sucio	excel-profiler
Martes: limpieza + EDA	csv-profiler + pandas-cleaning
Miercoles: warehouse cloud	sql-cloud-warehouse
Jueves: insights	insight-synthesis
Viernes: reporte ejecutivo	report-export
Viernes (deploy): API REST	api-builder
Viernes (persistir): tabla con resultados	sql-write (este release)

ADR-002 — estado

• ✅ excel-formulas (v0.6.0) — auditoria de formulas
• ✅ sql-write (v0.7.0) — escribir con guardrails
• ⏳ audit-log — transversal (siguiente)
• ⏳ sql-write modo full (ADR-003) — DROP/UPDATE/DELETE con rollback

v0.5.0 — api-builder: del analisis al servicio REST

ADR-002 Nivel 1 cerrado: end-to-end-delivery

Este release cierra el primer nivel del ADR-002: el toolkit ahora convierte una funcion Python de analisis terminada en una API REST production-ready, lista para servir con uvicorn o deployar con Docker.

Skill nueva (1)

**api-builder**\ — Toma un archivo .py con una funcion callable y genera 6 archivos en output_dir/:

• analysis.py — copia del input
• app.py — FastAPI con /health, /schema, y el endpoint de la funcion (GET si sin params, POST si con params)
• requirements.txt — fastapi + uvicorn + pydantic + imports top-level del archivo del usuario
• Dockerfile — python:3.11-slim + uvicorn
• README.md — instrucciones de uso local + Docker deploy
• tests/test_app.py — pytest con TestClient (test_health, test_schema, test_endpoint)

Seguridad

• NO ejecuta side effects del usuario durante la generacion — solo lee signature con inspect (stdlib).
• Validacion en directorio temporal: si la app generada no importa, rollback automatico y no escribe nada en output_dir/.
• Auth opcional: export API_KEY=tu-clave requiere header X-API-Key; sin API_KEY, la API es abierta (solo dev).
• Sin eval() ni SQL crudo del usuario.

Verificado end-to-end

```bash
make test-api-builder

-> 3 archivos generados en examples/api_builder_sample/out_api/

-> pytest 3/3 OK (test_health, test_schema, test_score)

-> API respondiendo en vivo:

GET /health -> {"status":"ok"}

POST /score -> {score: 324, nivel: Bajo, recomendacion: ...}

GET /schema -> pydantic model_json_schema

```

ADR-002 — 4 skills planeadas

• ✅ api-builder (este release)
• ⏳ excel-formulas — lectura de formulas Excel para auditoria
• ⏳ sql-write — escritura/DDL guarded (solo lectura por ahora)
• ⏳ audit-log — log de que agente disparo que query en produccion

Workflow end-to-end para una pega nueva

El lunes llegas a una fintech y te piden "expón el scoring como API para pricing". Con este toolkit:

1. Excel corporativo sucio → `excel-profiler` detecta hoja + headers + alertas
2. Limpieza + EDA → `csv-profiler` + `pandas-cleaning`
3. Warehouse cloud → `sql-cloud-warehouse` (Snowflake/BQ/Redshift con dialecto-aware)
4. Insights → `insight-synthesis`
5. Reporte ejecutivo → `report-export` (PDF / PPTX / HTML)
6. Servicio REST → `api-builder` (este release) — la skill toma tu funcion Python y produce la API lista para deployar

Misma toolchain, lunes a viernes, en cualquier pega de data analytics.

Peer dependencies (opcionales)

`fastapi`, `uvicorn`, `pydantic`, `httpx` (transitivo de TestClient) — el usuario instala solo lo que use.

v0.4.0 — ADR-001 portable-day1 cerrado

ADR-001 cerrado: portable-day1

Este release cierra el ADR-001 (ver `docs/adr/001-portable-day1.md`): el toolkit ahora entrega valor end-to-end desde un Excel corporativo sucio hasta un PDF ejecutivo, pasando por warehouses cloud con dialecto-aware.

Skills nuevas (3)

• `excel-profiler` — Detecta hoja con datos, fila de headers, merged cells, columnas con >30% nulos, columnas constantes, IDs únicos en Excels con merged cells, headers en filas 3-7, totales mal formateados.
• `report-export` — Exporta reporte ejecutivo a PDF (WeasyPrint + fallback pdfkit), PPTX (python-pptx nativo) o HTML standalone (imágenes embebidas en base64).
• `sql-cloud-warehouse` — Conexión a Snowflake, BigQuery o Redshift vía SQLAlchemy + driver oficial + snippets dialecto-aware (IFF/IF/CASE, DATE_TRUNC, TRY_CAST/SAFE_CAST, GETDATE).

Recetas importables

• 8 funciones en `skills/report-export/recetas/` (parse_insights, render_plotly, build_pdf, build_ppt, build_html, verify_*)
• 6 módulos en `skills/sql-cloud-warehouse/recetas/` (connect, introspect, dialect_snippets, validate, errors)
• Loader `skills_loader.py` para resolver el problema de imports con guión en nombres de skills.

Demos end-to-end

• `examples/excel_sample/` — sample sucio + test que detecta 3 hojas, header en fila 5, columna email 52% nulos, columna país constante.
• `examples/report_export_sample/` — 3 gráficos Plotly + insights.md → PDF 86KB + PPTX 126KB (6 slides) + HTML 139KB.
• `examples/sql_cloud_warehouse_sample/` — demo offline (sin credenciales) + demo con SQLite mock para validar introspección + JOIN discovery.

Smoke tests

```bash
make test-excel # excel-profiler end-to-end
make test-export-pdf # report-export → PDF
make test-export-ppt # report-export → PPTX
make test-export-html # report-export → HTML
make test-sql-cloud-offline # dialect snippets + validate + errores
```

Targets skipped (corren solo si tenés credenciales reales):
`make test-snowflake` / `test-bigquery` / `test-redshift` ejecutan `SELECT 1` contra el warehouse.

Peer dependencies opcionales

Las deps cloud son peerDeps opcionales — el usuario instala solo la que use. La skill emite error accionable con `pip install` si falta:

| Dep | Tamaño | Cuándo |
| |---|---|
| snowflake-connector-python | ~50MB | target=Snowflake |
| sqlalchemy-bigquery + google-cloud-bigquery | ~30MB | target=BigQuery |
| sqlalchemy-redshift + redshift-connector | ~20MB | target=Redshift |

SQLAlchemy, kaleido, python-pptx, weasyprint también son peerDeps (5-50MB cada una).

PRDs / ADRs incluidos

• `docs/adr/001-portable-day1.md` — decisión arquitectónica firmada 2026-09-14.
• `docs/prd/excel-profiler.md` + `docs/prd/report-export.md` + `docs/prd/sql-cloud-warehouse.md` — specs completos con workflow 6 fases, recetas y criterios de listo.

Próximo: ADR-002

Quedan como follow-up (ADR-002):

• `api-builder` — FastAPI wrapper para deployar análisis como servicio
• `excel-formulas` — lectura de fórmulas en Excel para auditoría
• `sql-write` — escritura/DDL guarded (solo lectura por ahora)
• Databricks SQL — extensión de sql-cloud-warehouse
• Audit logging — qué agente disparó qué query en producción