{"id":48437351,"url":"https://github.com/futuresearch/futuresearch-python","last_synced_at":"2026-06-09T21:01:05.477Z","repository":{"id":332677063,"uuid":"1134502076","full_name":"futuresearch/futuresearch-python","owner":"futuresearch","description":"Your team of research agents. Or give researchers to your AI.","archived":false,"fork":false,"pushed_at":"2026-05-28T12:56:01.000Z","size":18821,"stargazers_count":41,"open_issues_count":3,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T14:22:12.746Z","etag":null,"topics":["claude","claude-code","filtering","llm-agents","pandas-dataframe","ranking","semantic-analysis"],"latest_commit_sha":null,"homepage":"https://futuresearch.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/futuresearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-14T20:03:46.000Z","updated_at":"2026-05-28T12:56:05.000Z","dependencies_parsed_at":null,"dependency_job_id":"3c3a4528-9fcc-4da9-a492-4365f92c552e","html_url":"https://github.com/futuresearch/futuresearch-python","commit_stats":null,"previous_names":["futuresearch/everyrow-sdk","futuresearch/futuresearch-python"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/futuresearch/futuresearch-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/futuresearch%2Ffuturesearch-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/futuresearch%2Ffuturesearch-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/futuresearch%2Ffuturesearch-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/futuresearch%2Ffuturesearch-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/futuresearch","download_url":"https://codeload.github.com/futuresearch/futuresearch-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/futuresearch%2Ffuturesearch-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34125332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","filtering","llm-agents","pandas-dataframe","ranking","semantic-analysis"],"created_at":"2026-04-06T14:00:21.289Z","updated_at":"2026-06-09T21:01:05.470Z","avatar_url":"https://github.com/futuresearch.png","language":"Python","funding_links":[],"categories":["Data Comparison"],"sub_categories":[],"readme":"# FutureSearch Python SDK\n\n[PyPI version](https://pypi.org/project/futuresearch/)\n[License: MIT](https://opensource.org/licenses/MIT)\n[Python 3.12+](https://www.python.org/downloads/)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/team-dispatch.svg\" alt=\"FutureSearch dispatches a pool of web research agents that search, forecast, and synthesize answers\" width=\"760\"\u003e\n\u003c/p\u003e\n\nAn API for forecasting and multi-agent research.\n\nFutureSearch 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.\n\nTry 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).\n\n## Installation\n\nClaude.ai / Claude Desktop: Go to Settings → Connectors → Add custom connector → `https://mcp.futuresearch.ai/mcp`\n\nClaude Code:\n\n```bash\nclaude mcp add futuresearch --scope project --transport http https://mcp.futuresearch.ai/mcp\n```\n\nThen sign in with Google.\n\n## Endpoints\n\n| Role                                                                     | What it does                                | Cost      | Scales To |\n| ------------------------------------------------------------------------ | ------------------------------------------- | --------- | --------- |\n| **[forecast()](https://futuresearch.ai/docs/reference/FORECAST)**        | Predict outcomes                            | 50¢-1.20¢ | 1k rows   |\n| **[multi_agent()](https://futuresearch.ai/docs/reference/MULTIAGENT)**   | A team of researchers per for each question | $0.30-$2  | 1k rows   |\n| **[agent_map()](https://futuresearch.ai/docs/reference/RESEARCH)**       | One researcher per row of a dataset         | 1–11¢     | 10k rows  |\n| **[rank()](https://futuresearch.ai/docs/reference/RANK)**                | Research, then score                        | 1-5¢      | 10k rows  |\n| **[classify()](https://futuresearch.ai/docs/reference/CLASSIFY)**        | Research, then categorize                   | 0.1-0.7¢  | 10k rows  |\n| **[dedupe() and merge()](https://futuresearch.ai/docs/reference/MERGE)** | Find matching rows                          | 0.2-0.5¢  | 20k rows  |\n\nSee 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.)\n\nOr just ask Claude in your interface of choice:\n\n```\nFind every startup selling training data and evals to frontier AI labs.\n```\n\n```\nTake this 10,000-row CSV of drugs and find the FDA regulatory status of each.\n```\n\n```\nForecast which of these 500 cancer drug trials are most likely to succeed.\n```\n\n---\n\n## SDK Examples\n\n```python\nfrom futuresearch.ops import forecast, agent_map, multi_agent\nfrom pandas import DataFrame\n\n# A team of forecasters: research each question, then predict\nresult = await forecast(\n    input=DataFrame([\n        {\"question\": \"When will Anthropic IPO?\"},\n        {\"question\": \"When will OpenAI IPO?\"},\n    ]),\n    forecast_type=\"date\",\n)\nprint(result.data.head())\n\n# One web research agent per row, in parallel\nresult = await agent_map(\n    task=\"Find this company's latest funding round and lead investors\",\n    input=DataFrame([\n        {\"company\": \"Anthropic\"},\n        {\"company\": \"OpenAI\"},\n        {\"company\": \"Mistral\"},\n        # ... 100 more rows\n    ]),\n)\nprint(result.data.head())\n\n# A team of agents on one question; return_list emits one row per item\nresult = await multi_agent(\n    task=\"List the most-funded AI infrastructure startups founded since 2023\",\n    input=DataFrame(),\n    return_list=True,\n)\nprint(result.data.head())\n```\n\nSee 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/).\n\n## Sessions\n\nYou 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.\n\n```python\nfrom futuresearch import create_session\n\nasync with create_session(name=\"My Session\") as session:\n    print(f\"View session at: {session.get_url()}\")\n```\n\n### Async operations\n\nAll ops have async variants for background processing:\n\n```python\nfrom futuresearch import create_session\nfrom futuresearch.ops import rank_async\n\nasync with create_session(name=\"Async Ranking\") as session:\n    task = await rank_async(\n        session=session,\n        task=\"Score this organization\",\n        input=dataframe,\n        field_name=\"score\",\n    )\n    print(f\"Task ID: {task.task_id}\")  # Print this! Useful if your script crashes.\n    # Do other stuff...\n    result = await task.await_result()\n```\n\n**Tip:** Print the task ID after submitting. If your script crashes, you can fetch the result later using `fetch_task_data`:\n\n```python\nfrom futuresearch import fetch_task_data\n\n# Recover results from a crashed script\ndf = await fetch_task_data(\"12345678-1234-1234-1234-123456789abc\")\n```\n\n### Other AI agent plugins\n\n#### Gemini CLI\n\n[Official Docs](https://geminicli.com/docs/extensions/#installing-an-extension).\nEnsure that you're using version \u003e= 0.25.0\n\n```sh\ngemini --version\ngemini extensions install https://github.com/futuresearch/futuresearch-python\ngemini extensions enable futuresearch [--scope \u003cuser or workspace\u003e]\n```\n\nThen within the CLI\n\n```sh\n/settings \u003e Preview Features \u003e Enable\n/settings \u003e Agent Skills \u003e Enable\n/skills enable futuresearch-python\n/skills reload\n/model \u003e Manual \u003e gemini-3-pro-preview \u003e (Optionally Remember model, tab)\n```\n\n#### Codex CLI\n\n[Official docs](https://developers.openai.com/codex/skills#install-new-skills).\nInstall from GitHub using the built-in skill installer, requested via natural language:\n\n```sh\ncodex\n$skill-installer from the futuresearch/futuresearch-python github repo, install the futuresearch-python skill at --path skills/futuresearch-python\n```\n\nOr install directly:\n\n```sh\npython ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \\\n  --repo futuresearch/futuresearch-python --path skills/futuresearch-python\n```\n\nRestart Codex to pick up the new skill.\n\n#### Cursor\n\n[Official docs](https://cursor.com/docs/context/skills#installing-skills-from-github).\n\n```sh\n1. Open Cursor Settings → Rules\n2. In the Project Rules section, click Add Rule\n3. Select Remote Rule (Github)\n4. Enter: https://github.com/futuresearch/futuresearch-python.git\n```\n\nIf 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.\n\n---\n\n## Python SDK\n\nSee the [installation docs](https://futuresearch.ai/docs/).\n\nFor 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).\n\n```bash\npip install futuresearch\n```\n\n\u003e **Note:** The `everyrow` package still works but is deprecated. Please migrate to `futuresearch`.\n\nDevelopment:\n\n```bash\nuv pip install -e .\nuv sync\nuv sync --group case-studies  # for notebooks\n```\n\nRequires Python 3.12+. Then you can use the SDK directly:\n\n```python\nimport asyncio\nimport pandas as pd\nfrom futuresearch.ops import classify\n\ncompanies = pd.DataFrame([\n    {\"company\": \"Apple\"}, {\"company\": \"JPMorgan Chase\"}, {\"company\": \"ExxonMobil\"},\n    {\"company\": \"Tesla\"}, {\"company\": \"Pfizer\"}, {\"company\": \"Duke Energy\"},\n])\n\nasync def main():\n    result = await classify(\n        task=\"Classify this company by its GICS industry sector\",\n        categories=[\"Energy\", \"Materials\", \"Industrials\", \"Consumer Discretionary\",\n                     \"Consumer Staples\", \"Health Care\", \"Financials\",\n                     \"Information Technology\", \"Communication Services\",\n                     \"Utilities\", \"Real Estate\"],\n        input=companies,\n    )\n    print(result.data[[\"company\", \"classification\"]])\n\nasyncio.run(main())\n```\n\n## Development\n\n```bash\nuv sync\nlefthook install\n```\n\n```bash\nuv run pytest                                          # unit tests\nuv run --env-file .env pytest -m integration           # integration tests (requires FUTURESEARCH_API_KEY)\nuv run ruff check .                                    # lint\nuv run ruff format .                                   # format\nuv run basedpyright                                    # type check\n./generate_openapi.sh                                  # regenerate client\n```\n\n---\n\n## About\n\nBuilt by [FutureSearch](https://futuresearch.ai).\n\n[futuresearch.ai](https://futuresearch.ai) (app/dashboard) · [case studies](https://futuresearch.ai/solutions/) · [research](https://futuresearch.ai/research/) · [evals](https://evals.futuresearch.ai/)\n\n**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:\n\n```bibtex\n@software{futuresearch,\n  author       = {FutureSearch},\n  title        = {futuresearch},\n  url          = {https://github.com/futuresearch/futuresearch-python},\n  version      = {0.15.0},\n  year         = {2026},\n  license      = {MIT}\n}\n```\n\n**License** MIT license. See [LICENSE.txt](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffuturesearch%2Ffuturesearch-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffuturesearch%2Ffuturesearch-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffuturesearch%2Ffuturesearch-python/lists"}