{
  "openapi": "3.1.0",
  "info": {
    "title": "Bacalaurescu AI API",
    "version": "1.0.0",
    "description": "Public REST API for Romanian Baccalaureate (BAC) literature content. Optimized for use with LLM agents (ChatGPT, Claude, Gemini, Perplexity). All resources are available via GET requests with optional ?format=json|markdown.",
    "contact": {
      "name": "Bacalaurescu",
      "url": "https://bacalaurescu.ro/contact",
      "email": "contact@bacalaurescu.ro"
    },
    "license": {
      "name": "Free educational use",
      "url": "https://bacalaurescu.ro/termeni"
    }
  },
  "servers": [
    { "url": "https://bacalaurescu.ro", "description": "Production" }
  ],
  "tags": [
    { "name": "opere", "description": "Literary works in BAC 2026 curriculum" },
    { "name": "autori", "description": "Romanian authors" },
    { "name": "personaje", "description": "Literary characters" },
    { "name": "teme", "description": "Literary themes" },
    { "name": "curente", "description": "Literary movements" },
    { "name": "istoric", "description": "BAC exam history 2000-2025" },
    { "name": "calendar", "description": "BAC 2026 timeline" },
    { "name": "exec", "description": "Universal command executor" }
  ],
  "paths": {
    "/api/v1/ai/man": {
      "get": {
        "tags": ["exec"],
        "summary": "List all available commands",
        "responses": {
          "200": { "description": "Array of command definitions" }
        }
      }
    },
    "/api/v1/ai/exec": {
      "get": {
        "tags": ["exec"],
        "summary": "Execute any command via GET (no API key required, rate limited)",
        "description": "Generic command executor. Use for any command not covered by dedicated endpoints.",
        "parameters": [
          {
            "name": "cmd",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "example": "opera",
            "description": "Command name (e.g. opera, autor, personaj, comentariu, quiz, relatii, citat, etc.)"
          },
          {
            "name": "args",
            "in": "query",
            "schema": { "type": "string" },
            "example": "morometii",
            "description": "Comma-separated arguments for the command"
          },
          {
            "name": "lang",
            "in": "query",
            "schema": { "type": "string", "enum": ["ro", "en"], "default": "ro" }
          }
        ],
        "responses": {
          "200": { "description": "Command result with enriched metadata (canonicalUrl, media, sectionLinks, attribution)" },
          "404": { "description": "Command not found in manual" },
          "429": { "description": "Rate limit exceeded" }
        }
      },
      "post": {
        "tags": ["exec"],
        "summary": "Execute command via POST (alternative to GET, same response)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "cmd": { "type": "string" },
                  "args": { "type": "array", "items": { "type": "string" } },
                  "rawArgs": { "type": "string" },
                  "lang": { "type": "string", "enum": ["ro", "en"] }
                },
                "required": ["cmd"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Command result with enriched metadata" }
        }
      }
    },
    "/api/v1/ai/opere": {
      "get": {
        "tags": ["opere"],
        "summary": "List all 17 BAC operas",
        "responses": { "200": { "description": "List of operas with metadata" } }
      }
    },
    "/api/v1/ai/opere/{slug}": {
      "get": {
        "tags": ["opere"],
        "summary": "Get full opera data",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "morometii" },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "markdown"], "default": "json" } }
        ],
        "responses": { "200": { "description": "Opera details (title, author, summary, full commentary, themes, symbols, characters, etc.)" } }
      }
    },
    "/api/v1/ai/opere/{slug}/{section}": {
      "get": {
        "tags": ["opere"],
        "summary": "Get a specific section of an opera",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "morometii" },
          {
            "name": "section",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["comentariu", "film", "moment", "relatii", "quiz", "curiozitate", "locatie", "istoric", "podcast", "citate", "rezumat", "personaje"]
            }
          },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "markdown"] } }
        ],
        "responses": { "200": { "description": "Section data (interpretation depends on section)" } }
      }
    },
    "/api/v1/ai/autori": {
      "get": {
        "tags": ["autori"],
        "summary": "List all 15 BAC authors",
        "responses": { "200": { "description": "Authors with metadata" } }
      }
    },
    "/api/v1/ai/autori/{slug}": {
      "get": {
        "tags": ["autori"],
        "summary": "Get full author biography",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "mihai-eminescu" },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "markdown"] } }
        ],
        "responses": { "200": { "description": "Author biography, works, movements, citations" } }
      }
    },
    "/api/v1/ai/personaje": {
      "get": {
        "tags": ["personaje"],
        "summary": "List all 96 characters",
        "responses": { "200": { "description": "Characters list" } }
      }
    },
    "/api/v1/ai/personaje/{slug}": {
      "get": {
        "tags": ["personaje"],
        "summary": "Get character details",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "ilie-moromete" },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json", "markdown"] } }
        ],
        "responses": { "200": { "description": "Character traits, evolution, relations, citations" } }
      }
    },
    "/api/v1/ai/teme/{slug}": {
      "get": {
        "tags": ["teme"],
        "summary": "Get literary theme details",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "iubirea" }
        ],
        "responses": { "200": { "description": "Theme details with associated works" } }
      }
    },
    "/api/v1/ai/curente/{slug}": {
      "get": {
        "tags": ["curente"],
        "summary": "Get literary movement details",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "modernism" }
        ],
        "responses": { "200": { "description": "Movement description with works and authors" } }
      }
    },
    "/api/v1/ai/istoric": {
      "get": {
        "tags": ["istoric"],
        "summary": "BAC exam history",
        "parameters": [
          { "name": "year", "in": "query", "schema": { "type": "string" }, "example": "2024" }
        ],
        "responses": { "200": { "description": "Exam subjects history, optionally filtered by year" } }
      }
    },
    "/api/v1/ai/calendar": {
      "get": {
        "tags": ["calendar"],
        "summary": "BAC 2026 exam calendar",
        "responses": { "200": { "description": "All exam dates for BAC 2026" } }
      }
    },
    "/api/v1/ai/timer": {
      "get": {
        "tags": ["calendar"],
        "summary": "Countdown to BAC 2026",
        "responses": { "200": { "description": "Days/hours remaining until BAC 2026" } }
      }
    },
    "/api/v1/ai/search": {
      "get": {
        "tags": ["exec"],
        "summary": "Full-text search across opere, autori, personaje",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "natura morometii" }
        ],
        "responses": { "200": { "description": "Search results" } }
      }
    },
    "/api/v1/ai/opere/{slug}/context": {
      "get": {
        "tags": ["opere"],
        "summary": "LLM-optimized compact context for an opera",
        "description": "Returns minimal/exam/teacher context optimized for LLM consumption (less tokens, structured for explanations and quiz generation).",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "morometii" },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["compact", "exam", "teacher"], "default": "compact" } }
        ],
        "responses": {
          "200": {
            "description": "Structured opera context",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "opera": "Moromeții",
                    "autor": "Marin Preda",
                    "slug": "morometii",
                    "autor_slug": "marin-preda",
                    "incadrare": "roman, Realism, roman social",
                    "an_publicare": 1955,
                    "tema_principala": "destrămarea civilizației rurale traditionale",
                    "personaj_principal": "Ilie Moromete",
                    "rezumat_scurt": "Romanul descrie destrămarea familiei taranului Moromete...",
                    "simboluri": ["salcâmul", "pământul", "câmpia Dunării"],
                    "cele_mai_importante_2_scene": [
                      { "titlu": "Tabloul inițial al Câmpiei Dunării", "descriere": "Descrierea atmosferei matinale..." },
                      { "titlu": "Tăierea salcâmului", "descriere": "Moment simbolic al destramării..." }
                    ],
                    "personaje_cheie": [
                      { "nume": "Ilie Moromete", "rol": "protagonist" },
                      { "nume": "Catrina", "rol": "secondary" }
                    ],
                    "citate_emblematice": [
                      { "citat": "Ei, lasa ca merge si-asa...", "personaj": "Ilie Moromete" }
                    ]
                  },
                  "meta": {
                    "endpoint": "/api/v1/ai/opere/morometii/context",
                    "executedAt": "2026-05-22T12:00:00Z",
                    "canonicalUrl": "https://bacalaurescu.ro/opere/morometii",
                    "contentVersion": "2026.1.0",
                    "bacYear": "2026",
                    "attributionText": "Sursa: Bacalaurescu - fisa operei Moromeții",
                    "mode": "compact",
                    "level_hint": "Concentrat pe ce e cerut la examen...",
                    "filters_applied": { "level": "exam", "length": "full" }
                  },
                  "links": {
                    "opera_pagina": "https://bacalaurescu.ro/opere/morometii",
                    "comentariu_complet": "https://bacalaurescu.ro/api/v1/ai/opere/morometii/comentariu"
                  },
                  "suggestedNext": [
                    { "label": "Quiz pentru aceasta opera", "endpoint": "/api/v1/ai/opere/morometii/quiz" },
                    { "label": "Schema eseu", "endpoint": "/api/v1/ai/opere/morometii/schema-eseu" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai/opere/{slug}/lesson": {
      "get": {
        "tags": ["opere"],
        "summary": "Generate a structured lesson",
        "description": "Returns a 5-step lesson (explanation, 3 ideas, BAC example, questions, homework) with adjustable duration and style.",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "morometii" },
          { "name": "duration", "in": "query", "schema": { "type": "integer", "minimum": 5, "maximum": 60, "default": 15 } },
          { "name": "style", "in": "query", "schema": { "type": "string", "enum": ["calm", "motivational", "strict", "exam-focused"], "default": "calm" } }
        ],
        "responses": {
          "200": {
            "description": "Structured lesson",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "opera": "Moromeții",
                    "autor": "Marin Preda",
                    "slug": "morometii",
                    "lesson_type": "structured_lesson",
                    "lesson": {
                      "durata_estimata_minute": 15,
                      "nivel": "exam",
                      "pas_1_explicatie_scurta": {
                        "titlu": "Cine, ce, când",
                        "durata_minute": 3,
                        "continut": "Moromeții este un roman din curentul Realism scrisă de Marin Preda..."
                      },
                      "pas_2_trei_idei_de_memorat": { "idei": ["...", "...", "..."] },
                      "pas_3_exemplu_pentru_bac": { "scena_emblematica": { "titlu": "...", "descriere": "..." } },
                      "pas_4_intrebari_de_verificare": { "intrebari": [{ "intrebare": "...", "raspuns_corect": "..." }] },
                      "pas_5_tema_pentru_elev": { "sarcina": "...", "timp_recomandat": "15-20 minute" }
                    }
                  },
                  "meta": { "style": "calm", "style_hint": "Ton calm, prietenos...", "lesson_duration_minutes": 15 }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai/opere/{slug}/explain-audio-script": {
      "get": {
        "tags": ["opere"],
        "summary": "Audio script ready for TTS (2-3 minutes)",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Script conversational cu marker pentru pause si voice notes" } }
      }
    },
    "/api/v1/ai/opere/{slug}/checklist": {
      "get": {
        "tags": ["opere"],
        "summary": "BAC checklist (must_know / nice_to_know / common_traps)",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Checklist structurat pentru pregatire" } }
      }
    },
    "/api/v1/ai/opere/{slug}/teacher-notes": {
      "get": {
        "tags": ["opere"],
        "summary": "Teacher mode notes (what corector looks for, what penalizes)",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Notes profesionale pentru pregatire" } }
      }
    },
    "/api/v1/ai/opere/{slug}/istoric": {
      "get": {
        "tags": ["opere"],
        "summary": "Granular BAC history for this opera",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Aparitii istorice cu profil, sesiune, cerinta exacta, probabilitate" } }
      }
    },
    "/api/v1/ai/status": {
      "get": {
        "tags": ["exec"],
        "summary": "Health and status check",
        "responses": {
          "200": {
            "description": "Status OK",
            "content": {
              "application/json": {
                "example": {
                  "status": "ok",
                  "version": { "api": "1.0.0", "content": "2026.1.0", "bacYear": "2026" },
                  "database": { "status": "ok", "opere": 17, "autori": 15, "personaje": 96 }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai/capabilities": {
      "get": {
        "tags": ["exec"],
        "summary": "Capabilities and supported features",
        "responses": { "200": { "description": "Full feature list" } }
      }
    },
    "/api/v1/ai/priorities": {
      "get": {
        "tags": ["exec"],
        "summary": "Priority ranking of operas based on BAC history",
        "parameters": [
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30 } },
          { "name": "profile", "in": "query", "schema": { "type": "string", "enum": ["real", "uman"] } }
        ],
        "responses": { "200": { "description": "Ranked operas by priority score" } }
      }
    },
    "/api/v1/ai/simulation": {
      "get": {
        "tags": ["exec"],
        "summary": "Generate a BAC simulation (Subiect I + II + III)",
        "parameters": [
          { "name": "profile", "in": "query", "schema": { "type": "string", "enum": ["real", "uman"] } },
          { "name": "duration", "in": "query", "schema": { "type": "integer", "default": 180 } },
          { "name": "focus", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Full BAC-style simulation with random opera + cerinta" } }
      }
    },
    "/api/v1/ai/rubric/{subiect}": {
      "get": {
        "tags": ["exec"],
        "summary": "BAC grading rubric for each subject",
        "parameters": [
          { "name": "subiect", "in": "path", "required": true, "schema": { "type": "string", "enum": ["subiectul-i", "subiectul-ii", "subiectul-iii"] } }
        ],
        "responses": { "200": { "description": "Detailed rubric with what gains/loses points + score examples" } }
      }
    },
    "/api/v1/ai/repair": {
      "get": {
        "tags": ["exec"],
        "summary": "Repair specific mistakes with exercise",
        "parameters": [
          { "name": "work", "in": "query", "schema": { "type": "string" } },
          { "name": "mistake", "in": "query", "schema": { "type": "string" }, "example": "confunda-tema-cu-subiectul" }
        ],
        "responses": { "200": { "description": "Explanation + correct example + mini-exercise" } }
      }
    },
    "/api/v1/ai/vocab": {
      "get": {
        "tags": ["exec"],
        "summary": "Literary vocabulary with simple/academic explanations",
        "parameters": [
          { "name": "topic", "in": "query", "schema": { "type": "string", "enum": ["realism", "romantism", "modernism", "simbolism", "general"] } },
          { "name": "work", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "List of terms with explanations and examples" } }
      }
    },
    "/api/v1/ai/changelog": {
      "get": {
        "tags": ["exec"],
        "summary": "API changelog with version history",
        "parameters": [
          { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "Date YYYY-MM-DD" },
          { "name": "version", "in": "query", "schema": { "type": "string" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["major", "minor", "patch"] } }
        ],
        "responses": { "200": { "description": "Changelog entries with added/changed/fixed" } }
      }
    },
    "/api/v1/ai/test-cases": {
      "get": {
        "tags": ["exec"],
        "summary": "Golden test cases for API integrity",
        "responses": { "200": { "description": "10 test cases with expected responses" } }
      }
    },
    "/api/v1/ai/session-template": {
      "get": {
        "tags": ["exec"],
        "summary": "JSON template for session tracking with ChatGPT",
        "responses": { "200": { "description": "Session template structure" } }
      }
    },
    "/api/v1/ai/session-summary": {
      "post": {
        "tags": ["exec"],
        "summary": "Generate session summary with analysis and recommendations",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "duration_minutes": { "type": "integer" },
                  "opere_studied": { "type": "array", "items": { "type": "string" } },
                  "quizzes": { "type": "array", "items": { "type": "object" } },
                  "exercises_done": { "type": "integer" },
                  "weak_areas": { "type": "array", "items": { "type": "string" } },
                  "strong_areas": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Analysis + recommendations" } }
      }
    },
    "/api/v1/ai/review": {
      "get": {
        "tags": ["exec"],
        "summary": "Spaced repetition info and template",
        "responses": { "200": { "description": "Algorithm description + usage" } }
      },
      "post": {
        "tags": ["exec"],
        "summary": "Generate spaced repetition plan from progress",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "opera_slug": { "type": "string" },
                        "last_studied_iso": { "type": "string" },
                        "score": { "type": "integer" },
                        "difficulty": { "type": "string", "enum": ["easy", "medium", "hard"] },
                        "repetition_count": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Plan with today/tomorrow/this_week/next_week" } }
      }
    },
    "/api/v1/ai/opere/{slug}/schema-eseu": {
      "get": {
        "tags": ["opere"],
        "summary": "Essay structure for BAC exam",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["tema", "personaj", "relatie", "particularitati", "viziune"], "default": "tema" } },
          { "name": "profile", "in": "query", "schema": { "type": "string", "enum": ["real", "uman"], "default": "real" } },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["normal", "strict"], "default": "normal" } }
        ],
        "responses": { "200": { "description": "Paragraph-by-paragraph essay structure with examples" } }
      }
    },
    "/api/v1/ai/opere/{slug}/exercitii": {
      "get": {
        "tags": ["opere"],
        "summary": "Exercises with leveling",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "level", "in": "query", "schema": { "type": "string", "enum": ["easy", "medium", "bac"], "default": "medium" } }
        ],
        "responses": { "200": { "description": "Exercises adapted to difficulty level" } }
      }
    },
    "/api/v1/ai/opere/{slug}/greseli-frecvente": {
      "get": {
        "tags": ["opere"],
        "summary": "Common mistakes when writing about this opera",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Common mistakes (specific + general)" } }
      }
    },
    "/api/v1/ai/opere/{slug}/flashcards": {
      "get": {
        "tags": ["opere"],
        "summary": "Flashcards for spaced repetition",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Front/back flashcards organized by category and difficulty" } }
      }
    },
    "/api/v1/ai/opere/{slug}/citate": {
      "get": {
        "tags": ["opere"],
        "summary": "Citations with usage guidance",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "mode", "in": "query", "schema": { "type": "string", "enum": ["all", "exam-safe"], "default": "all" } }
        ],
        "responses": { "200": { "description": "Citations with usage hints and warnings" } }
      }
    },
    "/api/v1/ai/opere/{slug}/model-essay": {
      "get": {
        "tags": ["opere"],
        "summary": "[WIP] Model essays at different score levels",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "score", "in": "query", "schema": { "type": "integer", "enum": [15, 20, 25, 30] } }
        ],
        "responses": { "200": { "description": "Work in progress - see alternative" } }
      }
    },
    "/api/v1/ai/learning-path": {
      "get": {
        "tags": ["calendar"],
        "summary": "Personalized learning plan for BAC preparation",
        "parameters": [
          { "name": "subject", "in": "query", "schema": { "type": "string", "default": "romana" } },
          { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 120 } },
          { "name": "level", "in": "query", "schema": { "type": "string", "enum": ["beginner", "medium", "advanced"] } },
          { "name": "profile", "in": "query", "schema": { "type": "string", "enum": ["real", "uman"] } },
          { "name": "weakness", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated weakness keywords (e.g., 'poezie,subiectul-ii')" }
        ],
        "responses": {
          "200": {
            "description": "Day-by-day learning plan",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "subject": "Limba si Literatura Romana",
                    "totalDays": 30,
                    "level": "medium",
                    "plan": [
                      {
                        "day": 1,
                        "weekday": "Luni",
                        "topic": "Moromeții - introducere si rezumat",
                        "tasks": ["Citeste fisa operei", "Invata curentul literar", "Memoreaza tema centrala si 2 simboluri"],
                        "estimated_minutes": 30,
                        "resources": [{ "label": "Fisa opera", "url": "https://bacalaurescu.ro/opere/morometii.md" }]
                      }
                    ],
                    "general_advice": ["Studiaza minim 30-45 minute pe zi, regulat..."]
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/ai/diagnostic/{subject}": {
      "get": {
        "tags": ["exec"],
        "summary": "Diagnostic test to identify weak areas",
        "parameters": [
          { "name": "subject", "in": "path", "required": true, "schema": { "type": "string", "enum": ["romana"] } },
          { "name": "level", "in": "query", "schema": { "type": "string", "enum": ["all", "beginner", "medium", "advanced"] } },
          { "name": "profile", "in": "query", "schema": { "type": "string", "enum": ["real", "uman"] } }
        ],
        "responses": { "200": { "description": "Diagnostic questions with categories" } }
      }
    },
    "/api/v1/ai/evaluate-essay": {
      "post": {
        "tags": ["exec"],
        "summary": "[WIP] Evaluate essay against BAC scoring criteria",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "opera": { "type": "string" },
                  "cerinta": { "type": "string" },
                  "profile": { "type": "string" },
                  "text": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "503": { "description": "Work in progress - alternative provided" } }
      }
    },
    "/api/v1/ai/progress/export": {
      "get": {
        "tags": ["exec"],
        "summary": "Template for student progress export (for ChatGPT memory)",
        "responses": { "200": { "description": "JSON template to fill in" } }
      }
    },
    "/api/v1/ai/next": {
      "get": {
        "tags": ["exec"],
        "summary": "Next best action based on current opera + score + weakness",
        "parameters": [
          { "name": "current", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "score", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 } },
          { "name": "weakness", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Adaptive next-step recommendation" } }
      }
    },
    "/api/v1/ai/compare": {
      "get": {
        "tags": ["exec"],
        "summary": "Compare 2-4 operas (themes, movements, genres)",
        "parameters": [
          { "name": "works", "in": "query", "required": true, "schema": { "type": "string" }, "example": "morometii,ion" }
        ],
        "responses": { "200": { "description": "Comparison with similarities and differences" } }
      }
    },
    "/api/v1/ai/confusions": {
      "get": {
        "tags": ["exec"],
        "summary": "Common conceptual confusions (with examples)",
        "parameters": [
          { "name": "topic", "in": "query", "schema": { "type": "string", "enum": ["realism", "romantism", "modernism", "simbolism", "general"] } },
          { "name": "work", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Confusions with simple explanations" } }
      }
    },
    "/api/v1/ai/subiectul-i": {
      "get": {
        "tags": ["exec"],
        "summary": "Guide for BAC Subiectul I (text comprehension)",
        "responses": { "200": { "description": "Structure, examples, mistakes for Subiectul I" } }
      }
    },
    "/api/v1/ai/subiectul-i/exercitii": {
      "get": {
        "tags": ["exec"],
        "summary": "Exercises for Subiectul I",
        "responses": { "200": { "description": "Question templates for argumentative texts" } }
      }
    },
    "/api/v1/ai/subiectul-ii": {
      "get": {
        "tags": ["exec"],
        "summary": "Guide for BAC Subiectul II (literary commentary)",
        "responses": { "200": { "description": "All topics with structure and models" } }
      }
    },
    "/api/v1/ai/subiectul-ii/{topic}": {
      "get": {
        "tags": ["exec"],
        "summary": "Specific topic in Subiectul II",
        "parameters": [
          { "name": "topic", "in": "path", "required": true, "schema": { "type": "string", "enum": ["perspectiva-narativa", "rolul-notatiilor-autorului", "idee-poetica", "relatia-dintre-ideea-poetica-si-mijloacele-artistice"] } }
        ],
        "responses": { "200": { "description": "Detailed guide with model answers" } }
      }
    },
    "/api/v1/ai/subiecte/{subiect}/greseli-frecvente": {
      "get": {
        "tags": ["exec"],
        "summary": "Common mistakes for each BAC subiect",
        "parameters": [
          { "name": "subiect", "in": "path", "required": true, "schema": { "type": "string", "enum": ["subiectul-i", "subiectul-ii", "subiectul-iii"] } }
        ],
        "responses": { "200": { "description": "Mistakes specific to that BAC section" } }
      }
    },
    "/api/v1/ai/review": {
      "get": {
        "tags": ["exec"],
        "summary": "[WIP] Spaced repetition review plan",
        "responses": { "200": { "description": "Work in progress" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Optional. Anonymous tier: 60 req/min. With API key: 300+ req/min. Request at /ai or contact@bacalaurescu.ro"
      }
    },
    "parameters": {
      "LevelFilter": {
        "name": "level",
        "in": "query",
        "schema": { "type": "string", "enum": ["beginner", "medium", "advanced", "exam"], "default": "exam" },
        "description": "Adapteaza nivelul de detaliu si vocabular (universal filter pe majoritatea endpoints)"
      },
      "LengthFilter": {
        "name": "length",
        "in": "query",
        "schema": { "type": "string", "enum": ["short", "medium", "full"], "default": "full" },
        "description": "Trunchiaza output-ul (universal filter)"
      },
      "ProfileFilter": {
        "name": "profile",
        "in": "query",
        "schema": { "type": "string", "enum": ["real", "uman", "both"], "default": "both" },
        "description": "Adapteaza pentru profil BAC real sau uman"
      },
      "ExplainFilter": {
        "name": "explain",
        "in": "query",
        "schema": { "type": "string", "enum": ["simple", "normal", "academic"], "default": "normal" },
        "description": "explain=simple inlocuieste termenii literari complecsi cu echivalenti simpli (pentru elevi care invata)"
      },
      "ModeFilter": {
        "name": "mode",
        "in": "query",
        "schema": { "type": "string", "enum": ["normal", "strict"], "default": "normal" },
        "description": "mode=strict adauga note de tipul 'profesor exigent' cu greseli care vor fi penalizate"
      }
    }
  },
  "x-universal-filters": {
    "description": "Aceste query params sunt suportate pe majoritatea endpoint-urilor GET (opere, autori, personaje, sections, context, schema-eseu):",
    "filters": [
      "level: beginner | medium | advanced | exam",
      "length: short | medium | full",
      "profile: real | uman | both",
      "explain: simple | normal | academic",
      "mode: normal | strict"
    ],
    "example": "GET /api/v1/ai/opere/morometii?level=beginner&length=short&explain=simple"
  },
  "externalDocs": {
    "description": "Full AI integration guide",
    "url": "https://bacalaurescu.ro/ai"
  }
}