Evaluate a case

Successful decision responses identify the serving build in engine_version. Read that field from your response rather than relying on a version copied into a tutorial. What the deployed engine serves.

You are a coding agent. You want to answer ‘is this person eligible for X?’ This page is the full sequence. The three-call pattern:

Discover the schema — what fields does the ruleset need?
Collect values — either from user input, context, or an upstream tool.
Decide — send field values, receive a decision envelope.

Optional fourth step: explain — when the decision is not_eligible and the user asks why. Uses the public Free School Meals (FSM) child-eligibility ruleset. No API key needed.

1. Discover the schema

CLI
Python SDK
curl
MCP

aethis fields -b aethis/uk-fsm/child-eligibility

from aethis_sdk import Aethis

with Aethis() as client:
    schema = client.get_schema("aethis/uk-fsm/child-eligibility")
    for f in schema.fields:
        print(f.field_id, f.field_type, f.description)

curl https://api.aethis.ai/api/v1/public/rulesets/aethis/uk-fsm/child-eligibility/schema

Ask your coding agent (Claude Code, Cursor, Windsurf, …) in natural language:

“Use Aethis to fetch the field schema for aethis/uk-fsm/child-eligibility.”

Your agent invokes the aethis_schema tool for you:

aethis_schema({ ruleset_id: "aethis/uk-fsm/child-eligibility" })

The response (same shape across all four interfaces):

{
  "ruleset_id": "aethis/uk-fsm/child-eligibility",
  "slug": "aethis/uk-fsm/child-eligibility",
  "name": "UK FSM Child Eligibility",
  "fields": [
    {
      "field_id": "child.age",
      "field_type": "int",
      "description": "Child's age in whole years at the start of the relevant academic year (1 September).",
      "question": "Child's age in whole years at the start of the relevant academic year (1 September).",
      "weight": 1,
      "enum_values": null,
      "notes": [
        {
          "note_text": "WHY: Free school meals eligibility is tied to compulsory-school-age status, which is determined by the child's age at the start of the academic year.",
          "source": "DfE Free School Meals: guidance for local authorities",
          "metadata": { "type": "why", "section": "child_eligibility" }
        },
        {
          "note_text": "LEGAL BACKGROUND:\n\nCompulsory school age runs from 1 September following the child's 5th birthday to the last Friday of June in the academic year of their 16th birthday. Age is taken as at 1 September of the relevant academic year, not the application date.",
          "source": "Education Act 1996, s.8",
          "metadata": { "type": "legal_background", "section": "child_eligibility" }
        }
      ]
    },
    {
      "field_id": "child.school_type",
      "field_type": "enum",
      "description": "Type of school the child attends.",
      "weight": 2,
      "enum_values": ["state_funded", "independent", "home_educated"]
    }
  ]
}

What the agent needs: a map from field_id → value. For enum fields, only values listed in enum_values are accepted. For int / bool, standard JSON. notes — each field can carry a list of structured FieldNoteOut entries. By convention each note has metadata.type ∈ {"why", "legal_background"} and a source citation. Conversational agents (e.g. an information-gathering paralegal bot) typically surface the WHY:-prefixed note verbatim when a user replies “why?” to a question, and draw on the LEGAL BACKGROUND:-prefixed note for follow-up questions about evidence and edge cases. Older bundles may return "notes": [] — your code should treat the array as optional. weight — higher = less preferred to ask. The decision engine uses this for optimal-path computation when there are multiple ways to satisfy a ruleset (e.g. ask the cheap nationality question before the expensive English-test one).

2. Collect field values

Agent-side logic — the API doesn’t care how you got the values. In practice: ask the user, read from a session object, or derive from upstream context. If a field is missing, the decision can still return (as undetermined) — just be ready to ask for it next.

3. Decide

CLI
Python SDK
curl
MCP

aethis decide \
  -b aethis/uk-fsm/child-eligibility \
  -i '{"child.age": 10, "child.school_type": "state_funded"}' \
  --explain

from aethis_sdk import Aethis

with Aethis() as client:
    response = client.decide(
        ruleset_id="aethis/uk-fsm/child-eligibility",
        field_values={
            "child.age": 10,
            "child.school_type": "state_funded",
        },
        include_trace=True,
    )
    print(response.decision)

curl -X POST https://api.aethis.ai/api/v1/public/decide \
  -H "Content-Type: application/json" \
  -d '{
    "ruleset_id": "aethis/uk-fsm/child-eligibility",
    "field_values": {
      "child.age": 10,
      "child.school_type": "state_funded"
    },
    "include_trace": true
  }'

Ask your coding agent in natural language:

“Use Aethis to check whether a 10-year-old at a state-funded school qualifies for free school meals under aethis/uk-fsm/child-eligibility. Include the trace.”

Your agent invokes the aethis_decide tool for you:

aethis_decide({
  ruleset_id: "aethis/uk-fsm/child-eligibility",
  field_values: { "child.age": 10, "child.school_type": "state_funded" },
  include_trace: true
})

All four return the same decision envelope:

{
  "decision": "eligible",
  "fields_provided": 2,
  "fields_evaluated": 2,
  "ruleset_id": "uk-fsm-child-eligibility:20260528-244428c1",
  "slug": "aethis/uk-fsm/child-eligibility",
  "ruleset_version": "v3",
  "content_digest": "sha256:EXAMPLE_DIGEST_0000000000000000000000000000000000000000000000",
  "engine_version": "aethis-core@0.48.0",
  "decision_id": "dec_...",
  "inputs_hash": "sha256:...",
  "decision_time": "2026-07-26T01:26:33Z",
  "field_errors": null
}

