{
  "openapi": "3.1.0",
  "info": {
    "title": "Super Técnico AI Gateway",
    "version": "0.2.0",
    "description": "Contrato de diseño para la futura API autenticada de conocimiento técnico. No representa todavía un servicio ejecutable."
  },
  "x-super-tecnico-status": "design_contract",
  "x-execution-enabled": false,
  "x-do-not-call-until-enabled": true,
  "servers": [
    {
      "url": "https://app.replacor.com/super-tecnico/api/v1",
      "description": "Dirección reservada; no está activa durante la vista previa privada."
    }
  ],
  "security": [{"ApiKeyAuth": []}],
  "paths": {
    "/capabilities": {
      "get": {
        "operationId": "supertecnico_get_capabilities",
        "summary": "Consultar capacidades y versiones",
        "x-billing-tier": "free",
        "responses": {
          "200": {
            "description": "Capacidades disponibles",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}
          }
        }
      }
    },
    "/coverage": {
      "post": {
        "operationId": "supertecnico_check_coverage",
        "summary": "Comprobar cobertura antes de solicitar una respuesta",
        "x-billing-tier": "free",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CoverageRequest"}}}
        },
        "responses": {
          "200": {
            "description": "Cobertura y contexto mínimo necesario",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}
          }
        }
      }
    },
    "/knowledge/compact": {
      "post": {
        "operationId": "supertecnico_get_compact_context",
        "summary": "Obtener el contexto técnico mínimo para un objetivo",
        "x-billing-tier": "metered_basic_planned",
        "x-economic-class": "standard",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompactContextRequest"}}}
        },
        "responses": {
          "200": {"description": "Contexto compacto con versiones, fuentes y confianza", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}}
        }
      }
    },
    "/validate/measurements": {
      "post": {
        "operationId": "supertecnico_validate_measurements",
        "summary": "Validar unidades, rangos y coherencia de medidas",
        "x-billing-tier": "metered_basic_planned",
        "x-economic-class": "micro",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MeasurementValidationRequest"}}}
        },
        "responses": {
          "200": {"description": "Medidas válidas, dudosas o contradictorias", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}}
        }
      }
    },
    "/diagnostics/next-measurement": {
      "post": {
        "operationId": "supertecnico_get_next_measurement",
        "summary": "Obtener una sola medición útil para continuar",
        "x-billing-tier": "metered_diagnostic_planned",
        "x-economic-class": "advanced",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/NextMeasurementRequest"}}}
        },
        "responses": {
          "200": {"description": "Siguiente medición y motivo", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}}
        }
      }
    },
    "/validate/answer": {
      "post": {
        "operationId": "supertecnico_validate_answer",
        "summary": "Validar las afirmaciones de una respuesta técnica",
        "x-billing-tier": "metered_diagnostic_planned",
        "x-economic-class": "advanced",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AnswerValidationRequest"}}}
        },
        "responses": {
          "200": {"description": "Afirmaciones respaldadas, contradictorias o no verificables", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}}
        }
      }
    },
    "/hvac/resolve": {
      "post": {
        "operationId": "supertecnico_resolve_hvac_code",
        "summary": "Resolver un código HVAC sin mezclar variantes",
        "x-billing-tier": "metered_basic",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HvacCodeRequest"}}}
        },
        "responses": {
          "200": {"description": "Interpretaciones aplicables con trazabilidad", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}},
          "409": {"description": "Falta contexto para separar variantes"}
        }
      }
    },
    "/diagnostics": {
      "post": {
        "operationId": "supertecnico_get_diagnostic",
        "summary": "Obtener un diagnóstico guiado",
        "x-billing-tier": "metered_diagnostic",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DiagnosticRequest"}}}
        },
        "responses": {
          "200": {"description": "Diagnóstico trazable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}}
        }
      }
    },
    "/components/search": {
      "post": {
        "operationId": "supertecnico_search_components",
        "summary": "Buscar una referencia o marcaje",
        "x-billing-tier": "metered_basic",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ComponentSearchRequest"}}}
        },
        "responses": {
          "200": {"description": "Candidatos con calidad y confianza", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}}
        }
      }
    },
    "/field-cases/search": {
      "post": {
        "operationId": "supertecnico_search_field_cases",
        "summary": "Buscar averías reales moderadas",
        "x-billing-tier": "metered_field",
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/FieldCaseRequest"}}}
        },
        "responses": {
          "200": {"description": "Casos y nivel de confirmación", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Envelope"}}}}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-Super-Tecnico-Key"}
    },
    "schemas": {
      "CoverageRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["domain", "query"],
        "properties": {
          "domain": {"type": "string", "enum": ["hvac", "refrigeration", "electronics", "components", "field_cases", "diagrams", "regulations", "drainage"]},
          "query": {"type": "string", "minLength": 2, "maxLength": 300},
          "brand": {"type": "string", "maxLength": 80},
          "model_or_family": {"type": "string", "maxLength": 120}
        }
      },
      "CompactContextRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["domain", "query", "objective"],
        "properties": {
          "domain": {"type": "string", "enum": ["hvac", "refrigeration", "electronics", "components", "field_cases", "diagrams", "regulations", "drainage"]},
          "query": {"type": "string", "minLength": 2, "maxLength": 300},
          "objective": {"type": "string", "minLength": 3, "maxLength": 300},
          "source_ids": {"type": "array", "maxItems": 20, "items": {"type": "string", "maxLength": 180}},
          "max_records": {"type": "integer", "minimum": 1, "maximum": 8, "default": 4},
          "max_output_tokens": {"type": "integer", "minimum": 200, "maximum": 1200, "default": 600}
        }
      },
      "MeasurementValidationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["domain", "measurements"],
        "properties": {
          "domain": {"type": "string", "enum": ["refrigeration", "hvac", "electrical", "combustion", "airflow", "water"]},
          "context": {"type": "string", "maxLength": 600},
          "measurements": {
            "type": "array",
            "minItems": 1,
            "maxItems": 40,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["name", "value", "unit", "quality"],
              "properties": {
                "name": {"type": "string", "minLength": 1, "maxLength": 100},
                "value": {"type": "number"},
                "unit": {"type": "string", "minLength": 1, "maxLength": 40},
                "quality": {"type": "string", "enum": ["measured", "machine_read", "observed_estimate", "unknown"]}
              }
            }
          }
        }
      },
      "NextMeasurementRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["domain", "measurements"],
        "properties": {
          "domain": {"type": "string", "enum": ["refrigeration"]},
          "refrigerant": {"type": "string", "minLength": 2, "maxLength": 40},
          "goal": {"type": "string", "enum": ["pt_only", "superheat", "subcooling", "basic_system_study", "deep_analysis"], "default": "basic_system_study"},
          "measurements": {"type": "object"}
        }
      },
      "AnswerValidationRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["domain", "answer"],
        "properties": {
          "domain": {"type": "string", "enum": ["hvac", "refrigeration", "electronics", "components", "diagrams", "regulations", "drainage"]},
          "answer": {"type": "string", "minLength": 10, "maxLength": 6000},
          "source_ids": {"type": "array", "maxItems": 30, "items": {"type": "string", "maxLength": 180}},
          "strictness": {"type": "string", "enum": ["safety_critical", "technical", "informational"], "default": "technical"}
        }
      },
      "HvacCodeRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["brand", "code"],
        "properties": {
          "brand": {"type": "string", "maxLength": 80},
          "code": {"type": "string", "maxLength": 24},
          "model_or_family": {"type": "string", "maxLength": 120},
          "unit_scope": {"type": "string", "maxLength": 60},
          "display_location": {"type": "string", "maxLength": 120}
        }
      },
      "DiagnosticRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["record_id"],
        "properties": {
          "record_id": {"type": "string", "maxLength": 180},
          "symptoms": {"type": "array", "maxItems": 8, "items": {"type": "string", "maxLength": 160}},
          "measurements": {"type": "array", "maxItems": 12, "items": {"type": "string", "maxLength": 160}}
        }
      },
      "ComponentSearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["query"],
        "properties": {
          "query": {"type": "string", "maxLength": 120},
          "package": {"type": "string", "maxLength": 80},
          "minimum_confidence": {"type": "number", "minimum": 0, "maximum": 1},
          "limit": {"type": "integer", "minimum": 1, "maximum": 20, "default": 8}
        }
      },
      "FieldCaseRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["query"],
        "properties": {
          "query": {"type": "string", "maxLength": 300},
          "board_reference": {"type": "string", "maxLength": 120},
          "brand": {"type": "string", "maxLength": 80},
          "confirmed_only": {"type": "boolean", "default": true},
          "limit": {"type": "integer", "minimum": 1, "maximum": 10, "default": 5}
        }
      },
      "Envelope": {
        "type": "object",
        "additionalProperties": false,
        "required": ["ok", "status", "request_id", "service_version", "tool_id", "tool_version", "result", "confidence", "source_ids", "warnings", "usage"],
        "properties": {
          "ok": {"type": "boolean"},
          "status": {"type": "string", "enum": ["success", "not_found", "insufficient_context", "rejected", "error"]},
          "request_id": {"type": "string"},
          "service_version": {"type": "string"},
          "tool_id": {"type": "string"},
          "tool_version": {"type": "string"},
          "result": {"type": ["object", "array", "null"]},
          "confidence": {
            "type": ["object", "null"],
            "additionalProperties": false,
            "properties": {
              "score": {"type": "number", "minimum": 0, "maximum": 1},
              "level": {"type": "string", "enum": ["high", "medium", "low", "unknown"]},
              "basis": {"type": "string"}
            }
          },
          "source_ids": {"type": "array", "items": {"type": "string"}},
          "usage": {
            "type": "object",
            "additionalProperties": false,
            "required": ["billing_tier", "billable_units", "cache_status"],
            "properties": {
              "billing_tier": {"type": "string"},
              "billable_units": {"type": "integer", "minimum": 0},
              "cache_status": {"type": "string", "enum": ["hit", "miss", "not_applicable"]},
              "response_bytes": {"type": "integer", "minimum": 0},
              "estimated_tokens_avoided": {"type": ["integer", "null"], "minimum": 0},
              "estimated_searches_avoided": {"type": ["integer", "null"], "minimum": 0}
            }
          },
          "warnings": {"type": "array", "items": {"type": "string"}}
        }
      }
    }
  }
}