enya-agent 0.1.0

package/crates/enact-core/src/providers/trait.rs

@@ -0,0 +1,292 @@
+//! Model provider trait and capabilities
+//!
+//! This module defines the `ModelProvider` trait and related types. Provider implementations
+//! are in the separate `enact-providers` crate to enable independent release cadence.
+//!
+//! ## ⚠️ CODE OWNERSHIP & FORBIDDEN PATTERNS
+//!
+//! **Providers are replaceable adapters - execution semantics must never depend on provider behavior.**
+//!
+//! ### Code Ownership
+//! - Provider implementations live in `enact-providers` crate
+//! - This module contains only the trait and types (`ChatRequest`, `ChatResponse`, `ModelCapabilities`)
+//! - `enact-providers` depends on `enact-core` (for the trait), but `enact-core` must NOT depend on `enact-providers`
+//! - Providers are thin HTTP adapters
+//! - They should only see `ChatRequest`/`ChatResponse` and tool schemas
+//! - If providers need kernel types, that logic belongs in the kernel
+//!
+//! ### Explicitly Forbidden Patterns
+//!
+//! These patterns are **forbidden forever**. If any of these happen, Enact loses its "Now" guarantee.
+//!
+//! 1. **Providers enforcing policy** – Policy enforcement belongs to kernel, not providers.
+//!    - Providers are thin adapters, not policy engines
+//!    - No policy checks in provider implementations
+//!    - No quota enforcement in providers
+//!
+//! 2. **Providers importing kernel/flow/policy** – Providers must not import kernel types.
+//!    - `enact-providers` must NOT import `enact_core::kernel`, `enact_core::flow`, or `enact_core::policy`
+//!    - Providers should only see `ChatRequest`/`ChatResponse` and tool schemas
+//!    - If providers need kernel types, that logic belongs in the kernel
+//!    - No circular dependencies: `enact-core` must NOT depend on `enact-providers`
+//!
+//! 3. **Global registries or dynamic discovery in kernel** – Providers are resolved before kernel execution.
+//!    - The kernel receives resolved providers via `ExecutionRequest`, not provider names or registry lookups
+//!    - Provider resolution happens outside kernel (in runner/control plane)
+//!    - No provider registry in kernel
+//!
+//! 4. **Execution semantics depending on provider behavior** – Providers are replaceable adapters.
+//!    - Execution semantics must never depend on provider-specific behavior
+//!    - All providers must implement the same trait interface
+//!    - No provider-specific logic in kernel
+//!
+//! ### Invariants Enforced
+//!
+//! - **Providers are replaceable adapters**: Execution semantics must never depend on provider behavior
+//! - **No global registries or dynamic discovery in kernel**: Providers are resolved before kernel execution
+//! - **Provider resolution happens outside kernel**: Resolution belongs in runner/control plane, not in the kernel
+//! - **Providers must not import kernel/flow/policy**: `enact-providers` must NOT import `enact_core::kernel`, `enact_core::flow`, or `enact_core::policy`
+//! - **Crate boundary separation**: Provider implementations in `enact-providers`, trait in `enact-core`, one-way dependency only
+//!
+//! @see docs/TECHNICAL/04-KERNEL_INVARIANTS.md
+
+use async_trait::async_trait;
+use serde::{Deserialize, Serialize};
+
+// =============================================================================
+// Model Capabilities - What a model can do
+// =============================================================================
+
+/// Model capabilities - declares what a model supports
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ModelCapabilities {
+    /// Maximum context window (tokens)
+    pub max_tokens: u32,
+    /// Maximum output tokens
+    pub max_output_tokens: u32,
+    /// Supports streaming responses
+    pub supports_streaming: bool,
+    /// Supports tool/function calling
+    pub supports_tools: bool,
+    /// Supports vision/images
+    pub supports_vision: bool,
+    /// Supports structured output (JSON mode)
+    pub supports_json_mode: bool,
+    /// Supports embedding generation
+    pub supports_embeddings: bool,
+    /// Is PII-safe (no data retention)
+    pub pii_safe: bool,
+    /// Cost per 1K input tokens (USD)
+    pub cost_per_1k_input: Option<f64>,
+    /// Cost per 1K output tokens (USD)
+    pub cost_per_1k_output: Option<f64>,
+}
+
+impl Default for ModelCapabilities {
+    fn default() -> Self {
+        Self {
+            max_tokens: 4096,
+            max_output_tokens: 4096,
+            supports_streaming: true,
+            supports_tools: false,
+            supports_vision: false,
+            supports_json_mode: false,
+            supports_embeddings: false,
+            pii_safe: false,
+            cost_per_1k_input: None,
+            cost_per_1k_output: None,
+        }
+    }
+}
+
+impl ModelCapabilities {
+    /// GPT-4 capabilities
+    pub fn gpt4() -> Self {
+        Self {
+            max_tokens: 128_000,
+            max_output_tokens: 4096,
+            supports_streaming: true,
+            supports_tools: true,
+            supports_vision: true,
+            supports_json_mode: true,
+            supports_embeddings: true,
+            pii_safe: false,
+            cost_per_1k_input: Some(0.03),
+            cost_per_1k_output: Some(0.06),
+        }
+    }
+
+    /// Claude 3 Opus capabilities
+    pub fn claude3_opus() -> Self {
+        Self {
+            max_tokens: 200_000,
+            max_output_tokens: 4096,
+            supports_streaming: true,
+            supports_tools: true,
+            supports_vision: true,
+            supports_json_mode: true,
+            supports_embeddings: true,
+            pii_safe: false,
+            cost_per_1k_input: Some(0.015),
+            cost_per_1k_output: Some(0.075),
+        }
+    }
+
+    /// Gemini Pro capabilities
+    pub fn gemini_pro() -> Self {
+        Self {
+            max_tokens: 1_000_000,
+            max_output_tokens: 8192,
+            supports_streaming: true,
+            supports_tools: true,
+            supports_vision: true,
+            supports_json_mode: true,
+            supports_embeddings: true,
+            pii_safe: false,
+            cost_per_1k_input: Some(0.00125),
+            cost_per_1k_output: Some(0.005),
+        }
+    }
+}
+
+// =============================================================================
+// Chat Types
+// =============================================================================
+
+/// Chat message
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ChatMessage {
+    pub role: String,
+    pub content: String,
+}
+
+impl ChatMessage {
+    pub fn system(content: impl Into<String>) -> Self {
+        Self {
+            role: "system".to_string(),
+            content: content.into(),
+        }
+    }
+
+    pub fn user(content: impl Into<String>) -> Self {
+        Self {
+            role: "user".to_string(),
+            content: content.into(),
+        }
+    }
+
+    pub fn assistant(content: impl Into<String>) -> Self {
+        Self {
+            role: "assistant".to_string(),
+            content: content.into(),
+        }
+    }
+}
+
+/// Chat completion request
+#[derive(Debug, Clone, Serialize)]
+pub struct ChatRequest {
+    pub messages: Vec<ChatMessage>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub temperature: Option<f32>,
+}
+
+/// Chat completion response
+#[derive(Debug, Clone, Deserialize)]
+pub struct ChatResponse {
+    pub id: String,
+    pub choices: Vec<ChatChoice>,
+    pub usage: Option<ChatUsage>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct ChatChoice {
+    pub index: u32,
+    pub message: ChatMessage,
+    pub finish_reason: Option<String>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct ChatUsage {
+    pub prompt_tokens: u32,
+    pub completion_tokens: u32,
+    pub total_tokens: u32,
+}
+
+// =============================================================================
+// Embedding Types
+// =============================================================================
+
+/// Embedding request
+#[derive(Debug, Clone, Serialize)]
+pub struct EmbeddingRequest {
+    /// Text to embed (single string or array of strings for batch)
+    pub input: String,
+    /// Optional model override
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub model: Option<String>,
+}
+
+/// Embedding response
+#[derive(Debug, Clone, Deserialize)]
+pub struct EmbeddingResponse {
+    /// Embedding data (one per input)
+    pub data: Vec<EmbeddingData>,
+    /// Model used for embedding
+    pub model: String,
+    /// Token usage information
+    pub usage: Option<EmbeddingUsage>,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct EmbeddingData {
+    /// The embedding vector
+    pub embedding: Vec<f32>,
+    /// Index of the embedding in the batch
+    pub index: u32,
+}
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct EmbeddingUsage {
+    /// Number of tokens in the input
+    pub prompt_tokens: u32,
+    /// Total tokens used
+    pub total_tokens: u32,
+}
+
+/// Model provider trait
+#[async_trait]
+pub trait ModelProvider: Send + Sync {
+    /// Provider name
+    fn name(&self) -> &str;
+
+    /// Model name being used
+    fn model(&self) -> &str {
+        "default"
+    }
+
+    /// Get model capabilities
+    fn capabilities(&self) -> ModelCapabilities {
+        ModelCapabilities::default()
+    }
+
+    /// Whether this provider requires network access.
+    /// Default is `true` for cloud LLM providers.
+    /// Override to `false` for local providers (e.g., Ollama).
+    fn requires_network(&self) -> bool {
+        true
+    }
+
+    /// Create a chat completion
+    async fn chat(&self, request: ChatRequest) -> anyhow::Result<ChatResponse>;
+
+    /// Generate embeddings (if supported)
+    ///
+    /// Default implementation returns an error. Providers that support embeddings
+    /// should override this method.
+    async fn embed(&self, _request: EmbeddingRequest) -> anyhow::Result<EmbeddingResponse> {
+        anyhow::bail!("Embeddings not supported by this provider")
+    }
+}

package/crates/enact-core/src/runner/callbacks.rs

@@ -0,0 +1,6 @@
+//! Placeholder for runner callbacks.
+//!
+//! Will define before/after callbacks for agents, models, and tools,
+//! feeding directly into observability.
+
+