Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aethis.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Decision gives an unexpected result

Symptoms: aethis_decide returns not_eligible when you expect eligible, or vice versa. Steps:
  1. Call aethis_explain (or aethis explain -b <ruleset_id> in the CLI) to see human-readable descriptions of the compiled rules. Check that the rules match your source text.
  2. Call aethis_decide with include_trace: true. The trace shows exactly which criterion failed and why.
  3. If the rules are wrong, add a guidance hint pointing to the specific clause that was missed, then aethis_refine.
aethis_decide({
  ruleset_id: "my_section:20260416-abc123",
  field_values: { ... },
  include_trace: true,
  include_explanation: true
})

​
Undetermined outcome

What it means: The engine received the input fields but could not reach a definitive decision — the case falls outside the compiled rules or a required field was not provided. When to expect it:
  • A required field was missing from field_values
  • The source legislation has a discretionary clause (“may be granted”, “at the authority’s discretion”) — Aethis compiles these as undetermined rather than guessing
  • The case involves a combination of values not covered by any rule
How to handle it in your application:
  • undetermined means flag for human review, not auto-reject
  • Check fields_evaluated vs fields_provided — if they differ, a field was unrecognised or missing
  • Use aethis_next_question to find out what additional information the engine needs

​
Updating rules after publishing

Published rulesets are locked — this is intentional. To update:
  1. aethis_generate_and_test on the same project (adds a new ruleset version)
  2. Refine with aethis_refine until all tests pass
  3. aethis_publish — auto-deprecates the previous active ruleset
The old ruleset remains accessible by its specific ruleset ID. Systems pointing to latest_active automatically use the new version.

​
Generation timeout (504)

Rule generation takes 5–15 minutes for complex sections. If your client times out:
  1. Do not re-trigger generation — the server continues after your client disconnects. Re-triggering creates a duplicate run.
  2. Wait 10–15 minutes, then call aethis_list_rulesets({ project_id }) to check if a new ruleset appeared.
  3. If a ruleset is present, call aethis_publish.
  4. If not, wait and check again.
aethis_list_rulesets({ project_id: "proj_abc123" })
// Check the ruleset list for a new entry since the last publish

​
DATE field type error

DATE fields use integer ordinals (days since year 1), not ISO strings. 
# Convert a date to ordinal
python3 -c "from datetime import date; print(date(2025, 4, 13).toordinal())"
# → 739354

# JavaScript equivalent
Math.floor(new Date('2025-04-13').getTime() / 86400000) + 719163
# → 739354
Passing "2025-04-13" as a string will return a 422 Validation error.

​
”API key is required” on decision tools

Decision tools (aethis_decide, aethis_schema, aethis_next_question, aethis_explain) require no API key. If you see this error on a decision tool:
  • Check that you’re calling a decision tool, not an authoring tool
  • Make sure AETHIS_API_KEY is not set to an invalid value (empty string counts)

​
“Ruleset not found” (404)

  • Verify the ruleset ID format: section_id:YYYYMMDD-xxxxxxxx
  • Call aethis_list_projects → aethis_list_rulesets to find valid IDs
  • Check the ruleset hasn’t been archived

​
”Cannot publish: tests failing”

All tests must pass before publishing. Options:
  • Fix rules with aethis_refine and feedback pointing to the missed clause
  • Use aethis_explain_failure to get a targeted diagnosis for a specific failing case
  • Pass force: true to publish anyway (not recommended for production)

​
Rate limit exceeded (429)

{
  "error": "rate_limit_exceeded",
  "retry_after": 1714000000
}
Wait until the X-RateLimit-Reset timestamp, then retry. Contact eng@aethis.ai to increase your tier.