Dokumentation

Alles was du wissen musst, um TRM Oracle produktiv zu betreiben.

Übersicht

TRM Oracle ist ein self-hosted KI-Assistent für SAP Treasury and Risk Management. Das System crawlt dein eigenes SAP-System (DDIC-Schema, BAPIs, Customizing-Werte, System-Doku) und beantwortet Fragen mit konkreten Quellen-Zitaten — kombiniert aus drei Ebenen:

• Knowledge-Graph — strukturiertes TRM-Inventar deines Systems
• Vector-RAG — semantische Suche in der DOKHL-System-Doku
• Live-Verifikation — jede Antwort wird gegen das laufende SAP-System gegengeprüft

Architektur

Datenfluss

Installation

Auto-Installer wählt selbst zwischen Native (Python venv) und Docker — entscheidend ist Python 3.11+:

curl -sSL https://trm-oracle.pages.dev/install.sh | bash

• Mac/Linux mit Python 3.11+ → native (schneller, weniger Disk, sieht claude CLI)
• Windows oder kein Python → docker (universell, isoliert)

Modus erzwingen:

curl -sSL https://trm-oracle.pages.dev/install.sh | bash -s -- --native
curl -sSL https://trm-oracle.pages.dev/install.sh | bash -s -- --docker

Air-Gapped (keine Auto-Installation von Python/Docker):

curl -sSL https://trm-oracle.pages.dev/install.sh | bash -s -- --skip-prereq

Manuell:

git clone https://github.com/Lomtech/trm_oracle.git ~/trm-oracle
cd ~/trm-oracle
cp .env.example .env  # editieren (oder Browser-Wizard verwenden)
# Native:
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python -m uvicorn web.app:app --host 0.0.0.0 --port 8080
# Oder Docker:
docker compose up -d

Nach dem Install: trm CLI ist global verfügbar — siehe Daily Use.

Modes — Docker vs. Native

Beide Modi liefern dasselbe Frontend, dieselbe API, dieselben Antworten. Sie unterscheiden sich nur im wie der Service läuft.

Wahl-Hilfe:

• Single-User auf Mac/Linux mit Anthropic Pro/Max/Team/Enterprise → Native (kostenlos via OAuth)
• Windows → Docker (Python-Setup unter Windows ist Aufwand)
• Zentraler Team-Server / Enterprise-Deployment → Docker (Isolation, Reproduzierbarkeit)
• Multi-Instance auf einem Host (z.B. Test + Prod) → Docker

Wechsel jederzeit per CLI:

trm switch-to-native    # Docker → Python venv
trm switch-to-docker    # Native → Docker
trm mode                # aktuellen Modus anzeigen

Daten (.env, data/) bleiben beim Wechsel erhalten — nur das Runtime-Drumherum ändert sich.

Konfiguration (.env)

Komplette Liste der Umgebungsvariablen siehe Abschnitt .env-Reference. Minimale Konfiguration:

# SAP-Verbindung
SAP_HOST=https://your-sap.intern:44383
SAP_CLIENT=100
SAP_USER=TRM_READ
SAP_PASSWORD='deinPasswort'
SAP_VERIFY_TLS=false

# Lizenz (aus Trial-Mail)
TRM_ORACLE_LICENSE_KEY=trmo-XXXX-XXXX-XXXX-XXXX

# LLM-Synthese (optional)
ANTHROPIC_API_KEY=sk-ant-api03-...

# Vector-Embeddings (lokal = kein API-Key nötig)
TRM_EMBED_PROVIDER=local

Erstes Crawling

Über Web-UI:

1. Browser: localhost:8080/setup
2. SAP-Verbindung sollte grünes Häkchen zeigen
3. Klick "Crawl starten (Quick: ~3 Min)"

Per CLI:

cd ~/trm-oracle
docker compose exec trm-oracle python3 scripts/crawl_all.py --quick
# oder Full-Crawl (alle 14 Crawler)
docker compose exec trm-oracle python3 scripts/crawl_all.py --full
# oder einzelne
docker compose exec trm-oracle python3 scripts/crawl_all.py --only tcodes,bapi_params

Was beim Quick-Crawl gezogen wird (~3-5 Min):

• TRM-Transaktionen (~4.000)
• BAPI-Familie + Parameter (~27.000)
• Customizing-Werte (~1.500)
• Help-URL-Index
• System-Doku DOKHL (~2.600)

trm CLI — Daily Use

Der Installer richtet ein globales trm Command ein, das mode-aware ist (Docker oder Native). Du musst nie wieder docker compose … oder .venv/bin/python … tippen.

Steuerung

Browser

Nutzung

Wartung

Mode-Wechsel

Einrichten

Backups + manueller Zugriff

# .env-Backups (automatisch bei jedem Wizard-Save, 5 Versionen)
ls ~/trm-oracle/data/.env-backups/

# Knowledge-Graph + Vector-Store backuppen
tar czf trm-backup-$(date +%F).tgz ~/trm-oracle/data/

# Pfad-Overrides
TRM_INSTALL_DIR=/anderer/pfad trm up
TRM_URL=http://server:8080 trm status

Crawler (14)

Jeder Crawler ist eigenständig in crawlers/crawl_*.py:

Knowledge-Graph

JSONL-basiert (kompatibel mit MCP-Memory-Format). Liegt unter data/graph/trm-knowledge.jsonl.

