Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
main
mindnet/docs/03_Technical_References/03_tech_api_reference.md
Lars 0d2469f8fa WP25-v3.0.0-Dokumentation
2026-01-01 20:24:09 +01:00

9.1 KiB
Raw Permalink Blame History

doc_type audience scope status version context
technical_reference developer, integrator api, endpoints, integration, agentic_rag active 2.9.3 Vollständige API-Referenz für alle Mindnet-Endpunkte inklusive WP-25 Agentic Multi-Stream RAG. 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:

{
  "status": "ok",
  "qdrant": "http://localhost:6333",
  "prefix": "mindnet"
}

Query Endpoints

POST /query

Führt eine hybride oder semantische Suche im Wissensgraph durch.

Request Body:

{
  "query": "Was ist Mindnet?",
  "mode": "hybrid",  // "hybrid" oder "semantic"
  "top_k": 10,
  "expand_depth": 1,
  "explain": true
}

Response:

{
  "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:

{
  "message": "Was ist Mindnet?",
  "history": [],  // Optional: Chat-Verlauf
  "stream": true   // Optional: SSE-Streaming
}

Response (Non-Streaming):

{
  "query_id": "uuid",
  "answer": "Mindnet ist ein persönliches KI-Gedächtnis...",
  "sources": [
    {
      "node_id": "uuid",
      "note_id": "uuid",
      "semantic_score": 0.85,
      "total_score": 0.92,
      "stream_origin": "values_stream",  // WP-25: Ursprungs-Stream
      "explanation": {...}
    }
  ],
  "latency_ms": 450,
  "intent": "DECISION",  // WP-25: Gewählte Strategie
  "intent_source": "Keyword (FastPath)"  // WP-25: Quelle der Intent-Erkennung
}

Response (Streaming): Server-Sent Events (SSE) mit Chunks der Antwort.

Intent-Typen (WP-25):

  • FACT_WHAT: Wissensabfrage (Wissen/Listen)
  • FACT_WHEN: Zeitpunkte (Termine, Daten)
  • DECISION: Entscheidungsfrage (Beratung, Strategie)
  • EMPATHY: Emotionale Anfrage (Reflexion)
  • CODING: Technische Anfrage (Programmierung)
  • INTERVIEW: Wissen erfassen (Datenerfassung)

Stream-Tracing (WP-25): Jeder Treffer in sources enthält stream_origin, um die Zuordnung zum Quell-Stream zu ermöglichen (z.B. "values_stream", "facts_stream", "risk_stream").

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:

{
  "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",
      "target_section": "P3 – Disziplin",  // Optional: Abschnitts-Name bei Deep-Links
      "weight": 1.4,
      "direction": "out",
      "provenance": "explicit",
      "confidence": 1.0
    }
  ],
  "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:

{
  "text": "Markdown-Text...",
  "type": "concept"  // Optional: Notiz-Typ
}

Response:

{
  "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:

{
  "markdown_content": "---\nid: ...\n---\n# Titel\n...",
  "filename": "meine-notiz.md",  // Optional
  "folder": "00_Inbox"            // Optional, default: "00_Inbox"
}

Response:

{
  "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:

{
  "query_id": "uuid",
  "rating": 5,  // 1-5 Sterne
  "feedback_type": "global",  // "global" oder "granular"
  "chunk_id": "uuid"  // Optional für granular feedback
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "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)

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

# 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