Runtime configuration API for LLM and agent settings

Configuration is stored in the MongoDB sistema_config collection and takes priority over .env variables, enabling hot-reload of both LLM provider selection and per-agent tuning parameters without restarting the API process. When no database record exists the system falls back to the values loaded from .env at startup.

GET /config/llm

Return the currently active LLM provider configuration. Authentication: Authorization: Bearer <token> required.

Response `200 OK`

{
  "provider": "openrouter",
  "model": "minimax/minimax-m2.5:free",
  "host": null,
  "available_providers": ["ollama", "openrouter"],
  "available_models_ollama": ["phi3:mini"],
  "available_models_openrouter": ["minimax/minimax-m2.5:free", "google/gemma-3-27b-it:free"]
}

provider

string

Active provider. One of ollama | openrouter.

model

string

Model name currently in use for the active provider.

host

string | null

Ollama base URL (e.g. http://localhost:11434). Always null when provider is openrouter.

available_providers

array

Sorted list of supported providers: ["ollama", "openrouter"].

available_models_ollama

array

Models discovered from the OLLAMA_MODELS environment variable (comma-separated list), falling back to OLLAMA_MODEL.

available_models_openrouter

array

Models from OPENROUTER_MODEL plus any entries in OPENROUTER_FALLBACK_MODELS.

PUT /config/llm

Persist a new LLM provider configuration to MongoDB. Changes take effect on the next agent run — the config is read fresh by create_llm_provider() each time an agent starts. Authentication: Authorization: Bearer <token> required.

Request body

{
  "provider": "ollama",
  "model": "phi3:mini",
  "host": "http://localhost:11434"
}

provider

string

required

Target provider. Must be ollama or openrouter.

model

string

required

Model identifier for the chosen provider (e.g. phi3:mini, minimax/minimax-m2.5:free).

host

string

Base URL for the Ollama server. Required when provider is ollama. Ignored for openrouter.

Response `200 OK`

{
  "provider": "ollama",
  "model": "phi3:mini",
  "host": "http://localhost:11434",
  "timestamp": "2024-01-15T10:30:00.000000+00:00"
}

Error responses

Status	Condition
`400 Bad Request`	`provider` is `ollama` but `host` was not provided.
`422 Unprocessable Entity`	`provider` is not `ollama` or `openrouter`.

POST /config/llm/probar

Test connectivity to an LLM provider without persisting any changes. If the request body is empty (or omitted), the currently saved configuration is tested. Authentication: Authorization: Bearer <token> required.

Request body (optional)

{
  "provider": "ollama",
  "host": "http://localhost:11434"
}

Both fields are optional. When provided they override the stored config for this test only.

How the test works

Ollama — sends GET {host}/api/tags (5-second timeout) and parses the returned model list.
OpenRouter — calls OpenRouterProvider.health_check() which verifies the API key via the OpenRouter client.

Response `200 OK`

{
  "ok": true,
  "latencia_ms": 145,
  "provider": "ollama",
  "modelos_disponibles": ["phi3:mini", "gemma4:e4b"],
  "error": null,
  "mensaje": "Conexión exitosa"
}

boolean

true if the provider responded successfully.

latencia_ms

integer | null

Round-trip time in milliseconds. null on connection failure.

provider

string

The provider that was tested.

modelos_disponibles

array | null

For Ollama: list of model names returned by /api/tags. For OpenRouter: null (the health check only verifies the API key, it does not enumerate models).

error

string | null

Human-readable error detail when ok is false. null on success.

mensaje

string

"Conexión exitosa" or "No se pudo conectar al servidor".

Use POST /config/llm/probar before calling PUT /config/llm to verify that the new provider is reachable. Pass provider and host in the body to test without persisting anything.

GET /config/agentes

Return the current per-agent tuning configuration. If no custom configuration has been saved, the endpoint returns built-in defaults. Authentication: Authorization: Bearer <token> required.

Response `200 OK`

{
  "watcher":    { "timeout_segundos": 60,  "retry_veces": 3 },
  "ocr":        { "timeout_segundos": 120, "retry_veces": 2 },
  "classifier": { "temperatura": 0.7,      "max_tokens": 2000 },
  "storage":    { "timeout_segundos": 30 }
}

Agent	Parameters	Defaults
`watcher`	`timeout_segundos`, `retry_veces`	60 s, 3 retries
`ocr`	`timeout_segundos`, `retry_veces`	120 s, 2 retries
`classifier`	`temperatura`, `max_tokens`	0.7, 2000
`storage`	`timeout_segundos`	30 s

PUT /config/agentes

Save a new agent configuration to MongoDB (sistema_config collection, document key agentes_config). The full object for all four agents must be provided. Authentication: Authorization: Bearer <token> required.

Request body

{
  "watcher":    { "timeout_segundos": 90,  "retry_veces": 5 },
  "ocr":        { "timeout_segundos": 180, "retry_veces": 3 },
  "classifier": { "temperatura": 0.3,      "max_tokens": 4000 },
  "storage":    { "timeout_segundos": 60 }
}

All four agent blocks are required — partial updates are not supported. The endpoint performs an upsert, so the first call creates the document and subsequent calls replace it.

Response `200 OK`

{ "message": "Configuración guardada" }

GET /health

Check MongoDB connectivity. No authentication required.

{ "status": "ok" }

Returns 503 Service Unavailable if the MongoDB ping command fails.

GET /info

Return API metadata. No authentication required.

{
  "nombre": "Expedientes API",
  "version": "2.2.0",
  "descripcion": "API read-write con autenticación JWT para expedientes docentes UNEG",
  "fecha_deploy": "2026-04-19T00:00:00Z",
  "endpoints_totales": 37,
  "autenticacion": "JWT Bearer",
  "contacto": "soporte@uneg.edu.ve",
  "capacidades": {
    "lectura": true,
    "escritura": true,
    "auditoria": true,
    "validacion": true,
    "autenticacion": true
  },
  "documentacion": "/docs"
}

GET /config/tipos-documento

Return the full catalog of document types recognised by the system. No authentication required.

{
  "tipos_documento": [
    {
      "id": "cedula_identidad",
      "nombre": "Cédula de Identidad",
      "obligatorio": true,
      "descripcion": "Documento de identificación personal",
      "formatos_aceptados": ["pdf", "jpg", "png"],
      "tamaño_maximo_mb": 25
    },
    {
      "id": "titulo_universitario",
      "nombre": "Título Universitario",
      "obligatorio": true,
      "descripcion": "Diploma de licenciatura o grado",
      "formatos_aceptados": ["pdf"],
      "tamaño_maximo_mb": 25
    }
  ],
  "documentos_requeridos": 10,
  "total_tipos_posibles": 22
}

tipos_documento

array

Full list of 22 document type definitions. Each entry includes id, nombre, obligatorio, descripcion, formatos_aceptados, and tamaño_maximo_mb.

documentos_requeridos

integer

Number of mandatory document types (obligatorio: true). Currently 10.

total_tipos_posibles

integer

Total number of document type definitions in the catalog. Currently 22.

The mandatory types are: cedula_identidad, rif, partida_nacimiento, titulo_bachiller, certificado_notas_bachillerato, titulo_universitario, certificado_notas_pregrado, fondo_negro_titulo, acta_grado, resolucion_nombramiento. All others (postgrado certificates, diplomas, constancias, etc.) are optional.

GET /config/estados-validacion

Return the enumeration of valid document validation states. No authentication required.

{
  "estados": [
    { "id": "pendiente",         "descripcion": "Esperando revisión" },
    { "id": "aprobado",          "descripcion": "Válido para expediente" },
    { "id": "rechazado",         "descripcion": "No cumple requisitos" },
    { "id": "requiere_revision", "descripcion": "Requiere aclaración" }
  ]
}

Use the id values as the estado_validacion filter parameter on GET /estadisticas/documentos.

GET /config/estados-docente

Return the enumeration of valid docente status values. No authentication required.

{
  "estados": [
    { "id": "activo",       "descripcion": "Docente activo" },
    { "id": "inactivo",     "descripcion": "Docente inactivo" },
    { "id": "en_revision",  "descripcion": "Expediente en revisión" },
    { "id": "completo",     "descripcion": "Expediente completo" },
    { "id": "incompleto",   "descripcion": "Expediente incompleto" }
  ]
}

Use the id values as the agrupar_por=status grouping on GET /estadisticas/expedientes.

Autenticación

Expedientes y Documentos

Agentes y Sistema

GET /config/llm

Response `200 OK`

PUT /config/llm

Request body

Response `200 OK`

Error responses

POST /config/llm/probar

Request body (optional)

How the test works

Response `200 OK`

GET /config/agentes

Response `200 OK`

PUT /config/agentes

Request body

Response `200 OK`

GET /health

GET /info

GET /config/tipos-documento

GET /config/estados-validacion

GET /config/estados-docente

Build docs developers (and LLMs) love

Autenticación

Expedientes y Documentos

Agentes y Sistema

Documentation Index

​GET /config/llm

​Response 200 OK

​PUT /config/llm

​Request body

​Response 200 OK

​Error responses

​POST /config/llm/probar

​Request body (optional)

​How the test works

​Response 200 OK

​GET /config/agentes

​Response 200 OK

​PUT /config/agentes

​Request body

​Response 200 OK

​GET /health

​GET /info

​GET /config/tipos-documento

​GET /config/estados-validacion

​GET /config/estados-docente

Build docs developers (and LLMs) love

GET /config/llm

Response `200 OK`

PUT /config/llm

Request body

Response `200 OK`

Error responses

POST /config/llm/probar

Request body (optional)

How the test works

Response `200 OK`

GET /config/agentes

Response `200 OK`

PUT /config/agentes

Request body

Response `200 OK`

GET /health

GET /info

GET /config/tipos-documento

GET /config/estados-validacion

GET /config/estados-docente