Define next-gen requirements for Raven CMDB event integration

[alexandervazquez98]

Pre-flight Checks

• I searched existing issues for Raven/CMDB integration and did not find a duplicate.
• This issue is a requirements/TODO tracking issue for maintainer review.

Problem Description

Raven is being designed as a local CMDB + operational timeline for CIs. next-gen is expected to be one of the upstream ecosystems that observes network/CI activity and provides signals for Raven to record.

Before wiring the two systems together, we need to verify what next-gen must provide so Raven can reliably create CIs, attach events to the correct ci_id, preserve evidence, and deduplicate repeated alerts.

Proposed Solution

Define and verify a next-gen → Raven integration contract.

At minimum, next-gen should be able to emit or expose enough data for Raven commands such as:

raven event capture <ci-id> --source next-gen --text "..."
raven event ingest --source next-gen --file alert.json
raven timeline <ci-id>

Normalized event payload example:

{
  "ci_id": "FW-MAIN-001",
  "type": "network_alert",
  "severity": "warning",
  "summary": "High packet loss detected on WAN link",
  "external_id": "ng-98765",
  "observed_at": "2026-05-28T21:00:00Z",
  "raw": "{...source evidence...}"
}

TODO / Requirements to Verify

CI identity

• Confirm next-gen can provide a stable Raven-compatible ci_id for each monitored CI.
• If ci_id is unavailable, decide whether next-gen should resolve it before emitting events or include aliases such as IP/hostname/serial/MAC.
• Define naming conventions for ci_id values.

Event identity and deduplication

• Confirm every next-gen event has a stable external_id.
• Define Raven dedup key convention: usually next-gen:<external_id>.
• Confirm repeated alerts/retries do not create duplicate Raven events.

Event fields

• Define supported event type values, e.g. network_alert, diagnosis, maintenance, incident, resolution.
• Define supported severity vocabulary, e.g. info, warning, critical.
• Define status vocabulary, e.g. open, triaged, resolved.
• Ensure summary is short and operator-readable.
• Ensure raw evidence or source payload can be preserved when useful.

Timing

• Confirm next-gen can provide observed_at in RFC3339 format.
• Let Raven set ingested_at when it stores the event.

Transport

• Decide first integration method: file, stdout pipe, local HTTP, or direct command execution.
• For MVP, prefer either raven event capture for text or raven event ingest --file for normalized JSON.
• Later consider event ingest --stdin or local HTTP endpoint.

AI/proxy behavior

• Decide where Gemini CLI / Gemini proxy / Ollama agents receive Raven instructions.
• Ensure agents do not invent ci_id values.
• Ensure agents choose event capture for freeform diagnosis and event ingest for normalized structured events.
• Ensure source is explicit: next-gen, gemini-cli, ollama, etc.

Storage roadmap

• Raven currently stores JSON under user config.
• Verify what needs to be stable before moving Raven to SQLite.
• Avoid allowing models to write SQLite directly; prefer Raven CLI/API validation first.

Acceptance Criteria

• A minimal next-gen payload contract is documented.
• A sample next-gen alert can be converted into a Raven event.
• The event lands on the correct Raven CI timeline.
• Duplicate delivery of the same next-gen alert is rejected or safely ignored by Raven.
• Missing/unknown CI IDs have a defined handling path.

Additional Context

Related Raven docs/work in progress:

• docs/design/next-gen-event-ingest.md
• docs/ai-usage.md
• docs/agent-setup.md

Raven currently supports:

raven ci add ...
raven ci list
raven ci show <ci-id>
raven event capture <ci-id> --source ... --text ...
raven event ingest --source next-gen --file alert.json
raven timeline <ci-id>

[alexandervazquez98]

Yo lo pasaría a needs-revision antes de aprobarlo.

La intención está bien y no parece duplicado, pero falta cerrar el contrato contra lo que next-gen ya expone hoy: CI.id / ci_ref.id, eventos con id, ci_id, metric_id, severidad/estado en mayúsculas, created_at/last_seen, y dedupe interno por CI + métrica + tipo de evento. El payload propuesto suma external_id, observed_at, raw y vocabularios normalizados que todavía no están mapeados.

Para dejarlo accionable, agregaría:

• si Raven espeja CIs de next-gen o puede crear CIs faltantes;
• qué campo exacto será el external_id estable;
• cómo se mapean severity/status/type actuales;
• qué tiempo se usa: observed, created, last_seen o varios;
• MVP de transporte: REST pull, JSON file/stdout o Raven CLI.

[alexandervazquez98]

Ajusto el contrato con las decisiones actuales de Raven:

