Metadata-Version: 2.4
Name: langchain-latam-synth
Version: 0.1.1
Summary: LangChain tools for generating privacy-safe synthetic financial data for Latin American fintech applications.
Project-URL: Homepage, https://github.com/jmendozapuche/langchain-latam-synth
Project-URL: Repository, https://github.com/jmendozapuche/langchain-latam-synth
Project-URL: Source Generator, https://github.com/jmendozapuche/latam-synth
Project-URL: Issues, https://github.com/jmendozapuche/langchain-latam-synth/issues
Project-URL: MCP Registry, https://registry.modelcontextprotocol.io
License: MIT
License-File: LICENSE
Keywords: ai-agents,financial-data,fintech,langchain,latin-america,machine-learning,synthetic-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.10
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: langchain-core<2.0.0,>=1.0.0
Description-Content-Type: text/markdown

# langchain-latam-synth

[![PyPI version](https://img.shields.io/pypi/v/langchain-latam-synth.svg)](https://pypi.org/project/langchain-latam-synth/)
[![Python](https://img.shields.io/pypi/pyversions/langchain-latam-synth.svg)](https://pypi.org/project/langchain-latam-synth/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**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:

```text
generate_latam_financial_data
```

It generates linked synthetic:

- financial users
- savings goals
- deposit and withdrawal transactions

The underlying generator is [LatAm Synth](https://github.com/jmendozapuche/latam-synth), executed through its hosted Apify Actor.

---

## Installation

```bash
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

```bash
export APIFY_TOKEN="your-apify-token"
```

### Windows PowerShell

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

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

---

## Quick start

```python
from langchain_latam_synth import generate_latam_financial_data

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

print(result["run_id"])
print(len(result["users"]))
print(len(result["goals"]))
print(len(result["transactions"]))
```

The tool returns a dictionary with:

```text
run_id
generator
users
goals
transactions
```

---

## 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:

```python
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.

```python
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](https://github.com/jmendozapuche/latam-synth).

---

## How it works

The LangChain integration is intentionally small:

```text
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:

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

Official MCP Registry server name:

```text
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:

```text
LangChain agents -> langchain-latam-synth -> Apify Actor
MCP clients      -> Apify MCP Server      -> Apify Actor
```

See the [LatAm Synth repository](https://github.com/jmendozapuche/latam-synth) for MCP configuration details.

---

## Development

```bash
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, and required Apify authentication.

---

## Links

- [PyPI package](https://pypi.org/project/langchain-latam-synth/)
- [GitHub repository](https://github.com/jmendozapuche/langchain-latam-synth)
- [LatAm Synth source generator](https://github.com/jmendozapuche/latam-synth)
- [LatAm Synth Apify Actor](https://apify.com/active_yardstick/latam-synth)
- [Official MCP Registry](https://registry.modelcontextprotocol.io)

---

## License

MIT
