latam-synth

Безопасные с точки зрения приватности синтетические финансовые данные для латиноамериканских финтех-приложений — доступны через Python, CLI, REST, Apify Actor и Model Context Protocol (MCP) для ИИ-агентов.

Генератор синтетических данных о поведении финансовых сбережений, калиброванный по статистическим распределениям 506 311 реальных записей приложения сбережений LatAm (2015–2024): 305 808 транзакций, 108 570 сберегательных целей и 91 933 пользователя из Мексики, Колумбии, Аргентины, Перу, Чили и других стран.

Результат на 100% синтетический: ни одна запись не происходит от реального пользователя, только от агрегированных распределений. Без PII и без риска реидентификации.

Model Context Protocol (MCP)

LatAm Synth доступен ИИ-агентам как MCP-инструмент через два независимых пути:

• Удалённо (хостинг): Apify MCP Server предоставляет Actor active_yardstick/latam-synth как вызываемый MCP-инструмент через Streamable HTTP. Ничего устанавливать не нужно.

• Локально (stdio): latam-synth-mcp, поставляемый в этом репозитории, запускает генератор в собственном процессе без обращения к Apify. Для локальных MCP-клиентов и проверок каталога в контейнерах.

Оба пути возвращают одни и те же таблицы с одинаковой ссылочной целостностью, поскольку оба являются тонкими адаптерами поверх одного и того же SyntheticGenerator.

Детали MCP

• Возможность MCP: Tools

• Транспорт: Streamable HTTP (удалённо) / stdio (локально)

• Хостируемый MCP-сервер: Apify MCP Server

• Локальный MCP-сервер: latam-synth-mcp (extra [mcp], SDK mcp>=2,<3)

• Actor, доступный как инструмент: active_yardstick/latam-synth

• Аутентификация: Apify OAuth или Bearer token

• Официальное имя в MCP Registry: io.github.jmendozapuche/latam-fintech-synthetic-data

• Метаданные реестра: server.json

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

Конечная точка MCP

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

Параметр tools ограничивает Apify MCP Server только Actor LatAm Synth, делая его напрямую обнаруживаемым и вызываемым совместимыми ИИ-агентами.

Пример конфигурации MCP — OAuth

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

При первом подключении совместимый MCP-клиент может открыть поток OAuth Apify, чтобы пользователь мог авторизовать доступ, не помещая API-токен напрямую в конфигурацию.

Пример конфигурации MCP — Bearer token

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

Замените <APIFY_TOKEN> на API-токен Apify.

Что ИИ-агенты могут делать с LatAm Synth

MCP-совместимый агент может вызывать LatAm Synth для генерации:

• синтетических финансовых пользователей

• связанных сберегательных целей

• транзакций пополнения и снятия

• латиноамериканских наборов данных с фильтром по странам

• воспроизводимых наборов данных с использованием случайного зерна

• реалистичных тестовых данных fintech без раскрытия персональной информации

Типичные сценарии использования агента включают:

• оценку финансовых ИИ-агентов

• создание тестовых фикстур по требованию

• создание синтетических наборов данных для демо и POC

• тестирование рекомендательных или сберегательных ассистентов

• запуск экспериментов с ML и пайплайнами данных

LatAm Synth в настоящее время предоставляет свою функциональность через MCP Tools. Сейчас он не предоставляет MCP Resources или Prompts.

Как реализован MCP

Удалённый путь не требует MCP-транспортного сервера внутри этого репозитория: его хостирует Apify. Локальный путь включает такой сервер (src/latam_synth/mcp_server.py) для клиентов, которые предпочитают запускать генератор самостоятельно — без токена, без сети, без затрат на каждый запуск.

Архитектура такова:

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 предоставляет хостируемый MCP-сервер и уровень аутентификации. Actor LatAm Synth обеспечивает исполняемую функциональность инструмента и структурированный ввод/вывод.

Локальный MCP-сервер (stdio)

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

Конфигурация для локального MCP-клиента (Claude Desktop / Claude Code):

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

Доступные инструменты:

Оба инструмента аннотированы как read_only и idempotent: ничего не записывается, и одно и то же зерно возвращает один и тот же набор данных. Ограничение в 200 пользователей на вызов сохраняет ответы достаточно малыми для контекста агента — для больших объёмов используйте CLI или Actor.

Детали развёртывания, Docker-образ и конфигурация Glama: docs/mcp_local.md.

Related MCP server: Faker MCP Server

Для чего это нужно

