Futuresearch AI

https://futuresearch.ai/docs
Admin
Comprehensive documentation and resources for the Futuresearch AI platform.
Tokens:58,876
Snippets:601
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### MCP Tools Workflow Example

Source: https://futuresearch.ai/docs/progress-monitoring

Illustrates the sequence of commands used with MCP tools to start an operation, monitor its progress, and retrieve results.

```bash
futuresearch_agent        →  start the operation, get a task_id and session URL
futuresearch_progress     →  check status (blocks for a few seconds, then returns progress)
futuresearch_progress     →  check again (the agent loops automatically)
futuresearch_results      →  download results when complete
```

--------------------------------

### Initialize FutureSearch Forecasting

Source: https://futuresearch.ai/docs/find-profitable-prediction-market-trades

Basic Python setup to import necessary libraries and initialize the forecasting operation. This is the starting point for programmatic analysis.

```python
import asyncio
import pandas as pd
from futuresearch.ops import forecast

# Step 1: Collect questions and live prices.

```

--------------------------------

### Install FutureSearch Skill for Gemini from GitHub

Source: https://futuresearch.ai/docs

Installs the FutureSearch skill for Gemini directly from GitHub. Supports user-level or project-level installation. Requires enabling skills in Gemini settings.

```bash
gemini skills install https://github.com/futuresearch/futuresearch-python --path skills/futuresearch-python

```

```bash
/settings > Preview Features > Enable
/settings > Agent Skills > Enable
/skills enable futuresearch-python
/skills reload

```

--------------------------------

### Install and Configure FutureSearch SDK

Source: https://futuresearch.ai/docs/case-studies/llm-web-research-agents-at-scale

Installs the futuresearch library if not already present and sets up the API key from environment variables. Ensure you have a valid API key.

```python
# Setup: install futuresearch if needed and configure API key
try:
    import futuresearch
except ImportError:
    %pip install futuresearch

import os
if "FUTURESEARCH_API_KEY" not in os.environ:
    os.environ["FUTURESEARCH_API_KEY"] = "your-api-key-here"  # Get one at futuresearch.ai

```

--------------------------------

### Install FutureSearch and Dependencies

Source: https://futuresearch.ai/docs/case-studies/deep-research-bench-pareto-analysis

Installs the necessary Python libraries for fetching benchmark data and performing analysis. Run this in your Python environment.

```bash
pip install futuresearch requests pandas

```

--------------------------------

### Install FutureSearch and Set API Key

Source: https://futuresearch.ai/docs/case-studies/match-software-vendors-to-requirements

Install the FutureSearch Python SDK and set your API key as an environment variable. Obtain your API key from the FutureSearch app.

```bash
pip install futuresearch
export FUTURESEARCH_API_KEY=your_key_here  # Get one at futuresearch.ai/app/api-key

```

--------------------------------

### Install FutureSearch Python SDK using uv

Source: https://futuresearch.ai/docs

Installs the FutureSearch Python SDK using uv. Requires Python 3.12+ and uv. An API key must be set as an environment variable.

```bash
uv add futuresearch

```

```bash
export FUTURESEARCH_API_KEY=sk-cho-...

```

--------------------------------

### Install FutureSearch Extension for Gemini

Source: https://futuresearch.ai/docs

Installs the FutureSearch extension for Gemini, which bundles MCP server and skills. Requires Git and enabling the extension and skills in Gemini CLI.

```bash
gemini extensions install https://github.com/futuresearch/futuresearch-python --ref main

```

```bash
gemini extensions enable futuresearch [--scope <user or workspace>]

```

```bash
/settings > Preview Features > Enable
/settings > Agent Skills > Enable
/skills enable futuresearch-python
/skills reload
/model > Manual > gemini-3-pro-preview

```

--------------------------------

### Install FutureSearch Python SDK

Source: https://futuresearch.ai/docs/getting-started

Install the FutureSearch Python SDK using pip. Requires Python 3.12+.

```bash
pip install futuresearch

```

--------------------------------

### Install FutureSearch Skill for Codex from GitHub

Source: https://futuresearch.ai/docs

Installs the FutureSearch skill for Codex by cloning the Python SDK repository from GitHub. Requires restarting Codex and supplying an API key.

```bash
>>> codex
>>> Install the skill from github.com/futuresearch/futuresearch-python found under skills/futuresearch-python

```

```bash
python ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo futuresearch/futuresearch-python --path skills/futuresearch-python

```

```bash
export FUTURESEARCH_API_KEY=sk-cho...
codex

```

--------------------------------

### Install FutureSearch Python Skill via Claude Code Plugin

Source: https://futuresearch.ai/docs/skills-vs-mcp

Use these commands to add and install the FutureSearch Python skill as a plugin within Claude Code. This simplifies the setup process for using the skill.

```bash
claude plugin marketplace add futuresearch/futuresearch-python
claude plugin install futuresearch@futuresearch
```

