sendnrw/glpi-neural-brain

Fork 0

Files

T

jbergner 2253041756 RC-1

2026-08-07 23:51:55 +02:00

6.4 KiB

Raw Blame History

Integrated Source-Agent mode

The same neural-brain binary and Docker image now has two runtime roles:

BRAIN_MODE=brain

starts the full graph/AI application, while

BRAIN_MODE=agent

starts only the distributed source poller. Agent mode does not initialize the graph, Ollama, SearXNG, GLPI sync, AI-THINK or article synthesis.

Brain-side flow

The Brain owns Agent identities, source tasks and the Source Inbox in source-agents.db.

Open /source-agents.html.
Create an Agent. The plaintext token is returned exactly when it is created or rotated; only its SHA-256 hash is stored by the Brain.
Add RSS, Atom, sitemap or generic Web tasks and a polling interval.
The remote Agent obtains its task list from GET /api/v1/agent/config.
New documents are sent in batches to POST /api/v1/agent/ingest.
Documents enter the Inbox as received, not as graph nodes.
The Brain embeds a bounded Inbox batch and checks it against the existing KB. Relevant documents become candidate; weak matches become archived.
Adaptive article/reviewer research queries the candidate Inbox before SearXNG. For freshness-sensitive requests, only sufficiently recent Inbox documents are reused.
A Web document becomes a graph node only when a generated article actually grounds a supported claim in it. Then the Inbox row becomes used.

This deliberately separates discovered from knowledge.

Agent bootstrap

Minimal remote Agent configuration:

BRAIN_MODE=agent
BRAIN_AGENT_BRAIN_URL=https://brain.example.org
BRAIN_AGENT_ID=security-news-01
BRAIN_AGENT_TOKEN=brain_agent_...

Optional Agent settings:

BRAIN_AGENT_CONFIG_REFRESH=5m
BRAIN_AGENT_HTTP_TIMEOUT=30s
BRAIN_AGENT_CONCURRENCY=3
BRAIN_AGENT_BATCH_SIZE=50
BRAIN_AGENT_ALLOW_PRIVATE=false

The Agent caches the last successful remote task configuration in its data volume. Source polling uses SSRF-safe DNS/redirect handling and rejects private, loopback and link-local targets by default; set BRAIN_AGENT_ALLOW_PRIVATE=true only for intentionally trusted intranet sources. This restriction applies to source URLs, not to the Brain control-plane URL, so the Brain itself may live on a private LAN.

A local bootstrap JSON can be used instead of the three connection ENV values:

{
  "brain_url": "https://brain.example.org",
  "agent_id": "security-news-01",
  "token": "brain_agent_..."
}

and:

BRAIN_MODE=agent
BRAIN_AGENT_CONFIG_FILE=/run/secrets/brain-agent.json

Source task schema

Example task returned by the Brain:

{
  "id": "microsoft-security",
  "agent_id": "security-news-01",
  "name": "Microsoft Security",
  "type": "rss",
  "url": "https://example.org/feed.xml",
  "enabled": true,
  "poll_interval": "2h",
  "categories": ["Microsoft", "Security"],
  "max_items": 20,
  "config": {
    "refetch_seen": "false"
  }
}

Supported task types in v1 are rss, atom, sitemap and web. Set config.refetch_seen=true for sources whose existing URLs are expected to change (for example rolling advisories). Otherwise the Agent optimizes for discovery of new article URLs.

Agent API permissions

Agent Bearer tokens are accepted only on:

GET /api/v1/agent/config
POST /api/v1/agent/heartbeat
POST /api/v1/agent/ingest

They are separate from BRAIN_API_KEY and do not authorize graph, runtime, research, THINK or administration APIs. Agent-management and Source-Inbox management endpoints use the normal BRAIN_API_KEY whenever it is configured.

Source Inbox tuning

Brain-side defaults:

BRAIN_SOURCE_INBOX_ENABLED=true
BRAIN_SOURCE_INBOX_INTERVAL=30s
BRAIN_SOURCE_INBOX_BATCH_SIZE=12
BRAIN_SOURCE_INBOX_MIN_SIMILARITY=0.55
BRAIN_SOURCE_INBOX_MIN_PRIORITY=0.55
BRAIN_SOURCE_INBOX_NOVELTY_FLOOR=0.35
BRAIN_SOURCE_INBOX_MIN_RESULTS=2
BRAIN_SOURCE_INBOX_FRESH_MAX_AGE=168h

Classification is deliberately cheap: one batched embedding operation plus the configured precise/clustered nearest-neighbour retrieval and deterministic freshness/task/advisory scoring. There is no Gemma/Qwen call just to classify every incoming news item.

Docker

deployment/docker-compose.source-agent.yml is a minimal example that builds the exact same project with BRAIN_MODE=agent. The Agent only needs a persistent /app/data volume for local dedupe state and its cached remote configuration.

Verbindungsdiagnose und Docker-Adressen

Ein Agent registriert sich aus Sicherheitsgründen nicht selbst. Er muss zuerst im Brain unter /source-agents.html angelegt werden; dort entsteht der Token. Ein Agent darf bereits Tasks zugewiesen bekommen, bevor er das erste Mal online ist.

BRAIN_AGENT_BRAIN_URL=http://127.0.0.1:... oder localhost ist bei einem separaten Docker-Container fast immer falsch: Loopback zeigt auf den Agent-Container selbst. Für einen Agent auf demselben Docker-Host kann stattdessen http://host.docker.internal:<BRAIN_PORT> verwendet werden. Auf einem gemeinsamen Docker-Netz ist der Brain-Service-Name vorzuziehen.

Das Brain kann mit BRAIN_PUBLIC_URL die korrekte, aus Agent-Sicht erreichbare Adresse veröffentlichen. Das Webinterface verwendet diese Adresse beim Erzeugen/Rotieren von Tokens.

Der Agent stellt auf / eine kleine Statusseite und auf /api/status Diagnosedaten bereit. brain_connected, last_config_success_at, last_heartbeat_success_at und last_connection_error zeigen die tatsächliche Verbindung; config_issued_at kann dagegen aus dem lokalen Cache stammen und ist allein kein Verbindungsnachweis. Das Agent-Compose veröffentlicht die Statusseite standardmäßig über BRAIN_AGENT_PORT=8092.

Inbox-Klassifizierung für News und Advisories

Seit Classifier v2 ist BRAIN_SOURCE_INBOX_MIN_SIMILARITY kein alleiniger Ausschlussfilter mehr. Ein Dokument wird candidate, wenn es entweder direkt genug KB-Nähe erreicht oder oberhalb des Novelty-Floors durch einen kombinierten Prioritätsscore aus KB-Nähe, kuratiertem Task-/Quellenkontext, Aktualität und News-/Advisory-Signalen relevant bleibt.

BRAIN_SOURCE_INBOX_MIN_SIMILARITY=0.55: direkte semantische Übernahme als Candidate.
BRAIN_SOURCE_INBOX_MIN_PRIORITY=0.55: Mindestscore des kombinierten News-/Knowledge-Routings.
BRAIN_SOURCE_INBOX_NOVELTY_FLOOR=0.35: harte Mindestnähe zur KB; darunter bleibt auch ein frischer Security-Alert archiviert.

Beim ersten Start mit Classifier v2 werden bereits archivierte Dokumente einmalig auf received zurückgesetzt und mit der neuen Logik neu klassifiziert.

6.4 KiB Raw Blame History