Author a rule from legislation

You are a coding agent. Given source legislation + test cases, you’re producing a deterministic rule ruleset. This is the authoring workflow. Three phases — each gated on the previous. Only phase 3 has a TDD loop today; phases 1 and 2 are informal. Requires an Aethis API key with projects:write and rulesets:write. Set AETHIS_API_KEY in your environment. If you’re using MCP, the key goes in the MCP client config (see MCP install).

Phase 1 — Section discovery

Legislation often covers multiple independent criteria. Split each into its own section so they can be tested and regenerated separately. The two interfaces approach this differently. MCP has an explicit aethis_discover_sections tool the agent calls before authoring. The CLI infers section structure at generate time from the source documents plus any guidance you provide — if you want explicit sections, drop one source file per section into sources/ or add section hints to guidance/hints.yaml.

aethis init my-rule           # scaffolds aethis.yaml, sources/, tests/, guidance/
cd my-rule
# Drop legislation into sources/ — one file per section is the
# simplest way to make the section split explicit.
cp ~/Downloads/legislation.pdf sources/
# Optional: add hints in guidance/hints.yaml to steer the split, e.g.
#   - "Section A covers age eligibility; Section B covers household means-test."

Ask your coding agent in natural language:

“Use Aethis to split this legislation into independent eligibility sections: <paste source>.”

Your agent invokes aethis_discover_sections:

aethis_discover_sections({
  source_text: "<paste legislation>",
  hint: "Split into independent eligibility gates"
})

Authoring is multi-step and tightly stateful (project → sources → fields → generate → publish). The CLI and MCP tools orchestrate this for you. The Python SDK does not yet expose authoring endpoints; the raw HTTP endpoints are listed in the REST API reference for completeness but are not the recommended path.

Phase 2 — Field vocabulary

Define the input fields each section will consume. Shared vocabulary across sections lets rulebooks compose cleanly. The two interfaces approach this differently too. MCP exposes explicit discovery and pinning tools the agent invokes before generation. The CLI infers fields at generate time from your test inputs in tests/scenarios.yaml — the field IDs you write into your tests become the field vocabulary. Use prefixed names (applicant.age, household.income) to keep namespaces tidy across sections.

# tests/scenarios.yaml — field IDs you write here become the vocabulary
tests:
  - name: "eligible — meets age and visa"
    inputs:
      applicant.age: 35
      applicant.visa_status: settled
    expect:
      outcome: eligible
  - name: "not_eligible — student visa"
    inputs:
      applicant.age: 35
      applicant.visa_status: student
    expect:
      outcome: not_eligible

Field descriptions and enum constraints come from the source text + any hints in guidance/hints.yaml — e.g. “applicant.visa_status is an enum with values student, work, settled.”

Ask your agent to discover candidate fields from the section text, then pin them:

“Use Aethis to discover the input fields for project proj_abc from this section text, then set applicant.age as an int.”

Your agent invokes:

aethis_discover_fields({
  project_id: "proj_abc",
  source_text: "<section text>"
})

aethis_set_field_spec({
  project_id: "proj_abc",
  field_id: "applicant.age",
  field_type: "int",
  description: "Applicant age in whole years"
})

Phase 2 must be settled before generation starts — fields can’t be renamed freely once rules reference them.

Phase 3 — Rule generation (TDD loop)

The only phase with an automated test gate. Test-first is non-negotiable: write the tests, THEN generate, THEN iterate until green.

Step 3.1 — Write tests

Test cases drive everything — the generator iterates until every test passes, the publish endpoint refuses to ship a ruleset with a failing test, and (for the CLI) the field vocabulary is inferred from your test inputs. The default location after aethis init is tests/scenarios.yaml for the CLI; for MCP-driven authoring, test cases are supplied inline to aethis_create_ruleset or aethis_generate_and_test.

# tests/scenarios.yaml
tests:
  - name: "eligible — meets age and visa"
    inputs:
      applicant.age: 35
      applicant.visa_status: settled
    expect:
      outcome: eligible

  - name: "not_eligible — student visa"
    inputs:
      applicant.age: 35
      applicant.visa_status: student
    expect:
      outcome: not_eligible

Step 3.2 — Generate

aethis generate --poll     # creates a draft ruleset, waits for compilation

Ask your agent to run the test-driven generate loop:

