agent_knowledge_contract/
lib.rs1use serde::{Deserialize, Serialize};
7use serde_json::Value;
8
9pub const KNOWLEDGE_CAPABILITIES_PATH: &str = "/internal/v1/knowledge/capabilities";
10pub const KNOWLEDGE_QUERY_PATH: &str = "/internal/v1/knowledge/query";
11pub const KNOWLEDGE_RESOLVE_PATH: &str = "/internal/v1/knowledge/resolve-resources";
12pub const MAX_QUERY_BYTES: usize = 16 * 1024;
13pub const MAX_HITS: usize = 100;
14pub const MAX_EXCERPT_BYTES: usize = 64 * 1024;
15
16#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "snake_case")]
18pub enum KnowledgeRequirement {
19 Required,
20 #[default]
21 Optional,
22 Disabled,
23}
24
25#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
26#[serde(rename_all = "camelCase", deny_unknown_fields)]
27pub struct KnowledgeCapabilities {
28 pub provider: String,
29 #[serde(default)]
30 pub query_modes: Vec<String>,
31 pub resource_resolution: bool,
32 pub max_hits: usize,
33}
34
35#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
36#[serde(rename_all = "camelCase", deny_unknown_fields)]
37pub struct KnowledgeQueryRequest {
38 pub query: String,
39 #[serde(default)]
40 pub requirement: KnowledgeRequirement,
41 #[serde(default, skip_serializing_if = "Option::is_none")]
42 pub provider: Option<String>,
43 #[serde(default, skip_serializing_if = "Option::is_none")]
44 pub scope_ref: Option<String>,
45 #[serde(default = "default_top_k")]
46 pub top_k: usize,
47 #[serde(default, skip_serializing_if = "Value::is_null")]
48 pub filters: Value,
49}
50
51fn default_top_k() -> usize {
52 10
53}
54
55#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
56#[serde(rename_all = "camelCase", deny_unknown_fields)]
57pub struct KnowledgeHit {
58 pub provider: String,
59 pub resource_ref: String,
60 #[serde(default, skip_serializing_if = "Option::is_none")]
61 pub revision_ref: Option<String>,
62 #[serde(default, skip_serializing_if = "Option::is_none")]
63 pub segment_ref: Option<String>,
64 pub excerpt: String,
65 pub score: f64,
66 #[serde(default, skip_serializing_if = "Option::is_none")]
67 pub citation: Option<String>,
68 #[serde(default, skip_serializing_if = "Value::is_null")]
69 pub metadata: Value,
70}
71
72#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
73#[serde(rename_all = "camelCase", deny_unknown_fields)]
74pub struct KnowledgeQueryResponse {
75 pub hits: Vec<KnowledgeHit>,
76 #[serde(default)]
77 pub degraded: bool,
78 #[serde(default, skip_serializing_if = "Option::is_none")]
79 pub degradation_reason: Option<String>,
80}
81
82#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
83#[serde(rename_all = "camelCase", deny_unknown_fields)]
84pub struct ResolveKnowledgeResourcesRequest {
85 pub resource_refs: Vec<String>,
86}
87
88#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
89#[serde(rename_all = "camelCase", deny_unknown_fields)]
90pub struct KnowledgeResource {
91 pub provider: String,
92 pub resource_ref: String,
93 #[serde(default, skip_serializing_if = "Option::is_none")]
94 pub revision_ref: Option<String>,
95 pub title: String,
96 #[serde(default, skip_serializing_if = "Value::is_null")]
97 pub metadata: Value,
98}
99
100#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
101#[serde(rename_all = "camelCase", deny_unknown_fields)]
102pub struct ResolveKnowledgeResourcesResponse {
103 pub resources: Vec<KnowledgeResource>,
104}