--------------------------------

### Progress Monitoring Callback Example

Source: https://futuresearch.ai/docs/error-handling

Illustrates the output format of a progress monitoring callback, showing the progression of task completion and highlighting when failures occur.

```text
 5/10  50% |  5 running
 7/10  70% |  3 running | 1 failed
10/10 100% | 2 failed

```

--------------------------------

### Install FutureSearch Python SDK using pip

Source: https://futuresearch.ai/docs

Installs the FutureSearch Python SDK using pip. Requires Python 3.12+ and pip. An API key must be set as an environment variable.

```bash
pip install futuresearch

```

```bash
export FUTURESEARCH_API_KEY=sk-cho-...

```

--------------------------------

### Install FutureSearch SDK

Source: https://futuresearch.ai/docs/forecast-outcomes-for-list-of-entities

Add the FutureSearch SDK to your project using pip. Ensure you have obtained an API key from futuresearch.ai/app/api-key and set it as an environment variable.

```bash
pip install futuresearch
export FUTURESEARCH_API_KEY=your_key_here  # Get one at futuresearch.ai/app/api-key
```

--------------------------------

### Install FutureSearch Plugin for Claude Code

Source: https://futuresearch.ai/docs

Installs the FutureSearch plugin for Claude Code, which includes an MCP server and a Python SDK skill. No API key is needed.

```bash
claude plugin marketplace add futuresearch/futuresearch-python
claude plugin install futuresearch@futuresearch

```

--------------------------------

### Binary Forecast Example

Source: https://futuresearch.ai/docs/reference/FORECAST

Generates a binary forecast for a YES/NO question. The result includes the probability of a YES resolution and the rationale.

```python
from pandas import DataFrame
from futuresearch.ops import forecast

questions = DataFrame([
    {
        "question": "Will the US Federal Reserve cut rates by at least 25bp before July 1, 2027?",
        "resolution_criteria": "Resolves YES if the Fed announces at least one rate cut of 25bp or more at any FOMC meeting between now and June 30, 2027.",
    },
])

result = await forecast(input=questions, forecast_type="binary")
print(result.data[["question", "probability", "rationale"]])

```

--------------------------------

### FutureSearch Multi-Agent Tool Call Example

Source: https://futuresearch.ai/docs/case-studies/research-formal-verification-for-ai

This example shows the structure of a tool call to FutureSearch's multi_agent function. It includes the task, effort level, specific directions for agents, and a response schema to shape the output.

```text
Tool: futuresearch_multi_agent
├─ task: "Research the current state of formal verification for AI/ML systems"
├─ effort_level: "high"
├─ directions: [
│    "Neural network verification tools and their capabilities (a,b-CROWN...)",
│    "The scalability problem for verifying LLMs and transformers",
│    "Real-world deployments in safety-critical applications",
│    "Theoretical and practical limits, including undecidability",
│    "Alternative and hybrid approaches to AI assurance"
│ ]
└─ response_schema: {overall_maturity, what_works, key_limitations,
                     frontier_ai_gap, real_deployments, trajectory}

```

--------------------------------

### Set API Key and Run Example Script

Source: https://futuresearch.ai/docs/getting-started

Set your FutureSearch API key as an environment variable before running Python scripts.

```bash
export FUTURESEARCH_API_KEY=sk-cho...
python3 example_script.py

```

--------------------------------

### Python SDK Example for Ranking Permit Times

Source: https://futuresearch.ai/docs/case-studies/research-and-rank-permit-times

Demonstrates how to use the FutureSearch Python SDK to read a CSV, create a session, and rank cities by permit processing time. Ensure the 'texas_cities.csv' file is in your working directory.

```python
import asyncio
import pandas as pd
from futuresearch import create_session
from futuresearch.ops import rank

texas_cities_df = pd.read_csv("texas_cities.csv")

async def main():
    async with create_session(name="Texas Permit Times Research") as session:
        result = await rank(
            session=session,
            task="""
                Research the residential building permit processing time for
                this Texas city. Find official data from the city's permit
                department. Return the number of business days.
            """,
            input=texas_cities_df,
            field_name="score",
        )
        return result.data

results = asyncio.run(main())

```

--------------------------------

### MCP Progress Tool - Running Task with Failures

Source: https://futuresearch.ai/docs/error-handling

Example output from the MCP progress tool indicating a running task that has encountered some failures.

```text
Running: 7/10 complete, 3 running, 1 failed (45s elapsed)

```

--------------------------------

### Sample Qualified Postings

Source: https://futuresearch.ai/docs/filter-dataframe-with-llm

This snippet shows examples of qualified job postings, including company, role, location, and salary information.

```text
Bloomberg | Senior Software Engineer | Hybrid (NYC) | $160k - $240k USD + bonus
KoBold Metals | Senior Infrastructure Engineer | Remote (USA) | $170k - $230k
EnergyHub | Director of Engineering | Remote (US) | Salary $225k
Gladly | Staff Software Engineer | Remote (US, Colombia) | $60k–$215k + Equity
```