Entity-Types (17)

TRM_PACKAGE          TRM_PROGRAM         TRM_CLASS
TRM_FUNCTION_MODULE  TRM_BAPI            TRM_BAPI_PARAM
TRM_TCODE            TRM_DDIC_TABLE      TRM_DDIC_FIELD
TRM_DOMAIN           TRM_DATA_ELEMENT    TRM_FIXED_VALUE
TRM_VIEW             TRM_VIEW_CLUSTER    TRM_IMG_NODE
TRM_CUSTOMIZING_TABLE TRM_AUTH_OBJECT    TRM_MESSAGE
TRM_DOC_CHUNK

Relation-Types

BELONGS_TO_PACKAGE   IMPLEMENTS         CALLS
READS                WRITES             USES_DOMAIN
HAS_FIELD            HAS_PARAM          HAS_FIXED_VALUE
HAS_DATA_ELEMENT     CUSTOMIZES         MAPS_TO_TABLE
MAPS_TO_TCODE        MAPS_TO_VIEW       DOCUMENTED_BY
AUTHORIZES           PART_OF_VIEW_CLUSTER

Vector-RAG

LanceDB-basiert. Default-Embedding-Modell: intfloat/multilingual-e5-base (768-dim, lokal, kein API-Key).

Provider-Auswahl

LLM-Synthese

In oracle/synthesizer.py. Komponiert aus Graph-Treffern + RAG-Snippets + Live-Verifikation einen Customizing-Leitfaden mit Quellen-Zitaten inline. Anti-Halluzinations-System-Prompt: LLM darf nichts ausgeben das nicht in den übergebenen Daten vorkommt.

Fallback-Modus

Ohne ANTHROPIC_API_KEY rendert das System deterministisches Markdown statt LLM-Synthese. Funktioniert weiter, ist aber weniger fachlich formuliert.

MCP — Claude Desktop / Cursor / Continue / Zed

Das Orakel exponiert seine 5 Tools als Model Context Protocol Server (stdio). Damit kannst du es direkt in deiner IDE / AI-Assistent nutzen — Cursor ruft im Hintergrund trm_bapi_explain wenn du ABAP schreibst und einen BAPI-Aufruf brauchst.

Setup-Snippet (für Claude Desktop):

{
  "mcpServers": {
    "trm-oracle": {
      "command": "/Users/<you>/.pyenv/versions/3.12.3/bin/python3",
      "args": [
        "/Users/<you>/trm-oracle/scripts/run_mcp.py"
      ],
      "env": {
        "TRM_EMBED_PROVIDER": "local"
      }
    }
  }
}

Pro IDE-Setup-Guide siehe Repo: integrations/mcp/setup-*.md

Slack-Bot (Pro-Tier)

FastAPI-basierter Slack-Bot reagiert auf @trm-orakel-Mentions in Channels.

# 1. Slack-App via Manifest erstellen (integrations/slack/manifest.yml)
# 2. SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET in .env
# 3. Bot starten:
docker compose -f docker-compose.yml -f docker-compose.slack.yml up -d
# 4. In Slack: /invite @trm-orakel

Komplette Anleitung: integrations/slack/README.md

Direkter Script-Zugriff

Für Automation oder wenn das trm CLI nicht reicht — direkter Aufruf der Python-Scripts:

# Native:
cd ~/trm-oracle
.venv/bin/python scripts/ask.py "Welche Felder hat VTBFHA?"
.venv/bin/python scripts/ask.py --json "BAPI_FTR_CREATEFROMDATA"
.venv/bin/python scripts/bootstrap.py        # Konfig-Check
.venv/bin/python scripts/crawl_all.py --quick
.venv/bin/python scripts/status.py
.venv/bin/python eval/run_eval.py             # 12 Test-Szenarien

# Docker:
docker compose exec trm-oracle python3 scripts/ask.py "Welche Felder hat VTBFHA?"
docker compose exec trm-oracle python3 scripts/ask.py --json "BAPI_FTR_CREATEFROMDATA"
docker compose exec trm-oracle python3 scripts/crawl_all.py --quick
docker compose exec trm-oracle python3 eval/run_eval.py

# Mode-agnostisch via trm CLI (empfohlen für 90% der Fälle):
trm ask "Welche Felder hat VTBFHA?"
trm ask --json "BAPI_FTR_CREATEFROMDATA"
trm crawl                  # zeigt Liste der Crawler
trm crawl bapi_params      # einzelner Crawler

Web-API

5 MCP-Tools (Referenz)

trm_explain(scenario: str)

Vollständiges Szenario-Routing. Default-Entry-Point für freie Fragen.

trm_bapi_explain(name: str)

BAPI-Tiefenanalyse: Parameter, Doku, Live-Existenz-Check.

trm_field_lookup(table: str, field?: str)

DDIC-Tabelle bzw. einzelnes Feld erklären (Domain, Datenelement, Festwerte).

trm_customizing_path(topic: str)

IMG-Knoten + Customizing-Tabellen zu einem fachlichen Thema.

trm_doc_search(query: str, limit?: int)

Vektor-Suche im DOKHL-Korpus + Help + Notes.

.env-Reference

Lizenz-Tiers

Troubleshooting

FAQ

Changelog

Vollständig: GitHub-Commits