Coverage for node / src / stigmem_node / models / recall.py: 100%

1"""Recall route wire-format models.""" 

2 

3from __future__ import annotations 

4 

5from typing import Any 

6 

7from pydantic import BaseModel, Field 

8 

9from .facts import FactRecord 

10from .tombstones import TombstoneNotice 

11 

12_DEFAULT_WEIGHTS = { 

13 "lexical": 0.35, 

14 "semantic": 0.35, 

15 "graph": 0.15, 

16 "source_trust": 0.10, 

17 "recency": 0.05, 

18} 

19 

20 

21class RecallWeights(BaseModel): 

22 lexical: float = Field(_DEFAULT_WEIGHTS["lexical"], ge=0.0, le=1.0) 

23 semantic: float = Field(_DEFAULT_WEIGHTS["semantic"], ge=0.0, le=1.0) 

24 graph: float = Field(_DEFAULT_WEIGHTS["graph"], ge=0.0, le=1.0) 

25 source_trust: float = Field(_DEFAULT_WEIGHTS["source_trust"], ge=0.0, le=1.0) 

26 recency: float = Field(_DEFAULT_WEIGHTS["recency"], ge=0.0, le=1.0) 

27 

28 

29class RecallRequest(BaseModel): 

30 query: str = Field(..., min_length=1) 

31 scope: str = Field("local") 

32 token_budget: int = Field(4000, ge=1, le=200_000) 

33 depth: int = Field(2, ge=1, le=3) 

34 weights: RecallWeights = Field(default_factory=RecallWeights) 

35 min_confidence: float = Field(0.1, ge=0.0, le=1.0) 

36 include_neighbors: bool = Field(True) 

37 limit: int = Field(100, ge=1, le=500, description="Max candidates before token-budget packing") 

38 as_of: str | None = Field( 

39 None, 

40 description="Time-travel query: return facts visible at this ISO 8601 timestamp (Spec-X3-Time-Travel-Queries)", # noqa: E501 

41 ) 

42 

43 

44class ScoreBreakdown(BaseModel): 

45 lexical: float = 0.0 

46 semantic: float = 0.0 

47 graph: float = 0.0 

48 source_trust: float = 0.0 

49 recency: float = 0.0 

50 weighted_total: float = 0.0 

51 

52 

53class ScoredFact(BaseModel): 

54 fact: FactRecord 

55 score: float 

56 score_breakdown: ScoreBreakdown 

57 hop_distance: int = 0 

58 token_estimate: int 

59 from_card: bool = False 

60 

61 

62class FactChainProof(BaseModel): 

63 tenant_id: str 

64 checked_entries: int 

65 head_hash: str | None = None 

66 checkpoint: FactChainCheckpointProof | None = None 

67 

68 

69class FactChainCheckpointProof(BaseModel): 

70 id: str 

71 tenant_id: str 

72 covered_chain_seq: int 

73 chain_hash: str 

74 status: str 

75 attempt_count: int 

76 created_at: str 

77 submitted_at: str | None = None 

78 last_error: str | None = None 

79 tl_backend: str 

80 tl_log_id: str | None = None 

81 tl_leaf_hash: str | None = None 

82 tl_log_index: int | None = None 

83 tl_integrated_time: int | None = None 

84 tl_inclusion_proof: dict[str, Any] = Field(default_factory=dict) 

85 tl_raw: dict[str, Any] = Field(default_factory=dict) 

86 

87 

88class RecallResponse(BaseModel): 

89 recall_id: str 

90 query_hash: str 

91 facts: list[ScoredFact] 

92 content: list[ScoredFact] = Field(default_factory=list) 

93 instructions: list[ScoredFact] = Field(default_factory=list) 

94 total_scored: int | None = None 

95 token_budget: int 

96 tokens_used: int 

97 truncated: bool 

98 tombstone_notices: list[TombstoneNotice] = Field(default_factory=list) 

99 chain_proof: FactChainProof | None = None