triagesim.agents

Agents and the LLM backends that drive them.

from triagesim.agents import BaseLLM, OpenRouterLLM, NurseAgent, PatientAgent

See Agents and LLM backends for usage and for how to write a custom backend.

LLM backends

BaseLLM

Bases: ABC

Abstract interface for ALL language model backends. Agents will call .generate() to produce structured outputs.

generate abstractmethod 

generate(
    prompt: str,
    max_tokens: Optional[int] = None,
    stop: Optional[List[str]] = None,
    **kwargs,
) -> Union[str, BaseAgentOutput]

Generate a response given a prompt.

This method must return either: - raw text (for unstructured outputs), or - a structured Pydantic model (if output_type was provided).

The calling agent assumes the correct model/schema is applied via the backend's output_type during instantiation.

Parameters:

NameTypeDescriptionDefault
promptstr

the model input text

required
max_tokensOptional[int]

optional token cap

None
stopOptional[List[str]]

optional stop sequences

None
**kwargs

backend-specific overrides

{}

Returns:

TypeDescription
Union[str, BaseAgentOutput]

Model output (string or Pydantic output model)

OpenRouterLLM 

OpenRouterLLM(
    model_name: str,
    output_type: Type[BaseAgentOutput],
    **agent_kwargs,
)

Bases: BaseLLM

LLM backend using OpenRouter via the pydantic_ai SDK.

This wraps an Agent configured with a given output model type so that .generate() returns a structured output or text.

Parameters:

NameTypeDescriptionDefault
model_namestr

OpenRouter model specifier (e.g., "google/gemini-3-pro-preview")

required
output_typeType[BaseAgentOutput]

a subclass of BaseAgentOutput Pydantic model that the Agent will produce directly.

required
Usage

llm = OpenRouterLLM("google/gemini-3-pro-preview", output_type=NurseOutput) nurse_action = llm.generate(prompt)

Create an Agent configured to produce the right output type.

The API key is resolved from triagesim.config.OPENROUTER_API_KEY.

Parameters:

NameTypeDescriptionDefault
model_namestr

the OpenRouter model identifier

required
output_typeType[BaseAgentOutput]

Pydantic model to enforce output structure

required
agent_kwargs

any extra fields passed to Agent()

{}

generate 

generate(
    prompt: str,
    max_tokens: Optional[int] = None,
    stop: Optional[List[str]] = None,
    **kwargs,
) -> Union[str, BaseAgentOutput]

Run a synchronous request against the configured agent.

Because the agent is configured with output_type, this method should return a structured Pydantic model or a simple string

Parameters:

NameTypeDescriptionDefault
promptstr

the text prompt

required
max_tokensOptional[int]

optionally limit tokens

None
stopOptional[List[str]]

optional stop sequences

None
**kwargs

passed to agent.run_sync()

{}

Returns:

TypeDescription
Union[str, BaseAgentOutput]

Model output from the LLM call

Agents

NurseAgent 

NurseAgent(
    llm: BaseLLM,
    persona: NursePersona,
    algorithm: str = "esi",
)

Nurse agent responsible for: - Choosing the next triage action (NurseOutput) - Inferring belief updates from the nurse's perspective

The SAME LLM + persona is used for both decision-making and belief inference.

act 

act(history: str, known_vitals: set[str]) -> NurseOutput

Given dialogue history, produce the next nurse action as a structured NurseOutput.

infer_belief_updates 

infer_belief_updates(
    history: str, last_utterance: str, turn: int
) -> List[BeliefSlotUpdate]

Infer belief updates from the nurse's perspective.

This is called by the environment AFTER a patient utterance. Failures must never crash the episode.

PatientAgent 

PatientAgent(llm: BaseLLM, persona: PatientPersona)

PatientAgent generates patient utterances conditioned on: - dialogue history - a categorical persona - explicit response budget rules

act 

act(
    history: str, chief_complaint: str, pain: int
) -> PatientOutput

Generate the patient's next utterance as a structured PatientOutput.

The LLM backend MUST have been initialized with

output_type = PatientOutput

← PreviousRunner
Next →Core