Merge

merge left-joins two DataFrames using LLM-powered agents to resolve the key mapping instead of requiring exact or fuzzy key matches. Agents resolve semantic relationships by reasoning over the data and, when needed, searching the web for external information to establish matches: subsidiaries, regional names, abbreviations, and product-to-parent-company mappings.

Examples

Every operation is a coroutine. Run it with asyncio.run() as below, or await it directly in a Jupyter notebook. Later snippets on this page omit the wrapper for brevity.

import asyncio

from pandas import DataFrame
from futuresearch.ops import merge

software_products = DataFrame([{"product": "Photoshop"}, {"product": "Slack"}])
approved_vendors = DataFrame([{"vendor": "Adobe"}, {"vendor": "Salesforce"}])


async def main():
    result = await merge(
        task="Match each software product to its parent company",
        left_table=software_products,   # table being enriched; all rows kept
        right_table=approved_vendors,    # lookup/reference table; columns appended
        # merge_on_left/merge_on_right omitted: auto-detection handles most cases.
        # Only specify them when you expect exact string matches on specific columns
        # or want to draw agent attention to them.
    )
    print(result.data.head())


asyncio.run(main())

For ambiguous cases, add context. Here merge_on_left/merge_on_right are set because the column names ("sponsor", "company") are too generic for auto-detection:

result = await merge(
    task="""
        Match clinical trial sponsors to parent pharma companies.

        Watch for:
        - Subsidiaries (Genentech → Roche, Janssen → J&J)
        - Regional names (MSD is Merck outside the US)
        - Abbreviations (BMS → Bristol-Myers Squibb)
    """,
    left_table=trials,              # table being enriched; all rows kept
    right_table=pharma_companies,   # lookup table
    merge_on_left="sponsor",        # specified: draws agent attention to this column
    merge_on_right="company",       # specified: draws agent attention to this column
)
print(result.data.head())

What you get back

A DataFrame with all left table columns plus matched right table columns. Rows that don't match get nulls for the right columns (like a left join).

Parameters

Performance

Via MCP

MCP tool: futuresearch_merge

Related docs

Blog posts

• Software Supplier Matching
• HubSpot Contact Merge
• CRM Merge Workflow