latam-synth

Generador de datos sintéticos de comportamiento de ahorro financiero, calibrado con las distribuciones estadísticas de 506,311 registros reales de una app de ahorro LatAm (2015-2024): 305,808 transacciones, 108,570 metas de ahorro y 91,933 usuarios de México, Colombia, Argentina, Perú, Chile y más.

El output es 100% sintético: ningún registro deriva de un usuario real, solo de distribuciones agregadas. Sin PII, sin riesgo de reidentificación.

Para qué sirve

• Testing y QA fintech: fixtures realistas para pipelines de pago, apps de presupuesto, motores de metas.
• Demos y POCs: dashboards con datos verosímiles de LatAm que se pueden mostrar públicamente.
• Entrenamiento de ML: datos de arranque para modelos de churn, recomendación y segmentación con patrones reales (estacionalidad, tasas de abandono, categorías de metas).
• Educación: datasets ilimitados para cursos de data science con narrativa de negocio real.

Uso rápido

pip install -e .
latam-synth generate --users 5000 --seed 42 --format csv --out ./output
# Solo México y Colombia, formato parquet:
latam-synth generate --users 10000 --countries Mexico Colombia --format parquet

from latam_synth import SyntheticGenerator, GeneratorConfig
data = SyntheticGenerator(GeneratorConfig(n_users=1000, seed=42)).generate()
data["transactions"].head()

Qué hace fiel a este generador

Calibración verificada contra datos reales (ver docs/validation_report.txt): distribuciones de montos lognormales por tipo de transacción, estacionalidad mensual real (pico de enero post-propósitos, valle de diciembre), 8 categorías de metas con montos y horizontes propios, tasas de logro/abandono reales (73.8% de metas vencidas), uplift de metas compartidas, y scores de usuario correlacionados (cópula gaussiana, ρ=0.89 disciplina-logro).

Where to find your output (Apify)

Every run writes output to two places:

Key-value store — all three tables

1. Open the run in Apify Console and click the Storage tab.
2. Click Key-value store.
3. Download the generated files:
   • users.csv — one row per synthetic user
   • goals.csv — savings goals linked to users
   • transactions.csv — deposit/withdrawal transactions linked to goals
   • OUTPUT — always present; JSON summary of the run (parameters used, row counts, list of downloadable keys)
   • (if format: json was selected, OUTPUT_DATA contains all three tables in a single JSON file instead of the three CSVs)
4. Click the download icon next to each key to save the file.

Dataset — transactions (Apify-native export)

By default (push_to_dataset: true), all transactions are also pushed to the run's Dataset. This lets you:

• Export as JSON, CSV, or Excel directly from the Dataset tab — no manual download needed.
• Connect native Apify integrations (Google Sheets, webhooks, etc.) to the Dataset output.

To disable for very large runs (> 10K users where you only need the KVS files), set push_to_dataset: false in the input.

The run log prints exact file names and row counts at the end of execution.

API REST

pip install -e ".[api]"
uvicorn latam_synth.api:app --port 8000

# JSON con las tres tablas (users, goals, transactions)
curl -s -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"users": 100, "seed": 42, "countries": ["Mexico", "Colombia"]}' | jq .meta
# {"users": 100, "goals": 121, "transactions": 453}

# CSV de transacciones directamente
curl -s -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -H "Accept: text/csv" \
  -d '{"users": 500, "seed": 7}' -o transactions.csv

# Health check
curl http://localhost:8000/health
# {"status": "ok", "version": "0.2.0"}

Rate limit: 10 requests/min por IP. Máximo 50,000 usuarios por request.

Desarrollo

pip install -e ".[dev]"
pytest

Changelog: v0.2 añade mezcla de lognormales (KS=0.032), snap a valores redondos (69.5% en malla), trayectorias temporales coherentes por meta (100% tx en ventana [created_at, deadline]), API FastAPI y actor Apify.