Pre-release Harn is pre-1.0 — the language, standard library, and CLI may change between releases. See the release notes

Route requests by meaning

Use std/decision to bind natural-language meanings to typed handlers. Harn checks the input, asks a native decision model two questions, and invokes one handler when your acceptance policy passes.

Replay the included lookup from the repository root without provider access:

HARN_LLM_CALLS_DISABLED=1 harn run examples/semantic-dispatch/run.harn \
  --evaluation-tape examples/semantic-dispatch/lookup.tape \
  -- '{"order_id":"A42","message":"Where is my order?"}'

The reply names the lookup handler. Accounting reports source: "tape" and zero physical attempts. Changing the request makes replay fail. Evaluation replay still invokes handlers; this lookup uses only synthetic data.

Start the repository's synthetic order service from the repository root:

harn serve site examples/semantic-dispatch/server.harn --bind 127.0.0.1:8080

Choose an available native route with harn models recommend --operation decision. The example uses openrouter/typesafe/jev-1.14 and requires its provider credential. Change policy() in the example to choose another native route. Requests send their input and route meanings to that provider. Use synthetic data until its data controls meet your requirements.

Send a request:

curl --fail-with-body http://127.0.0.1:8080/orders \
  -H 'Content-Type: application/json' \
  -d '{"order_id":"A42","message":"Where is my order?"}'

An accepted request returns kind: "dispatched", value.handler: "lookup", and the evaluation receipt reference. A cancellation request prepares a review; it doesn't change an order. A delivery dispute starts a bounded agent with one tool that reads a synthetic delivery record.

Handle the other HTTP responses explicitly:

StatusMeaningNext action
400Invalid JSON or input shapeCorrect the request
409Insufficient probability or marginAsk for clarification or review
422No supported action fitsOffer another service
502Investigation agent didn't finish normallyInspect agent_terminal and retry or review
503Evaluation failedInspect the typed evaluation outcome before retrying

An evaluation failure preserves cancellation, budget, refusal, transport, and replay outcomes. A handler failure propagates to the host. Dispatch doesn't retry handlers or select a second handler after an error.

Define your own router with router<T, R>. Supply a SchemaContract<T>, a stable ID, shared instructions, a route list, and a DecisionPolicy. Each route contains its name, meaning, minimum probability, and fn(Harness, T, DecisionEvidence) -> R handler. All handlers return the same type R.

Use assess(harness.llm, input) to inspect a selection without executing a handler. Use dispatch(harness, input) when selection should invoke the handler. Both use the same definition and the existing evaluation budget, receipt, fixture, and replay mechanisms.

Keep authorization and irreversible changes behind ordinary deterministic checks. A selected handler receives the same harness authority as its caller. The decision doesn't grant capabilities or prove permission.

Before choosing production thresholds, measure wrong selections and abstentions on representative labeled inputs. The example thresholds are demonstration policy. Read what confidence means and the dispatch reference.