Illustrative values — content_digest is a placeholder and the published ruleset_id / ruleset_version depend on what is live when you call. Field names and meanings are exact.ruleset_version is never "unknown" for a published leaf ruleset, and replay pins to content_digest, which changes on every republish. Both are served by api.aethis.ai today.

Three possible outcomes:

eligible — all criteria satisfied
not_eligible — one or more criteria failed
undetermined — engine couldn’t decide (missing field, discretionary clause, a blocking input error, or a case outside the compiled rules)

Check field_errors first. If it is non-null, an input could not be applied — an unknown field name or a value that failed its type — and the decision is forced to undetermined regardless of everything else in the envelope. A positive verdict never appears beside a blocking error, so treat a non-null field_errors as “fix the input and call again”, not as a partial answer. When you get undetermined with field_errors: null, inspect missing_fields. Add the missing values and call again. include_trace adds per-group outcomes so you can show the user why.

4. (Optional) Explain the decision

For a not_eligible where the user asks “why”:

CLI
Python SDK
curl
MCP

aethis decide \
  -b aethis/uk-fsm/child-eligibility \
  -i '{"child.age": 16, "child.school_type": "state_funded"}' \
  --explain

The CLI’s --explain flag calls /decide with trace, then /explain-failure when the outcome is not_eligible, and renders both in one pass.

Requires aethis-sdk >= 0.6.0.

/explain-failure resolves a slug the same way /decide, /schema, and /explain do — pass either the slug or the concrete ruleset_id from the /decide envelope.

from aethis_sdk import Aethis

with Aethis() as client:
    response = client.decide(
        ruleset_id="aethis/uk-fsm/child-eligibility",
        field_values={"child.age": 16, "child.school_type": "state_funded"},
        include_trace=True,
    )
    if response.decision == "not_eligible":
        # Either the slug or the concrete ruleset_id from the envelope works.
        explanation = client.explain_failure(
            ruleset_id=response.ruleset_id,
            field_values={"child.age": 16, "child.school_type": "state_funded"},
            expected_outcome="eligible",
        )
        print(explanation)

Either the slug (URL-encoded, %2F for /) or the concrete ruleset_id from the /decide envelope resolves here.

curl -X POST https://api.aethis.ai/api/v1/public/rulesets/aethis%2Fuk-fsm%2Fchild-eligibility/explain-failure \
  -H "Content-Type: application/json" \
  -d '{
    "field_values": { "child.age": 16, "child.school_type": "state_funded" },
    "expected_outcome": "eligible"
  }'

Ask your coding agent in natural language:

“Use Aethis to explain why a 16-year-old at a state-funded school is not eligible under aethis/uk-fsm/child-eligibility.”

Your agent invokes the aethis_explain_failure tool for you (it accepts either the slug or the concrete ruleset_id — the server resolves the slug directly):

aethis_explain_failure({
  ruleset_id: "aethis/uk-fsm/child-eligibility",
  field_values: { "child.age": 16, "child.school_type": "state_funded" },
  expected_outcome: "eligible"
})

Returns human-readable reasons for the failure, keyed by criterion, plus a DSL mechanism hint.

Composing multiple sections (rulebook)

If your domain has more than one section and you want one decision over the composition (e.g. FSM: child eligibility AND (household criteria OR universal infant)), use the rulebook_id field instead of ruleset_id. Rulebook evaluation always requires an API key — see Nomenclature for why.

curl -X POST https://api.aethis.ai/api/v1/public/decide \
  -H "Content-Type: application/json" \
  -H "x-api-key: $AETHIS_API_KEY" \
  -d '{
    "rulebook_id": "aethis/uk-fsm",
    "field_values": { ... }
  }'

The response includes a section_results array with each section’s individual outcome.

Know what the outcome ranged over

section_results says which sections were evaluated. complete_determination says whether that is the whole of the question:

Value	Meaning
`true`	The outcome settles the question the rulebook names — either way.
`false`	The rulebook models only part of the real requirement, so what it models is necessary but not sufficient.
`null`	The rulebook has not declared. Infer nothing either way; a `null` is not a `true`.

Under false the two directions are not symmetric. Branch on decision:

eligible + false — not terminal. Every modelled requirement is met, which is necessary and does not establish sufficiency. The unmodelled ones may still fail, so do not present this as a final answer.
not_eligible + false — still terminal. A necessary requirement failed, and no unmodelled requirement can repair that. Treating this one as provisional is its own error: it keeps a case open that cannot succeed.

The asymmetry follows from the word necessary in the declaration, not from how the rulebook composes its own sections, so it holds whatever outcome logic the rulebook uses.

A false here does not mean the decision is wrong. The engine evaluated the rules it was given and answered correctly about them — this field tells you how much of the question those rules covered, so your interface can make a claim it can justify. It is always null for a single-ruleset_id decide: completeness is a rulebook-level property.

Next steps

Debug a failing decide — when things don’t go as expected
MCP tools reference — every tool + parameters
Decision envelope — replay and audit contract

Getting started (no key)

AI coding agents

Interfaces

Recipes

Authoring (invite-only)

Reference

Changelog

Evaluate a case

1. Discover the schema

2. Collect field values

3. Decide

4. (Optional) Explain the decision

Composing multiple sections (rulebook)

Know what the outcome ranged over

Next steps

​1. Discover the schema

​2. Collect field values

​3. Decide

​4. (Optional) Explain the decision

​Composing multiple sections (rulebook)

​Know what the outcome ranged over

​Next steps

1. Discover the schema

2. Collect field values

3. Decide

4. (Optional) Explain the decision

Composing multiple sections (rulebook)

Know what the outcome ranged over

Next steps