/ reference

Skill Parameters

Every skill's parameters with their defaults, typed and validated: the same names in ace.yaml (a tenant's skills) and in the hosted skills API (skill_params).

One schema, two places. Each skill's parameters are a typed model in the gateway (ace.skill_params), the single source of their defaults. On-prem they sit beside mode under tenants.<t>.skills.<skill> in ace.yaml; hosted they are skill_params.<skill> on POST /api/v1/dev_key/skills (enterprise tier for any parameter but the router allowlist). GET /api/v1/config/schema serves the same models, and the on-prem export writes each listed skill's defaults as comments.

Validated where they are written. An unknown parameter, a wrong type or an out-of-range value is refused: by ace config validate / plan / apply / test (with file and line), and by the hosted save (422 skill_params_invalid, nothing stored). A skill not listed below takes no parameters. A hosted save names only the parameters it changes; they are merged into what is stored, and an explicit null removes one so its default applies again. A parameter stored before the parameters were typed is ignored on the request path (logged once), never an error on a request.

Inheritance. A tenants level inherits its parent's parameters and lists only what differs, one parameter at a time; a list value (rules, disabled_procedure_ids) replaces the parent's list whole.

tenants:
  acme:
    skills:
      prompt_compaction:
        mode: prod
        default: lossless
        rules:
          - {part: user, position: opening, compact: "off"}
          - {part: tool_result, content: code, compact: "off"}
  acme:prod:
    skills:
      prompt_compaction:
        rules: []        # replaces acme's list: no rules in prod
      output_budget:
        mode: prod
        max_output_tokens: 8192

prompt_compaction's rules and default decide, per part of a request, whether it is sent as received (off), rewritten losslessly or word-pruned: see skill:prompt_compaction for the selectors and their semantics. A bare off is read as the action (YAML loads it as false); a bare on is refused.

Defaults are what a tenant that sets nothing gets. A parameter the deployment supplies at boot (epoch_size, token_watermark, tool_result_ratio, ...) is shown at the value it resolves to on a default deployment; a tenant that leaves it unset follows its deployment. Only parameters whose default is a rule rather than a value are null (compress_prefix, default, scorer, keep_recent_turns, payback_turns).

`prompt_compaction`

Parameter	Default	Meaning
`prune_words`	`false`	False: rewrite LOSSLESSLY only -- compact JSON, reference link triples collapsed, exact repeated lines, whitespace and markdown decoration; no word is deleted. True: run the keep-score word pruner after it, at the ratios below.
`drop_empty_fields`	`false`	True: the lossless pass also drops null, "", [] and {} members of JSON regions of 200+ characters. Off by default: an empty field (unassigned) says something an absent one does not.
`protect_cached_history`	`false`	True: conversation spans inside the provider's cached span are priced and held with the system prefix. For a key whose sessions also reach the vendor directly, so a rewritten history is one another route's cache never saw.
`compress_prefix`	`null`	The system prefix (system prompt). null: compacted when not cached, else when the break-even gate says the rewrite pays back; true: always; false: never.
`prefix_ratio`	`0.8`	Words kept in the system prefix (word pruner).
`compress_tool_results`	`true`	False: tool results are never compacted.
`tool_result_ratio`	`0.5`	Words kept in tool results (word pruner). null: the deployment's compression_ratio, the same the user turns get.
`instruction_ratio`	`1.0`	Words kept in text typed as instructions (an operator's ask). 1.0: sent byte-identical.
`pasted_ratio`	`0.35`	Words kept in pasted material (a quoted ticket, a log excerpt).
`payback_turns`	`null`	Pins the break-even gate's payback horizon, in requests. null: max(one epoch, turns so far), capped by expected_task_steps.
`expected_task_steps`	`12`	Caps the payback horizon at what is left of the task. null: the skill default (12).
`max_span_tokens`	`200000`	The largest span the word pruner scores, in tokens (len/4). A larger span goes as received (x-ace-compaction-partial: span_too_large). 0 or null lifts the bound. Default 200000, or ACE_COMPACTION_MAX_SPAN_TOKENS.
`background_span_tokens`	`16000`	A span to be pruned that is larger than this (tokens, len/4) and not memoised goes upstream as its lossless rewrite while its prune runs off the request; later requests read the memoised prune. Applies to the system prompt, and to other spans only when the request declares no prompt-cache breakpoint (under one, a span already sent keeps its bytes). 0 or null scores every span on the request, under the skill ceiling.
`tool_yield_memo`	`true`	Skip scoring a tool whose last tool_yield_window results pruned nothing, except every tool_yield_resample-th request.
`tool_yield_window`	`8`	Results remembered per tool.
`tool_yield_resample`	`20`	Every Nth request of a skipped tool is scored anyway.
`scorer`	`null`	The scorer for prune spans no rule sets one for: heuristic or learned. null: the deployment's -- learned when a model is loaded, else heuristic.
`default`	`null`	The action for a span no rule matches. null: prune when prune_words is true, else lossless (what the skill has always done).
`rules`	`[]`	Ordered; the first rule whose every field matches a span decides it. Tried before compress_prefix: false and compress_tool_results: false, which are rules too. The task statement and a serialised object are never word-pruned: a prune rule on them is applied as lossless.

`semantic_cache`

Parameter	Default	Meaning
`lookup_on_tool_results`	`false`	Run the approximate (embedding) tier on an agent step whose live turn is a tool result. Off: such a step is served from the exact-prompt table only.

`agent_trajectory_compaction`

Parameter	Default	Meaning
`epoch_size`	`5`	Turns per fold epoch. null: 5.
`keep_recent_turns`	`null`	Most recent turns never folded. null: the epoch rule.
`keep_recent_images`	`1`	Most recent images kept. null: 1.
`token_watermark`	`20000`	Fold once the trajectory passes this. 0: off. null: 20000.
`max_tool_repeats`	`0`	Identical tool calls in a row before the fold refuses (tool loop). 0: off. null: the deployment's ACE_AGENT_MAX_TOOL_REPEATS, 0 (off) by default.
`payback_turns`	`null`	Pins the break-even gate's payback horizon.
`expected_task_steps`	`12`	Caps the payback horizon at what is left of the task.

`output_budget`

Parameter	Default	Meaning
`max_output_tokens`	`16384`	The ceiling on a declared completion budget. 0: no ceiling.
`min_output_tokens`	`1024`	Never cap below this.
`default_max_output_tokens`	`0`	The budget given to a caller who declared none. 0: leave them alone.

`reasoning_effort`

Parameter	Default	Meaning
`max_effort`	`medium`	The ceiling on an OpenAI reasoning level.
`max_budget_tokens`	`8192`	The ceiling on an Anthropic / Bedrock / Gemini thinking budget.
`min_budget_tokens`	`1024`	Never cap below this (Anthropic refuses under 1024).

`skill_knowledge_graph`

Parameter	Default	Meaning
`disabled_procedure_ids`	`[]`	Procedures never recalled for this tenant (kill switch).

`llm_router`

Parameter	Default	Meaning
`allowlist`	`null`	Hosted: the model ids the router may route to. null or []: the router routes nothing.

On-prem Configuration as Code (ace.yaml)Error Contracts & Status Codes