latam-synth

Datenschutzfreundliche synthetische Finanzdaten für lateinamerikanische Fintechs – verfügbar über Python, CLI, REST, Apify Actor und Model Context Protocol (MCP) für KI-Agenten.

Generator für synthetische Daten zum Finanzsparverhalten, kalibriert mit den statistischen Verteilungen von 506.311 echten Datensätzen einer lateinamerikanischen Spar-App (2015–2024): 305.808 Transaktionen, 108.570 Sparziele und 91.933 Nutzer aus Mexiko, Kolumbien, Argentinien, Peru, Chile und weiteren Ländern.

Die Ausgabe ist zu 100 % synthetisch: Kein Datensatz stammt von einem echten Nutzer, sondern nur aus aggregierten Verteilungen. Ohne PII und ohne Reidentifikationsrisiko.

Model Context Protocol (MCP)

LatAm Synth ist für KI-Agenten über zwei unabhängige Wege als MCP-Tool verfügbar:

• Remote (gehostet): Der Apify MCP Server stellt den active_yardstick/latam-synth-Actor als aufrufbares MCP-Tool über Streamable HTTP bereit. Nichts muss installiert werden.

• Lokal (stdio): latam-synth-mcp, das in diesem Repository enthalten ist, führt den Generator prozessintern aus, ohne Apify aufzurufen. Für lokale MCP-Clients und containerisierte Katalogprüfungen.

Beide Wege liefern dieselben Tabellen mit derselben referenziellen Integrität, da beide nur dünne Adapter über demselben SyntheticGenerator sind.

MCP-Details

• MCP-Fähigkeit: Tools

• Transport: Streamable HTTP (remote) / stdio (lokal)

• Gehosteter MCP-Server: Apify MCP Server

• Lokaler MCP-Server: latam-synth-mcp (Extra [mcp], SDK mcp>=2,<3)

• Als Tool bereitgestellter Actor: active_yardstick/latam-synth

• Authentifizierung: Apify OAuth oder Bearer-Token

• Offizieller MCP-Registry-Name: io.github.jmendozapuche/latam-fintech-synthetic-data

• Registry-Metadaten: server.json

• Apify-Actor: https://apify.com/active_yardstick/latam-synth

MCP-Endpunkt

https://mcp.apify.com?tools=active_yardstick/latam-synth

Der Parameter tools schränkt den Apify MCP Server auf den LatAm-Synth-Actor ein, sodass er für kompatible KI-Agenten direkt auffindbar und aufrufbar ist.

Beispiel-MCP-Konfiguration – OAuth

{
  "mcpServers": {
    "latam-synth": {
      "url": "https://mcp.apify.com?tools=active_yardstick/latam-synth"
    }
  }
}

Bei der ersten Verbindung kann ein kompatibler MCP-Client den Apify-OAuth-Ablauf öffnen, damit der Nutzer den Zugriff autorisieren kann, ohne ein API-Token direkt in der Konfiguration zu hinterlegen.

Beispiel-MCP-Konfiguration – Bearer-Token

{
  "mcpServers": {
    "latam-synth": {
      "url": "https://mcp.apify.com?tools=active_yardstick/latam-synth",
      "headers": {
        "Authorization": "Bearer <APIFY_TOKEN>"
      }
    }
  }
}

Ersetzen Sie <APIFY_TOKEN> durch ein Apify-API-Token.

Was KI-Agenten mit LatAm Synth tun können

Ein MCP-kompatibler Agent kann LatAm Synth aufrufen, um Folgendes zu generieren:

• synthetische Finanznutzer

• verknüpfte Sparziele

• Ein- und Auszahlungstransaktionen

• nach Ländern gefilterte lateinamerikanische Datensätze

• reproduzierbare Datensätze mithilfe eines Zufalls-Seeds

• realistische Fintech-Testdaten ohne Offenlegung personenbezogener Daten

Typische Anwendungsfälle für Agenten sind:

• Bewertung finanzieller KI-Agenten

• bedarfsgerechte Erzeugung von Test-Fixtures

• Erstellung synthetischer Datensätze für Demos und POCs

• Testen von Empfehlungs- oder Sparassistenten

• Bootstrapping von ML- und Data-Pipeline-Experimenten

