latam-synth

面向拉丁美洲金融科技的安全隐私合成金融数据——可通过Python、CLI、REST、Apify Actor和模型上下文协议（MCP）供AI代理使用。

金融储蓄行为合成数据生成器，根据来自拉丁美洲储蓄应用（2015–2024年）的506,311条真实记录的统计分布进行校准：来自墨西哥、哥伦比亚、阿根廷、秘鲁、智利等国家的305,808笔交易、108,570个储蓄目标和91,933名用户。

输出100%为合成数据：没有任何记录来自真实用户，仅来自聚合分布。无PII，无重新识别风险。

模型上下文协议（MCP）

LatAm Synth 可通过两条独立路径作为MCP工具提供给AI代理：

• 远程（托管）： Apify MCP Server 通过Streamable HTTP将active_yardstick/latam-synth Actor暴露为可调用的MCP工具。无需安装任何东西。

• 本地（stdio）： 本仓库附带的latam-synth-mcp在进程内运行生成器，无需调用Apify。适用于本地MCP客户端和容器化目录检查。

两条路径返回相同的表，具有相同的引用完整性，因为两者都是同一SyntheticGenerator之上的薄适配器。

MCP详情

• MCP能力： 工具

• 传输： Streamable HTTP（远程）/ stdio（本地）

• 托管MCP服务器： Apify MCP Server

• 本地MCP服务器： latam-synth-mcp（额外[mcp]，SDK mcp>=2,<3）

• 作为工具暴露的Actor： active_yardstick/latam-synth

• 认证： Apify OAuth或Bearer令牌

• 官方MCP注册表名称： 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限制为LatAm Synth Actor，使其可被兼容的AI代理直接发现和调用。

示例MCP配置——OAuth

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

首次连接时，兼容的MCP客户端可以打开Apify OAuth流程，让用户授权访问，而无需在配置中直接放置API令牌。

示例MCP配置——Bearer令牌

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

将<APIFY_TOKEN>替换为Apify API令牌。

AI代理可以用LatAm Synth做什么

兼容MCP的代理可以调用LatAm Synth来生成：

• 合成金融用户

• 关联的储蓄目标

• 存款和取款交易

• 按国家过滤的拉丁美洲数据集

• 使用随机种子生成可复现的数据集

• 不暴露个人身份信息的真实金融科技测试数据

典型代理用例包括：

• 评估金融AI代理

• 按需生成测试夹具

• 为演示和概念验证创建合成数据集

• 测试推荐或储蓄助手

• 引导ML和数据管道实验

LatAm Synth目前通过MCP工具暴露其功能。目前不暴露MCP资源或提示。

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服务器和认证层。LatAm Synth Actor提供可执行的工具功能和结构化输入/输出。

本地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: LiveDataLink

用途

• 金融科技测试和质量保证：为支付管道、预算应用和目标引擎提供逼真的夹具。

• 演示和概念验证：可公开展示的拉丁美洲可信数据仪表板。

• 机器学习训练：用于流失、推荐和细分模型的启动数据，具有季节性、放弃率和目标类别等真实模式。

• AI代理：通过MCP按需生成合成金融数据集。

• 教育：用于数据科学课程的无限数据集，具有真实业务叙事。

快速使用

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%的过期目标

• 共享目标的提升

• 相关的用户评分

• ρ=0.89的高斯copula用于纪律-成就

• 每个目标一致的时间轨迹

• 用户、目标和交易之间的引用完整性

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暴露给AI客户端。

示例输入：

{
  "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）

每次运行都会将输出写入两个位置。

键值存储——所有三个表

1. 在Apify Console中打开运行，点击存储选项卡。

2. 点击键值存储。

3. 下载生成的文件：

   • users.csv——每个合成用户一行

   • goals.csv——链接到用户的储蓄目标

   • transactions.csv——链接到目标的存款/取款交易

   • OUTPUT——始终存在；运行的JSON摘要，包括参数、行数和可下载的键

   • 如果选择了format: json，OUTPUT_DATA包含单个JSON文件中的三个表，而不是三个CSV文件

4. 点击每个键旁边的下载图标以保存文件。

数据集——交易

默认情况下（push_to_dataset: true），所有交易也会推送到运行的数据集。

这允许您：

• 直接从数据集选项卡导出为JSON、CSV或Excel

• 将原生Apify集成连接到数据集输出

• 以编程方式消费交易

对于只需要键值存储文件的大型运行，要禁用此功能，请设置：

{
  "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限制：

• 速率限制：每个IP每分钟10个请求

• 最大：每次请求50,000个用户

隐私

生成的数据集旨在用于开发、测试、演示、实验和教育，无需生产PII。

关键属性：

• 100%合成记录

• 没有一行是从真实用户复制的

• 校准数据集中不复制姓名、电子邮件、ID或其他直接PII

• 生成基于聚合统计分布

• 合成表保留用户、目标和交易之间的真实关系

开发

pip install -e ".[dev]"
pytest

MCP注册表元数据

本仓库包含用于MCP注册表发现的server.json。

当前服务器身份：

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

• 通过托管的Apify MCP Server进行MCP暴露