--------------------------------

### MCP Tools: Command-line Progress Output

Source: https://futuresearch.ai/docs/progress-monitoring

Example of progress updates displayed in the console when using MCP tools for FutureSearch operations.

```text
Running: 20/50 complete, 30 running (45s elapsed)
```

--------------------------------

### FutureSearch Rank Tool Usage Example

Source: https://futuresearch.ai/docs/case-studies/research-and-rank-permit-times

Illustrates the parameters used by the futuresearch_rank tool when called by Claude. This shows the task, input file, and field details for ranking.

```text
Tool: futuresearch_rank
├─ task: "Research residential building permit processing time for this Texas city..."
├─ input_csv: "/Users/you/texas_cities.csv"
├─ field_name: "permit_days"
├─ field_type: "int"
└─ ascending_order: true

```

--------------------------------

### Binary Forecasting Prompt for Claude

Source: https://futuresearch.ai/docs/turn-claude-into-forecaster

Example prompt for Claude to forecast the probability of a binary event. Claude will call the `futuresearch_forecast` tool.

```text
Will Anthropic IPO before July 2027? Forecast the probability.

```

--------------------------------

### Example Prompt for Screening Questions

Source: https://futuresearch.ai/docs/find-profitable-prediction-market-trades

Use this prompt to instruct Claude to find interesting prediction-market questions within specific categories. Claude will use the futuresearch_agent tool to compile the list.

```text
Find 100 interesting prediction-market questions where there might be
profit opportunity. Focus on politics, AI, economics, and geopolitics.
Skip sports and crypto.

```

--------------------------------

### Example Claude Prompt for Screening Recalls

Source: https://futuresearch.ai/docs/case-studies/llm-powered-screening-at-scale

This is an example prompt to give to Claude to screen FDA product recalls. It specifies the dataset and the criteria for relevance based on a child's birth date.

```text
Screen this FDA product recalls dataset to find recalls of products that I might
have used for my child born on 2021-08-01.

```

--------------------------------

### Example End-to-End Flow for MCP Operations

Source: https://futuresearch.ai/docs/mcp-server

Demonstrates a typical workflow involving data upload, task submission, progress tracking, and result retrieval using MCP server tools. This flow is simplified in MCP clients with widget UIs.

```text
1. futuresearch_upload_data(source="https://example.com/leads.csv")
   → artifact_id, session_id

2. futuresearch_agent(
     task="Find each company's latest funding round and lead investors",
     artifact_id=...,
   )
   → task_id (~0.6s)

3. futuresearch_progress(task_id=...)
   → "Running: 5/50 complete, 8 running (15s elapsed)" + cursor

4. futuresearch_progress(task_id=..., cursor=...)
   → "Completed: 49 succeeded, 1 failed (142s total)"

5. futuresearch_results(task_id=...)
   → preview rows, total count, download URL

```

--------------------------------

### Binary Forecasting Example

Source: https://futuresearch.ai/docs/forecast-outcomes-for-list-of-entities

Demonstrates binary forecasting to predict whether a candidate will win. The `forecast_type` is set to 'binary', and the input DataFrame should contain relevant questions for each candidate.

```python
# Binary: "Will each candidate win?"
result = await forecast(
    input=candidates,
    forecast_type="binary",
)
```

--------------------------------

### MCP Tools: Completion Output

Source: https://futuresearch.ai/docs/progress-monitoring

Example of the final output from MCP tools indicating successful completion and the location of saved results.

```text
Completed: 50/50 (0 failed) in 100s
... 
Saved 50 rows to /path/to/output.csv
```

--------------------------------

### Date Forecast Example

Source: https://futuresearch.ai/docs/reference/FORECAST

Generates a date forecast for a timing question. The output includes percentile date estimates (p10 to p90) for the specified output field, formatted as YYYY-MM-DD.

```python
result = await forecast(
    input=DataFrame([
        {
            "question": "When will Anthropic IPO?",
            "resolution_criteria": "Date Anthropic common shares first trade on a public exchange.",
        },
    ]),
    forecast_type="date",
    output_field="ipo_date",
)
print(result.data[["ipo_date_p10", "ipo_date_p50", "ipo_date_p90", "rationale"]])

```

--------------------------------

### Numeric Forecast Example

Source: https://futuresearch.ai/docs/reference/FORECAST

Generates a numeric forecast for a continuous quantity. The output provides percentile estimates (p10 to p90) for the specified output field and units.

```python
result = await forecast(
    input=DataFrame([
        {
            "question": "What will the price of Brent crude oil be on December 31, 2026?",
            "resolution_criteria": "Closing spot price of Brent crude oil (ICE) on Dec 31, 2026.",
        },
    ]),
    forecast_type="numeric",
    output_field="price",
    units="USD per barrel",
)
print(result.data[["price_p10", "price_p25", "price_p50", "price_p75", "price_p90"]])

```