LatAm Synth stellt seine Funktionalität derzeit über MCP-Tools bereit. Derzeit werden keine MCP-Ressourcen oder -Prompts bereitgestellt.

Wie MCP implementiert ist

Der Remote-Pfad erfordert keinen MCP-Transportserver in diesem Repository: Apify hostet ihn. Der lokale Pfad enthält jedoch einen (src/latam_synth/mcp_server.py) für Clients, die den Generator lieber selbst ausführen – ohne Token, ohne Netzwerk, ohne Kosten pro Lauf.

Die Architektur sieht wie folgt aus:

MCP-compatible AI client
        |
        |  Streamable HTTP
        v
Apify MCP Server
        |
        |  exposes Actor as MCP Tool
        v
active_yardstick/latam-synth
        |
        v
Synthetic users + goals + transactions

Apify stellt den gehosteten MCP-Server und die Authentifizierungsebene bereit. Der LatAm-Synth-Actor bietet die ausführbare Tool-Funktionalität sowie strukturierte Ein-/Ausgaben.

Lokaler MCP-Server (stdio)

pip install -e ".[mcp]"
latam-synth-mcp                    # entry point
python -m latam_synth.mcp_server   # equivalent

Konfiguration für einen lokalen MCP-Client (Claude Desktop / Claude Code):

{
  "mcpServers": {
    "latam-synth": {
      "command": "latam-synth-mcp"
    }
  }
}

Bereitgestellte Tools:

Beide sind als read_only und idempotent annotiert: Es wird nichts geschrieben, und derselbe Seed liefert denselben Datensatz. Das Limit von 200 Nutzern pro Aufruf hält die Antworten klein genug für einen Agentenkontext – für größere Mengen verwenden Sie die CLI oder den Actor.

Bereitstellungsdetails, Docker-Image und Glama-Konfiguration: docs/mcp_local.md.

Related MCP server: Faker MCP Server

Wozu es dient

• Testing und Fintech-QA: realistische Fixtures für Zahlungs-Pipelines, Budget-Apps und Ziel-Engines.

• Demos und POCs: Dashboards mit plausiblen LatAm-Daten, die öffentlich gezeigt werden können.

• ML-Training: Startdaten für Churn-, Empfehlungs- und Segmentierungsmodelle mit echten Mustern wie Saisonalität, Abbrecherquoten und Zielkategorien.

• KI-Agenten: bedarfsgerechte Generierung synthetischer Finanzdatensätze über MCP.

• Bildung: unbegrenzte Datensätze für Data-Science-Kurse mit echter Geschäftsnarrative.

Schnellstart

CLI

pip install -e .
latam-synth generate --users 5000 --seed 42 --format csv --out ./output

Nur Mexiko und Kolumbien, Parquet-Format:

latam-synth generate --users 10000 --countries Mexico Colombia --format parquet

Python

from latam_synth import SyntheticGenerator, GeneratorConfig

data = SyntheticGenerator(
    GeneratorConfig(n_users=1000, seed=42)
).generate()

data["transactions"].head()

Was diesen Generator realistisch macht

Die Kalibrierung wurde anhand echter Daten verifiziert. Siehe:

docs/validation_report.txt

Der Generator umfasst:

• lognormale Betragsverteilungen nach Transaktionstyp

• echte monatliche Saisonalität

• Januar-Peak nach den Neujahrsvorsätzen und Dezember-Tal

• 8 Zielkategorien mit eigenen Beträgen und Zeithorizonten

• beobachtete Erfolgs- und Abbrecherquoten

• 73,8 % überfällige Ziele

• Uplift bei gemeinsamen Zielen

• korrelierte Nutzer-Scores

• Gauß-Copula mit ρ=0,89 für Disziplin-Erfolg

• kohärente zeitliche Verläufe pro Ziel

• referenzielle Integrität zwischen Nutzern, Zielen und Transaktionen

Apify Actor

LatAm Synth ist auch als gehosteter Apify-Actor verfügbar:

active_yardstick/latam-synth

Actor-Seite:

https://apify.com/active_yardstick/latam-synth

Der Actor kann direkt von Apify aus, über die Apify-API oder über den Apify MCP Server für KI-Clients bereitgestellt werden.

