extract()

Extract structured data from an LLM response.

Usage

Source

extract(
    chatbot,
    message,
    *,
    data_model,
    agent=None,
)

Sends a message to a ChatBot or Agent and parses the response into a typed dictionary matching a Pydantic model schema.

When the ChatBot has mock responses configured, the first mock response is consumed and parsed as JSON. When a real LLM is configured, the chatlas extract_data() method is used for provider-native structured output support.

Parameters

chatbot: Any

A ChatBot instance (or the chatbot attribute of an Agent).

message: str

The prompt to send.

data_model: type

A Pydantic BaseModel subclass describing the desired output schema.

agent: Any | None = None

An optional Agent whose chatbot will be used. If provided, chatbot is ignored.

Returns

ExtractResult

The extracted data, model name, and timing.

Raises

ValueError

If the mock response is not valid JSON matching the schema.

Examples

With mock responses (for testing):

import talk_box as tb
from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str
    population: int

bot = tb.ChatBot()
bot.mock_responses(['{"name": "Paris", "country": "France", "population": 2161000}'])
result = tb.extract(bot, "Tell me about Paris", data_model=City)
result.data  # {"name": "Paris", "country": "France", "population": 2161000}

With an Agent:

agent = tb.Agent.from_persona("data_analyst")
agent.chatbot.mock_responses(['{"name": "Tokyo", "country": "Japan", "population": 13960000}'])
result = tb.extract(agent.chatbot, "Tell me about Tokyo", data_model=City, agent=agent)