# Cost Tracking Schema
# Based on REF-057 Agent Laboratory (84% cost reduction with HITL)
# Issue: #130

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/cost-tracking/v1"
title: "Workflow Cost Tracking Schema"
description: |
  Schema for tracking and reporting costs across AIWG workflows.
  Enables optimization opportunities per Agent Laboratory research
  showing 84% cost reduction potential with HITL patterns.

type: object
required:
  - tracking_id
  - workflow
  - costs

properties:
  tracking_id:
    type: string
    format: uuid
    description: "Unique tracking session identifier"

  workflow:
    type: object
    required: [name]
    properties:
      name:
        type: string
        description: "Workflow name"
      phase:
        type: string
        description: "Current SDLC phase"
      iteration:
        type: integer
        description: "Iteration number if Ralph loop"

  started_at:
    type: string
    format: date-time

  completed_at:
    type: string
    format: date-time

  costs:
    $ref: "#/$defs/CostSummary"

  phases:
    type: array
    items:
      $ref: "#/$defs/PhaseCost"
    description: "Breakdown by workflow phase"

  agents:
    type: array
    items:
      $ref: "#/$defs/AgentCost"
    description: "Breakdown by agent"

  artifacts:
    type: array
    items:
      $ref: "#/$defs/ArtifactCost"
    description: "Cost per artifact produced"

  optimization:
    $ref: "#/$defs/OptimizationReport"

$defs:
  CostSummary:
    type: object
    properties:
      total_tokens:
        type: integer
        minimum: 0
      input_tokens:
        type: integer
        minimum: 0
      output_tokens:
        type: integer
        minimum: 0
      total_cost_usd:
        type: number
        minimum: 0
      model_calls:
        type: integer
        minimum: 0
      cached_tokens:
        type: integer
        minimum: 0
        description: "Tokens served from cache"
      cache_savings_usd:
        type: number
        minimum: 0

  PhaseCost:
    type: object
    required: [phase, costs]
    properties:
      phase:
        type: string
        enum:
          - concept
          - inception
          - elaboration
          - construction
          - transition
          - maintenance
      started_at:
        type: string
        format: date-time
      completed_at:
        type: string
        format: date-time
      costs:
        $ref: "#/$defs/CostSummary"
      hitl_interventions:
        type: integer
        minimum: 0
        description: "Human interventions in this phase"

  AgentCost:
    type: object
    required: [agent, costs]
    properties:
      agent:
        type: string
        description: "Agent name"
      model:
        type: string
        description: "Model used by agent"
      invocations:
        type: integer
        minimum: 0
      costs:
        $ref: "#/$defs/CostSummary"
      average_tokens_per_call:
        type: number
      efficiency_rating:
        type: string
        enum: [excellent, good, fair, poor]
        description: "Based on output quality vs cost"

  ArtifactCost:
    type: object
    required: [artifact, costs]
    properties:
      artifact:
        type: string
        description: "Artifact path or identifier"
      artifact_type:
        type: string
        enum:
          - requirement
          - use_case
          - architecture
          - design
          - source_code
          - test
          - documentation
      costs:
        $ref: "#/$defs/CostSummary"
      cost_per_line:
        type: number
        description: "Cost divided by lines of output"
      revisions:
        type: integer
        minimum: 0
        description: "Number of revision attempts"

  OptimizationReport:
    type: object
    properties:
      potential_savings_usd:
        type: number
        minimum: 0
      recommendations:
        type: array
        items:
          type: object
          properties:
            type:
              type: string
              enum:
                - use_smaller_model
                - add_hitl_gate
                - enable_caching
                - batch_operations
                - reduce_iterations
                - improve_prompts
            description:
              type: string
            estimated_savings_usd:
              type: number
            priority:
              type: string
              enum: [high, medium, low]
      hitl_opportunities:
        type: array
        items:
          type: object
          properties:
            phase:
              type: string
            reason:
              type: string
            estimated_savings_percent:
              type: number
        description: "Where HITL could reduce costs per REF-057"

