Logs streaming, download, and audit trail endpoints

The system maintains two complementary audit trails: real-time operational logs streamed over Server-Sent Events (SSE) from operational.log, and a structured event history written to both audit.jsonl (JSONL file) and the MongoDB auditoria collection. The file-based trail is designed for export and long-term retention; the MongoDB trail supports per-docente and per-document queries.

GET /logs/stream

Stream new log lines in real time using Server-Sent Events. Authentication: JWT passed as a query parameter ?token=<jwt> (EventSource in browsers does not support custom headers). Response content type: text/event-stream

Query parameters

token

string

required

Valid JWT. Passed as a query parameter because the browser EventSource API does not allow custom headers.

agente

string

Filter events to a specific agent. Accepted values: watcher | ocr | classifier | storage | api. When omitted, events from all agents are returned.

nivel

string

Filter events by log level (case-insensitive). Accepted values: INFO | WARNING | ERROR. When omitted, all levels are forwarded.

Event format

Each event has type log and a JSON payload:

event: log
data: {"timestamp":"2024-01-15T10:30:01.123456","nivel":"INFO","agente":"ocr","mensaje":"Procesando archivo cedula_12345678.pdf"}

event: log
data: {"timestamp":"2024-01-15T10:30:02.456789","nivel":"ERROR","agente":"classifier","mensaje":"LLM timeout after 120s"}

A keepalive event is sent every 15 seconds when no new lines are available, to prevent proxies from closing the connection:

event: keepalive
data:

Browser usage

const token = localStorage.getItem("jwt");
const es = new EventSource(`/logs/stream?token=${token}&agente=ocr&nivel=ERROR`);

es.addEventListener("log", (event) => {
  const entry = JSON.parse(event.data);
  console.log(`[${entry.nivel}] ${entry.agente}: ${entry.mensaje}`);
});

es.addEventListener("keepalive", () => {
  // connection is alive — no-op
});

es.onerror = () => {
  // EventSource natively retries on disconnect
};

Response headers

Header	Value
`Content-Type`	`text/event-stream`
`Cache-Control`	`no-cache`
`X-Accel-Buffering`	`no` (disables nginx response buffering)
`Content-Encoding`	`identity` (disables gzip so chunks flush immediately)

The stream tails operational.log from the end of file at connection time — you will only receive lines written after you connect. The embedded dashboard (/ui/index.html) uses this endpoint to display a live log panel showing the most recent events. If operational.log does not yet exist, the server holds the connection open and sends keepalive events until the file is created.

GET /logs/descargar

Download the full audit trail as a JSONL file attachment. Authentication: Authorization: Bearer <token> required.

Response

Returns a StreamingResponse with:

Content-Type: application/json
Content-Disposition: attachment; filename="audit-YYYY-MM-DD.jsonl" (date of the download request)

The file is in JSONL format — one loguru-serialized JSON object per line. Each line is produced by loguru’s serialize=True sink and has the following top-level structure:

{"text":"...","record":{"time":{"repr":"2024-01-15T10:30:00.000000+00:00","timestamp":1705316200.0},"level":{"name":"INFO","no":20,"icon":"ℹ️"},"message":"[classifier] clasificado: ok","extra":{"audit":true,"agent":"classifier","cedula":"12345678","documento_tipo":"titulo_universitario","archivo":"titulo_12345678.pdf","detalle":"Clasificado con confianza 0.97","timestamp_utc":"2024-01-15T10:30:00.000000+00:00"}}}

JSONL field reference

All audit-specific data is stored under record.extra:

Path	Description
`record.time.repr`	ISO 8601 timestamp with timezone
`record.level.name`	Log level, always `"INFO"` for audit events
`record.message`	Human-readable summary: `"[{agente}] {accion}: {resultado}"`
`record.extra.agent`	Agent or subsystem that produced the event
`record.extra.cedula`	Docente identifier, when applicable (`null` otherwise)
`record.extra.documento_tipo`	Document type, when applicable (`null` otherwise)
`record.extra.archivo`	Source filename, when applicable (`null` otherwise)
`record.extra.detalle`	Free-text context or error message (`null` otherwise)
`record.extra.timestamp_utc`	ISO 8601 UTC event time from `audit_log()`

Log rotation

Parameter	Default
Max file size	50 MB (configurable via `AUDIT_ROTATION`)
Retention	90 days (configurable via `AUDIT_RETENTION`)

Returns 404 Not Found if no audit events have been written yet (file does not exist).

GET /admin/auditoria/expediente/{cedula}

Retrieve structured audit events for a specific docente’s dossier from MongoDB. Authentication: Admin role required (Authorization: Bearer <admin-token>). Returns 403 Forbidden for non-admin tokens.

Path parameters

cedula

string

required

The docente’s national ID (cédula). Must match an existing docente record or a 404 is returned.

Query parameters

dias

integer

default:"7"

