https://github.com/futuresearch/futuresearch-python
Your team of research agents. Or give researchers to your AI.
https://github.com/futuresearch/futuresearch-python
claude claude-code filtering llm-agents pandas-dataframe ranking semantic-analysis
Last synced: 18 days ago
JSON representation
Your team of research agents. Or give researchers to your AI.
- Host: GitHub
- URL: https://github.com/futuresearch/futuresearch-python
- Owner: futuresearch
- License: mit
- Created: 2026-01-14T20:03:46.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T12:56:01.000Z (about 1 month ago)
- Last Synced: 2026-05-28T14:22:12.746Z (about 1 month ago)
- Topics: claude, claude-code, filtering, llm-agents, pandas-dataframe, ranking, semantic-analysis
- Language: Python
- Homepage: https://futuresearch.ai
- Size: 17.9 MB
- Stars: 41
- Watchers: 0
- Forks: 6
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Citation: CITATION.cff
Awesome Lists containing this project
- awesome-data-engineering - FutureSearch SDK - Python SDK that dispatches parallel web-research agents across (Data Comparison)
README
# 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/)
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 ]
```
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{futuresearch,
author = {FutureSearch},
title = {futuresearch},
url = {https://github.com/futuresearch/futuresearch-python},
version = {0.15.0},
year = {2026},
license = {MIT}
}
```
**License** MIT license. See [LICENSE.txt](LICENSE.txt).