Typed I/O
A tactic declares what it accepts and what it returns as Pydantic types.
Every call validates both ends: call() works with real objects instead of
guessing at dicts, callers get a typed result or a clear error, and the same
types are published as JSON schemas that services and tools read.
Here a support tactic takes a Ticket and returns a Triage. The caller
passes a plain dict, and the model's JSON comes back as a validated object:
from typing import Literal
from pydantic import BaseModel, Field
from lllm import Prompt, Tactic
class Ticket(BaseModel):
subject: str
body: str
class Triage(BaseModel):
team: Literal["billing", "bugs", "accounts"]
priority: int = Field(ge=1, le=3, description="1 is most urgent")
TRIAGE = Prompt(
path="support/triage",
prompt="Route this ticket.\nSubject: {subject}\n{body}",
format=Triage, # (1)!
)
class Route(Tactic):
"""Route a support ticket to a team."""
name = "route"
agent_group = ["router"]
input_model = Ticket # (2)!
output_model = Triage
def call(self, ticket: Ticket) -> Triage:
router = self.agents["router"]
router.open("triage")
router.receive_prompt(TRIAGE, ticket.model_dump()) # (3)!
return router.respond().parsed # (4)!
config = {
"global": {"model_name": "gpt-4o-mini"},
"agent_configs": [
{"name": "router", "system_prompt": "You route support tickets."}
],
}
route = Route(config)
triage = route({"subject": "Charged twice", "body": "I was billed twice."})
print(repr(triage))
#> Triage(team='billing', priority=2)
format=asks the model for JSON in the shape ofTriage(Structured output).- The tactic's contract. Every call validates its input into a
Ticketand its result into aTriage, andinfo()publishes both. - The caller passed a dict, but
call()receives aTicket. parsedis a dict decoded from the model's JSON. The tactic validates it into aTriagebefore the caller sees it.
Declaring types
input_model and output_model take Pydantic models. They are aliases of
input_type and output_type, which take any type Pydantic can validate,
so use whichever reads better; a subclass's own declaration wins over the one
it inherits.
| Declared type | Accepts | Published schema |
|---|---|---|
A BaseModel |
An instance, or data that validates into it, such as a dict | An object with the model's fields |
str, int, float, bool |
Values Pydantic converts, such as "5" for int |
string, integer, number, boolean |
list[str], dict[str, int] |
Lists and dicts of those | array, object |
Literal["a", "b"] |
One of the values | An enum |
A dataclass or TypedDict |
An instance or a dict | An object |
Typed I/O does not need agents. This tactic is plain Python:
from typing import Literal
from lllm import Tactic
class Stars(Tactic):
"""Turn a star rating into a label."""
name = "stars"
input_type = int
output_type = Literal["negative", "neutral", "positive"]
def call(self, stars: int) -> str:
if stars >= 4:
return "positive"
return "neutral" if stars == 3 else "negative"
stars = Stars()
print(stars("5")) # (1)!
#> positive
print(stars.info().input_schema)
#> {'type': 'integer'}
print(stars.info().output_schema)
#> {'enum': ['negative', 'neutral', 'positive'], 'type': 'string'}
- The input is validated before
call()runs, so"5"arrives as5.
Only these attributes are enforced and published. The type hints on call()
and the generic parameters in Tactic[Ticket, Triage] are for you and your
type checker; a tactic without declared types passes values through
unchecked, and its info() has no schemas.
Validation
The input is checked before call() runs, so a bad request never reaches an
agent or costs a model call. The result is checked after call() returns,
so a bad result never reaches the caller:
from typing import Literal
from pydantic import BaseModel
from lllm import SchemaError, Tactic
class Ticket(BaseModel):
subject: str
body: str
class Triage(BaseModel):
team: Literal["billing", "bugs", "accounts"]
priority: int
class KeywordRoute(Tactic):
"""Route a ticket by keywords."""
name = "keyword_route"
input_model = Ticket
output_model = Triage
def call(self, ticket: Ticket) -> dict:
if "charge" in ticket.body:
return {"team": "billing", "priority": 2}
return {"team": "sales", "priority": 3} # (1)!
route = KeywordRoute()
print(repr(route({"subject": "Refund", "body": "Double charge."})))
#> Triage(team='billing', priority=2)
bad = [{"subject": "Refund"}, {"subject": "Hi", "body": "Pricing?"}]
for ticket in bad:
try:
route(ticket)
except SchemaError as error: # (2)!
problem = error.__cause__.errors()[0]
print(error.__cause__.title, problem["loc"], problem["msg"])
#> Ticket ('body',) Field required
#> Triage ('team',) Input should be 'billing', 'bugs' or 'accounts'
- A bug:
salesis not a team. The result is checked on the way out, so the caller gets an error instead of bad data. - The first ticket has no
body. The second one passes, but its result names a team that does not exist.
Both failures raise SchemaError (from lllm), with a message like
Value does not match schema Ticket: .... Its __cause__ is Pydantic's
ValidationError, whose errors() list each problem with its location. The
call's session records the failure, and a
service answers it with status 400.
When the model's reply does not fit
Most results start as a model reply, and LLLM checks replies at two points:
| Check | Runs on | When it fails |
|---|---|---|
The prompt's format= or parser= |
Each model reply | The error goes back to the model to fix; after max_exception_retry repairs (3), AgentException |
The tactic's output_model |
The tactic's result | SchemaError; the call fails |
format= decodes the reply as JSON, and providers with structured output
enforce the schema as they generate. It does not check the decoded fields
against the model, though. When a reply can still be wrong, for example with
a provider that lacks structured output, validate it with the model in a
parser. A reply that does not fit is then repaired inside the agent loop
instead of failing the call:
from typing import Literal
from pydantic import BaseModel, ValidationError
from lllm import ParseError, Prompt, Tactic
class Triage(BaseModel):
team: Literal["billing", "bugs", "accounts"]
priority: int
def as_triage(text: str, **kwargs) -> dict: # (1)!
try:
return Triage.model_validate_json(text).model_dump()
except ValidationError as error:
problems = "; ".join(e["msg"] for e in error.errors())
raise ParseError(f"Invalid triage: {problems}")
TRIAGE = Prompt(
path="support/triage_checked",
prompt=(
"Route this ticket to billing, bugs, or accounts: {ticket}\n"
'Reply with JSON like {{"team": "bugs", "priority": 2}}.'
),
parser=as_triage,
)
agent = Tactic.quick(
system_prompt="You route tickets.", model="gpt-4o-mini"
)
agent.open("triage")
ticket = "My invoice has the wrong company name."
agent.receive_prompt(TRIAGE, {"ticket": ticket})
session = agent.respond(return_session=True)
print(session.exception_retries_count) # (2)!
#> 1
print(repr(Triage.model_validate(session.delivery.parsed)))
#> Triage(team='billing', priority=3)
- A parser turns the reply text into
parsed. AParseErrorsends its message back to the model:Error: Invalid triage: Input should be 'billing', 'bugs' or 'accounts'. Please fix. - The first reply named a team that does not exist, and the model fixed it after one repair.
A prompt uses format= or a parser, not both: when format= is set, the
parser is not called. In a tactic with output_model = Triage, return
parsed as before. A parser's result also carries the reply text under
raw, which validation ignores unless the model forbids extra fields. The
same goes for steps inside call():
Plan.model_validate(planner.respond().parsed) turns a planner's reply into
an object the rest of the program can use (Tactics).
JSON schemas
info() returns the tactic's public description, a TacticInfo, with both
types as JSON schemas. They come from the types alone, so call() does not
run:
from typing import Literal
from pydantic import BaseModel, Field
from lllm import Tactic
class Ticket(BaseModel):
subject: str
body: str
class Triage(BaseModel):
team: Literal["billing", "bugs", "accounts"]
priority: int = Field(ge=1, le=3)
class Route(Tactic):
"""Route a support ticket to a team."""
name = "route"
input_model = Ticket
output_model = Triage
def call(self, ticket: Ticket) -> Triage:
return Triage(team="billing", priority=2)
info = Route().info()
print(info.name, "|", info.description)
#> route | Route a support ticket to a team.
print(info.input_schema["required"])
#> ['subject', 'body']
print(info.output_schema["properties"]["priority"])
#> {'maximum': 3, 'minimum': 1, 'title': 'Priority', 'type': 'integer'}
The rest of LLLM reads these schemas:
- Services.
lllm servevalidates each request'sinputagainst the input type, publishes both schemas atGET /infoand in the OpenAPI docs, and answers a request that does not validate with status 400 (Serving). - Tools. When a tactic becomes a tool, its input schema becomes the tool's parameters and its docstring the tool's description (Tactics as tools).
- Inspection.
lllm inspect module:tactic --jsonprints the name, description, capabilities, and both schemas (CLI). - Other runtimes. Plain functions wrapped with
as_tactic()(which reads the function's annotations) and Pydantic AI agents takeinput_typeandoutput_typetoo, so every kind of tactic publishes the same contract (Other runtimes).