Look-back window in days. Minimum 1, maximum 90. Events older than now - dias are excluded.

Response `200 OK`

Returns up to 100 events, sorted by timestamp descending (newest first).

{
  "docente_cedula": "12345678",
  "rango_dias": 7,
  "fecha_desde": "2024-01-08T10:00:00",
  "total_eventos": 12,
  "eventos": [
    {
      "timestamp": "2024-01-15T10:30:00",
      "tipo_evento": "chat_expediente_consulta",
      "usuario": "admin@uneg.edu.ve",
      "detalles": { "pregunta": "¿Cuántos documentos faltan?" },
      "resultado": "exitoso"
    },
    {
      "timestamp": "2024-01-14T09:15:00",
      "tipo_evento": "documento_insertado",
      "usuario": "sistema",
      "detalles": { "tipo": "cedula_identidad" },
      "resultado": "exitoso"
    }
  ]
}

eventos[].timestamp

string

ISO 8601 event timestamp.

eventos[].tipo_evento

string

Event type string (see common event types below).

eventos[].usuario

string

The authenticated user (sub claim from JWT) or "sistema" for agent-generated events.

eventos[].detalles

object

Event-specific context payload. Contents vary by tipo_evento.

eventos[].resultado

string

Outcome string, e.g. "exitoso", "error", "ok".

Events are sanitised before being returned. Only the fields timestamp, tipo_evento, usuario, detalles, and resultado are included. Internal filesystem paths, IP addresses, and other sensitive fields stored in MongoDB are stripped.

Error responses

Status	Condition
`403 Forbidden`	Token is valid but the user does not have the `admin` role.
`404 Not Found`	No docente with the given `cedula` exists.

GET /admin/auditoria/documento/{documento_id}

Retrieve the full change history for a specific document. Authentication: Admin role required.

Path parameters

documento_id

string

required

MongoDB ObjectId of the document (as a hex string). No date limit is applied — all events for this document are returned.

Response `200 OK`

{
  "documento_id": "6624a1f3c2e4b5f0a1234567",
  "total_eventos": 4,
  "eventos": [
    {
      "timestamp": "2024-01-15T10:31:05",
      "tipo_evento": "documento_insertado",
      "usuario": "sistema",
      "detalles": { "tipo": "titulo_universitario", "archivo": "titulo_12345678.pdf" },
      "resultado": "exitoso"
    },
    {
      "timestamp": "2024-01-15T10:30:00",
      "tipo_evento": "ocr_completado",
      "usuario": "sistema",
      "detalles": { "confianza": 0.97, "paginas": 2 },
      "resultado": "exitoso"
    }
  ]
}

Events are sorted newest first. Unlike the dossier endpoint, there is no 100-event cap or date filter.

Audit event types

Audit events are written by all four pipeline agents and by the API itself via the audit_log() function in src/core/logger.py.

Event type	Producer	Description
`clasificado`	`classifier`	Document classified by LLM
`documento_insertado`	`storage`	Document record persisted to MongoDB
`archivo_movido`	`storage`	Source file relocated to processed folder
`ocr_completado`	`ocr`	OCR extraction finished for a file
`docente_creado`	`storage`	New docente record created
`chat_expediente_consulta`	`api`	User queried a dossier via the chat endpoint
`stop_agente`	`api`	User called `POST /agentes/{nombre}/stop`

The auditoria MongoDB collection and the audit.jsonl file are written in parallel. The JSONL file is optimised for bulk export and offline analysis; the MongoDB collection is optimised for per-docente and per-document queries via the admin endpoints above.

Autenticación

Expedientes y Documentos

Agentes y Sistema

GET /logs/stream

Query parameters

Event format

Browser usage

Response headers

GET /logs/descargar

Response

JSONL field reference

Log rotation

GET /admin/auditoria/expediente/{cedula}

Path parameters

Query parameters

Response `200 OK`

Error responses

GET /admin/auditoria/documento/{documento_id}

Path parameters

Response `200 OK`

Audit event types

Build docs developers (and LLMs) love

Autenticación

Expedientes y Documentos

Agentes y Sistema

Documentation Index

​GET /logs/stream

​Query parameters

​Event format

​Browser usage

​Response headers

​GET /logs/descargar

​Response

​JSONL field reference

​Log rotation

​GET /admin/auditoria/expediente/{cedula}

​Path parameters

​Query parameters

​Response 200 OK

​Error responses

​GET /admin/auditoria/documento/{documento_id}

​Path parameters

​Response 200 OK

​Audit event types

Build docs developers (and LLMs) love

GET /logs/stream

Query parameters

Event format

Browser usage

Response headers

GET /logs/descargar

Response

JSONL field reference

Log rotation

GET /admin/auditoria/expediente/{cedula}

Path parameters

Query parameters

Response `200 OK`

Error responses

GET /admin/auditoria/documento/{documento_id}

Path parameters

Response `200 OK`

Audit event types