• Тестирование и QA в финтехе: реалистичные фикстуры для платёжных пайплайнов, бюджетных приложений и механизмов целей.

• Демо и POC: дашборды с правдоподобными данными LatAm, которые можно публично показывать.

• Обучение ML: стартовые данные для моделей оттока, рекомендаций и сегментации с реальными паттернами, такими как сезонность, уровень отказов и категории целей.

• ИИ-агенты: генерация синтетических финансовых наборов данных по требованию через MCP.

• Образование: неограниченные наборы данных для курсов по data science с реальной бизнес-логикой.

Быстрое использование

CLI

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

Только Мексика и Колумбия, формат parquet:

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()

Что делает этот генератор достоверным

Калибровка была проверена на реальных данных. См.:

docs/validation_report.txt

Генератор включает:

• логнормальные распределения сумм по типу транзакции

• реальную месячную сезонность

• январский пик после новогодних обещаний и декабрьский спад

• 8 категорий целей с собственными суммами и горизонтами

• наблюдаемые показатели достижения и отказа

• 73.8% просроченных целей

• эффект uplift от совместных целей

• коррелированные пользовательские скоринг-баллы

• гауссову копулу с ρ=0.89 для связи дисциплины и достижения

• согласованные временные траектории по каждой цели

• ссылочную целостность между пользователями, целями и транзакциями

Apify Actor

LatAm Synth также доступен как хостируемый Apify Actor:

active_yardstick/latam-synth

Страница Actor:

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

Actor можно вызывать напрямую из Apify, через Apify API или предоставлять ИИ-клиентам через Apify MCP Server.

Пример ввода:

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

Параметр seed делает генерацию воспроизводимой. Одно и то же зерно и конфигурация дают один и тот же синтетический результат.

Где найти результат (Apify)

Каждый запуск записывает результат в два места.

Key-value store — все три таблицы

1. Откройте запуск в Apify Console и нажмите вкладку Storage.

2. Нажмите Key-value store.

3. Скачайте созданные файлы:

   • users.csv — одна строка на каждого синтетического пользователя

   • goals.csv — сберегательные цели, связанные с пользователями

   • transactions.csv — транзакции пополнения/снятия, связанные с целями

   • OUTPUT — присутствует всегда; JSON-сводка запуска, включая параметры, количество строк и ключи для скачивания

   • если выбран format: json, OUTPUT_DATA содержит все три таблицы в одном JSON-файле вместо трёх CSV-файлов

4. Нажмите значок загрузки рядом с каждым ключом, чтобы сохранить файл.

Dataset — транзакции

По умолчанию (push_to_dataset: true) все транзакции также помещаются в Dataset запуска.

Это позволяет вам:

• экспортировать в JSON, CSV или Excel прямо из вкладки Dataset

• подключать встроенные интеграции Apify к выходным данным Dataset

• потреблять транзакции программно

Чтобы отключить это для очень больших запусков, где нужны только файлы key-value store, установите:

{
  "push_to_dataset": false
}

Журнал запуска выводит точные имена файлов и количество строк в конце выполнения.

Локальный REST API

Установите зависимости API:

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

Сгенерируйте JSON с тремя таблицами:

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 с транзакциями напрямую:

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

Проверка работоспособности:

curl http://localhost:8000/health

{
  "status": "ok",
  "version": "0.2.0"
}

Ограничения локального REST API:

• Ограничение скорости: 10 запросов/мин на IP

• Максимум: 50 000 пользователей на запрос

Конфиденциальность

Сгенерированные наборы данных предназначены для разработки, тестирования, демо, экспериментов и образования и не требуют реальных PII из продакшена.

Ключевые свойства:

• 100% синтетические записи

• ни одна строка не скопирована у реального пользователя

• имена, email, ID и другие прямые PII не воспроизводятся из калибровочного набора данных

• генерация основана на агрегированных статистических распределениях

• синтетические таблицы сохраняют реалистичные взаимосвязи между пользователями, целями и транзакциями

Разработка

pip install -e ".[dev]"
pytest

Метаданные MCP registry

Этот репозиторий включает server.json для обнаружения в MCP registry.

Текущий идентификатор сервера:

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

Зарегистрированная удалённая конечная точка MCP:

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

История изменений

v0.2

• смесь логнормальных распределений (KS=0.032)

• привязка к круглым значениям (69.5% на сетке)

• согласованные временные траектории по каждой цели

• 100% транзакций в окне [created_at, deadline]

• FastAPI API

• Apify Actor

• предоставление MCP через хостируемый Apify MCP Server