optimizes

optimizes

Declare performance targets and fitness criteria for a machine. The optimizes section defines measurable metrics with target thresholds and reward signals that guide the machine’s evolution over time. These declarations serve two purposes: they are checked by the evaluate interpretation mode (ask ... from: machine, to: evaluate), and they feed into the evolution ledger’s governed improvement pipeline.

When to use

Use optimizes when you want to:

• Set measurable performance targets (accuracy, latency, cost, throughput)
• Define reward signals that guide machine improvement
• Enable the evaluate interpretation mode to assess machine fitness
• Track whether a machine meets its quality criteria across versions

Most machines benefit from at least one metric. Even a simple classifier should declare its accuracy target. Omit optimizes only for trivial machines with no measurable quality dimension.

Syntax

optimizes
  metrics
    <name> type: <metric_type>, target: <value>
    ...
  rewards
    <name> weight: <value>, signal: "<description>"
    ...

Subsections

metrics

Named measurements with types and target thresholds. Each metric declares what is being measured and what value constitutes success.

metrics
  accuracy type: percentage, target: 90
  latency type: milliseconds, target: 500
  cost_per_run type: currency, target: 0.05

Field	Required	Description
type	Yes	Metric type: percentage, milliseconds, currency, count, ratio
target	Yes	Target threshold value. The evaluate mode checks actual results against this.

rewards

Named reward signals with weights and descriptions. Rewards express preferences for the evolution pipeline: what behaviors should be encouraged or discouraged.

rewards
  relevance weight: 0.6, signal: "Response directly addresses the user's question"
  conciseness weight: 0.3, signal: "Response is under 200 words"
  safety weight: 0.1, signal: "No PII or sensitive data in output"

Field	Required	Description
weight	Yes	Relative importance (0.0 to 1.0). Weights across all rewards should sum to 1.0.
signal	Yes	Human-readable description of what constitutes a positive signal.

Examples

Classifier with accuracy target

machine ticket_classifier
  accepts
    message as text, is required

  responds with
    team as text
    confidence as decimal

  implements
    ask classify, using: "anthropic:claude-haiku-4"
      with task "Classify this ticket: ${input.message}"
      returns
        team as text
        confidence as decimal

  optimizes
    metrics
      accuracy type: percentage, target: 90
      avg_confidence type: ratio, target: 0.85

Pipeline with latency and cost targets

machine data_pipeline
  optimizes
    metrics
      latency type: milliseconds, target: 2000
      cost_per_run type: currency, target: 0.10
      throughput type: count, target: 100

Agent with reward signals

machine research_agent
  has agency

  optimizes
    metrics
      accuracy type: percentage, target: 85
      response_time type: milliseconds, target: 5000

    rewards
      thoroughness weight: 0.4, signal: "Response covers all aspects of the question"
      citation weight: 0.3, signal: "Claims are backed by specific sources"
      clarity weight: 0.2, signal: "Response is well-structured and easy to follow"
      safety weight: 0.1, signal: "No hallucinated facts or unsupported claims"

Interaction with evaluate mode

When a machine is invoked with ask ... from: machine, to: evaluate, the runtime reads the optimizes > metrics declarations and checks actual results against the declared targets:

// Run the classifier against test cases and check metrics
ask report, from: ticket_classifier, to: evaluate
  dataset: test_tickets

The evaluate interpreter returns a fitness report showing each metric, its actual value, its target, and whether it passed.

Canonical ordering

optimizes appears after ensures and before records:

machine name
  ...
  implements ...
  expresses ...
  ensures ...
  optimizes ...       <-- here (section 8)
  records ...
  verifies ...

Governance

optimizes declarations are not directly governed. They are metadata that informs the evolution pipeline and the evaluate interpreter. However, the evolution process itself (propose, verify, promote) is governed by the evolution ledger (Inv 8: Governed Evolution). A machine version cannot be promoted unless its optimizes metrics meet the declared targets.

Translations

Language	Keyword
English	optimizes
Spanish	optimiza
French	optimise
German	optimiert
Japanese	最適化
Chinese	优化
Korean	최적화

See also

• achieves - Goal specification (qualitative, vs. optimizes’ quantitative)
• records - Behavioral ledger that captures the raw data metrics are derived from
• verifies - Test cases that provide evaluation datasets