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/// Shared base struct and macro for CLI runner boilerplate
75pub mod cli_common;
76/// Cline CLI runner
77pub mod cline_cli;
78/// Codex CLI runner
79pub mod codex_cli;
80/// Version compatibility and capability detection
81pub mod compat;
82/// Shared configuration types for CLI runners
83pub mod config;
84/// Container-based execution backend
85pub mod container;
86/// Continue CLI runner
87pub mod continue_cli;
88/// GitHub Copilot CLI runner
89pub mod copilot;
90/// Cursor Agent CLI runner
91pub mod cursor_agent;
92/// Binary auto-detection and discovery
93pub mod discovery;
94/// Provider fallback chains
95pub mod fallback;
96/// Gemini CLI runner
97pub mod gemini_cli;
98/// Goose CLI runner
99pub mod goose_cli;
100/// MCP tool definition to text-tool-simulation bridge
101pub mod mcp_tool_bridge;
102/// Cost/latency normalization decorator
103pub mod metrics;
104/// `OpenCode` CLI runner
105pub mod opencode;
106/// Subprocess spawning with safety limits
107pub mod process;
108/// Prompt construction from `ChatMessage` sequences
109pub mod prompt;
110/// Response quality validation with retry
111pub mod quality_gate;
112/// Environment sandboxing and tool policy
113pub mod sandbox;
114/// Stream wrapper for child process lifecycle management
115pub mod stream;
116/// Schema-enforced JSON output from any provider
117pub mod structured_output;
118/// Text-based tool simulation for CLI runners without native function calling
119pub mod tool_simulation;
120
121// Copilot SDK modules (behind feature flag)
122/// Configuration for the Copilot SDK provider
123#[cfg(feature = "copilot-sdk")]
124pub mod copilot_sdk_config;
125/// GitHub Copilot SDK runner (persistent JSON-RPC server)
126#[cfg(feature = "copilot-sdk")]
127pub mod copilot_sdk_runner;
128/// Tool definition conversion for Copilot SDK native tool calling
129#[cfg(feature = "copilot-sdk")]
130pub mod tool_bridge;
131
132// Re-export the runner structs for ergonomic access
133pub use agent::{AgentExecutor, AgentResult, OnTurnCallback, TurnInfo};
134pub use auth::ProviderReadiness;
135pub use capability_guard::validate_capabilities;
136pub use claude_code::ClaudeCodeRunner;
137pub use cli_common::CliRunnerBase;
138pub use cline_cli::ClineCliRunner;
139pub use codex_cli::CodexCliRunner;
140pub use compat::CliCapabilities;
141pub use config::{CliRunnerType, RunnerConfig};
142pub use container::{ContainerConfig, ContainerExecutor, NetworkMode};
143pub use continue_cli::ContinueCliRunner;
144pub use copilot::{copilot_fallback_models, discover_copilot_models, CopilotRunner};
145pub use cursor_agent::CursorAgentRunner;
146pub use discovery::{discover_runner, resolve_binary};
147pub use fallback::FallbackProvider;
148pub use gemini_cli::GeminiCliRunner;
149pub use goose_cli::GooseCliRunner;
150pub use mcp_tool_bridge::{McpToolDefinition, McpToolExecutor};
151pub use metrics::{MetricsProvider, MetricsReport};
152pub use opencode::OpenCodeRunner;
153pub use quality_gate::{QualityGateProvider, QualityPolicy};
154pub use structured_output::{request_structured_output, StructuredOutputRequest};
155
156// Tool simulation re-exports
157pub use tool_simulation::{
158    execute_with_text_tools, format_tool_results_as_text, generate_tool_catalog,
159    inject_tool_catalog, parse_tool_call_blocks, strip_tool_call_blocks, FunctionCall,
160    FunctionDeclaration, FunctionResponse, TextToolHandler, TextToolResponse,
161};
162
163// Copilot SDK re-exports (behind feature flag)
164#[cfg(feature = "copilot-sdk")]
165pub use copilot_sdk_config::CopilotSdkConfig;
166#[cfg(feature = "copilot-sdk")]
167pub use copilot_sdk_runner::{CopilotSdkRunner, SdkToolResponse};
168#[cfg(feature = "copilot-sdk")]
169pub use tool_bridge::{convert_function_declarations, extract_declarations_from_tool_value};
170
171// Re-export copilot-sdk types so consumers don't need a direct dependency
172#[cfg(feature = "copilot-sdk")]
173pub use copilot_sdk::{Tool as SdkTool, ToolHandler, ToolResultObject};
embacle/lib.rs

embacle/
lib.rs
