This commit is contained in:
Lars committed 2025-12-07 19:29:48 +01:00
1 parent d49da1b5fe
commit caab41a760
5 files changed
+155 -46

No files matched your search

+32 -30
View File
@@ -4,28 +4,26 @@ app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04 Endpunkte
Zweck:
Laufzeit-Modelle für FastAPI (Requests/Responses), getrennt von JSON-Schemas.
Deckt die Graph-/Retriever-Endpunkte ab.
Enthält Erweiterungen für WP-04b (Explanation Layer).
Enthält Erweiterungen für WP-04b (Explanation Layer) und WP-04c (Feedback).
Kompatibilität:
Python 3.12+, Pydantic 2.x, FastAPI 0.110+
Version:
0.2.0 (Update für WP-04b Explanation Layer)
0.3.0 (Update für WP-04c Feedback)
Stand:
2025-12-07
Bezug:
- schemas/*.json (Speicherschema für Notes/Chunks/Edges)
- WP-04 API-Design (Query- und Graph-Endpunkte)
Nutzung:
from app.models.dto import QueryRequest, QueryResponse, GraphResponse
"""
from __future__ import annotations
from pydantic import BaseModel, Field
from typing import List, Literal, Optional, Dict, Any
import uuid
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to", "depends_on", "related_to", "similar_to"]
# --- Basis-DTOs ---
class NodeDTO(BaseModel):
"""Darstellung eines Knotens (Note oder Chunk) im API-Graph."""
id: str
@@ -51,12 +49,14 @@ class EdgeDTO(BaseModel):
direction: Literal["out", "in", "undirected"] = "out"
# --- Request Models ---
class QueryRequest(BaseModel):
"""
Request für /query:
- mode: 'semantic' | 'edge' | 'hybrid'
- query: (optional) Freitext; Embedding wird später angebunden
- query_vector: (optional) direkter Vektor (384d) für Quick-Tests ohne Embedding
- query: (optional) Freitext
- query_vector: (optional) direkter Vektor
- explain: (optional) Fordert detaillierte Erklärungen an (WP-04b)
"""
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
@@ -65,24 +65,29 @@ class QueryRequest(BaseModel):
top_k: int = 10
expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next", "depends_on", "related_to"]}
filters: Optional[Dict] = None
# Flags zur Steuerung der Rückgabe
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
# WP-04b: Soll eine Erklärung generiert werden?
explain: bool = False
class FeedbackRequest(BaseModel):
"""
User-Feedback zu einem spezifischen Treffer (WP-04c).
"""
query_id: str = Field(..., description="ID der ursprünglichen Suche")
node_id: str = Field(..., description="ID des bewerteten Treffers")
score: int = Field(..., ge=0, le=1, description="1 (Positiv) oder 0 (Negativ/Irrelevant)")
comment: Optional[str] = None
# --- WP-04b Explanation Models ---
class ScoreBreakdown(BaseModel):
"""
Aufschlüsselung der Score-Komponenten.
Zeigt die gewichteten Beiträge zum Total Score.
"""
"""Aufschlüsselung der Score-Komponenten."""
semantic_contribution: float = Field(..., description="W_sem * semantic_score * weight")
edge_contribution: float = Field(..., description="W_edge * edge_bonus")
centrality_contribution: float = Field(..., description="W_cent * centrality_bonus")
# Rohwerte für Transparenz
# Rohwerte
raw_semantic: float
raw_edge_bonus: float
raw_centrality: float
@@ -90,10 +95,7 @@ class ScoreBreakdown(BaseModel):
class Reason(BaseModel):
"""
Ein semantischer Grund für das Ranking.
z.B. 'Verlinkt von Projekt X', 'Hohe Textähnlichkeit'.
"""
"""Ein semantischer Grund für das Ranking."""
kind: Literal["semantic", "edge", "type", "centrality"]
message: str
score_impact: Optional[float] = None
@@ -101,24 +103,20 @@ class Reason(BaseModel):
class Explanation(BaseModel):
"""
Container für alle Erklärungsdaten eines Treffers.
"""
"""Container für alle Erklärungsdaten eines Treffers."""
breakdown: ScoreBreakdown
reasons: List[Reason]
# Optional: Pfade im Graphen, die zu diesem Treffer geführt haben
related_edges: Optional[List[EdgeDTO]] = None
# --- End Explanation Models ---
# --- Response Models ---
class QueryHit(BaseModel):
"""Einzelnes Trefferobjekt für /query."""
node_id: str
note_id: Optional[str]
# Flache Scores (Kompatibilität WP-04a)
# Flache Scores
semantic_score: float
edge_bonus: float
centrality_bonus: float
@@ -127,19 +125,23 @@ class QueryHit(BaseModel):
paths: Optional[List[List[Dict]]] = None
source: Optional[Dict] = None
# WP-04b: Erklärungsobjekt (nur gefüllt, wenn explain=True)
# WP-04b: Erklärungsobjekt
explanation: Optional[Explanation] = None
class QueryResponse(BaseModel):
"""Antwortstruktur für /query (Liste von Treffern + Telemetrie)."""
"""
Antwortstruktur für /query (Liste von Treffern + Telemetrie).
Enthält query_id für Traceability (WP-04c).
"""
query_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
results: List[QueryHit]
used_mode: str
latency_ms: int
class GraphResponse(BaseModel):
"""Antwortstruktur für /graph/{note_id} (Nachbarschaft)."""
"""Antwortstruktur für /graph/{note_id}."""
center_note_id: str
nodes: List[NodeDTO]
edges: List[EdgeDTO]