aiwg/agentic/code/addons/rlm/schemas/rlm-cost.yaml

Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.

# RLM Cost Schema
# Cost tracking and budget enforcement for recursive language model operations
# Research basis: REF-089 (Zhang et al., 2026)

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/rlm-cost/v1"
title: "RLM Cost Schema"
description: |
  Schema for tracking costs (tokens and USD) across recursive task decomposition.
  Implements budget enforcement and percentile-based cost reporting per REF-089
  research showing bimodal cost distribution with high variance.

type: object
required:
  - version
  - tree_id
  - records

properties:
  version:
    type: string
    pattern: "^1\\.\\d+\\.\\d+$"
    default: "1.0.0"

  tree_id:
    type: string
    pattern: "^tree-[a-f0-9]{8}$"
    description: "Associated task tree ID"

  records:
    type: array
    items:
      $ref: "#/$defs/CostRecord"
    description: "Per-node cost records"

  aggregates:
    $ref: "#/$defs/CostAggregates"

  budget:
    $ref: "#/$defs/CostBudget"

  percentile_report:
    $ref: "#/$defs/PercentileReport"

  alerts:
    type: array
    items:
      $ref: "#/$defs/CostAlert"
    description: "Budget threshold alerts"

$defs:
  CostRecord:
    type: object
    description: "Cost tracking for a single task node"
    required:
      - node_id
      - model
    properties:
      node_id:
        type: string
        pattern: "^task-[a-f0-9]{8}$"
        description: "Task tree node ID"
        examples:
          - "task-a1b2c3d4"

      model:
        type: string
        description: "Model used for this node"
        examples:
          - "claude-sonnet-4.5"
          - "gpt-5.3-codex"
          - "codex-mini-latest"
          - "claude-opus-4.6"

      provider:
        type: string
        description: "Provider name"
        examples:
          - "claude"
          - "codex"
          - "copilot"
          - "factory"

      input_tokens:
        type: integer
        minimum: 0
        description: "Input tokens consumed"

      output_tokens:
        type: integer
        minimum: 0
        description: "Output tokens generated"

      total_tokens:
        type: integer
        minimum: 0
        description: "Total tokens (input + output)"

      cost_usd:
        type: number
        minimum: 0
        description: "Estimated cost in USD"
        examples:
          - 0.015
          - 0.032
          - 0.001

      input_cost_usd:
        type: number
        minimum: 0
        description: "Cost of input tokens"

      output_cost_usd:
        type: number
        minimum: 0
        description: "Cost of output tokens"

      started_at:
        type: string
        format: date-time
        description: "Node execution start time"

      completed_at:
        type: string
        format: date-time
        description: "Node execution completion time"

      duration_ms:
        type: integer
        minimum: 0
        description: "Execution duration in milliseconds"

      cache_hits:
        type: integer
        minimum: 0
        description: "Number of cache hits (if caching enabled)"

      cache_savings_usd:
        type: number
        minimum: 0
        description: "Cost saved from caching"

      pricing:
        $ref: "#/$defs/PricingInfo"

  PricingInfo:
    type: object
    description: "Pricing information for cost calculation"
    properties:
      input_cost_per_1k:
        type: number
        minimum: 0
        description: "Cost per 1k input tokens"
        examples:
          - 0.003
          - 0.01

      output_cost_per_1k:
        type: number
        minimum: 0
        description: "Cost per 1k output tokens"
        examples:
          - 0.015
          - 0.03

      currency:
        type: string
        default: "USD"

      pricing_date:
        type: string
        format: date
        description: "Date of pricing (for historical accuracy)"

  CostAggregates:
    type: object
    description: "Aggregate cost statistics across entire task tree"
    properties:
      total_input_tokens:
        type: integer
        minimum: 0
        description: "Sum of all input tokens"

      total_output_tokens:
        type: integer
        minimum: 0
        description: "Sum of all output tokens"

      total_tokens:
        type: integer
        minimum: 0
        description: "Sum of all tokens"

      total_cost_usd:
        type: number
        minimum: 0
        description: "Total cost in USD"

      total_cache_savings_usd:
        type: number
        minimum: 0
        description: "Total savings from caching"

      effective_cost_usd:
        type: number
        minimum: 0
        description: "Net cost after cache savings"

      node_count:
        type: integer
        minimum: 0
        description: "Total number of nodes"

      sub_call_count:
        type: integer
        minimum: 0
        description: "Number of recursive sub-calls (non-root nodes)"

      depth_max:
        type: integer
        minimum: 0
        description: "Maximum tree depth"

      root_model:
        type: string
        description: "Model used for root task"

      sub_model:
        type: string
        description: "Model used for sub-tasks"

      by_model:
        type: object
        description: "Cost breakdown by model"
        additionalProperties:
          type: object
          properties:
            node_count:
              type: integer
            total_tokens:
              type: integer
            total_cost_usd:
              type: number

      by_depth:
        type: array
        items:
          type: object
          properties:
            depth:
              type: integer
            node_count:
              type: integer
            total_tokens:
              type: integer
            total_cost_usd:
              type: number

  CostBudget:
    type: object
    description: "Budget configuration and enforcement"
    properties:
      budget_tokens:
        type: integer
        minimum: 0
        default: 500000
        description: "Token budget limit (default 500k)"

      budget_usd:
        type: number
        minimum: 0
        description: "USD budget limit (optional)"

      warn_threshold_pct:
        type: number
        minimum: 0
        maximum: 100
        default: 80
        description: "Percentage threshold for warnings (default 80%)"

      abort_threshold_pct:
        type: number
        minimum: 0
        maximum: 100
        default: 100
        description: "Percentage threshold for abort (default 100%)"

      enforcement:
        type: string
        enum: [warn, abort, log-only]
        default: warn
        description: "Budget enforcement mode"
        examples:
          - "warn: log warnings when thresholds exceeded"
          - "abort: terminate execution at abort threshold"
          - "log-only: only log usage, no enforcement"

      current_usage_tokens:
        type: integer
        minimum: 0
        description: "Current token usage"

      current_usage_usd:
        type: number
        minimum: 0
        description: "Current USD usage"

      remaining_tokens:
        type: integer
        description: "Tokens remaining in budget"

      remaining_usd:
        type: number
        description: "USD remaining in budget"

      usage_pct:
        type: number
        minimum: 0
        maximum: 100
        description: "Percentage of budget consumed"

      status:
        type: string
        enum: [ok, warning, critical, exceeded]
        description: "Budget status"
        examples:
          - "ok: under warn threshold"
          - "warning: over warn threshold"
          - "critical: over abort threshold"
          - "exceeded: budget exhausted"

  PercentileReport:
    type: object
    description: |
      Percentile-based cost statistics per REF-089 research.
      Research shows bimodal cost distribution with high variance,
      making percentile reporting essential.
    properties:
      sample_count:
        type: integer
        minimum: 0
        description: "Number of samples in report"

      metric:
        type: string
        enum: [tokens, cost_usd]
        description: "Which metric this report covers"

      percentiles:
        type: object
        description: "Percentile values"
        properties:
          p25:
            type: number
            description: "25th percentile (Q1)"

          p50:
            type: number
            description: "50th percentile (median)"

          p75:
            type: number
            description: "75th percentile (Q3)"

          p90:
            type: number
            description: "90th percentile"

          p95:
            type: number
            description: "95th percentile"

          p99:
            type: number
            description: "99th percentile"

      mean:
        type: number
        description: "Arithmetic mean"

      std_dev:
        type: number
        minimum: 0
        description: "Standard deviation"

      min:
        type: number
        description: "Minimum value"

      max:
        type: number
        description: "Maximum value"

      comparison_to_base_model:
        type: object
        description: "Comparison to base model without RLM"
        properties:
          ratio:
            type: number
            description: "RLM cost / base cost ratio"
            examples:
              - 0.33  # 3x cheaper (REF-089 finding)
              - 1.0   # comparable (median case)
              - 2.5   # outlier expensive case

          interpretation:
            type: string
            examples:
              - "RLM is 67% cheaper than base model"
              - "RLM cost comparable to base model"
              - "RLM 2.5x more expensive (outlier)"

      comparison_to_summarization:
        type: object
        description: "Comparison to summarization agent pattern"
        properties:
          ratio:
            type: number
            description: "RLM cost / summarization cost ratio"
            examples:
              - 0.33  # 3x cheaper (REF-089 finding)
              - 1.0   # comparable

          interpretation:
            type: string
            examples:
              - "RLM is 67% cheaper than summarization agents"

      notes:
        type: array
        items:
          type: string
        description: "Additional observations"
        examples:
          - "Bimodal distribution observed (REF-089)"
          - "High variance: outliers significantly more expensive"
          - "Median cost comparable to base model"

  CostAlert:
    type: object
    description: "Budget threshold alert"
    required:
      - alert_type
      - threshold_pct
      - timestamp
    properties:
      alert_id:
        type: string
        pattern: "^alert-[a-f0-9]{8}$"
        description: "Unique alert identifier"

      alert_type:
        type: string
        enum: [warn, abort, info]
        description: "Alert severity"
        examples:
          - "warn: warning threshold crossed"
          - "abort: abort threshold crossed, execution should stop"
          - "info: informational milestone"

      threshold_pct:
        type: number
        minimum: 0
        maximum: 100
        description: "Threshold percentage that triggered alert"

      current_usage:
        type: object
        description: "Current usage at time of alert"
        properties:
          tokens:
            type: integer
          cost_usd:
            type: number
          usage_pct:
            type: number

      budget_remaining:
        type: object
        description: "Remaining budget at time of alert"
        properties:
          tokens:
            type: integer
          cost_usd:
            type: number

      timestamp:
        type: string
        format: date-time
        description: "When alert was triggered"

      node_id:
        type: string
        description: "Node that caused threshold crossing"

      recommendation:
        type: string
        description: "Recommended action"
        examples:
          - "Continue monitoring usage"
          - "Consider stopping execution to stay within budget"
          - "Review sub-task decomposition strategy for efficiency"
          - "Abort execution: budget exceeded"

      acknowledged:
        type: boolean
        default: false
        description: "Whether alert has been acknowledged"

      acknowledged_by:
        type: string
        description: "Who acknowledged the alert"

      acknowledged_at:
        type: string
        format: date-time
        description: "When alert was acknowledged"

