converge_provider/
capability.rs

1// Copyright 2024-2026 Reflective Labs
2
3// SPDX-License-Identifier: MIT
4
5//! Capability declarations for backends.
6//!
7//! Capabilities describe *what a backend can do*, independent of its kind.
8//! A single backend may support multiple capabilities (e.g., a multimodal
9//! LLM supports `TextGeneration` + Vision + `CodeGeneration`).
10//!
11//! # Design
12//!
13//! Capabilities are intentionally fine-grained. Selection logic matches
14//! required capabilities against declared capabilities. This avoids the
15//! need to know *which specific backend* you need — just declare what
16//! you need and let the selector find it.
17
18use serde::{Deserialize, Serialize};
19
20/// A capability that a backend declares it supports.
21///
22/// Organized by domain but not restricted to any single backend kind.
23/// A backend of any kind can declare any capability it genuinely supports.
24///
25/// # Extensibility
26///
27/// The `Other(String)` variant allows declaring capabilities not yet
28/// enumerated. Use it for experimental or domain-specific capabilities.
29#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
30pub enum Capability {
31    // ── LLM / Generation ──────────────────────────────────────────────
32    /// Generate natural language text.
33    TextGeneration,
34    /// Multi-step reasoning and chain-of-thought.
35    Reasoning,
36    /// Generate or analyze source code.
37    CodeGeneration,
38    /// Understand and generate text in multiple languages.
39    MultilingualText,
40    /// Search the web for current information.
41    WebSearch,
42    /// Understand images, screenshots, diagrams.
43    ImageUnderstanding,
44    /// Generate structured output (JSON, schemas).
45    StructuredOutput,
46    /// Use external tools / function calling.
47    ToolUse,
48    /// Stream partial results as they are generated.
49    Streaming,
50
51    // ── Policy / Governance ───────────────────────────────────────────
52    /// Evaluate access control rules (who can do what).
53    AccessControl,
54    /// Check regulatory compliance (GDPR, HIPAA, SOC2).
55    ComplianceCheck,
56    /// Generate audit trail entries.
57    AuditTrail,
58    /// Evaluate business rules and constraints.
59    RuleEvaluation,
60
61    // ── Optimization / Solving ────────────────────────────────────────
62    /// Solve constraint satisfaction problems.
63    ConstraintSolving,
64    /// Allocate resources under constraints.
65    ResourceAllocation,
66    /// Schedule tasks/events with dependencies.
67    Scheduling,
68    /// Linear/integer programming.
69    MathematicalProgramming,
70
71    // ── Analytics / ML ────────────────────────────────────────────────
72    /// Generate vector embeddings from text/images.
73    Embedding,
74    /// Rerank candidates by relevance.
75    Reranking,
76    /// Find similar vectors (nearest neighbor search).
77    VectorSearch,
78    /// Group data points by similarity.
79    Clustering,
80    /// Predict continuous values.
81    Regression,
82    /// Assign categories to data.
83    Classification,
84    /// Detect anomalies in data patterns.
85    AnomalyDetection,
86
87    // ── Search / Recall ───────────────────────────────────────────────
88    /// Full-text document search.
89    FullTextSearch,
90    /// Graph traversal and relationship queries.
91    GraphTraversal,
92    /// Semantic search using embeddings.
93    SemanticSearch,
94
95    // ── Storage / Persistence ─────────────────────────────────────────
96    /// Key-value storage.
97    KeyValue,
98    /// Document storage (JSON, BSON).
99    DocumentStore,
100    /// Append-only event sourcing.
101    EventSourcing,
102
103    // ── Infrastructure ────────────────────────────────────────────────
104    /// Deterministic replay of operations.
105    Replay,
106    /// Operate without network access.
107    Offline,
108
109    /// Extension point for capabilities not yet enumerated.
110    Other(String),
111}
112
113impl std::fmt::Display for Capability {
114    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
115        match self {
116            Self::Other(name) => write!(f, "other:{name}"),
117            other => write!(f, "{other:?}"),
118        }
119    }
120}
121
122#[cfg(test)]
123mod tests {
124    use super::*;
125
126    #[test]
127    fn display_text_generation() {
128        assert_eq!(Capability::TextGeneration.to_string(), "TextGeneration");
129    }
130
131    #[test]
132    fn display_reasoning() {
133        assert_eq!(Capability::Reasoning.to_string(), "Reasoning");
134    }
135
136    #[test]
137    fn display_embedding() {
138        assert_eq!(Capability::Embedding.to_string(), "Embedding");
139    }
140
141    #[test]
142    fn display_access_control() {
143        assert_eq!(Capability::AccessControl.to_string(), "AccessControl");
144    }
145
146    #[test]
147    fn display_vector_search() {
148        assert_eq!(Capability::VectorSearch.to_string(), "VectorSearch");
149    }
150
151    #[test]
152    fn display_other_variant() {
153        assert_eq!(
154            Capability::Other("custom-cap".into()).to_string(),
155            "other:custom-cap"
156        );
157    }
158
159    #[test]
160    fn equality() {
161        assert_eq!(Capability::Reasoning, Capability::Reasoning);
162        assert_ne!(Capability::Reasoning, Capability::Embedding);
163        assert_eq!(Capability::Other("x".into()), Capability::Other("x".into()));
164        assert_ne!(Capability::Other("x".into()), Capability::Other("y".into()));
165    }
166}
converge_provider/capability.rs

converge_provider/
capability.rs
