Dokumentationsaupdate
Deploy mindnet to llm-node / deploy (push) Successful in 3s

This commit is contained in:
Lars committed 2025-12-28 10:56:34 +01:00
1 parent e9532e8878
commit 5225090490
15 files changed
+2553 -17

No files matched your search

@@ -0,0 +1,435 @@
---
doc_type: technical_reference
audience: developer, integrator
scope: api, endpoints, integration
status: active
version: 2.9.1
context: "Vollständige API-Referenz für alle Mindnet-Endpunkte. Basis für Integration und Entwicklung."
---
# API Reference
Diese Dokumentation beschreibt alle verfügbaren API-Endpunkte von Mindnet. Die API basiert auf FastAPI und nutzt automatische OpenAPI-Dokumentation (verfügbar unter `/docs`).
## Basis-URL
```
http://localhost:8001 # Production
http://localhost:8002 # Development
```
## Health Check
### `GET /healthz`
Prüft den Status der API und der Verbindung zu Qdrant.
**Response:**
```json
{
"status": "ok",
"qdrant": "http://localhost:6333",
"prefix": "mindnet"
}
```
---
## Query Endpoints
### `POST /query`
Führt eine hybride oder semantische Suche im Wissensgraph durch.
**Request Body:**
```json
{
"query": "Was ist Mindnet?",
"mode": "hybrid", // "hybrid" oder "semantic"
"top_k": 10,
"expand_depth": 1,
"explain": true
}
```
**Response:**
```json
{
"query_id": "uuid-v4",
"hits": [
{
"chunk_id": "uuid",
"note_id": "uuid",
"text": "Auszug...",
"score": 0.85,
"explanation": {
"reasons": [...]
}
}
],
"stats": {
"total_hits": 10,
"query_time_ms": 45
}
}
```
**Hinweis:** Das Feedback-Logging erfolgt asynchron im Hintergrund (Background Tasks).
---
## Chat Endpoints
### `POST /chat/`
Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming.
**Request Body:**
```json
{
"message": "Was ist Mindnet?",
"history": [], // Optional: Chat-Verlauf
"stream": true // Optional: SSE-Streaming
}
```
**Response (Non-Streaming):**
```json
{
"intent": "FACT",
"response": "Mindnet ist ein persönliches KI-Gedächtnis...",
"sources": [...],
"query_id": "uuid"
}
```
**Response (Streaming):**
Server-Sent Events (SSE) mit Chunks der Antwort.
**Intent-Typen:**
- `FACT`: Wissensabfrage
- `DECISION`: Entscheidungsfrage
- `EMPATHY`: Emotionale Anfrage
- `INTERVIEW`: Wissen erfassen
---
## Graph Endpoints
### `GET /graph/{note_id}`
Lädt den Subgraphen um eine Note herum.
**Query Parameters:**
- `depth` (int, default: 1): Tiefe der Graph-Expansion
- `edge_types` (List[str], optional): Filter für Kanten-Typen
**Response:**
```json
{
"center_note_id": "uuid",
"nodes": [
{
"id": "uuid",
"type": "project",
"title": "Projekt Alpha",
"tags": ["ki"],
"in_degree": 5,
"out_degree": 3
}
],
"edges": [
{
"id": "uuid->uuid:depends_on",
"kind": "depends_on",
"source": "uuid",
"target": "uuid",
"weight": 1.4,
"direction": "out"
}
],
"stats": {
"node_count": 10,
"edge_count": 15
}
}
```
---
## Ingest Endpoints
### `POST /ingest/analyze`
Analysiert einen Text-Draft und liefert Link-Vorschläge (Intelligence-Feature).
**Request Body:**
```json
{
"text": "Markdown-Text...",
"type": "concept" // Optional: Notiz-Typ
}
```
**Response:**
```json
{
"suggestions": [
{
"text": "Mindnet",
"type": "exact_match",
"note_id": "uuid",
"confidence": 0.95
},
{
"text": "KI-Gedächtnis",
"type": "semantic",
"note_id": "uuid",
"confidence": 0.82
}
]
}
```
### `POST /ingest/save`
Speichert eine Notiz und startet die Ingestion im Hintergrund (WP-14: Background Tasks).
**Request Body:**
```json
{
"markdown_content": "---\nid: ...\n---\n# Titel\n...",
"filename": "meine-notiz.md", // Optional
"folder": "00_Inbox" // Optional, default: "00_Inbox"
}
```
**Response:**
```json
{
"status": "queued",
"file_path": "00_Inbox/meine-notiz.md",
"note_id": "pending",
"message": "Speicherung & Hybrid-KI-Analyse (WP-20) im Hintergrund gestartet.",
"stats": {
"chunks": -1, // -1 = Async Processing
"edges": -1
}
}
```
**Wichtig:**
- Die Datei wird sofort auf der Festplatte gespeichert
- Die Ingestion (Chunking, Embedding, Smart Edges) läuft asynchron im Hintergrund
- Dies verhindert Timeouts bei großen Dateien oder langsamen LLM-Calls
---
## Feedback Endpoints
### `POST /feedback`
Nimmt explizites User-Feedback entgegen (WP-04c).
**Request Body:**
```json
{
"query_id": "uuid",
"rating": 5, // 1-5 Sterne
"feedback_type": "global", // "global" oder "granular"
"chunk_id": "uuid" // Optional für granular feedback
}
```
**Response:**
```json
{
"status": "recorded",
"query_id": "uuid"
}
```
---
## Tools Endpoints
### `GET /tools/ollama`
Liefert JSON-Schemas für die Integration als Tools in externe Agenten (Ollama, OpenAI, etc.).
**Response:**
```json
{
"tools": [
{
"type": "function",
"function": {
"name": "mindnet_query",
"description": "Hybrid-Retrieval über mindnet (Semantik + Edges).",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Freitext-Query"
},
"top_k": {
"type": "integer",
"default": 10,
"minimum": 1,
"maximum": 50
}
}
}
}
},
{
"type": "function",
"function": {
"name": "mindnet_subgraph",
"description": "Gibt die Nachbarschaft (Edges) einer Note/Seed-ID zurück.",
"parameters": {
"type": "object",
"properties": {
"note_id": {
"type": "string"
},
"depth": {
"type": "integer",
"default": 1,
"minimum": 0,
"maximum": 3
}
},
"required": ["note_id"]
}
}
}
]
}
```
**Verwendung:** Diese Schemas können direkt in Ollama-Function-Calling oder OpenAI-Tools integriert werden.
---
## Admin Endpoints
### `GET /admin/stats`
Liefert Statistiken über die Qdrant-Collections und die aktuelle Konfiguration.
**Response:**
```json
{
"collections": {
"notes": {
"name": "mindnet_notes",
"count": 150
},
"chunks": {
"name": "mindnet_chunks",
"count": 1250
},
"edges": {
"name": "mindnet_edges",
"count": 3200
}
},
"config": {
"qdrant": "http://localhost:6333",
"prefix": "mindnet",
"vector_size": 768,
"distance": "Cosine",
"retriever": {
"w_sem": 0.70,
"w_edge": 0.25,
"w_cent": 0.05,
"top_k": 10,
"expand_depth": 1
}
}
}
```
**Hinweis:** Dieser Endpunkt ist optional und kann deaktiviert sein, wenn der `admin`-Router nicht geladen wird.
---
## Fehlerbehandlung
Alle Endpunkte verwenden standardisierte HTTP-Status-Codes:
- `200 OK`: Erfolgreiche Anfrage
- `201 Created`: Ressource erfolgreich erstellt
- `400 Bad Request`: Ungültige Anfrage (z.B. fehlende Parameter)
- `500 Internal Server Error`: Server-Fehler
**Fehler-Response-Format:**
```json
{
"detail": "Fehlerbeschreibung"
}
```
---
## Rate Limiting & Timeouts
- **Chat-Endpunkte:** Keine Retries (max_retries=0) für schnelle Fallback-Kaskade
- **Ingest-Endpunkte:** Background Tasks verhindern Timeouts
- **Query-Endpunkte:** Standard-Timeout konfigurierbar via `MINDNET_API_TIMEOUT`
---
## OpenAPI Dokumentation
Die vollständige interaktive API-Dokumentation ist verfügbar unter:
- Swagger UI: `http://localhost:8001/docs`
- ReDoc: `http://localhost:8001/redoc`
- OpenAPI JSON: `http://localhost:8001/openapi.json`
---
## Integration Beispiele
### Python (requests)
```python
import requests
# Query
response = requests.post(
"http://localhost:8001/query",
json={"query": "Was ist Mindnet?", "top_k": 5}
)
print(response.json())
# Chat
response = requests.post(
"http://localhost:8001/chat/",
json={"message": "Erkläre mir Mindnet"}
)
print(response.json())
```
### cURL
```bash
# Health Check
curl http://localhost:8001/healthz
# Query
curl -X POST http://localhost:8001/query \
-H "Content-Type: application/json" \
-d '{"query": "Was ist Mindnet?", "top_k": 5}'
```
---
## Weitere Informationen
- **Chat-Backend Details:** Siehe [Chat Backend Dokumentation](03_tech_chat_backend.md)
- **Ingestion-Pipeline:** Siehe [Ingestion Pipeline](03_tech_ingestion_pipeline.md)
- **Retrieval & Scoring:** Siehe [Retrieval & Scoring](03_tech_retrieval_scoring.md)
@@ -3,7 +3,7 @@ doc_type: technical_reference
audience: developer, architect
scope: backend, chat, llm_service, traffic_control, resilience
status: active
version: 2.8.1
version: 2.9.1
context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik."
---
@@ -20,13 +20,15 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der
| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB API. |
| `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. |
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
| `MINDNET_PREFIX` | *(leer)* | **Alternative zu COLLECTION_PREFIX.** Falls gesetzt, wird dieser Wert verwendet. |
| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
| `MINDNET_DISTANCE` | `Cosine` | Metrik für Vektor-Ähnlichkeit (`Cosine`, `Euclidean`, `Dot`). |
| `MINDNET_VECTOR_NAME` | `default` | **Neu (WP-14):** Basis-Vektorname für Named Vectors Support. |
| `NOTES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Notes-Collection (Override). |
| `CHUNKS_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Chunks-Collection (Override). |
| `EDGES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Edges-Collection (Override). |
| `MINDNET_VOCAB_PATH` | *(Pfad)* | **Neu (WP-22):** Absoluter Pfad zur `01_edge_vocabulary.md`. Definiert den Ort des Dictionarys. |
| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. |
| `MINDNET_VAULT_ROOT` | `./vault_master` | **Achtung:** Standard ist `./vault_master`, nicht `./vault`! Basis-Pfad für Datei-Operationen. |
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. |
@@ -66,7 +66,24 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc
## 2. Betrieb & CLI Befehle
### 2.1 Standard-Betrieb (Inkrementell)
### 2.1 API-Endpunkt: `/ingest/save` (Background Tasks)
Seit WP-14 nutzt der `/ingest/save` Endpunkt **Background Tasks** für non-blocking Ingestion:
**Workflow:**
1. **Request:** Frontend sendet Markdown an `/ingest/save`
2. **Sofortige Antwort:** API antwortet mit `status: "queued"` und `note_id: "pending"`
3. **Datei-Persistenz:** Markdown wird sofort auf Festplatte geschrieben
4. **Background Task:** Ingestion läuft asynchron im Hintergrund
- Chunking
- Embedding-Generierung
- Smart Edge Allocation (WP-15)
- Hybrid-Cloud-Analyse (WP-20)
5. **Vorteil:** Keine Timeouts bei großen Dateien oder langsamen LLM-Calls
**Hinweis:** Die tatsächliche `note_id` steht erst nach dem Parsing fest. Das Frontend sollte den `file_path` für Tracking nutzen.
### 2.2 CLI-Betrieb (Inkrementell)
Erkennt Änderungen via Multi-Hash.
```bash