TypedLMv0.1.0

Tools

Let the model choose one typed action; Rust authorizes, confirms writes, and executes it.

A tool in TypedLM is a variant of an enum. The model chooses one variant with its arguments — validated like any output — and your code decides whether it runs. The model proposes, Rust validates and executes.

Actions

/// What the assistant does next.
#[derive(Serialize, Deserialize, JsonSchema)]
enum SupportAction {
    /// Look up the status of an order by its number.
    FindOrder { order_id: u64 },
    /// Cancel an order by its number, with the customer's reason.
    CancelOrder { order_id: u64, reason: String },
    /// Hand the conversation to a human agent.
    Escalate,
}

/// Decide the single next action for a customer support message.
#[derive(TypedLm, Serialize)]
#[lm(output = SupportAction)]
struct DecideAction {
    message: String,
}

The doc comments matter: each becomes the description of its tool. Variants with named fields and variants without fields work; tuple variants do not.

Choosing an action is an ordinary program run, so validation, repair, evaluation, optimization and compiled programs apply unchanged — measure how often the right tool is chosen like any other classification.

Executing

Implement Action on the enum: which variants change data, and what each one does.

use typedlm::tools::{Action, Effect};

impl Action for SupportAction {
    type Context = Session;
    type Output = String;
    type Error = ShopError;

    fn effect(&self) -> Effect {
        match self {
            Self::CancelOrder { .. } => Effect::Write,
            _ => Effect::Read,
        }
    }

    async fn execute(self, session: &Session) -> Result<String, ShopError> {
        match self {
            Self::FindOrder { order_id } => session.shop.status(order_id).await,
            Self::CancelOrder { order_id, reason } => session.shop.cancel(order_id, &reason).await,
            Self::Escalate => session.handover().await,
        }
    }
}

The match is exhaustive: a new variant does not compile until it has an implementation.

Policy

A Policy decides whether a chosen action may run:

use typedlm::tools::Policy;

struct SupportPolicy;

impl Policy<SupportAction> for SupportPolicy {
    fn authorize(&self, action: &SupportAction, session: &Session) -> Result<(), String> {
        match action {
            SupportAction::CancelOrder { order_id, .. } if !session.owns(*order_id) => {
                Err("the order belongs to another customer".into())
            }
            _ => Ok(()),
        }
    }

    async fn confirm(&self, action: &SupportAction, session: &Session) -> bool {
        session.ask_user(&format!("{action:?}?")).await
    }
}
  • authorize runs for every action, with the validated arguments and your context — the user’s identity, permissions.
  • confirm runs for Effect::Write actions only. Its default refuses: an action that changes data runs only with a policy that confirms it.

Running

Focus
From the model's choice to an executed action
From the model's choice to an executed actionToolProgram::run: the model chooses one action, the policy authorizes it, actions that change data also need confirmation, and only then does your code execute it.Model chooses → Valid action?Valid action? → policy.authorize: yesValid action? → ToolError: Choicepolicy.authorize → Changes data?: allowedpolicy.authorize → ToolError: DeniedChanges data? → Your code executes: noChanges data? → policy.confirm: yespolicy.confirm → Your code executes: confirmedpolicy.confirm → ToolError: NotConfirmedYour code executes → Outcome: okYour code executes → ToolError: ExecutionyesChoiceallowedDeniednoyesconfirmedNotConfirmedokExecutionModel chooses – one actionModel choosesone actionValid action?Valid action?policy.authorizepolicy.authorizeChanges data? – Effect::WriteChanges data?Effect::Writepolicy.confirm – refuses by defaultpolicy.confirmrefuses by defaultYour code executes – Action::executeYour code executesAction::executeOutcomeOutcomeToolError – says which stepToolErrorsays which step

Source: crates/typedlm/src/tools.rs

Show chart data
Data for From the model's choice to an executed action
StepKindLeads to
Model choosesstartValid action?
Valid action?decisionpolicy.authorize (yes), ToolError (Choice)
policy.authorizedecisionChanges data? (allowed), ToolError (Denied)
Changes data?decisionYour code executes (no), policy.confirm (yes)
policy.confirmdecisionYour code executes (confirmed), ToolError (NotConfirmed)
Your code executesstepOutcome (ok), ToolError (Execution)
Outcomeend
ToolErrorend
Focus
From the model's choice to an executed action
From the model's choice to an executed actionToolProgram::run: the model chooses one action, the policy authorizes it, actions that change data also need confirmation, and only then does your code execute it.Model chooses → Valid action?Valid action? → policy.authorize: yesValid action? → ToolError: Choicepolicy.authorize → Changes data?: allowedpolicy.authorize → ToolError: DeniedChanges data? → Your code executes: noChanges data? → policy.confirm: yespolicy.confirm → Your code executes: confirmedpolicy.confirm → ToolError: NotConfirmedYour code executes → Outcome: okYour code executes → ToolError: ExecutionyesChoiceallowedDeniednoyesconfirmedNotConfirmedokExecutionModel chooses – one actionModel choosesone actionValid action?Valid action?policy.authorizepolicy.authorizeChanges data? – Effect::WriteChanges data?Effect::Writepolicy.confirm – refuses by defaultpolicy.confirmrefuses by defaultYour code executes – Action::executeYour code executesAction::executeOutcomeOutcomeToolError – says which stepToolErrorsays which step

Source: crates/typedlm/src/tools.rs

Show chart data
Data for From the model's choice to an executed action
StepKindLeads to
Model choosesstartValid action?
Valid action?decisionpolicy.authorize (yes), ToolError (Choice)
policy.authorizedecisionChanges data? (allowed), ToolError (Denied)
Changes data?decisionYour code executes (no), policy.confirm (yes)
policy.confirmdecisionYour code executes (confirmed), ToolError (NotConfirmed)
Your code executesstepOutcome (ok), ToolError (Execution)
Outcomeend
ToolErrorend
use typedlm::tools::ToolProgram;

let assistant = ToolProgram::new(Program::new(provider), SupportPolicy);
let outcome = assistant.run("Please cancel order 8812, wrong size.", &session).await?;
println!("{}: {}", outcome.action, outcome.output);

run chooses an action, authorizes it, confirms it if it writes, and executes it. Errors say which step stopped it: Choice (no valid action), Denied, NotConfirmed, Execution. A typedlm.tool tracing span records the action, its effect and the outcome.

ToolProgram uses native tool calls when the provider supports them: every variant is offered as a tool with its description, and the model must call one. Tool calls a local model writes as text are recognised too. Tested live with qwen3:32b on Ollama.

One action per call

The result goes back to your code, not to the model; there is no loop of tool calls. Ask again with the result in the input if a second step is needed — every step stays visible and checked in your code. Multi-step agents are out of scope.

Edit this page on GitHub · Docs for v0.1.0