langchain-latam-synth

LangChain tool for generating realistic, privacy-safe synthetic financial data for Latin American fintech applications.

langchain-latam-synth exposes the LatAm Synth generator as a ready-to-use LangChain tool for AI agents, testing, QA, demos, machine-learning experiments, data pipelines, and agent evaluation without using personally identifiable information.

The package provides one tool:

generate_latam_financial_data

It generates linked synthetic:

• financial users
• savings goals
• deposit and withdrawal transactions

The underlying generator is LatAm Synth, executed through its hosted Apify Actor.

---

Installation

pip install -U langchain-latam-synth

Requires Python 3.10+.

---

Authentication

The tool runs the hosted LatAm Synth Actor on Apify, so you need an Apify API token.

Set it as the APIFY_TOKEN environment variable:

macOS / Linux

export APIFY_TOKEN="your-apify-token"

Windows PowerShell

$env:APIFY_TOKEN = "your-apify-token"

Do not hard-code API tokens in source code or commit them to GitHub.

---

Quick start

from langchain_latam_synth import generate_latam_financial_data

result = generate_latam_financial_data.invoke(
    {
        "users": 25,
        "seed": 42,
        "countries": ["Colombia", "Mexico"],
    }
)

print(result["meta"])
print(len(result["users"]))
print(len(result["goals"]))
print(len(result["transactions"]))

The tool returns a dictionary with:

run_id
generator
meta
users
goals
transactions

meta carries the row counts, the seed, the requested countries, the Apify run id and the generation timestamp:

{
    "users": 25,
    "goals": 31,
    "transactions": 87,
    "seed": 42,
    "countries": ["Colombia", "Mexico"],
    "generated_at": "2026-08-25T10:00:00Z",
    "run_id": "abc123",
    "transport": "apify-actor",
    "synthetic": True,
    "contains_pii": False,
}

This is the same meta block returned by the LatAm Synth local MCP server and by the Actor's OUTPUT_DATA record, so an agent can consume any of the three integration paths interchangeably.

---

Tool arguments

Argument	Type	Default	Description
users	int	25	Number of synthetic users to generate. Accepted range: 1–200.
seed	int	42	Random seed for reproducible datasets.
countries	list[str] | None	None	Optional list of Latin American countries to include.

Example:

result = generate_latam_financial_data.invoke(
    {
        "users": 100,
        "seed": 7,
        "countries": ["Colombia"],
    }
)

---

Use inside a LangChain agent

Because generate_latam_financial_data is a LangChain tool, it can be passed directly to an agent.

from langchain.agents import create_agent
from langchain_latam_synth import generate_latam_financial_data

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[generate_latam_financial_data],
)

response = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Generate a small synthetic Colombian fintech dataset "
                    "for testing a savings recommendation agent."
                ),
            }
        ]
    }
)

A model with tool-calling support can decide when to invoke LatAm Synth based on the user's request.

---

Example agent use cases

langchain-latam-synth is useful when an agent needs realistic financial test data without accessing production customer data.

Examples include:

• generating QA fixtures for fintech applications
• evaluating financial AI agents
• testing savings or recommendation assistants
• creating synthetic datasets for demos and POCs
• bootstrapping ML experiments
• validating data pipelines
• generating reproducible test datasets for regression tests

---

Privacy

LatAm Synth is designed to generate synthetic financial behavior for development and experimentation.

The generator produces synthetic users, savings goals, and transactions rather than returning production customer records. It is intended for scenarios where realistic financial structure is useful but personally identifiable information should not be used.

For details about the source generator and its statistical calibration, see the LatAm Synth repository.

---

How it works

The LangChain integration is intentionally small:

LangChain agent
      |
      | tool call
      v
generate_latam_financial_data
      |
      | Apify API
      v
LatAm Synth Actor
      |
      v
synthetic users + goals + transactions

The package starts the hosted Actor, waits for the run to finish, reads the generated JSON output, and returns the structured data to LangChain.

---

Related MCP access

LatAm Synth is also available independently to MCP-compatible AI clients through the hosted Apify MCP Server.

MCP endpoint:

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

Official MCP Registry server name:

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

The MCP server and this LangChain package are two different integration paths to the same underlying LatAm Synth generator:

LangChain agents -> langchain-latam-synth -> Apify Actor
MCP clients      -> Apify MCP Server      -> Apify Actor
MCP clients      -> latam-synth-mcp (local, stdio, no Apify)

All three return the same tables with the same referential integrity and the same meta block, because all three are thin adapters over the same generator.

See the LatAm Synth repository for MCP configuration details.

---

Development

git clone https://github.com/jmendozapuche/langchain-latam-synth.git
cd langchain-latam-synth
pip install -e .
pip install pytest
pytest -v

The test suite validates the tool name and schema, input limits, required Apify authentication, and the returned contract against a simulated Apify API — no network calls and no Actor runs are billed while testing.

---

Links

• PyPI package
• GitHub repository
• LatAm Synth source generator
• LatAm Synth Apify Actor
• Official MCP Registry

---

License

MIT