• Raven no va a tener permisos sobre next-gen. Raven funciona como memoria CMDB/timeline para IA y operadores, no como writer/orchestrator de next-gen.
• Raven va a manejar su propio ci_id, totalmente separado de CI.id / ci_ref.id de next-gen. No queremos depender de IDs internos de next-gen como identidad canónica.
• Los IDs de next-gen entran como referencias externas o aliases. Ejemplo: source=next-gen, type=ci_id, value=<next-gen CI.id> resuelve hacia un ci_id de Raven.
• El external_id del evento Raven debería mapear al event.id estable de next-gen, y el dedupe recomendado sería next-gen:<event.id>.
• Severidad Raven queda limitada a tres valores: warning, exception, informative. Hay que mapear desde la severidad/estado actual en mayúsculas de next-gen.
• observed_at debe venir de created_at de next-gen. last_seen puede preservarse en raw o en detalles si hace falta, pero no reemplaza el tiempo observado inicial para el MVP.
• Transporte MVP: consumir JSON desde una API/export existente de next-gen y pasarlo a Raven por CLI, idealmente raven event ingest --source next-gen --stdin o --file.

Payload Raven objetivo después de normalizar:

{
  "ci_id": "RAVEN-FW-MAIN-001",
  "type": "network_alert",
  "severity": "warning",
  "status": "open",
  "summary": "High packet loss detected on WAN link",
  "external_id": "<next-gen event.id>",
  "observed_at": "<next-gen created_at>",
  "raw": "{...original next-gen payload...}"
}

Próximo ajuste recomendado en Raven: agregar alias/reference resolution para mapear next-gen CI refs, IP, hostname, serial o MAC hacia el ci_id canónico de Raven antes de ingerir eventos.

[alexandervazquez98]

Perfecto, con estas decisiones el contrato queda mucho más claro.

Entonces para este issue tomaría como conclusión:

• Raven mantiene identidad propia de CI y next-gen entra como alias/reference.
• external_id será next-gen event.id, con dedupe next-gen:<event.id>.
• observed_at sale de created_at; last_seen se preserva como detalle/raw.
• El MVP no requiere permisos de Raven sobre next-gen, solo consumo/export JSON y posterior ingest por CLI.

Me parece que el próximo corte debería ser:

1. Raven: alias/reference resolution hacia ci_id canónico.
2. next-gen: payload/export mínimo estable con event.id, CI refs, created_at, severity/status/type y raw.
3. Integración: normalizador hacia el payload Raven objetivo.

Con eso, este issue puede pasar de revisión abierta a contrato aceptado para desglosar tareas.

[alexandervazquez98]

De acuerdo. Tomo este issue como contrato aceptado para desglose.

Del lado de Raven voy a abrir/implementar primero alias/reference resolution hacia ci_id canónico. Eso deja listo el punto donde next-gen puede entregar CI.id / ci_ref.id, IP, hostname, serial o MAC como referencia externa sin que Raven dependa de esos IDs como identidad.

Después quedaría pendiente del lado next-gen definir/exportar el payload mínimo estable, y la integración/normalizador puede mapearlo al payload Raven objetivo.

[alexandervazquez98]

Actualización sobre agente local / bridge Ollama-Raven-next-gen:

Como next-gen ya tiene soporte nativo para una IA local/chat operacional, parece mejor ubicar acá el bridge/tool-loop local en vez de esperar que la UI oficial de Ollama ejecute tools/MCP por sí sola.

Hallazgo de diseño:

• Ollama puede emitir tool_calls por API, pero el cliente debe ejecutar las tools y devolver los resultados al modelo.
• La UI oficial de Ollama sirve para chat/instrucciones, pero no conviene asumir ejecución MCP/tooling nativa estable.
• Por lo tanto, si queremos consultas reales desde IA local, el loop debería vivir en next-gen o en un wrapper local asociado al runtime de next-gen.

Propuesta inicial para next-gen:

• Implementar un bridge local/simple, posiblemente empezando con bash/shell, que actúe como cliente de herramientas.
• Mantener Raven como memoria operacional/CMDB/timeline/persistencia.
• Mantener next-gen como sistema upstream/event source y host natural del chat IA local.
• Para reads automáticos:
  • Raven: resolver CI refs y leer timeline vía Raven MCP/CLI.
  • next-gen: consultar eventos/nodos/métricas vía API o raven nextgen-mcp read-only.
• Para writes:
  • Raven event writes requieren aprobación explícita del operador.
  • Mutaciones en next-gen siguen deshabilitadas/diferidas (ack, comment, close, run_diagnostic) hasta definir guardrails.

Regla crítica de identidad que debe mantenerse:

• Raven CI IDs son canónicos para Raven.
• next-gen CI IDs son upstream refs, no Raven CI IDs.
• Deben representarse como source=next-gen type=ci_id value=<nextgen_ci_id> y resolverse por Raven aliases antes de razonamiento o persistencia CI-specific en Raven.

Esto evita entregar tokens/capacidad de mutación directamente al modelo/Ollama UI y aprovecha el chat local existente en next-gen como punto de integración operacional.