--------------------------------

### FutureSearch Progress and Results Tool Calls

Source: https://futuresearch.ai/docs/case-studies/research-formal-verification-for-ai

These examples show the output from FutureSearch's progress and results tools, indicating the status of the multi-agent research and where the final synthesized data is saved.

```text
Tool: futuresearch_progress
→ Running: 5 agents researching (60s elapsed)

...

Tool: futuresearch_progress
→ Completed in 249s. Synthesized 1 row, 6 fields.

Tool: futuresearch_results
→ Saved to /Users/you/formal_verification.csv

```

--------------------------------

### Numeric Forecasting Prompt for Claude

Source: https://futuresearch.ai/docs/turn-claude-into-forecaster

Example prompt for Claude to forecast numeric values like market capitalization. Claude automatically uses percentile mode.

```text
Forecast the first-day market cap of Anthropic and OpenAI when they IPO,
in billions of USD.

```

--------------------------------

### Screen Job Postings with Claude Prompt

Source: https://futuresearch.ai/docs/filter-dataframe-with-llm

Use a detailed prompt in Claude to screen job postings based on remote-friendliness, seniority, and salary disclosure. This example shows the expected output from Claude's interaction with FutureSearch tools.

```text
Screen hn_jobs_screen.csv to find job postings that meet ALL THREE criteria:

1. Remote-friendly: explicitly allows remote work, hybrid, WFH,
   teams, or "work from anywhere"
2. Senior-level: title contains Senior/Staff/Lead/Principal/Architect, OR
   requires 5+ years experience, OR mentions "founding engineer"
3. Salary disclosed: specific compensation numbers are mentioned.
   "$150K-200K" qualifies. "Competitive" or "DOE" does not.

```

--------------------------------

### Sequential Prompting for Prediction Market Analysis

Source: https://futuresearch.ai/docs/find-profitable-prediction-market-trades

This sequence of prompts guides Claude through the entire process: finding questions, forecasting, and analyzing potential profits using live data. Ensure the FutureSearch connector is added.

```text
> Find 100 interesting prediction-market questions where there might be profit opportunity. Focus on politics, AI, economics, and geopolitics.
Then:
> Forecast these questions.
Then:
> Use the prediction-market API to fetch live order books and compute expected value, sorted by annualized ROI.

```

--------------------------------

### Deduplication with 'select' Strategy

Source: https://futuresearch.ai/docs/reference/DEDUPE

Use the 'select' strategy to pick the best representative row from each duplicate cluster. A `strategy_prompt` can guide the selection process, for example, preferring records with more complete information.

```python
result = await dedupe(
    input=crm_data,
    equivalence_relation="Same legal entity",
    strategy="select",
    strategy_prompt="Prefer the record with the most complete contact information",
)
deduped = result.data[result.data["selected"] == True]
```

--------------------------------

### Structured Output with agent_map and Pydantic

Source: https://futuresearch.ai/docs/reference/RESEARCH

Leverage agent_map with a custom Pydantic model to get structured output for each row. This example retrieves annual revenue, employee count, and funding round information.

```python
from pandas import DataFrame
from pydantic import BaseModel, Field
from futuresearch.ops import agent_map

companies = DataFrame([
    {"company": "Stripe"},
    {"company": "Databricks"},
    {"company": "Canva"},
])

class CompanyFinancials(BaseModel):
    annual_revenue_usd: int = Field(description="Most recent annual revenue in USD")
    employee_count: int = Field(description="Current number of employees")
    last_funding_round: str = Field(description="Most recent funding round, e.g. 'Series C'")

result = await agent_map(
    task="Research each company's financials and latest funding",
    input=companies,
    response_model=CompanyFinancials,
)
print(result.data.head())

```

--------------------------------

### API Result Response for Failed Task

Source: https://futuresearch.ai/docs/error-handling

Example JSON response from the `GET /tasks/{task_id}/result` API endpoint when a task has failed, showing overall status, error summary, and individual row statuses.

```json
{
  "task_id": "...",
  "status": "failed",
  "artifact_id": "...",
  "error": "2/10 rows failed",
  "data": [
    {"name": "Example A", "answer": "...", "_status": "completed", "_error": null},
    {"name": "Example B", "answer": null, "_status": "failed", "_error": "Content policy violation: the model refused to process this input."}
  ]
}

```

--------------------------------

### Initialize FutureSearch SDK in Python

Source: https://futuresearch.ai/docs/rank-by-external-metric

Initialize the FutureSearch SDK in a Python script. This involves importing necessary libraries and setting up the API key.

```python
import asyncio
import requests
import pandas as pd
from futuresearch.ops import rank

```

--------------------------------

### Python SDK: Basic Progress Monitoring

Source: https://futuresearch.ai/docs/progress-monitoring

Use the `print_progress` callback to display progress updates directly in the console while a task is running.

