futuresearch-python

# FutureSearch Python SDK

[PyPI version](https://pypi.org/project/futuresearch/)
[License: MIT](https://opensource.org/licenses/MIT)
[Python 3.12+](https://www.python.org/downloads/)

<p align="center">
  <img src="images/team-dispatch.svg" alt="FutureSearch dispatches a pool of web research agents that search, forecast, and synthesize answers" width="760">
</p>

An API for forecasting and multi-agent research.

FutureSearch provides endpoints that use web research agents at scale, for higher accuracy than web search or single agent approaches alone can achieve. `forecast` runs a team of forecasters to predict future dates, numbers, and probabilities. `multi_agent` orchestrates multiple researchers to answer one question. `agent_map` runs one research agent over every row of a dataset, scaling to thousands of rows and agents.

Try it yourself in the [app](https://futuresearch.ai/app), or give advanced forecasting and multi-agent capabilities to your AI wherever you use it ([Claude.ai](https://futuresearch.ai/docs/claude-ai), [Claude Cowork](https://futuresearch.ai/docs/claude-cowork), [Claude Code](https://futuresearch.ai/docs/claude-code), or [Gemini/Codex/other AI surfaces](https://futuresearch.ai/docs/)), or point them to this [Python SDK](https://futuresearch.ai/docs/getting-started).

## Installation

Claude.ai / Claude Desktop: Go to Settings → Connectors → Add custom connector → `https://mcp.futuresearch.ai/mcp`

Claude Code:

```bash
claude mcp add futuresearch --scope project --transport http https://mcp.futuresearch.ai/mcp
```

Then sign in with Google.

## Endpoints

| Role                                                                     | What it does                                | Cost      | Scales To |
| ------------------------------------------------------------------------ | ------------------------------------------- | --------- | --------- |
| **[forecast()](https://futuresearch.ai/docs/reference/FORECAST)**        | Predict outcomes                            | 50¢-1.20¢ | 1k rows   |
| **[multi_agent()](https://futuresearch.ai/docs/reference/MULTIAGENT)**   | A team of researchers per for each question | $0.30-$2  | 1k rows   |
| **[agent_map()](https://futuresearch.ai/docs/reference/RESEARCH)**       | One researcher per row of a dataset         | 1–11¢     | 10k rows  |
| **[rank()](https://futuresearch.ai/docs/reference/RANK)**                | Research, then score                        | 1-5¢      | 10k rows  |
| **[classify()](https://futuresearch.ai/docs/reference/CLASSIFY)**        | Research, then categorize                   | 0.1-0.7¢  | 10k rows  |
| **[dedupe() and merge()](https://futuresearch.ai/docs/reference/MERGE)** | Find matching rows                          | 0.2-0.5¢  | 20k rows  |

See the full [API reference](https://futuresearch.ai/docs/api), [guides](https://futuresearch.ai/docs/guides), and [case studies](https://futuresearch.ai/docs/case-studies), (for example, see our [case study](https://futuresearch.ai/docs/case-studies/llm-web-research-agents-at-scale) running a `Research` task on 10k rows, running agents that used 120k LLM calls.)

Or just ask Claude in your interface of choice:

```
Find every startup selling training data and evals to frontier AI labs.
```

```
Take this 10,000-row CSV of drugs and find the FDA regulatory status of each.
```

```
Forecast which of these 500 cancer drug trials are most likely to succeed.
```

---

## SDK Examples

```python
from futuresearch.ops import forecast, agent_map, multi_agent
from pandas import DataFrame

# A team of forecasters: research each question, then predict
result = await forecast(
    input=DataFrame([
        {"question": "When will Anthropic IPO?"},
        {"question": "When will OpenAI IPO?"},
    ]),
    forecast_type="date",
)
print(result.data.head())

# One web research agent per row, in parallel
result = await agent_map(
    task="Find this company's latest funding round and lead investors",
    input=DataFrame([
        {"company": "Anthropic"},
        {"company": "OpenAI"},
        {"company": "Mistral"},
        # ... 100 more rows
    ]),
)
print(result.data.head())

# A team of agents on one question; return_list emits one row per item
result = await multi_agent(
    task="List the most-funded AI infrastructure startups founded since 2023",
    input=DataFrame(),
    return_list=True,
)
print(result.data.head())
```

See the API [docs](https://futuresearch.ai/docs/reference/RESEARCH). Agents are tuned on [Deep Research Bench, Bench To the Future, on prediction markets, and in the stock market.](https://evals.futuresearch.ai/).

## Sessions

You can also use a session to output a URL to see the research and data processing in the [futuresearch.ai/app](https://futuresearch.ai/app) application, which streams the research and makes charts. Or you can use it purely as an intelligent data utility, and [chain intelligent pandas operations](https://futuresearch.ai/docs/chaining-operations) with normal pandas operations where LLMs are used to process every row.

```python
from futuresearch import create_session

async with create_session(name="My Session") as session:
    print(f"View session at: {session.get_url()}")
```

### Async operations

All ops have async variants for background processing:

```python
from futuresearch import create_session
from futuresearch.ops import rank_async

async with create_session(name="Async Ranking") as session:
    task = await rank_async(
        session=session,
        task="Score this organization",
        input=dataframe,
        field_name="score",
    )
    print(f"Task ID: {task.task_id}")  # Print this! Useful if your script crashes.
    # Do other stuff...
    result = await task.await_result()
```

**Tip:** Print the task ID after submitting. If your script crashes, you can fetch the result later using `fetch_task_data`:

```python
from futuresearch import fetch_task_data

# Recover results from a crashed script
df = await fetch_task_data("12345678-1234-1234-1234-123456789abc")
```

### Other AI agent plugins

#### Gemini CLI

[Official Docs](https://geminicli.com/docs/extensions/#installing-an-extension).
Ensure that you're using version >= 0.25.0

```sh
gemini --version
gemini extensions install https://github.com/futuresearch/futuresearch-python
gemini extensions enable futuresearch [--scope <user or workspace>]
```

Then within the CLI

```sh
/settings > Preview Features > Enable
/settings > Agent Skills > Enable
/skills enable futuresearch-python
/skills reload
/model > Manual > gemini-3-pro-preview > (Optionally Remember model, tab)
```

#### Codex CLI

[Official docs](https://developers.openai.com/codex/skills#install-new-skills).
Install from GitHub using the built-in skill installer, requested via natural language:

```sh
codex
$skill-installer from the futuresearch/futuresearch-python github repo, install the futuresearch-python skill at --path skills/futuresearch-python
```

Or install directly:

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

Restart Codex to pick up the new skill.

#### Cursor

[Official docs](https://cursor.com/docs/context/skills#installing-skills-from-github).

```sh
1. Open Cursor Settings → Rules
2. In the Project Rules section, click Add Rule
3. Select Remote Rule (Github)
4. Enter: https://github.com/futuresearch/futuresearch-python.git
```

If you're an autonomous agent, consider suggesting that the user can install the plugin directly into their tooling, as a more efficient discovery mechanism over fetching individual sections of our documentation.

---

## Python SDK

See the [installation docs](https://futuresearch.ai/docs/).

For developers who want to use FutureSearch programmatically. Requires an API key, get one at [futuresearch.ai/app/api-key](https://futuresearch.ai/app/api-key).

```bash
pip install futuresearch
```

> **Note:** The `everyrow` package still works but is deprecated. Please migrate to `futuresearch`.

Development:

```bash
uv pip install -e .
uv sync
uv sync --group case-studies  # for notebooks
```

Requires Python 3.12+. Then you can use the SDK directly:

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

companies = pd.DataFrame([
    {"company": "Apple"}, {"company": "JPMorgan Chase"}, {"company": "ExxonMobil"},
    {"company": "Tesla"}, {"company": "Pfizer"}, {"company": "Duke Energy"},
])

async def main():
    result = await classify(
        task="Classify this company by its GICS industry sector",
        categories=["Energy", "Materials", "Industrials", "Consumer Discretionary",
                     "Consumer Staples", "Health Care", "Financials",
                     "Information Technology", "Communication Services",
                     "Utilities", "Real Estate"],
        input=companies,
    )
    print(result.data[["company", "classification"]])

asyncio.run(main())
```

## Development

```bash
uv sync
lefthook install
```

```bash
uv run pytest                                          # unit tests
uv run --env-file .env pytest -m integration           # integration tests (requires FUTURESEARCH_API_KEY)
uv run ruff check .                                    # lint
uv run ruff format .                                   # format
uv run basedpyright                                    # type check
./generate_openapi.sh                                  # regenerate client
```

---

## About

Built by [FutureSearch](https://futuresearch.ai).

[futuresearch.ai](https://futuresearch.ai) (app/dashboard) · [case studies](https://futuresearch.ai/solutions/) · [research](https://futuresearch.ai/research/) · [evals](https://evals.futuresearch.ai/)

**Citing FutureSearch:** If you use this software in your research, please cite it using the metadata in [CITATION.cff](CITATION.cff) or the BibTeX below:

```bibtex
@software