noos 0.4.1

Reliability layer for Rust LLM agents: scope drift, cost circuit breaks, and procedural correction memory as event-driven Decisions.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! AI Provider trait — pluggable LLM backend abstraction (P4 trait boundary).
//!
//! The cognitive engine NEVER imports concrete provider implementations.
//! All AI calls go through this trait, enabling:
//! - Swap between Anthropic/OpenAI/Google/local models
//! - Mock for testing
//! - Future: on-device inference via WASM

use async_trait::async_trait;
use serde::{Deserialize, Serialize};

use crate::errors::NoosResult;

/// AI provider identifier.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum AiProviderType {
    Anthropic,
    OpenAi,
    Google,
    Local,
}

/// A message in the conversation (provider-agnostic).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ProviderMessage {
    pub role: MessageRole,
    pub content: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MessageRole {
    System,
    User,
    Assistant,
}

/// Request for AI completion.
#[derive(Debug, Clone)]
pub struct CompletionRequest {
    pub model: String,
    pub messages: Vec<ProviderMessage>,
    pub system_prompt: Option<String>,
    pub max_tokens: u32,
    pub temperature: f32,
    pub stream: bool,
}

/// Response from AI completion (non-streaming).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CompletionResponse {
    pub text: String,
    pub usage: TokenUsage,
    pub model: String,
}

/// Token usage statistics.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TokenUsage {
    pub input_tokens: u32,
    pub output_tokens: u32,
}

/// A chunk from streaming response.
#[derive(Debug, Clone)]
pub enum StreamChunk {
    /// Incremental text content.
    TextDelta(String),
    /// Token usage (typically at end of stream).
    Usage(TokenUsage),
    /// Stream complete.
    Done,
    /// Error during streaming.
    Error(String),
}

/// The core AI provider trait.
///
/// Implement this for each LLM backend (Anthropic, OpenAI, etc.).
/// The cognitive engine only knows this trait — never the concrete type.
#[async_trait]
pub trait AiProvider: Send + Sync {
    /// Provider identifier.
    fn provider_type(&self) -> AiProviderType;

    /// Non-streaming completion.
    async fn complete(&self, request: CompletionRequest) -> NoosResult<CompletionResponse>;

    /// Streaming completion — returns chunks via channel.
    async fn stream(
        &self,
        request: CompletionRequest,
        sender: tokio::sync::mpsc::Sender<StreamChunk>,
    ) -> NoosResult<()>;
}

/// Embedding provider trait — separate from completion.
///
/// Noos may use different providers for completion vs embedding
/// (e.g., Claude for completion, OpenAI for embeddings).
#[async_trait]
pub trait EmbeddingProvider: Send + Sync {
    /// Generate embedding vector for text.
    async fn embed(&self, text: &str) -> NoosResult<Vec<f32>>;

    /// Embedding dimension size.
    fn dimension(&self) -> usize;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn completion_request_builds() {
        let req = CompletionRequest {
            model: "claude-3-5-sonnet".into(),
            messages: vec![ProviderMessage {
                role: MessageRole::User,
                content: "Hello".into(),
            }],
            system_prompt: Some("You are helpful".into()),
            max_tokens: 1024,
            temperature: 0.7,
            stream: false,
        };
        assert_eq!(req.messages.len(), 1);
    }

    #[test]
    fn token_usage_default() {
        let usage = TokenUsage::default();
        assert_eq!(usage.input_tokens, 0);
        assert_eq!(usage.output_tokens, 0);
    }
}