Beispieleingabe:

{
  "users": 1000,
  "seed": 42,
  "countries": ["Mexico", "Colombia"],
  "format": "csv",
  "push_to_dataset": true,
  "start_date": "2023-01-01",
  "end_date": "2024-12-31"
}

Der Parameter seed macht die Generierung reproduzierbar. Derselbe Seed und dieselbe Konfiguration erzeugen dieselbe synthetische Ausgabe.

Wo Sie Ihre Ausgabe finden (Apify)

Jeder Lauf schreibt die Ausgabe an zwei Orte.

Key-Value-Store – alle drei Tabellen

1. Öffnen Sie den Lauf in der Apify Console und klicken Sie auf den Tab Storage.

2. Klicken Sie auf Key-value store.

3. Laden Sie die generierten Dateien herunter:

   • users.csv – eine Zeile pro synthetischem Nutzer

   • goals.csv – mit Nutzern verknüpfte Sparziele

   • transactions.csv – mit Zielen verknüpfte Ein-/Auszahlungstransaktionen

   • OUTPUT – immer vorhanden; JSON-Zusammenfassung des Laufs, einschließlich Parametern, Zeilenzahlen und herunterladbarer Schlüssel

   • wenn format: json ausgewählt wurde, enthält OUTPUT_DATA alle drei Tabellen in einer einzigen JSON-Datei anstelle der drei CSV-Dateien

4. Klicken Sie auf das Download-Symbol neben jedem Schlüssel, um die Datei zu speichern.

Dataset – Transaktionen

Standardmäßig (push_to_dataset: true) werden alle Transaktionen auch in das Dataset des Laufs geschrieben.

Damit können Sie:

• direkt als JSON, CSV oder Excel über den Tab Dataset exportieren

• native Apify-Integrationen mit der Dataset-Ausgabe verbinden

• Transaktionen programmatisch abrufen

Um dies bei sehr großen Läufen zu deaktivieren, wenn nur die Dateien aus dem Key-Value-Store benötigt werden, setzen Sie:

{
  "push_to_dataset": false
}

Das Laufprotokoll gibt am Ende der Ausführung die genauen Dateinamen und Zeilenzahlen aus.

Lokale REST-API

Installieren Sie die API-Abhängigkeiten:

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

JSON mit den drei Tabellen generieren:

curl -s -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"users": 100, "seed": 42, "countries": ["Mexico", "Colombia"]}' | jq .meta

Beispiel-Metadatenantwort:

{
  "users": 100,
  "goals": 121,
  "transactions": 453
}

Transaktions-CSV direkt herunterladen:

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"
}

Limits der lokalen REST-API:

• Rate-Limit: 10 Anfragen/min pro IP

• Maximum: 50.000 Nutzer pro Anfrage

Datenschutz

Die generierten Datensätze sind für Entwicklung, Tests, Demos, Experimente und Bildung konzipiert, ohne dass Produktions-PII erforderlich ist.

Wichtige Eigenschaften:

• 100 % synthetische Datensätze

• keine Zeile wird von einem echten Nutzer kopiert

• keine Namen, E-Mails, IDs oder andere direkte PII aus dem Kalibrierungsdatensatz werden reproduziert

• die Generierung basiert auf aggregierten statistischen Verteilungen

• synthetische Tabellen bewahren realistische Beziehungen zwischen Nutzern, Zielen und Transaktionen

Entwicklung

pip install -e ".[dev]"
pytest

MCP-Registry-Metadaten

Dieses Repository enthält server.json für die MCP-Registry-Erkennung.

Aktuelle Server-Identität:

io.github.jmendozapuche/latam-fintech-synthetic-data

Der registrierte Remote-MCP-Endpunkt ist:

https://mcp.apify.com?tools=active_yardstick/latam-synth

Changelog

v0.2

• Mischung von Lognormalverteilungen (KS=0,032)

• Anpassung an runde Werte (69,5 % im Raster)

• kohärente zeitliche Verläufe pro Ziel

• 100 % der Transaktionen innerhalb des Fensters [created_at, deadline]

• FastAPI-API

• Apify-Actor

• MCP-Bereitstellung über den gehosteten Apify MCP Server