```python
from futuresearch import print_progress

result = await task.await_result(on_progress=print_progress)
```

--------------------------------

### Create and Use a FutureSearch Session

Source: https://futuresearch.ai/docs/getting-started

Demonstrates creating an explicit session for grouping related operations like classification and ranking. The session URL allows monitoring in the web UI.

```python
from futuresearch import create_session
from futuresearch.ops import classify, rank

async with create_session(name="Lead Qualification") as session:
    # Get the URL to view this session in the dashboard
    print(f"View at: {session.get_url()}")

    # All operations share this session
    classified = await classify(
        session=session,
        task="Has a company email domain (not gmail, yahoo, etc.)",
        categories=["qualified", "unqualified"],
        input=leads,
    )

    ranked = await rank(
        session=session,
        task="Score by likelihood to convert",
        input=classified.data,
        field_name="conversion_score",
    )

```

--------------------------------

### FutureSearch Results Tool Usage Example

Source: https://futuresearch.ai/docs/case-studies/research-and-rank-permit-times

Shows the output of the futuresearch_results tool, indicating that the processed data has been saved to a CSV file.

```text
Tool: futuresearch_results
→ Saved 30 rows to /Users/you/permit_times.csv

```

--------------------------------

### Fetch Top PyPI Packages

Source: https://futuresearch.ai/docs/rank-by-external-metric

Fetches a list of top PyPI packages and prepares a DataFrame for analysis. Skips the top AWS libraries.

```python
response = requests.get(
    "https://hugovk.github.io/top-pypi-packages/top-pypi-packages-30-days.min.json"
)
packages = response.json()["rows"][50:350]  # Skip AWS libs at top
df = pd.DataFrame(packages).rename(
    columns={"project": "package", "download_count": "monthly_downloads"}
)
```

--------------------------------

### Instruct Claude to Run Merge Experiments

Source: https://futuresearch.ai/docs/case-studies/understanding-costs-and-speed-for-merge

Provide instructions to Claude for running a series of merge experiments with varying data and matching strategies, including cost reporting.

```text
Create a test dataset of 10 companies with exact names, then merge them.
Then create a version with typos and merge again. Then test semantic
matching (Instagram to Meta, YouTube to Alphabet). Then test pharma
subsidiaries (Genentech to Roche, MSD to Merck). Show costs for each.

```

--------------------------------

### Python SDK for SaaS Pricing Lookup

Source: https://futuresearch.ai/docs/add-column-web-lookup

This Python script uses the FutureSearch SDK to read a CSV of SaaS products, perform parallel web research to find the lowest paid tier's annual price and tier name, and prints the results.

```python
import asyncio
import pandas as pd
from pydantic import BaseModel, Field
from futuresearch import create_session, print_progress
from futuresearch.ops import agent_map_async


class PricingInfo(BaseModel):
    lowest_paid_tier_annual_price: float = Field(
        description="Annual price in USD for the lowest paid tier. "
                    "Use monthly price * 12 if only monthly shown. "
                    "0 if no paid tier exists."
    )
    tier_name: str = Field(
        description="Name of the lowest paid tier (e.g. 'Pro', 'Starter', 'Basic')"
    )

async def main():
    df = pd.read_csv("saas_products.csv")  # Single column: product

    async with create_session(name="SaaS pricing lookup") as session:
        print("Submitting task...")
        job = await agent_map_async(
            session=session,
            task="""
                Find the pricing for this SaaS product's lowest paid tier.
                Visit the product's pricing page to find this information.

                Look for the cheapest paid plan (not free tier). Report:
                - The annual price in USD (if monthly, multiply by 12)
                - The name of that tier

                If the product has no paid tier or pricing isn't public, use 0.
            """,
            input=df,
            response_model=PricingInfo,
        )
        result = await job.await_result(on_progress=print_progress)
    print(result.data)

asyncio.run(main())

```

--------------------------------

### Measure Merge Costs with FutureSearch SDK

Source: https://futuresearch.ai/docs/case-studies/understanding-costs-and-speed-for-merge

Python code to measure the cost of merge operations using the FutureSearch SDK, including exact and semantic matching examples.

```python
import asyncio
import pandas as pd
from futuresearch import create_session, get_billing_balance
from futuresearch.ops import merge

async def measure_merge(name, task, left_table, right_table, **kwargs):
    balance_before = await get_billing_balance()
    async with create_session(name=name) as session:
        result = await merge(
            task=task,
            session=session,
            left_table=left_table,
            right_table=right_table,
            **kwargs,
        )
    balance_after = await get_billing_balance()
    cost = balance_before.current_balance_dollars - balance_after.current_balance_dollars
    return result.data, cost

# Exact matches: $0.00
result, cost = await measure_merge(
    "Exact matches only",
    "Match companies by name.",
    companies_exact, revenue_exact,
    merge_on_left="company", merge_on_right="company_name",
)

# Semantic matches: ~$0.03
result, cost = await measure_merge(
    "Semantic matches",
    "Match companies. Instagram and WhatsApp are owned by Meta.",
    companies_semantic, revenue_exact,
    merge_on_left="company", merge_on_right="company_name",
)

```