# Cost estimation models
pricing:
  claude_opus_4:
    input_per_mtok: 15.00
    output_per_mtok: 75.00
  claude_sonnet_4:
    input_per_mtok: 3.00
    output_per_mtok: 15.00
  claude_haiku_35:
    input_per_mtok: 0.80
    output_per_mtok: 4.00
  gpt_4_turbo:
    input_per_mtok: 10.00
    output_per_mtok: 30.00
  gpt_4o:
    input_per_mtok: 5.00
    output_per_mtok: 15.00

# Agent protocol
agent_protocol:
  instrumentation:
    description: "How agents track costs"
    capture_points:
      - before_model_call
      - after_model_call
      - on_artifact_completion
      - on_phase_transition
    fields:
      - model_id
      - input_tokens
      - output_tokens
      - cached_tokens
      - latency_ms

  reporting:
    description: "Cost report generation"
    triggers:
      - workflow_completion
      - phase_completion
      - on_demand (aiwg cost report)
    formats:
      - summary (terminal)
      - detailed (JSON)
      - csv (export)

  optimization_analysis:
    description: "Identify savings opportunities"
    analysis:
      - compare_agent_efficiency
      - identify_high_cost_phases
      - detect_iteration_waste
      - suggest_model_downgrades
      - recommend_hitl_gates

# HITL optimization patterns (from REF-057)
hitl_patterns:
  description: |
    Agent Laboratory research shows 84% cost reduction
    with strategic human-in-the-loop intervention.

  high_value_gates:
    - name: requirements_validation
      phase: inception
      savings_potential: 30%
      rationale: "Catch misunderstandings early"

    - name: architecture_review
      phase: elaboration
      savings_potential: 25%
      rationale: "Prevent costly rework"

    - name: test_strategy_approval
      phase: elaboration
      savings_potential: 15%
      rationale: "Ensure correct coverage targets"

    - name: code_review_checkpoint
      phase: construction
      savings_potential: 20%
      rationale: "Catch issues before extensive testing"

# Storage
storage:
  location: ".aiwg/metrics/costs/"
  current_session: "current.json"
  history: "history/"
  aggregates: "aggregates.json"
  retention_days: 90

# Examples
examples:
  workflow_cost_report:
    tracking_id: "cost-001-example"
    workflow:
      name: "sdlc-elaboration"
      phase: "elaboration"
    started_at: "2026-01-25T10:00:00Z"
    completed_at: "2026-01-25T14:30:00Z"
    costs:
      total_tokens: 150000
      input_tokens: 100000
      output_tokens: 50000
      total_cost_usd: 2.25
      model_calls: 45
      cached_tokens: 20000
      cache_savings_usd: 0.30
    phases:
      - phase: elaboration
        costs:
          total_tokens: 150000
          total_cost_usd: 2.25
        hitl_interventions: 3
    agents:
      - agent: "Requirements Analyst"
        model: "claude-sonnet-4"
        invocations: 15
        costs:
          total_tokens: 60000
          total_cost_usd: 0.90
        efficiency_rating: good
      - agent: "Architecture Designer"
        model: "claude-opus-4"
        invocations: 10
        costs:
          total_tokens: 50000
          total_cost_usd: 1.00
        efficiency_rating: excellent
    optimization:
      potential_savings_usd: 0.75
      recommendations:
        - type: use_smaller_model
          description: "Use Sonnet for routine analysis"
          estimated_savings_usd: 0.50
          priority: medium
      hitl_opportunities:
        - phase: elaboration
          reason: "Architecture decision could benefit from early review"
          estimated_savings_percent: 20

# References
references:
  research:
    - "@.aiwg/research/findings/REF-057-agent-laboratory.md"
  implementation:
    - "#130"
  related:
    - "@.claude/rules/hitl-gates.md"
    - "@agentic/code/frameworks/sdlc-complete/schemas/flows/execution-snapshot.yaml"