Extractor: Collect Data and Match Intents

The Extractor object (ctx.extractor) provides two key helpers, one for pulling structured data from user utterances and another for classifying what the user wants to do.

ctx.extractor.collect() : Extract Structured Data

Use collect() to extract specific fields from the user's message. The engine reads the user's input, identifies the relevant values, and validates them against your Pydantic model. You can specify which fields to extract using either fields (a list of field names from your global state) or schema (a custom Pydantic model).

Using fields (from your state model):

result = await ctx.extractor.collect(
    fields=["name"],
    prompt="Ask the user for their full name to begin the application.",
)

if not result.extracted.name:
    return Interrupt(say="Could you please tell me your full name?")

Using a custom schema:

class NameSchema(GraphState):
    name: str = Field(..., description="Full name (first + last)")

result = await ctx.extractor.collect(
    schema=NameSchema,
    prompt="Ask for the user's full name.",
)

Parameter	Type	Description
fields	list[str]	Field names from your state model to extract.
schema	Type[BaseModel]	Custom Pydantic model defining extraction targets.
prompt	str	LLM-facing instruction for asking the user.

Provide either fields or schema, not both.

Output of Collect:

Attribute	Type	Description
.extracted	BaseModel	Schema instance with extracted values (unfilled fields are None).
.success	bool	True when all fields have been populated.

ctx.extractor.match_intent() : Classify User Intent

Use match_intent() to classify what the user wants to do. You provide a dictionary of intent keys with natural language descriptions, and the LLM scores the user's message against each one. This is useful for routing the conversation based on user intent. For example, determining whether the user wants to apply, check status, or exit.

intent = await ctx.extractor.match_intent(
    intents={
        "apply":  "User wants to apply for a loan",
        "status": "User wants to check application status",
        "exit":   "User wants to hang up or say goodbye",
    }
)

if intent == "exit":
    return END
elif intent == "status":
    return Route("check_status")
else:
    return Route("collect_name")

Returns the best-scoring intent key, or "unknown" if no match exceeds the threshold.