--------------------------------

### futuresearch_task_cost

Source: https://futuresearch.ai/docs/mcp-server

Get the billed cost of a completed task. There is a delay between task completion and cost calculation; this function returns `pending` if the cost has not yet been settled. It requires a `task_id` as a parameter.

```APIDOC
## futuresearch_task_cost

### Description
Get the billed cost of a completed task. Returns `pending` if not yet settled.

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The task ID.
```

--------------------------------

### Python SDK: Multi-Stage Lead Qualification Pipeline

Source: https://futuresearch.ai/docs/case-studies/multi-stage-lead-qualification

Execute a multi-stage lead qualification pipeline using the FutureSearch Python SDK. This involves scoring, filtering, estimating team sizes, and final classification.

```python
import asyncio
import pandas as pd
from futuresearch import create_session
from futuresearch.ops import rank, classify

async def main():
    async with create_session(name="Multi-Stage Lead Screening") as session:
        # Stage 1: Score by research tool adoption
        scored = await rank(
            session=session,
            task="Score funds 0-100 on likelihood to adopt research tools",
            input=funds_df,
            field_name="score",
        )

        # Stage 2: Filter by threshold
        filtered = scored.data[scored.data["score"] >= 50].copy()

        # Stage 3: Research team sizes
        with_teams = await rank(
            session=session,
            task="Estimate investment team size per fund",
            input=filtered,
            field_name="team_size_estimate",
        )

        # Stage 4: Final screening
        final = await classify(
            session=session,
            task="Include if score >= 70 OR team size <= 5",
            categories=["include", "exclude"],
            input=with_teams.data,
        )
        return final.data

results = asyncio.run(main())

```

--------------------------------

### Authenticate FutureSearch in Claude Code

Source: https://futuresearch.ai/docs

Launches Claude Code and authenticates with FutureSearch via MCP. This is a post-installation step.

```bash
claude
/mcp 	select FutureSearch 	Authenticate

```

--------------------------------

### Classify Companies Based on Criteria

Source: https://futuresearch.ai/docs/getting-started

Example of using the classify operation to categorize companies based on specific criteria like remote-friendliness, seniority, and salary disclosure. Requires pandas and asyncio.

```python
import asyncio
import pandas as pd
from futuresearch.ops import classify

companies = pd.DataFrame([
    {"company": "Airtable",},
    {"company": "Vercel",},
    {"company": "Notion",}
])

async def main():
    result = await classify(
        task="""Qualifies if: 1. Remote-friendly, 2. Senior, and 3. Discloses salary""",
        categories=["yes", "no"],
        input=companies,
    )
    print(result.data.head())

asyncio.run(main())

```

--------------------------------

### FutureSearch Progress and Results Tools

Source: https://futuresearch.ai/docs/case-studies/forecast-spacex-valuation

Demonstrates the usage of futuresearch_progress to monitor task status and futuresearch_results to retrieve the forecast data. The task completes in approximately 410 seconds.

```text
Tool: futuresearch_progress
├─ task_id: "c41a..."
→ Running: 0/7 complete, 7 running (30s elapsed)

...

Tool: futuresearch_progress
→ Completed: 7/7 (0 failed) in 410s.

Tool: futuresearch_results
├─ task_id: "c41a..."
├─ output_path: "/Users/you/spacex_sotp.csv"
→ Saved 7 rows to /Users/you/spacex_sotp.csv

```

--------------------------------

### Generate a List of Items

Source: https://futuresearch.ai/docs/reference/MULTIAGENT

Set 'return_list=True' to generate one output row per item found. The 'response_schema' should describe a single item, and an '_expand_index' column will be added to the result.

```python
import pandas as pd
from futuresearch.ops import multi_agent

result = await multi_agent(
    task="Find startups that sell training data, benchmarks, or RL environments to frontier AI labs",
    input=pd.DataFrame(),
    return_list=True,
    response_schema={
        "type": "object",
        "properties": {
            "company_name": {"type": "string"},
            "category": {"type": "string"},
            "funding_stage": {"type": "string"},
        },
        "required": ["company_name", "category", "funding_stage"],
    },
)
print(result.data)  # one row per company

```

--------------------------------

### Define Pydantic Model for Multi-Label Classification

Source: https://futuresearch.ai/docs/classify-dataframe-rows-llm

Example of a Pydantic model for multi-label classification using Python's `list[str]` type. It includes a list of all applicable tags and a primary tag.

```python
class MultiLabel(BaseModel):
    tags: list[str] = Field(description="All applicable tags for this item")
    primary_tag: str = Field(description="The most relevant tag")

```

--------------------------------

### Instruct Claude to Screen Job Postings

Source: https://futuresearch.ai/docs/case-studies/screen-job-postings-by-criteria

