This commit is contained in:
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
|
||||
|
||||
Reference in new issue
Block a user