# Examples
examples:
  simple_cost_tree:
    version: "1.0.0"
    tree_id: "tree-12345678"
    records:
      - node_id: "task-root001"
        model: "claude-sonnet-4.5"
        provider: "claude"
        input_tokens: 5000
        output_tokens: 1500
        total_tokens: 6500
        cost_usd: 0.0975
        input_cost_usd: 0.015
        output_cost_usd: 0.0825
        started_at: "2026-02-09T10:00:00Z"
        completed_at: "2026-02-09T10:00:45Z"
        duration_ms: 45000
      - node_id: "task-sub001"
        model: "codex-mini-latest"
        provider: "codex"
        input_tokens: 2000
        output_tokens: 800
        total_tokens: 2800
        cost_usd: 0.014
        started_at: "2026-02-09T10:00:45Z"
        completed_at: "2026-02-09T10:01:15Z"
        duration_ms: 30000
      - node_id: "task-sub002"
        model: "codex-mini-latest"
        provider: "codex"
        input_tokens: 1800
        output_tokens: 700
        total_tokens: 2500
        cost_usd: 0.0125
        started_at: "2026-02-09T10:00:45Z"
        completed_at: "2026-02-09T10:01:10Z"
        duration_ms: 25000
    aggregates:
      total_input_tokens: 8800
      total_output_tokens: 3000
      total_tokens: 11800
      total_cost_usd: 0.124
      node_count: 3
      sub_call_count: 2
      depth_max: 1
      root_model: "claude-sonnet-4.5"
      sub_model: "codex-mini-latest"
      by_model:
        claude-sonnet-4.5:
          node_count: 1
          total_tokens: 6500
          total_cost_usd: 0.0975
        codex-mini-latest:
          node_count: 2
          total_tokens: 5300
          total_cost_usd: 0.0265
      by_depth:
        - depth: 0
          node_count: 1
          total_tokens: 6500
          total_cost_usd: 0.0975
        - depth: 1
          node_count: 2
          total_tokens: 5300
          total_cost_usd: 0.0265
    budget:
      budget_tokens: 100000
      warn_threshold_pct: 80
      abort_threshold_pct: 100
      enforcement: warn
      current_usage_tokens: 11800
      remaining_tokens: 88200
      usage_pct: 11.8
      status: ok

  budget_warning_scenario:
    version: "1.0.0"
    tree_id: "tree-87654321"
    records:
      - node_id: "task-root001"
        model: "claude-opus-4.6"
        provider: "claude"
        input_tokens: 50000
        output_tokens: 20000
        total_tokens: 70000
        cost_usd: 1.65
      - node_id: "task-sub001"
        model: "claude-sonnet-4.5"
        input_tokens: 15000
        output_tokens: 5000
        total_tokens: 20000
        cost_usd: 0.3
    aggregates:
      total_tokens: 90000
      total_cost_usd: 1.95
      node_count: 2
    budget:
      budget_tokens: 100000
      budget_usd: 2.0
      warn_threshold_pct: 80
      abort_threshold_pct: 100
      enforcement: warn
      current_usage_tokens: 90000
      current_usage_usd: 1.95
      remaining_tokens: 10000
      remaining_usd: 0.05
      usage_pct: 90.0
      status: warning
    alerts:
      - alert_id: "alert-00000001"
        alert_type: warn
        threshold_pct: 80
        current_usage:
          tokens: 90000
          cost_usd: 1.95
          usage_pct: 90.0
        budget_remaining:
          tokens: 10000
          cost_usd: 0.05
        timestamp: "2026-02-09T10:05:00Z"
        node_id: "task-sub001"
        recommendation: "Consider stopping execution to stay within budget"
        acknowledged: false

  percentile_report_example:
    version: "1.0.0"
    tree_id: "tree-report001"
    percentile_report:
      sample_count: 100
      metric: cost_usd
      percentiles:
        p25: 0.15
        p50: 0.35
        p75: 0.60
        p90: 1.20
        p95: 2.50
        p99: 8.00
      mean: 0.85
      std_dev: 1.45
      min: 0.05
      max: 12.00
      comparison_to_base_model:
        ratio: 1.05
        interpretation: "RLM cost comparable to base model (median case)"
      comparison_to_summarization:
        ratio: 0.33
        interpretation: "RLM is 67% cheaper than summarization agents"
      notes:
        - "Bimodal distribution observed (REF-089)"
        - "High variance: p99 is 22x higher than median"
        - "Outliers significantly more expensive than typical runs"
        - "Median RLM cost comparable to base model"
        - "Up to 3x cheaper than summarization in typical cases"

  cache_savings_example:
    version: "1.0.0"
    tree_id: "tree-cached001"
    records:
      - node_id: "task-root001"
        model: "claude-sonnet-4.5"
        input_tokens: 10000
        output_tokens: 3000
        total_tokens: 13000
        cost_usd: 0.195
        cache_hits: 2
        cache_savings_usd: 0.045
      - node_id: "task-sub001"
        model: "claude-sonnet-4.5"
        input_tokens: 5000
        output_tokens: 1500
        total_tokens: 6500
        cost_usd: 0.0975
        cache_hits: 1
        cache_savings_usd: 0.015
    aggregates:
      total_tokens: 19500
      total_cost_usd: 0.2925
      total_cache_savings_usd: 0.06
      effective_cost_usd: 0.2325
      node_count: 2

