skill_runtime/
lib.rs

1//! Skill Runtime - Universal execution engine for AI agent skills
2//!
3//! This crate provides a secure, portable runtime for executing AI agent skills across multiple
4//! runtime types: WASM Component Model, Docker containers, and native command execution.
5//!
6//! # Features
7//!
8//! - **WASM Sandbox**: Execute skills in isolated WASM environments with capability-based security
9//! - **Docker Runtime**: Run containerized skills with full environment control
10//! - **Native Execution**: Direct command execution for system tools (kubectl, git, etc.)
11//! - **RAG-Powered Search**: Semantic search with hybrid retrieval, reranking, and context compression
12//! - **Multi-Instance Support**: Configure multiple instances per skill (dev/staging/prod)
13//! - **Audit Logging**: Comprehensive execution tracking and security auditing
14//!
15//! # Quick Start
16//!
17//! ```rust,no_run
18//! use skill_runtime::{SkillEngine, SkillManifest};
19//!
20//! # async fn run() -> anyhow::Result<()> {
21//! // Initialize the runtime
22//! let engine = SkillEngine::new()?;
23//!
24//! // Load a skill manifest
25//! let manifest = SkillManifest::from_file(".skill-engine.toml")?;
26//!
27//! // Execute a tool
28//! let result = engine.execute_tool("kubernetes", "get", serde_json::json!({
29//!     "resource": "pods",
30//!     "namespace": "default"
31//! })).await?;
32//!
33//! println!("Result: {}", result);
34//! # Ok(())
35//! # }
36//! ```
37//!
38//! # Architecture
39//!
40//! ```text
41//! ┌─────────────────────────────────────────┐
42//! │           SkillEngine                    │
43//! │  (Orchestrates execution & search)       │
44//! └─────────────────────────────────────────┘
45//!                   │
46//!       ┌───────────┼───────────┐
47//!       ▼           ▼           ▼
48//! ┌─────────┐ ┌──────────┐ ┌────────────┐
49//! │  WASM   │ │  Docker  │ │   Native   │
50//! │ Runtime │ │ Runtime  │ │  Executor  │
51//! └─────────┘ └──────────┘ └────────────┘
52//!       │           │           │
53//!       └───────────┴───────────┘
54//!                   │
55//!       ┌───────────┴───────────┐
56//!       ▼                       ▼
57//! ┌──────────────┐    ┌────────────────┐
58//! │ Vector Store │    │  Audit Logger  │
59//! │ (Search)     │    │  (Security)    │
60//! └──────────────┘    └────────────────┘
61//! ```
62//!
63//! # Security Model
64//!
65//! Skills execute with capability-based security:
66//!
67//! - **WASI Sandbox**: Network and filesystem access must be explicitly granted
68//! - **Command Allowlist**: Native skills declare allowed commands in `allowed-tools`
69//! - **Docker Isolation**: Containerized skills run in separate namespaces
70//! - **Audit Trail**: All executions are logged with timestamps and arguments
71//!
72//! # Performance
73//!
74//! - WASM cold start: ~100ms (includes AOT compilation)
75//! - WASM warm start: <10ms (cached)
76//! - Vector search: <50ms (384-dim embeddings)
77//! - Native commands: Near-instant (direct execution)
78//!
79//! # Feature Flags
80//!
81//! - `hybrid-search`: BM25 + dense vector fusion with RRF
82//! - `reranker`: Cross-encoder reranking for improved precision
83//! - `context-compression`: Token-aware output compression
84//! - `qdrant`: Production vector database backend
85//! - `job-queue`: Async job scheduling and execution
86//! - `sqlite-storage`: SQLite-backed job storage
87
88#![warn(missing_docs)]
89
90pub mod audit;
91pub mod config_mapper;
92pub mod credentials;
93pub mod docker_runtime;
94pub mod engine;
95pub mod errors;
96pub mod executor;
97pub mod generation;
98pub mod git_loader;
99pub mod git_source;
100pub mod instance;
101pub mod local_loader;
102pub mod manifest;
103pub mod metrics;
104pub mod sandbox;
105pub mod skill_md;
106pub mod types;
107pub mod vector_store;
108pub mod embeddings;
109pub mod search;
110pub mod search_config;
111
112#[cfg(feature = "job-queue")]
113pub mod jobs;
114
115pub use audit::{AuditEntry, AuditEventType, AuditLogger};
116pub use config_mapper::ConfigMapper;
117pub use credentials::{parse_keyring_reference, CredentialStore, SecureString};
118pub use engine::SkillEngine;
119pub use errors::{RuntimeError, Result};
120pub use executor::{ComponentCache, SkillExecutor};
121pub use git_loader::{ClonedSkill, GitSkillLoader, SkillType};
122pub use git_source::{is_git_url, parse_git_url, GitRef, GitSource};
123pub use instance::{InstanceConfig, InstanceManager};
124pub use local_loader::LocalSkillLoader;
125pub use docker_runtime::{DockerOutput, DockerRuntime, DockerSecurityPolicy};
126pub use manifest::{
127    DockerRuntimeConfig, ServiceRequirement, SkillManifest, SkillRuntime, ResolvedInstance, SkillInfo, expand_env_vars
128};
129pub use metrics::ExecutionMetrics;
130pub use sandbox::{HostState, SandboxBuilder};
131pub use skill_md::{
132    parse_skill_md, parse_skill_md_content, find_skill_md,
133    SkillMdContent, SkillMdFrontmatter, ToolDocumentation, CodeExample, ParameterDoc
134};
135pub use types::*;
136pub use vector_store::{
137    VectorStore, InMemoryVectorStore,
138    EmbeddedDocument, DocumentMetadata, Filter, SearchResult,
139    UpsertStats, DeleteStats, HealthStatus, DistanceMetric,
140    cosine_similarity, euclidean_distance,
141};
142
143#[cfg(feature = "qdrant")]
144pub use vector_store::{QdrantVectorStore, QdrantConfig};
145pub use embeddings::{
146    EmbeddingProvider, EmbeddingConfig, EmbeddingProviderType,
147    FastEmbedProvider, FastEmbedModel,
148    OpenAIEmbedProvider, OpenAIEmbeddingModel,
149    OllamaProvider,
150    EmbeddingProviderFactory, create_provider,
151};
152
153pub use search::{FusionMethod, reciprocal_rank_fusion, weighted_sum_fusion};
154
155#[cfg(feature = "hybrid-search")]
156pub use search::{BM25Index, BM25Config, BM25SearchResult, HybridRetriever, HybridConfig, HybridSearchResult};
157
158#[cfg(feature = "reranker")]
159pub use search::{Reranker, RerankResult, RerankDocument, FastEmbedReranker, RerankerModel, RerankerConfig};
160
161#[cfg(feature = "context-compression")]
162pub use search::{
163    ContextCompressor, CompressionStrategy, CompressionConfig,
164    CompressedToolContext, ToolParameter, CompressionResult,
165};
166
167pub use search::{
168    QueryProcessor, QueryIntent, ExtractedEntity, EntityType,
169    ProcessedQuery, QueryExpansion,
170};
171
172pub use search::{
173    IndexManager, IndexMetadata, SkillChecksum,
174    IndexStats, SyncResult,
175};
176
177pub use search::{
178    SearchPipeline, PipelineSearchResult, PipelineIndexStats,
179    PipelineHealth, ProviderStatus, IndexDocument,
180};
181
182pub use search_config::{
183    SearchConfig, BackendConfig, BackendType,
184    EmbeddingConfig as SearchEmbeddingConfig,
185    RetrievalConfig, RerankerConfig as SearchRerankerConfig,
186    ContextConfig, QdrantConfig as SearchQdrantConfig,
187    IndexConfig as SearchIndexConfig,
188    FusionMethod as SearchFusionMethod,
189    CompressionStrategy as SearchCompressionStrategy,
190    AiIngestionConfig, AiProvider,
191    OllamaLlmConfig, OpenAiLlmConfig, AnthropicLlmConfig,
192};
193
194pub use generation::{
195    GenerationEvent, GeneratedExample, AgentStep,
196    SearchResultRef, GenerationStreamBuilder,
197    LlmProvider, LlmResponse, LlmChunk, TokenUsage,
198    ChatMessage, CompletionRequest, create_llm_provider,
199    ExampleValidator, ValidationResult, ParsedCommand,
200    ExampleGenerator, GeneratorConfig,
201};
202
203#[cfg(feature = "ollama")]
204pub use generation::OllamaProvider;
205
206#[cfg(feature = "openai")]
207pub use generation::OpenAIProvider;
208
209#[cfg(feature = "job-queue")]
210pub use jobs::{
211    JobConfig, StorageBackend, ConfigError as JobConfigError,
212    Job, JobId, JobStatus, JobPriority, JobType, JobProgress, JobStats,
213    MaintenanceTask, JobStorage, JobFilter, JobQueue,
214    StorageError, StorageResult, create_storage, create_job_queue,
215    WorkerConfig, WorkerPool, WorkerPoolStats, WorkerPoolError,
216    JobHandler, JobError, WorkerContext, PoolState, LoggingJobHandler,
217};
218
219#[cfg(feature = "sqlite-storage")]
220pub use jobs::SqliteJobStorage;
221
222/// Initialize the skill runtime
223///
224///  Creates a new [`SkillEngine`] instance with default configuration.
225///
226/// # Returns
227///
228/// Returns a configured `SkillEngine` ready to load and execute skills.
229///
230/// # Errors
231///
232/// Returns an error if the runtime fails to initialize, typically due to:
233/// - Missing dependencies (e.g., Wasmtime components)
234/// - Invalid system configuration
235/// - Insufficient permissions
236///
237/// # Example
238///
239/// ```rust,no_run
240/// use skill_runtime::init;
241///
242/// # fn main() -> anyhow::Result<()> {
243/// let engine = init()?;
244/// // Use the engine to load and execute skills
245/// # Ok(())
246/// # }
247/// ```
248pub fn init() -> anyhow::Result<SkillEngine> {
249    SkillEngine::new()
250}
skill_runtime/lib.rs

skill_runtime/
lib.rs
