Erste Version des WP04b
This commit is contained in:
1 parent
9e7104e362
commit
34cbc0c0eb
3 files changed
+311
-205
No files matched your search
+63
-11
@@ -3,27 +3,27 @@ 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, ohne bestehende Funktionen zu ändern.
|
||||
Deckt die Graph-/Retriever-Endpunkte ab.
|
||||
Enthält Erweiterungen für WP-04b (Explanation Layer).
|
||||
|
||||
Kompatibilität:
|
||||
Python 3.12+, Pydantic 2.x, FastAPI 0.110+
|
||||
Version:
|
||||
0.1.0 (Erstanlage für WP-04)
|
||||
0.2.0 (Update für WP-04b Explanation Layer)
|
||||
Stand:
|
||||
2025-10-07
|
||||
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
|
||||
Änderungsverlauf:
|
||||
0.1.0 (2025-10-07) – Erstanlage.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
from pydantic import BaseModel
|
||||
from typing import List, Literal, Optional, Dict
|
||||
from pydantic import BaseModel, Field
|
||||
from typing import List, Literal, Optional, Dict, Any
|
||||
|
||||
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to"]
|
||||
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to", "depends_on", "related_to", "similar_to"]
|
||||
|
||||
|
||||
class NodeDTO(BaseModel):
|
||||
@@ -44,7 +44,7 @@ class NodeDTO(BaseModel):
|
||||
class EdgeDTO(BaseModel):
|
||||
"""Darstellung einer Kante im API-Graph."""
|
||||
id: str
|
||||
kind: EdgeKind
|
||||
kind: str # String statt Literal, um flexibel für Custom-Types zu bleiben
|
||||
source: str
|
||||
target: str
|
||||
weight: float
|
||||
@@ -57,26 +57,78 @@ class QueryRequest(BaseModel):
|
||||
- mode: 'semantic' | 'edge' | 'hybrid'
|
||||
- query: (optional) Freitext; Embedding wird später angebunden
|
||||
- query_vector: (optional) direkter Vektor (384d) für Quick-Tests ohne Embedding
|
||||
- explain: (optional) Fordert detaillierte Erklärungen an (WP-04b)
|
||||
"""
|
||||
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
|
||||
query: Optional[str] = None
|
||||
query_vector: Optional[List[float]] = None
|
||||
top_k: int = 10
|
||||
expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next"]}
|
||||
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
|
||||
|
||||
|
||||
# --- WP-04b Explanation Models ---
|
||||
|
||||
class ScoreBreakdown(BaseModel):
|
||||
"""
|
||||
Aufschlüsselung der Score-Komponenten.
|
||||
Zeigt die gewichteten Beiträge zum Total Score.
|
||||
"""
|
||||
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
|
||||
raw_semantic: float
|
||||
raw_edge_bonus: float
|
||||
raw_centrality: float
|
||||
node_weight: float = Field(..., description="Typ-Gewicht (retriever_weight)")
|
||||
|
||||
|
||||
class Reason(BaseModel):
|
||||
"""
|
||||
Ein semantischer Grund für das Ranking.
|
||||
z.B. 'Verlinkt von Projekt X', 'Hohe Textähnlichkeit'.
|
||||
"""
|
||||
kind: Literal["semantic", "edge", "type", "centrality"]
|
||||
message: str
|
||||
score_impact: Optional[float] = None
|
||||
details: Optional[Dict[str, Any]] = None
|
||||
|
||||
|
||||
class Explanation(BaseModel):
|
||||
"""
|
||||
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 ---
|
||||
|
||||
|
||||
class QueryHit(BaseModel):
|
||||
"""Einzelnes Trefferobjekt für /query."""
|
||||
node_id: str
|
||||
note_id: Optional[str]
|
||||
|
||||
# Flache Scores (Kompatibilität WP-04a)
|
||||
semantic_score: float
|
||||
edge_bonus: float
|
||||
centrality_bonus: float
|
||||
total_score: float
|
||||
|
||||
paths: Optional[List[List[Dict]]] = None
|
||||
source: Optional[Dict] = None
|
||||
|
||||
# WP-04b: Erklärungsobjekt (nur gefüllt, wenn explain=True)
|
||||
explanation: Optional[Explanation] = None
|
||||
|
||||
|
||||
class QueryResponse(BaseModel):
|
||||
@@ -91,4 +143,4 @@ class GraphResponse(BaseModel):
|
||||
center_note_id: str
|
||||
nodes: List[NodeDTO]
|
||||
edges: List[EdgeDTO]
|
||||
stats: Dict[str, int]
|
||||
stats: Dict[str, int]
|
||||
Reference in new issue
Block a user