latam-synth

ラテンアメリカのフィンテック向けのプライバシー安全な合成金融データ — Python、CLI、REST、Apify Actor、およびAIエージェント向けのModel Context Protocol (MCP)を通じて利用可能。

金融貯蓄行動の合成データ生成器で、ラテンアメリカの貯蓄アプリの506,311件の実記録（2015〜2024年）の統計分布に基づいて較正されています：メキシコ、コロンビア、アルゼンチン、ペルー、チリなどの305,808件の取引、108,570件の貯蓄目標、91,933人のユーザー。

出力は100%合成です：どの記録も実際のユーザーに由来するものではなく、集計された分布のみに基づいています。PIIはなく、再識別のリスクもありません。

Model Context Protocol (MCP)

LatAm Synthは、AIエージェントに対してMCPツールとして、2つの独立した経路で利用可能です：

• リモート（ホスト型）： Apify MCP Serverがactive_yardstick/latam-synth ActorをStreamable HTTP経由で呼び出し可能なMCPツールとして公開します。インストールは不要です。

• ローカル（stdio）： このリポジトリに同梱されているlatam-synth-mcpは、Apifyを呼び出さずにジェネレーターをプロセス内で実行します。ローカルMCPクライアントやコンテナ化されたカタログチェック用です。

両方の経路は、同じSyntheticGeneratorに対する薄いアダプターであるため、同じ参照整合性を持つ同じテーブルを返します。

MCP詳細

• MCP機能： ツール

• トランスポート： 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トークン

• 公式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エージェントの評価

• オンデマンドでのテストフィクスチャの生成

• デモやPOC用の合成データセットの作成

• レコメンデーションや貯蓄アシスタントのテスト

• 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

何に使えるか

• フィンテックのテストとQA：支払いパイプライン、予算アプリ、目標エンジン向けの現実的なフィクスチャ。

• デモとPOC：公に表示できるラテンアメリカの信頼できるデータを使ったダッシュボード。

• MLトレーニング：季節性、離脱率、目標カテゴリなどの実際のパターンを用いたチャーン、レコメンデーション、セグメンテーションモデル用の初期データ。

• 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

ジェネレーターには以下が組み込まれています：

• 取引タイプごとの対数正規分布の金額分布

• 実際の月次季節性

• 新年の決意後の1月のピークと12月の谷

• 独自の金額と期間を持つ8つの目標カテゴリ

• 観測された達成率と放棄率

• 73.8%の期限切れ目標

• 共有目標のアップリフト

• 相関するユーザースコア

• ガウスコピュラ（ρ=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を通じて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）

すべての実行は出力を2か所に書き込みます。

キーバリューストア — 3つのテーブルすべて

1. Apifyコンソールで実行を開き、Storageタブをクリックします。

2. Key-value storeをクリックします。

3. 生成されたファイルをダウンロードします：

   • users.csv — 合成ユーザーごとに1行

   • goals.csv — ユーザーにリンクされた貯蓄目標

   • transactions.csv — 目標にリンクされた入金/出金取引

   • OUTPUT — 常に存在します。パラメータ、行数、ダウンロード可能なキーを含む実行のJSONサマリー。

   • format: jsonが選択された場合、OUTPUT_DATAには3つのCSVファイルの代わりに、3つのテーブルすべてが1つのJSONファイルに含まれます。

4. 各キーの横にあるダウンロードアイコンをクリックしてファイルを保存します。

データセット — 取引

デフォルト（push_to_dataset: true）では、すべての取引も実行のDatasetにプッシュされます。

これにより、以下が可能になります：

• Datasetタブから直接JSON、CSV、またはExcelとしてエクスポート

• ネイティブのApify統合をDataset出力に接続

• プログラムで取引を消費

キーバリューストアのファイルのみが必要な非常に大規模な実行では、これを無効にするには、次のように設定します：

{
  "push_to_dataset": false
}

実行ログは、実行終了時に正確なファイル名と行数を出力します。

ローカルREST API

API依存関係をインストール：

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

3つのテーブルを含む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が含まれています。

現在のサーバーID：

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公開