Skip to main content

agent_knowledge_contract/
lib.rs

1//! Provider-neutral contract for externally owned knowledge systems.
2//!
3//! This crate intentionally contains no persistence, embedding or ingestion
4//! types. Resource, revision and segment identifiers remain opaque.
5
6use 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}