# Cost Model Schema
# Schema for cost-model.yaml generated by aiwg nlp productionize and cost-analyst agent

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/nlp-prod/cost-model/v1"
title: "NLP Pipeline Cost Model"
description: |
  Schema for cost-model.yaml — the TCO model for a production pipeline.
  Generated by the Cost Analyst agent and `aiwg nlp estimate-cost`.
  Stored in the pipeline directory alongside pipeline.config.yaml.

type: object
required:
  - version
  - pipeline
  - analyzed_at
  - steps
  - totals

properties:
  version:
    type: string
    default: "1.0.0"

  pipeline:
    type: string
    description: "Pipeline name"

  analyzed_at:
    type: string
    format: date-time

  monthly_volume:
    type: integer
    description: "Assumed monthly call volume for projections"

  steps:
    type: array
    items:
      $ref: "#/$defs/StepCost"

  totals:
    $ref: "#/$defs/TotalCost"

  recommendations:
    type: array
    items:
      $ref: "#/$defs/CostRecommendation"

$defs:
  StepCost:
    type: object
    required:
      - name
      - model
      - avg_input_tokens
      - avg_output_tokens
      - cost_per_call_usd
    properties:
      name:
        type: string

      model:
        type: string

      avg_input_tokens:
        type: integer

      avg_output_tokens:
        type: integer

      cost_per_call_usd:
        type: number

      cacheable_prefix_tokens:
        type: integer
        default: 0
        description: "Tokens in stable system prompt prefix eligible for caching"

      cache_savings_per_call_usd:
        type: number
        default: 0.0
        description: "Per-call savings if prompt cache enabled"

      parallelizable_with:
        type: array
        items:
          type: string
        description: "Names of steps with no data dependency (can run concurrently)"

  TotalCost:
    type: object
    required:
      - cost_per_call_usd
    properties:
      cost_per_call_usd:
        type: number

      monthly_cost_usd:
        type: number
        description: "Monthly cost without any optimizations"

      monthly_cost_with_caching_usd:
        type: number
        description: "Monthly cost with prompt caching enabled"

      monthly_cost_optimized_usd:
        type: number
        description: "Monthly cost after all recommended optimizations"

      potential_savings_pct:
        type: number
        minimum: 0.0
        maximum: 100.0
        description: "Percentage savings from current to optimized"

  CostRecommendation:
    type: object
    required:
      - type
      - action
      - estimated_savings_pct
    properties:
      type:
        type: string
        enum: [model_downgrade, caching, parallelization, prompt_trim, batching]

      step:
        type: string
        nullable: true
        description: "Step this applies to (null if pipeline-wide)"

      action:
        type: string
        description: "Specific action to take"

      estimated_savings_pct:
        type: number
        minimum: 0.0
        maximum: 100.0

      risk:
        type: string
        enum: [low, medium, high]
        default: low

      validation:
        type: string
        description: "Command or method to verify the optimization doesn't regress quality"

# Example
examples:
  - version: "1.0.0"
    pipeline: product-extractor
    analyzed_at: "2026-04-01T12:00:00Z"
    monthly_volume: 100000
    steps:
      - name: extract
        model: claude-haiku-4-5
        avg_input_tokens: 800
        avg_output_tokens: 200
        cost_per_call_usd: 0.000090
        cacheable_prefix_tokens: 320
        cache_savings_per_call_usd: 0.000029
    totals:
      cost_per_call_usd: 0.000090
      monthly_cost_usd: 9.00
      monthly_cost_with_caching_usd: 6.10
      monthly_cost_optimized_usd: 6.10
      potential_savings_pct: 32.2
    recommendations:
      - type: caching
        step: extract
        action: "Enable prefix caching — system prompt is 320 tokens and stable across all calls"
        estimated_savings_pct: 32.0
        risk: low
        validation: "Enable cache_prefix: true in pipeline.config.yaml; verify output quality unchanged"