agent-knowledge-contract 0.1.0

Transport-neutral contracts for Agent Infra knowledge APIs
Documentation
//! Provider-neutral contract for externally owned knowledge systems.
//!
//! This crate intentionally contains no persistence, embedding or ingestion
//! types. Resource, revision and segment identifiers remain opaque.

use serde::{Deserialize, Serialize};
use serde_json::Value;

pub const KNOWLEDGE_CAPABILITIES_PATH: &str = "/internal/v1/knowledge/capabilities";
pub const KNOWLEDGE_QUERY_PATH: &str = "/internal/v1/knowledge/query";
pub const KNOWLEDGE_RESOLVE_PATH: &str = "/internal/v1/knowledge/resolve-resources";
pub const MAX_QUERY_BYTES: usize = 16 * 1024;
pub const MAX_HITS: usize = 100;
pub const MAX_EXCERPT_BYTES: usize = 64 * 1024;

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum KnowledgeRequirement {
    Required,
    #[default]
    Optional,
    Disabled,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeCapabilities {
    pub provider: String,
    #[serde(default)]
    pub query_modes: Vec<String>,
    pub resource_resolution: bool,
    pub max_hits: usize,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeQueryRequest {
    pub query: String,
    #[serde(default)]
    pub requirement: KnowledgeRequirement,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provider: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scope_ref: Option<String>,
    #[serde(default = "default_top_k")]
    pub top_k: usize,
    #[serde(default, skip_serializing_if = "Value::is_null")]
    pub filters: Value,
}

fn default_top_k() -> usize {
    10
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeHit {
    pub provider: String,
    pub resource_ref: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub revision_ref: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub segment_ref: Option<String>,
    pub excerpt: String,
    pub score: f64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub citation: Option<String>,
    #[serde(default, skip_serializing_if = "Value::is_null")]
    pub metadata: Value,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeQueryResponse {
    pub hits: Vec<KnowledgeHit>,
    #[serde(default)]
    pub degraded: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub degradation_reason: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ResolveKnowledgeResourcesRequest {
    pub resource_refs: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct KnowledgeResource {
    pub provider: String,
    pub resource_ref: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub revision_ref: Option<String>,
    pub title: String,
    #[serde(default, skip_serializing_if = "Value::is_null")]
    pub metadata: Value,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ResolveKnowledgeResourcesResponse {
    pub resources: Vec<KnowledgeResource>,
}