“Run aethis_generate_and_test on project proj_abc. If any test fails, refine the guidance and retry.”

Your agent invokes:

aethis_generate_and_test({ project_id: "proj_abc" })

Each call generates a fresh ruleset and runs all tests against it; the agent loops by calling it again after adjusting source / guidance, not via a max_iterations arg on the tool itself.

Step 3.3 — Review + refine

aethis test                # runs all test cases against the draft ruleset

Refinement in the CLI is iteration on inputs — there is no standalone refine command. If a test fails:

Re-read the failing case — was the relevant clause in sources/ actually clear?
Add a guidance hint in guidance/hints.yaml, e.g. “The age cap is 65, not 60 — see Section 7.2.”
Re-run aethis generate --poll && aethis test.

Rules compile from the source, not from the tests — so you refine the source text or the hints, never the generated rules.

Refinement is iteration on inputs from the MCP side too. Ask your agent to add guidance and re-run:

“Add a guidance hint to project proj_abc: ‘The age cap is 65, not 60 — see Section 7.2.’ Then re-run generate-and-test.”

Your agent invokes:

aethis_add_guidance({
  project_id: "proj_abc",
  guidance_text: "The age cap is 65, not 60 — see Section 7.2.",
  process_type: "rule_generation"
})

aethis_generate_and_test({ project_id: "proj_abc" })

Step 3.4 — Publish

Only publish when aethis test shows 100% pass. The publish endpoint runs the tests again server-side as a gate.

aethis publish --slug my-team/my-rule
# → ✓ Published ruleset <ruleset_id> — slug: my-team/my-rule

Ask your agent to publish:

“Publish project proj_abc under slug my-team/my-rule and tell me the resulting ruleset_id.”

Your agent invokes:

aethis_publish({
  project_id: "proj_abc",
  slug: "my-team/my-rule"
})

The aethis/* namespace is reserved for first-party rulesets maintained by Aethis. Use a tenant namespace (e.g. my-team/*, my-company/*) for your own rulesets. See Nomenclature.

Composing sections into a rulebook

Once each section has an active ruleset with a stable slug, create the rulebook. See the worked UK Free School Meals example for a full multi-section composition including the outcome_logic AST.

curl -X POST https://api.aethis.ai/api/v1/public/rulebooks/ \
  -H "x-api-key: $AETHIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Rulebook",
    "domain": "my_domain",
    "slug": "my-team/my-rulebook",
    "ruleset_refs": [
      { "section_id": "section_a", "pin_mode": "latest_active" },
      { "section_id": "section_b", "pin_mode": "latest_active" }
    ],
    "outcome_logic": {
      "type": "op", "operator": "and",
      "args": [
        { "type": "field_ref", "key": "section_a_group" },
        { "type": "field_ref", "key": "section_b_group" }
      ]
    }
  }'

The outcome_logic must be a proper Expr AST. The server rejects the text shorthand { "expr": "A AND B" } with HTTP 422 at ingress since aethis-core 0.7.2. To find the group names your sections emit, inspect each ruleset’s compiled criteria — or use a known pattern like the one in the FSM example.

Verification checklist

Before declaring a rule complete:

aethis test passes 100% on the ruleset that’s about to be published
/decide with the published ruleset_id returns the expected decision for each test input
If the rule is public-facing, visibility is public (auto-set for aethis/* slugs; use PATCH /rulesets/<id>/visibility otherwise)
The ruleset shows up in GET /api/v1/public/rulesets (public) or via the authored key (private)

Next steps

Debug a failing decide — when tests pass but /decide surprises you
Worked examples — full projects you can crib from
MCP tools reference — every authoring tool

​Phase 1 — Section discovery

​Phase 2 — Field vocabulary

​Phase 3 — Rule generation (TDD loop)

​Step 3.1 — Write tests

​Step 3.2 — Generate

​Step 3.3 — Review + refine

​Step 3.4 — Publish

​Composing sections into a rulebook

​Verification checklist

​Next steps

Phase 1 — Section discovery

Phase 2 — Field vocabulary

Phase 3 — Rule generation (TDD loop)

Step 3.1 — Write tests

Step 3.2 — Generate

Step 3.3 — Review + refine

Step 3.4 — Publish

Composing sections into a rulebook

Verification checklist

Next steps