Classify

classify takes a DataFrame and a list of allowed categories, then assigns each row to exactly one category using web research that scales to the difficulty of the classification. Supports binary (yes/no) and multi-category classification with optional reasoning output.

Screening (pass/fail filtering) is a special case of classification: set categories=["yes", "no"] and only rows classified as "yes" pass the filter.

Examples

GICS sector classification

Every operation is a coroutine. Run it with asyncio.run() as below, or await it directly in a Jupyter notebook. Later snippets on this page omit the wrapper for brevity.

import asyncio

from pandas import DataFrame
from futuresearch.ops import classify

companies = DataFrame([
    {"company": "Apple"},
    {"company": "JPMorgan Chase"},
    {"company": "ExxonMobil"},
    {"company": "Pfizer"},
    {"company": "Procter & Gamble"},
    {"company": "Tesla"},
    {"company": "AT&T"},
    {"company": "Caterpillar"},
    {"company": "Duke Energy"},
    {"company": "Simon Property Group"},
])


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())

Output:

company	classification
Apple	Information Technology
JPMorgan Chase	Financials
ExxonMobil	Energy
Pfizer	Health Care
Procter & Gamble	Consumer Staples
Tesla	Consumer Discretionary
AT&T	Communication Services
Caterpillar	Industrials
Duke Energy	Utilities
Simon Property Group	Real Estate

Binary classification

For yes/no questions, use two categories:

result = await classify(
    task="Is this company founder-led?",
    categories=["yes", "no"],
    input=companies,
)

Custom output column and reasoning

result = await classify(
    task="Classify each company by its primary industry sector",
    categories=["Technology", "Finance", "Healthcare", "Energy"],
    input=companies,
    classification_field="sector",
    include_reasoning=True,
)
print(result.data[["company", "sector", "reasoning"]])

Parameters

Name	Type	Default	Description
`task`	str	required	Natural-language instructions describing how to classify each row
`categories`	list[str]	required	Allowed category values (minimum 2). Each row is assigned exactly one.
`input`	DataFrame	required	Rows to classify
`classification_field`	str	`"classification"`	Name of the output column for the assigned category
`include_reasoning`	bool	`False`	If True, adds a `reasoning` column with the agent's justification
`session`	Session	Optional, auto-created if omitted

Output

One column is added to each input row (name controlled by classification_field):

Column	Type	Description
`classification`	str	One of the provided `categories` values
`reasoning`	str	Agent's justification (only if `include_reasoning=True`)

Via MCP

MCP tool: futuresearch_classify

Parameter	Type	Description
`task`	string	Classification instructions
`categories`	list[string]	Allowed categories (minimum 2)
`classification_field`	string	Output column name (default: `"classification"`)
`include_reasoning`	boolean	Include reasoning column (default: false)

Related docs

Blog posts