kindling_types/
retrieval.rs

1use serde::{Deserialize, Serialize};
2
3#[cfg(feature = "ts-rs")]
4use ts_rs::TS;
5
6use crate::common::{Id, ScopeIds};
7use crate::observation::Observation;
8use crate::pin::Pin;
9use crate::summary::Summary;
10
11/// An entity returned from retrieval — either an observation or a summary.
12/// Untagged so the wire format matches the TS structural union `Observation | Summary`.
13#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
14#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
15#[serde(untagged)]
16pub enum RetrievedEntity {
17    Observation(Observation),
18    Summary(Summary),
19}
20
21/// Options for a retrieval request.
22#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
23#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
24#[serde(rename_all = "camelCase")]
25pub struct RetrieveOptions {
26    pub query: String,
27    pub scope_ids: ScopeIds,
28    /// Deprecated: token-budget assembly is a downstream-system responsibility.
29    /// Prefer `max_candidates` for bounded result sets.
30    #[serde(default, skip_serializing_if = "Option::is_none")]
31    #[cfg_attr(feature = "ts-rs", ts(optional))]
32    pub token_budget: Option<u32>,
33    #[serde(default, skip_serializing_if = "Option::is_none")]
34    #[cfg_attr(feature = "ts-rs", ts(optional))]
35    pub max_candidates: Option<u32>,
36    #[serde(default, skip_serializing_if = "Option::is_none")]
37    #[cfg_attr(feature = "ts-rs", ts(optional))]
38    pub include_redacted: Option<bool>,
39}
40
41/// Pin together with the observation or summary it points at.
42#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
43#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
44#[serde(rename_all = "camelCase")]
45pub struct PinResult {
46    pub pin: Pin,
47    pub target: RetrievedEntity,
48}
49
50/// Candidate (observation or summary) ranked by score.
51#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
52#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
53#[serde(rename_all = "camelCase")]
54pub struct CandidateResult {
55    pub entity: RetrievedEntity,
56    pub score: f64,
57    #[serde(default, skip_serializing_if = "Option::is_none")]
58    #[cfg_attr(feature = "ts-rs", ts(optional))]
59    pub match_context: Option<String>,
60}
61
62/// Provenance for a retrieval result.
63#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
64#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
65#[serde(rename_all = "camelCase")]
66pub struct RetrieveProvenance {
67    pub query: String,
68    pub scope_ids: ScopeIds,
69    pub total_candidates: u32,
70    pub returned_candidates: u32,
71    pub truncated_due_to_token_budget: bool,
72    pub provider_used: String,
73}
74
75/// Complete retrieval result: pins, optional current summary, ranked candidates, provenance.
76#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
77#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
78#[serde(rename_all = "camelCase")]
79pub struct RetrieveResult {
80    pub pins: Vec<PinResult>,
81    #[serde(default, skip_serializing_if = "Option::is_none")]
82    #[cfg_attr(feature = "ts-rs", ts(optional))]
83    pub current_summary: Option<Summary>,
84    pub candidates: Vec<CandidateResult>,
85    pub provenance: RetrieveProvenance,
86}
87
88/// Search options for a retrieval provider.
89#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
90#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
91#[serde(rename_all = "camelCase")]
92pub struct ProviderSearchOptions {
93    pub query: String,
94    pub scope_ids: ScopeIds,
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    #[cfg_attr(feature = "ts-rs", ts(optional))]
97    pub max_results: Option<u32>,
98    #[serde(default, skip_serializing_if = "Option::is_none")]
99    #[cfg_attr(feature = "ts-rs", ts(optional))]
100    pub exclude_ids: Option<Vec<Id>>,
101    #[serde(default, skip_serializing_if = "Option::is_none")]
102    #[cfg_attr(feature = "ts-rs", ts(optional))]
103    pub include_redacted: Option<bool>,
104}
105
106/// A single result from a retrieval provider.
107#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
108#[cfg_attr(feature = "ts-rs", derive(TS), ts(export, export_to = "../bindings/"))]
109#[serde(rename_all = "camelCase")]
110pub struct ProviderSearchResult {
111    pub entity: RetrievedEntity,
112    pub score: f64,
113    #[serde(default, skip_serializing_if = "Option::is_none")]
114    #[cfg_attr(feature = "ts-rs", ts(optional))]
115    pub match_context: Option<String>,
116}
kindling_types/retrieval.rs

kindling_types/
retrieval.rs
