{
  "openapi": "3.1.0",
  "info": {
    "title": "RPCS1 Agent Tuner API",
    "version": "0.2.0",
    "description": "Deterministic AI agent configuration recommendations based on RPCS1 receiver dynamics."
  },
  "servers": [
    {
      "url": "https://rpcs1.dev"
    }
  ],
  "paths": {
    "/api/recommend": {
      "post": {
        "operationId": "recommendAgentConfiguration",
        "summary": "Recommend an AI agent configuration",
        "description": "Maps an agent task and operating environment to receiver primitives, platform parameters, stability regime, warnings, and an explainable reasoning trace.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecommendInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent configuration recommendation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recommendation"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "429": {
            "description": "Free-tier rate limit exceeded"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RecommendInput": {
        "type": "object",
        "required": ["task", "environment", "target_platform"],
        "properties": {
          "task": {
            "type": "object",
            "required": ["task_summary"],
            "properties": {
              "task_summary": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "domain": {
                "type": "string",
                "maxLength": 100
              },
              "expected_duration_per_call": {
                "type": "string",
                "enum": ["short", "medium", "long"]
              }
            }
          },
          "environment": {
            "type": "object",
            "required": ["entropy", "predictability", "stakes", "context_relevance", "commitment_style"],
            "properties": {
              "entropy": {
                "type": "string",
                "enum": ["stable", "moderate", "dynamic", "chaotic"]
              },
              "predictability": {
                "type": "string",
                "enum": ["highly_predictable", "somewhat_predictable", "unpredictable"]
              },
              "stakes": {
                "type": "string",
                "enum": ["low", "medium", "high", "catastrophic"]
              },
              "context_relevance": {
                "type": "string",
                "enum": ["short", "medium", "long"]
              },
              "commitment_style": {
                "type": "string",
                "enum": ["decisive", "balanced", "cautious"]
              }
            }
          },
          "target_platform": {
            "type": "string",
            "enum": ["anthropic", "openai", "open_source", "generic"]
          }
        }
      },
      "Recommendation": {
        "type": "object",
        "required": [
          "receiver_profile",
          "platform_parameters",
          "predicted_regime",
          "reasoning",
          "warnings",
          "imm_principles_applied",
          "confidence"
        ],
        "properties": {
          "receiver_profile": {
            "type": "object",
            "required": ["TI", "SG", "FT", "UE", "AR"],
            "properties": {
              "TI": { "type": "number" },
              "SG": { "type": "number" },
              "FT": { "type": "number" },
              "UE": { "type": "number" },
              "AR": { "type": "number" }
            }
          },
          "platform_parameters": {
            "type": "object",
            "required": ["temperature", "max_tokens"],
            "additionalProperties": true,
            "properties": {
              "temperature": { "type": "number" },
              "max_tokens": { "type": "integer" }
            }
          },
          "predicted_regime": {
            "type": "string",
            "enum": ["stable", "near_oscillation", "near_overload", "near_freeze"]
          },
          "reasoning": { "type": "string" },
          "warnings": {
            "type": "array",
            "items": { "type": "string" }
          },
          "imm_principles_applied": {
            "type": "array",
            "items": { "type": "string" }
          },
          "confidence": {
            "type": "string",
            "enum": ["high", "medium", "low"]
          }
        }
      }
    }
  }
}