Provide instructions to Claude for screening job postings based on remote-friendly, senior-level, and salary disclosed criteria.

```bash
Screen each job posting to find roles that meet ALL THREE criteria:
1. Remote-friendly: explicitly allows remote, hybrid, or distributed work
2. Senior-level: title includes Senior/Staff/Lead/Principal, or requires 5+ years
3. Salary disclosed: specific compensation figures, not "competitive" or "DOE"

```

--------------------------------

### FutureSearch Merge MCP Tool Call

Source: https://futuresearch.ai/docs/case-studies/match-software-vendors-to-requirements

Example of Claude calling the futuresearch_merge MCP tool to merge tables based on company name and ticker. It shows the submitted rows and the session URL.

```text
Tool: futuresearch_merge
├─ task: "Merge the tables based on company name and ticker"
├─ left_csv: "/Users/you/company_info.csv"
└─ right_csv: "/Users/you/valuations.csv"

→ Submitted: 438 rows for merging.
  Session: https://futuresearch.ai/sessions/d7819b7e-c48d-49e5-9f6e-55d972b85467

...

Tool: futuresearch_results
→ Saved 438 rows to /Users/you/merged.csv

```

--------------------------------

### Prompt Claude for Stock Screening

Source: https://futuresearch.ai/docs/case-studies/screen-stocks-by-margin-sensitivity

Instruct Claude to screen a dataset for companies whose profit margins are negatively impacted by rising oil prices. This prompt guides the AI's analysis.

```plaintext
Screen this S&P 500 dataset to find companies whose profit margins fall when
oil prices go up.
Consider energy-intensive operations, transportation dependence,
consumer discretionary sensitivity, and historical correlation with oil price spikes.
Exclude energy companies and those with strong pricing power.

```

--------------------------------

### Custom Response Schema Example

Source: https://futuresearch.ai/docs/mcp-server

Defines a JSON schema for custom response objects, specifying properties like annual revenue and employee count. Top-level type must be 'object' with at most 50 properties.

```json
{
  "type": "object",
  "properties": {
    "annual_revenue": {
      "type": "integer",
      "description": "Annual revenue in USD"
    },
    "employee_count": {
      "type": "integer",
      "description": "Number of employees"
    }
  },
  "required": ["annual_revenue"]
}
```

--------------------------------

### Filter Job Postings with FutureSearch Python SDK

Source: https://futuresearch.ai/docs/filter-dataframe-with-llm

Use the FutureSearch Python SDK to programmatically filter job postings based on complex criteria. This example defines the criteria and uses the `classify` operation.

```python
import asyncio
import pandas as pd
from pydantic import BaseModel, Field
from futuresearch.ops import classify

jobs = pd.read_csv("hn_jobs_screen.csv")  # 3,616 job postings

class JobScreenResult(BaseModel):
    qualifies: bool = Field(description="True if meets ALL criteria")

async def main():
    result = await classify(
        task="""
        A job posting qualifies if it meets ALL THREE criteria:

        1. Remote-friendly: Explicitly allows remote work, hybrid, WFH,
           distributed teams, or "work from anywhere".

        2. Senior-level: Title contains Senior/Staff/Lead/Principal/Architect,
           OR requires 5+ years experience, OR mentions "founding engineer".

        3. Salary disclosed: Specific compensation numbers are mentioned.
           "$150K-200K" qualifies. "Competitive" or "DOE" does not.
        """,
        categories=["yes", "no"],
        input=jobs,
        response_model=JobScreenResult,
    )


```

--------------------------------

### Programmatic IPO Valuation Forecasting with FutureSearch SDK

Source: https://futuresearch.ai/docs/case-studies/forecast-anthropic-openai-ipo-valuation

Use the FutureSearch Python SDK to programmatically forecast IPO market caps. This script defines input questions and background for Anthropic and OpenAI, then uses the `forecast` operation to generate percentile distributions for market cap.

```python
import asyncio
import pandas as pd
from futuresearch import create_session
from futuresearch.ops import forecast

valuation_questions = pd.DataFrame([
    {
        "company": "Anthropic",
        "question": "What will Anthropic's first-day public market cap be on its IPO?",
        "resolution_criteria": "First-day closing market cap in billions USD on the day Anthropic lists on a public exchange.",
        "background": "Anthropic raised $30B at a $380B valuation in early 2026, on roughly $19B ARR. Engaged Wilson Sonsini in late 2025; talks with JPMorgan, Goldman, Morgan Stanley.",
    },
    {
        "company": "OpenAI",
        "question": "What will OpenAI's first-day public market cap be on its IPO?",
        "resolution_criteria": "First-day closing market cap in billions USD on the day OpenAI lists on a public exchange.",
        "background": "OpenAI raised at a $852B valuation in March 2026. CFO Sarah Friar has guided toward a 2027 listing. Recently completed transition to a Public Benefit Corporation.",
    },
])

async def main():
    async with create_session(name="IPO Market Cap Forecasts") as session:
        result = await forecast(
            session=session,
            input=valuation_questions,
            forecast_type="numeric",
            output_field="market_cap",
            units="billions USD",
            effort_level="HIGH",
        )
        return result.data

results = asyncio.run(main())
print(results[["company", "market_cap_p10", "market_cap_p50", "market_cap_p90"]])

```

