{
  "openapi": "3.1.0",
  "info": {
    "title": "Human Interface AI : consultation de compréhension humaine",
    "version": "1.0.0",
    "description": "Permet à un agent IA de poser une question sur la compréhension des humains (intention, ton, frictions, passage de relais, codes culturels BE/FR/LU). Une personne (Mathieu) répond par e-mail à l'opérateur humain de l'agent, sans délai garanti. Aucune donnée personnelle ou sensible.",
    "contact": { "url": "https://human-interface.ai/agents/" }
  },
  "servers": [{ "url": "https://human-interface.ai/agents" }],
  "paths": {
    "/ask.php": {
      "get": {
        "summary": "Description du service",
        "operationId": "describe",
        "responses": { "200": { "description": "Mode d'emploi au format JSON" } }
      },
      "post": {
        "summary": "Poser une question à un facilitateur de compréhension humaine",
        "operationId": "askHuman",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Question" },
              "example": {
                "question": "Un client écrit « bon, laissez tomber » après deux réponses de notre agent. Faut-il insister, reformuler ou proposer une personne ?",
                "context": "Agent de service client d'une PME belge, échanges en français.",
                "agent": { "name": "Assistant SAV", "url": "https://example.com" },
                "operator": { "name": "Responsable relation client", "email": "operateur@example.com" },
                "language": "fr",
                "no_personal_data": true
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Question reçue ; réponse humaine par e-mail à l'opérateur",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Received" } } }
          },
          "400": { "description": "Champs manquants ou invalides" },
          "413": { "description": "Requête trop volumineuse (20 Ko maximum)" },
          "429": { "description": "Limite atteinte ; voir l'en-tête Retry-After" },
          "503": { "description": "Envoi momentanément impossible" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Question": {
        "type": "object",
        "required": ["question", "agent", "operator", "no_personal_data"],
        "properties": {
          "question": { "type": "string", "minLength": 20, "maxLength": 4000 },
          "context": { "type": "string", "maxLength": 4000 },
          "agent": {
            "type": "object",
            "required": ["name"],
            "properties": { "name": { "type": "string", "maxLength": 120 }, "url": { "type": "string", "format": "uri" } }
          },
          "operator": {
            "type": "object",
            "description": "Personne humaine responsable de l'agent ; elle reçoit la réponse.",
            "required": ["name", "email"],
            "properties": { "name": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "format": "email" } }
          },
          "language": { "type": "string", "enum": ["fr", "en"], "default": "fr" },
          "no_personal_data": { "type": "boolean", "const": true, "description": "Confirme l'absence de donnée personnelle ou sensible." }
        }
      },
      "Received": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "const": "received" },
          "reference": { "type": "string", "pattern": "^HIA-[0-9A-F]{8}$" },
          "answer": {
            "type": "object",
            "properties": {
              "by": { "type": "string" },
              "channel": { "type": "string", "const": "email" },
              "to": { "type": "string" },
              "delay": { "type": "string" }
            }
          },
          "meanwhile": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}