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: 2 months 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-03-30T11:53:42.000Z (2 months ago)
- Last Synced: 2026-03-30T13:30:11.105Z (2 months ago)
- Topics: claude, claude-code, filtering, llm-agents, pandas-dataframe, ranking, semantic-analysis
- Language: Python
- Homepage: https://futuresearch.ai
- Size: 17.5 MB
- Stars: 26
- Watchers: 0
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Citation: CITATION.cff
Awesome Lists containing this project
README
# FutureSearch Python SDK
[](https://pypi.org/project/futuresearch/)
[](#claude-code)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
Deploy a team of researchers to forecast, score, classify, or gather data. Use yourself in the [app](https://futuresearch.ai/app), or give your team of researchers 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).
Requires Google sign in, no credit card required.
## Quick installation steps:
Claude.ai / Cowork (in 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.
## Operations
Spin up a team of:
| Role | What it does | Cost | Scales To |
| ---- | ------------ | ---- | --------- |
| [**Agents**](https://futuresearch.ai/docs/reference/RESEARCH) | Research, then analyze | 1–3¢/researcher | 10k rows |
| [**Forecasters**](https://futuresearch.ai/docs/reference/FORECAST) | Predict outcomes | 20-50¢/researcher | 10k rows |
| [**Scorers**](https://futuresearch.ai/docs/reference/RANK) | Research, then score | 1-5¢/researcher | 10k rows |
| [**Classifiers**](https://futuresearch.ai/docs/reference/CLASSIFY) | Research, then categorize | 0.1-0.7¢/researcher | 10k rows |
| [**Matchers**](https://futuresearch.ai/docs/reference/MERGE) | Find matching rows | 0.2-0.5¢/researcher | 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:
```
Label this 5,000 row CSV with the right categories.
```
```
Find the rows in this 10,000 row pandas dataframe that represent good opportunities.
```
```
Rank these 2,000 people from Wikipedia on who is the most bullish on AI.
```
---
## Web Agents
The base operation is `agent_map`: one web research agent per row. The other operations (rank, classify, forecast, merge, dedupe) use the agents under the hood as necessary. Agents are tuned on [Deep Research Bench](https://arxiv.org/abs/2506.06287), our benchmark for questions that need extensive searching and cross-referencing, and tuned to get correct answers at minimal cost.
Under the hood, Claude will:
```python
from futuresearch.ops import single_agent, agent_map
from pandas import DataFrame
from pydantic import BaseModel
class CompanyInput(BaseModel):
company: str
# Single input, run one web research agent
result = await single_agent(
task="Find this company's latest funding round and lead investors",
input=CompanyInput(company="Anthropic"),
)
print(result.data.head())
# Map input, run a set of web research agents 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"},
]),
)
print(result.data.head())
```
See the API [docs](https://futuresearch.ai/docs/reference/RESEARCH), a case study of [labeling data](https://futuresearch.ai/docs/classify-dataframe-rows-llm) or a case study for [researching government data](https://futuresearch.ai/docs/case-studies/research-and-rank-permit-times) at scale.
## 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/)
**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.8.3},
year = {2026},
license = {MIT}
}
```
**License** MIT license. See [LICENSE.txt](LICENSE.txt).