155 lines
4.6 KiB
Python
155 lines
4.6 KiB
Python
"""
|
|
app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04/WP-05/WP-06
|
|
|
|
Zweck:
|
|
Laufzeit-Modelle für FastAPI (Requests/Responses).
|
|
WP-06 Update: Intent & Intent-Source in ChatResponse.
|
|
|
|
Version:
|
|
0.6.1 (WP-06: Decision Engine Transparency)
|
|
Stand:
|
|
2025-12-09
|
|
"""
|
|
|
|
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
|
|
type: Literal["note", "chunk"]
|
|
title: Optional[str] = None
|
|
note_id: Optional[str] = None
|
|
tags: Optional[List[str]] = None
|
|
in_degree: Optional[int] = None
|
|
out_degree: Optional[int] = None
|
|
score: Optional[float] = None
|
|
section_title: Optional[str] = None
|
|
section_path: Optional[str] = None
|
|
path: Optional[str] = None
|
|
|
|
|
|
class EdgeDTO(BaseModel):
|
|
"""Darstellung einer Kante im API-Graph."""
|
|
id: str
|
|
kind: str
|
|
source: str
|
|
target: str
|
|
weight: float
|
|
direction: Literal["out", "in", "undirected"] = "out"
|
|
|
|
|
|
# --- Request Models ---
|
|
|
|
class QueryRequest(BaseModel):
|
|
"""
|
|
Request für /query.
|
|
"""
|
|
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", "depends_on", "related_to"]}
|
|
filters: Optional[Dict] = None
|
|
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
|
|
explain: bool = False
|
|
|
|
|
|
class FeedbackRequest(BaseModel):
|
|
"""
|
|
User-Feedback zu einem spezifischen Treffer.
|
|
"""
|
|
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
|
|
|
|
|
|
class ChatRequest(BaseModel):
|
|
"""
|
|
WP-05: Request für /chat.
|
|
"""
|
|
message: str = Field(..., description="Die Nachricht des Users")
|
|
conversation_id: Optional[str] = Field(None, description="Optional: ID für Chat-Verlauf (noch nicht implementiert)")
|
|
# RAG Parameter (Override defaults)
|
|
top_k: int = 5
|
|
explain: bool = False
|
|
|
|
|
|
# --- WP-04b Explanation Models ---
|
|
|
|
class ScoreBreakdown(BaseModel):
|
|
"""Aufschlüsselung der Score-Komponenten."""
|
|
semantic_contribution: float
|
|
edge_contribution: float
|
|
centrality_contribution: float
|
|
raw_semantic: float
|
|
raw_edge_bonus: float
|
|
raw_centrality: float
|
|
node_weight: float
|
|
|
|
|
|
class Reason(BaseModel):
|
|
"""Ein semantischer Grund für das Ranking."""
|
|
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]
|
|
related_edges: Optional[List[EdgeDTO]] = None
|
|
|
|
|
|
# --- Response Models ---
|
|
|
|
class QueryHit(BaseModel):
|
|
"""Einzelnes Trefferobjekt für /query."""
|
|
node_id: str
|
|
note_id: Optional[str]
|
|
semantic_score: float
|
|
edge_bonus: float
|
|
centrality_bonus: float
|
|
total_score: float
|
|
paths: Optional[List[List[Dict]]] = None
|
|
source: Optional[Dict] = None
|
|
payload: Optional[Dict] = None # Added for flexibility & WP-06 meta-data
|
|
explanation: Optional[Explanation] = None
|
|
|
|
|
|
class QueryResponse(BaseModel):
|
|
"""Antwortstruktur für /query."""
|
|
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}."""
|
|
center_note_id: str
|
|
nodes: List[NodeDTO]
|
|
edges: List[EdgeDTO]
|
|
stats: Dict[str, int]
|
|
|
|
|
|
class ChatResponse(BaseModel):
|
|
"""
|
|
WP-05/06: Antwortstruktur für /chat.
|
|
"""
|
|
query_id: str = Field(..., description="Traceability ID (dieselbe wie für Search)")
|
|
answer: str = Field(..., description="Generierte Antwort vom LLM")
|
|
sources: List[QueryHit] = Field(..., description="Die für die Antwort genutzten Quellen")
|
|
latency_ms: int
|
|
intent: Optional[str] = Field("FACT", description="WP-06: Erkannter Intent (FACT/DECISION)")
|
|
intent_source: Optional[str] = Field("Unknown", description="WP-06: Quelle der Intent-Erkennung (Keyword vs. LLM)") |