# Storage paths
storage_paths:
  cost_tree: ".aiwg/rlm/trees/{tree_id}/cost.json"
  cost_report: ".aiwg/rlm/trees/{tree_id}/cost-report.md"
  budget_alerts: ".aiwg/rlm/trees/{tree_id}/alerts.jsonl"
  percentile_history: ".aiwg/rlm/cost-history/percentiles.jsonl"

# Agent protocol
agent_protocol:
  track_node_cost:
    description: "Record cost for a single node execution"
    steps:
      - capture_token_counts
      - lookup_pricing_info
      - calculate_cost
      - create_cost_record
      - update_aggregates
      - check_budget_thresholds
      - trigger_alerts_if_needed

  check_budget:
    description: "Check budget status before spawning sub-task"
    steps:
      - load_current_usage
      - calculate_projected_cost
      - compare_to_budget
      - if_over_threshold:
          - generate_alert
          - optionally_abort
      - return_budget_status

  generate_percentile_report:
    description: "Generate percentile-based cost report"
    steps:
      - collect_historical_cost_data
      - calculate_percentiles
      - calculate_mean_std_dev
      - compare_to_base_model
      - compare_to_summarization
      - format_report

  handle_budget_alert:
    description: "Handle budget threshold alert"
    actions:
      warn:
        - log_alert
        - notify_user
        - continue_execution
      abort:
        - log_alert
        - notify_user
        - stop_execution
        - save_state
      log_only:
        - log_alert

