KnowledgeOS

KnowledgeOS ist eine modulare Plattform für Wissensaufnahme, Extraktion und Aufbereitung:

• Ingest von Quellen (Datei, RSS, weitere Skills als Platzhalter)
• Queue-basierte Verarbeitung mit BullMQ Worker(n)
• Strukturierte Wissensspeicherung in MongoDB (entities, knowledge_chunks, prompts, audit_log)
• Prompt-gesteuerte LLM-Extraktion mit konfigurierbarem Model-Routing
• UI mit Next.js für Entitäten, Monitoring, Provider-Überblick und einfache Graph-Ansicht

Das Projekt ist so aufgebaut, dass neue Skills und Processing-Pipelines schrittweise erweitert werden können.

Architektur auf einen Blick

Frontend (Next.js, Port 3000)
        |
        v
Orchestrator API (Express, Port 3001)
  - CRUD, Ingest, Routing, Monitoring
  - erstellt Jobs in BullMQ
        |
        v
Redis (Queue + Broker)
        |
        v
Worker (BullMQ Consumer, replizierbar)
  - Skill-Execution
  - Chunk-Erzeugung
  - LLM-Extraktion (best effort)
  - Komprimierung / Tuning-Jobs
        |
        v
MongoDB
  - entities
  - knowledge_chunks
  - providers
  - model_routing
  - prompts
  - audit_log

Kernfunktionen (aktueller Stand)

API und Daten

• CRUD für Provider, Entitäten und Routing-Regeln
• Datei-Ingest via Multipart (POST /api/ingest/file)
• Chunk-Liste je Entität (GET /api/entities/:id/chunks)
• Monitoring via SSE (/api/monitor/stream) + einfache Statistiken

Verarbeitung

• Skill Queue (skill-queue) für Ingest/Skill-Ausführung
• Compression Queue (compression-queue) für Digest-Erzeugung
• Tuning Queue (tuning-queue) für Prompt-Challenger-Erzeugung

LLM-Funktionen

• PromptEngine mit Prompt-Versionen aus MongoDB
• ModelRouter mit Provider + Routing-Regeln pro Task-Type
• Extraktor aktualisiert Chunk-Metadaten und Entity-Felder

Frontend

• Übersicht und Einstieg (/)
• Entities-Liste (/entities)
• Entity-Detailansicht inkl. Felder/Chunks/Beziehungen (/entities/[id])
• Provider-Übersicht (/settings/providers)
• Monitoring-View (/monitor)
• Vereinfachte Graph-Visualisierung (/graph)

Schnellstart mit Docker oder Podman

1. Umgebungsdatei anlegen

cp .env.example .env

Pflichtwerte in .env:

• MONGO_PASSWORD
• ENCRYPTION_KEY

Hinweis:

• Compose ist jetzt auf fail-fast gestellt. Fehlen diese Variablen, bricht compose up sofort mit klarer Fehlermeldung ab.
• Redis läuft mit maxmemory-policy noeviction (empfohlen für BullMQ), damit Queue-Daten nicht unter Speicherdruck verworfen werden.

Für ENCRYPTION_KEY wird ein 32-Byte-Wert erwartet (oder 64 Hex-Zeichen).

Beispiel-Generierung:

openssl rand -hex 32

2. Stack starten

Mit Podman:

podman compose up -d

Mit Docker:

docker compose up -d

3. Health prüfen

curl -sS http://localhost:3001/health

Erwartet:

{"ok":true}

Lokale Entwicklung ohne Compose

Orchestrator

cd orchestrator
npm install
npm run dev

Worker

cd orchestrator
npm run build
npm run worker

Frontend

cd frontend
npm install
npm run dev

Voraussetzung lokal:

• MongoDB erreichbar unter MONGODB_URI
• Redis erreichbar unter REDIS_URL

Projektstruktur

knowledgeOS/
├── docker-compose.yml
├── .env.example
├── frontend/
│   ├── app/
│   └── Dockerfile
├── orchestrator/
│   ├── src/
│   │   ├── core/
│   │   ├── db/
│   │   ├── queue/
│   │   ├── routes/
│   │   ├── skills/
│   │   └── utils/
│   ├── Dockerfile
│   └── Dockerfile.worker
└── docs/

API-Kurzüberblick

• GET /health
• GET|POST|PUT|DELETE /api/providers
• POST /api/providers/:id/sync-models
• GET|POST|PUT|DELETE /api/entities
• POST /api/entities/:id/crawl-now
• POST /api/entities/:id/compress
• GET /api/entities/:id/chunks
• GET /api/entity-types
• GET|PUT /api/routing
• GET /api/skills
• GET /api/monitor/stats
• GET /api/monitor/costs
• GET /api/monitor/stream
• POST /api/ingest/file

Details siehe docs/API.md.

Sicherheit

• Provider-API-Keys werden verschlüsselt gespeichert (AES-256-GCM)
• CORS ist global aktiviert (aktuell ohne Whitelist)
• Branch-Schutz für GitHub main wird empfohlen (und weiter unten dokumentiert)

Details:

• docs/BETRIEB.md
• docs/GITHUB_REPO_UND_BRANCH_PROTECTION.md

Dokumentation

• Architektur
• API
• Datenmodell
• Betrieb und Deployment
• Frontend
• Release-Prozess
• GitHub Repo + Main Branch Protection
• Contributing Guide
• Security Policy
• Changelog

GitHub Setup Automation

• CI-Workflow für main/PRs: .github/workflows/ci.yml
• Automationsskript für Public Repo + Main Protection:

./scripts/create_public_repo_secure_main.sh <github-owner> <repo-name>

Wichtige Hinweise zum Reifegrad

• Mehrere Skills sind aktuell Scaffolds und liefern noch keine echte Datenaufnahme (imap, playwright, rest-api, linkedin, messaging).
• Der file-Skill nutzt aktuell utf8-Dateilesen; binäre Formate erfordern Erweiterung.
• Es gibt aktuell keine automatisierten Tests im Repository.
• UI nutzt teils hartkodierte API-URLs (http://localhost:3001).