latam-synth

라틴아메리카 핀테크를 위한 프라이버시 보호 합성 금융 데이터 — Python, CLI, REST, Apify Actor 및 AI 에이전트용 Model Context Protocol(MCP)로 제공됩니다.

라틴아메리카 저축 앱(2015–2024)의 506,311건의 실제 기록에 대한 통계적 분포로 보정된 금융 저축 행동 합성 데이터 생성기입니다: 멕시코, 콜롬비아, 아르헨티나, 페루, 칠레 등의 305,808건의 거래, 108,570건의 저축 목표, 91,933명의 사용자.

출력은 100% 합성 데이터입니다: 어떤 기록도 실제 사용자에게서 파생되지 않으며, 오직 집계된 분포로부터만 생성됩니다. PII가 없고 재식별 위험이 없습니다.

Model Context Protocol (MCP)

LatAm Synth는 두 가지 독립적인 경로를 통해 AI 에이전트에 MCP 도구로 제공됩니다:

• 원격(호스팅): Apify MCP Server는 active_yardstick/latam-synth Actor를 Streamable HTTP를 통해 호출 가능한 MCP 도구로 노출합니다. 설치할 것이 없습니다.

• 로컬(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 토큰

• 공식 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 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 서버와 인증 계층을 제공합니다. 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: 공개적으로 표시할 수 있는 그럴듯한 LatAm 데이터가 포함된 대시보드.

• ML 학습: 계절성, 이탈률, 목표 카테고리 같은 실제 패턴을 가진 이탈(churn), 추천, 세분화 모델용 부트스트랩 데이터.

• 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%의 만료된 목표

• 공유 목표의 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를 통해 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에서 실행을 열고 Storage 탭을 클릭합니다.

2. 키-값 저장소를 클릭합니다.

3. 생성된 파일을 다운로드합니다:

   • users.csv — 합성 사용자당 한 행

   • goals.csv — 사용자에게 연결된 저축 목표

   • transactions.csv — 목표에 연결된 입금/출금 거래

   • OUTPUT — 항상 존재; 매개변수, 행 수, 다운로드 가능한 키를 포함한 실행의 JSON 요약

   • format: json을 선택한 경우, OUTPUT_DATA에는 세 개의 CSV 파일 대신 단일 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

세 테이블이 포함된 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 노출