--------------------------------

### Python SDK for AI Data-Supply Startups Research

Source: https://futuresearch.ai/docs/case-studies/find-startups-selling-to-ai-labs

Use the FutureSearch Python SDK to create a session and run a multi-agent task to find AI data-supply startups. This code returns a list of companies with detailed information.

```python
import asyncio
import pandas as pd
from futuresearch import create_session
from futuresearch.ops import multi_agent

SCHEMA = {
    "type": "object",
    "properties": {
        "company_name": {"type": "string"},
        "category": {"type": "string", "description": "e.g. Training Data, "
                     "Benchmarks/Evals, RL Environments, Red Teaming"},
        "product_description": {"type": "string"},
        "known_customers": {"type": "string"},
        "funding_stage": {"type": "string"},
        "founded_year": {"type": "string"},
    },
    "required": ["company_name", "category", "product_description",
                 "known_customers", "funding_stage", "founded_year"],
}

async def main():
    async with create_session(name="AI data-supply startups") as session:
        result = await multi_agent(
            session=session,
            task=(
                "Find startups that sell training data, benchmarks, evaluation "
                "sets, or RL environments to frontier AI labs such as OpenAI, "
                "Anthropic, Google DeepMind, Meta AI, xAI, and Mistral."
            ),
            input=pd.DataFrame(),
            effort_level="high",
            return_list=True,
            response_schema=SCHEMA,
        )
        return result.data

results = asyncio.run(main())
print(f"{len(results)} companies")
print(results["category"].value_counts())

```

--------------------------------

### Instruct Claude for Web Research

Source: https://futuresearch.ai/docs/add-column-web-lookup

Provide these instructions to Claude to find the annual price of the lowest paid tier for each product in a CSV file. It handles monthly pricing conversion and cases with no paid tiers.

```plaintext
For each product in saas_products.csv, find the annual price of its lowest paid tier.
Visit the product's pricing page to find this. If only monthly pricing is shown,
multiply by 12. Return the price and the tier name. If no paid tier exists, use 0.

```

--------------------------------

### Claude's FutureSearch MCP Tool Calls for Forecasting

Source: https://futuresearch.ai/docs/case-studies/forecast-anthropic-openai-ipo-valuation

Illustrates the sequence of tool calls Claude makes to FutureSearch for forecasting. It begins with the `forecast` call, followed by `progress` checks, and finally `results` retrieval, including the output path for the forecast data.

```text
Tool: futuresearch_forecast
├─ forecast_type: "numeric"
├─ output_field: "market_cap"
├─ units: "billions USD"
├─ effort_level: "HIGH"
└─ input: 2 rows (Anthropic, OpenAI)

→ Submitted: 2 rows for forecasting.
  Session: https://futuresearch.ai/sessions/...
  Task ID: 7af2...

Tool: futuresearch_progress
├─ task_id: "7af2..."
→ Running: 0/2 complete, 2 running (60s elapsed)

... 

Tool: futuresearch_progress
→ Completed: 2/2 (0 failed) in 600s.

Tool: futuresearch_results
├─ task_id: "7af2..."
├─ output_path: "/Users/you/ipo_market_caps.csv"
→ Saved 2 rows with columns: market_cap_p10..p90, units, rationale.

```

--------------------------------

### Consolidate, Dedupe, and Rank Leads with Python SDK

Source: https://futuresearch.ai/docs/chaining-operations

Combines lead data from multiple sources, removes duplicate entries while accounting for variations in company names, and then ranks the remaining leads based on their fit for a specific product. Requires pandas for concatenation and the FutureSearch SDK for dedupe and rank operations.

```python
# Combine sources
all_leads = pd.concat([trade_show, purchased_list, crm_export])

# Dedupe across sources
deduped = await dedupe(
    input=all_leads,
    equivalence_relation="Same company, accounting for Inc/LLC variations, abbreviations, and parent/subsidiary relationships",
)

# Prioritize for outreach
ranked = await rank(
    task="Score by likelihood to need our data integration product",
    input=deduped.data,
    field_name="fit_score",
)

```

--------------------------------

### Research a Question with Multiple Agents

Source: https://futuresearch.ai/docs/api

Employ the multi_agent function to answer a single question using a team of web research agents with diverse angles. The effort_level parameter controls the number of agents, or explicit directions can be provided. Set return_list=True to get a list of outputs.

```python
result = await multi_agent(
    task="Research the current state of formal verification for AI systems",
    input=pd.DataFrame(),
)

```
Tokens:
Raw