# Budget enforcement strategies
budget_enforcement:
  warn:
    description: "Log warnings, continue execution"
    use_case: "Development, exploratory analysis"
    actions:
      - log_warning
      - notify_user
      - continue_execution

  abort:
    description: "Terminate execution at threshold"
    use_case: "Production, cost-sensitive operations"
    actions:
      - log_alert
      - save_checkpoint
      - stop_execution
      - return_partial_results

  log_only:
    description: "Only log usage, no enforcement"
    use_case: "Cost tracking without limits"
    actions:
      - log_usage
      - continue_execution

# Cost optimization strategies
optimization_strategies:
  model_selection:
    description: "Use cheaper models for sub-tasks"
    pattern: "root: opus/gpt-5, sub: sonnet/codex-mini"
    savings: "50-70% typical"

  caching:
    description: "Enable prompt caching for repeated context"
    savings: "Variable, up to 40% for repeated patterns"

  context_minimization:
    description: "Minimize context passed to sub-tasks"
    pattern: "Pass only relevant excerpts, not full documents"
    savings: "20-30% typical"

  parallel_execution:
    description: "Execute sub-tasks in parallel to reduce total time"
    savings: "Cost neutral, but reduces wall-clock time"

  early_termination:
    description: "Stop on budget exhaustion or sufficient confidence"
    savings: "Prevents runaway costs"

# Pricing reference (as of 2026-02-09)
pricing_reference:
  note: "Pricing subject to change, use provider APIs for current rates"
  examples:
    claude-opus-4.6:
      input_per_1k: 0.015
      output_per_1k: 0.075
    claude-sonnet-4.5:
      input_per_1k: 0.003
      output_per_1k: 0.015
    codex-mini-latest:
      input_per_1k: 0.002
      output_per_1k: 0.006
    gpt-5.3-codex:
      input_per_1k: 0.01
      output_per_1k: 0.03

# Limits
limits:
  max_cost_records: 10000
  max_alerts_per_tree: 100
  budget_check_interval_nodes: 1  # Check after every node

# References
references:
  research:
    - "REF-089: Recursive Language Models (Zhang et al., 2026)"
    - "REF-089 Figure 3: Cost comparison showing bimodal distribution"
  related:
    - "@agentic/code/addons/rlm/schemas/rlm-task-tree.yaml"
    - "@agentic/code/addons/rlm/schemas/rlm-state.yaml"
    - "@agentic/code/addons/rlm/schemas/rlm-trajectory.yaml"
  implementation:
    - "@tools/rlm/"
    - "@agentic/code/addons/rlm/"