embacle/
lib.rs

1// ABOUTME: Standalone LLM runner library wrapping AI CLI tools and SDKs as providers
2// ABOUTME: Re-exports runners, agent loop, fallback chains, metrics, quality gates, MCP bridge, and structured output
3//
4// SPDX-License-Identifier: Apache-2.0
5// Copyright (c) 2026 dravr.ai
6
7//! # Embacle — LLM Runners
8//!
9//! Standalone library providing pluggable [`LlmProvider`](types::LlmProvider)
10//! implementations that delegate to CLI tools (Claude Code, Copilot, Cursor Agent,
11//! `OpenCode`, Gemini, Codex, Goose, Cline, Continue) and SDKs (Copilot SDK) for LLM completions.
12//!
13//! CLI runners wrap a binary, build prompts from [`ChatMessage`](types::ChatMessage)
14//! sequences, parse JSON output, and manage session continuity. The Copilot SDK
15//! runner maintains a persistent `copilot --headless` server via JSON-RPC.
16//!
17//! ## Quick Start
18//!
19//! ```rust,no_run
20//! use std::path::PathBuf;
21//! use embacle::{ClaudeCodeRunner, RunnerConfig};
22//! use embacle::types::{ChatMessage, ChatRequest, LlmProvider};
23//!
24//! # async fn example() -> Result<(), embacle::types::RunnerError> {
25//! let config = RunnerConfig::new(PathBuf::from("claude"));
26//! let runner = ClaudeCodeRunner::new(config);
27//! let request = ChatRequest::new(vec![ChatMessage::user("Hello!")]);
28//! let response = runner.complete(&request).await?;
29//! println!("{}", response.content);
30//! # Ok(())
31//! # }
32//! ```
33//!
34//! ## Modules
35//!
36//! - [`types`] — Core types: `LlmProvider` trait, messages, requests, errors
37//! - [`config`] — Runner types and configuration
38//! - [`agent`] — Configurable agent loop with multi-turn tool calling
39//! - [`fallback`] — Provider fallback chains (try providers in order)
40//! - [`mcp_tool_bridge`] — MCP tool definition to text-tool-simulation bridge
41//! - [`metrics`] — Cost/latency normalization decorator
42//! - [`quality_gate`] — Response quality validation with retry
43//! - [`structured_output`] — Schema-enforced JSON output from any provider
44//! - [`compat`] — Version compatibility and capability detection
45//! - [`container`] — Container-based execution backend
46//! - [`discovery`] — Automatic binary detection on the host
47//! - [`capability_guard`] — Request/provider capability validation
48//! - [`auth`] — Readiness and authentication checking
49//! - [`process`] — Subprocess spawning with timeout and output limits
50//! - [`sandbox`] — Environment variable whitelisting and working directory control
51//! - [`prompt`] — Prompt building from `ChatMessage` slices
52//! - [`claude_code`] — Claude Code CLI runner
53//! - [`copilot`] — GitHub Copilot CLI runner
54//! - [`cursor_agent`] — Cursor Agent CLI runner
55//! - [`opencode`] — `OpenCode` CLI runner
56//! - [`gemini_cli`] — Gemini CLI runner
57//! - [`codex_cli`] — Codex CLI runner
58//! - [`goose_cli`] — Goose CLI runner
59//! - [`cline_cli`] — Cline CLI runner
60//! - [`continue_cli`] — Continue CLI runner
61//! - [`copilot_sdk_runner`] — GitHub Copilot SDK runner (requires `copilot-sdk` feature)
62
63/// Core types: traits, messages, requests, responses, and errors
64pub mod types;
65
66/// Configurable agent loop with multi-turn tool calling
67pub mod agent;
68/// Auth readiness checking for CLI runners
69pub mod auth;
70/// Request/provider capability validation
71pub mod capability_guard;
72/// Claude Code CLI runner
73pub mod claude_code;
74/// Cline CLI runner
75pub mod cline_cli;
76/// Codex CLI runner
77pub mod codex_cli;
78/// Version compatibility and capability detection
79pub mod compat;
80/// Shared configuration types for CLI runners
81pub mod config;
82/// Container-based execution backend
83pub mod container;
84/// Continue CLI runner
85pub mod continue_cli;
86/// GitHub Copilot CLI runner
87pub mod copilot;
88/// Cursor Agent CLI runner
89pub mod cursor_agent;
90/// Binary auto-detection and discovery
91pub mod discovery;
92/// Provider fallback chains
93pub mod fallback;
94/// Gemini CLI runner
95pub mod gemini_cli;
96/// Goose CLI runner
97pub mod goose_cli;
98/// MCP tool definition to text-tool-simulation bridge
99pub mod mcp_tool_bridge;
100/// Cost/latency normalization decorator
101pub mod metrics;
102/// `OpenCode` CLI runner
103pub mod opencode;
104/// Subprocess spawning with safety limits
105pub mod process;
106/// Prompt construction from `ChatMessage` sequences
107pub mod prompt;
108/// Response quality validation with retry
109pub mod quality_gate;
110/// Environment sandboxing and tool policy
111pub mod sandbox;
112/// Stream wrapper for child process lifecycle management
113pub mod stream;
114/// Schema-enforced JSON output from any provider
115pub mod structured_output;
116/// Text-based tool simulation for CLI runners without native function calling
117pub mod tool_simulation;
118
119// Copilot SDK modules (behind feature flag)
120/// Configuration for the Copilot SDK provider
121#[cfg(feature = "copilot-sdk")]
122pub mod copilot_sdk_config;
123/// GitHub Copilot SDK runner (persistent JSON-RPC server)
124#[cfg(feature = "copilot-sdk")]
125pub mod copilot_sdk_runner;
126/// Tool definition conversion for Copilot SDK native tool calling
127#[cfg(feature = "copilot-sdk")]
128pub mod tool_bridge;
129
130// Re-export the runner structs for ergonomic access
131pub use agent::{AgentExecutor, AgentResult, OnTurnCallback, TurnInfo};
132pub use auth::ProviderReadiness;
133pub use capability_guard::validate_capabilities;
134pub use claude_code::ClaudeCodeRunner;
135pub use cline_cli::ClineCliRunner;
136pub use codex_cli::CodexCliRunner;
137pub use compat::CliCapabilities;
138pub use config::{CliRunnerType, RunnerConfig};
139pub use container::{ContainerConfig, ContainerExecutor, NetworkMode};
140pub use continue_cli::ContinueCliRunner;
141pub use copilot::CopilotRunner;
142pub use cursor_agent::CursorAgentRunner;
143pub use discovery::{discover_runner, resolve_binary};
144pub use fallback::FallbackProvider;
145pub use gemini_cli::GeminiCliRunner;
146pub use goose_cli::GooseCliRunner;
147pub use mcp_tool_bridge::{McpToolDefinition, McpToolExecutor};
148pub use metrics::{MetricsProvider, MetricsReport};
149pub use opencode::OpenCodeRunner;
150pub use quality_gate::{QualityGateProvider, QualityPolicy};
151pub use structured_output::{request_structured_output, StructuredOutputRequest};
152
153// Tool simulation re-exports
154pub use tool_simulation::{
155    execute_with_text_tools, format_tool_results_as_text, generate_tool_catalog,
156    inject_tool_catalog, parse_tool_call_blocks, strip_tool_call_blocks, FunctionCall,
157    FunctionDeclaration, FunctionResponse, TextToolHandler, TextToolResponse,
158};
159
160// Copilot SDK re-exports (behind feature flag)
161#[cfg(feature = "copilot-sdk")]
162pub use copilot_sdk_config::CopilotSdkConfig;
163#[cfg(feature = "copilot-sdk")]
164pub use copilot_sdk_runner::{CopilotSdkRunner, SdkToolResponse};
165#[cfg(feature = "copilot-sdk")]
166pub use tool_bridge::{convert_function_declarations, extract_declarations_from_tool_value};
167
168// Re-export copilot-sdk types so consumers don't need a direct dependency
169#[cfg(feature = "copilot-sdk")]
170pub use copilot_sdk::{Tool as SdkTool, ToolHandler, ToolResultObject};
embacle/lib.rs

embacle/
lib.rs
