zeph_core/
lib.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Zeph core agent: multi-model inference, semantic memory, skills orchestration, and tool execution.
5//!
6//! This crate provides the [`Agent`] struct — the autonomous AI system at the heart of Zeph.
7//! It integrates LLM providers (Claude, `OpenAI`, Ollama, Candle), semantic memory (Qdrant),
8//! skill registry and matching, tool execution (shell, web, custom), MCP client support, and
9//! security/compliance subsystems into a single composable agent framework.
10//!
11//! # Usage
12//!
13//! The main entry point is [`Agent::new`] or [`Agent::new_with_registry_arc`]. After creating
14//! an agent, call [`Agent::run`] to execute the main loop.
15//! Always call [`Agent::shutdown`] before dropping to persist state.
16//!
17//! See the `bootstrap` module in the `zeph` binary crate for config loading and provider setup examples.
18//!
19//! # Key Components
20//!
21//! - [`Agent`] — Main struct that runs the agent loop
22//! - [`Channel`] — Abstraction for user interaction (send/receive messages and events)
23//! - [`channel::ChannelMessage`] — Structured messages flowing to/from the user
24//! - `config` — Configuration schema (LLM providers, memory, skills, etc.)
25//! - `agent::session_config` — Per-session configuration (budget, timeouts, etc.)
26//! - `agent::context` — Context assembly and token budgeting utilities
27//! - [`pipeline`] — Structured execution pipelines for complex workflows
28//! - [`project`] — Project indexing and semantic retrieval
29//! - [`memory_tools`] — Memory search and management utilities
30//!
31//! Note: The `bootstrap` module (`AppBuilder`, provider setup, etc.) lives in the `zeph` binary crate.
32//!
33//! # Architecture
34//!
35//! The agent operates as a **single-turn finite state machine** that processes each user
36//! message through a series of stages:
37//!
38//! 1. **Input** — Receive user message via channel
39//! 2. **Context assembly** — Build prompt from conversation history, memory, and skills
40//! 3. **LLM inference** — Call the model with multi-tool calling support
41//! 4. **Tool execution** — Run tool calls concurrently with streaming output
42//! 5. **Feedback loop** — Feed tool results back to LLM for synthesis
43//! 6. **Output** — Send agent response via channel
44//! 7. **Persistence** — Save messages and state (async, deferred)
45//!
46//! All async operations (`await` points) are bounded with timeouts to prevent stalls.
47//!
48//! # Channel Contract
49//!
50//! Implementing the [`Channel`] trait allows the agent to integrate with any I/O system:
51//!
52//! - **CLI** — `cargo run -- --config config.toml`
53//! - **Telegram** — Bot interface with streaming updates
54//! - **TUI** — Multi-panel dashboard with real-time metrics
55//! - **HTTP gateway** — Webhook ingestion and agent event streaming
56//! - **Custom** — Implement [`Channel`] for domain-specific systems
57//!
58//! # Feature Flags
59//!
60//! - `candle` — Local inference via Candle (default off, requires CUDA/Metal)
61//! - `classifiers` — ML-based content classification and trust scoring
62//! - `metal` — Candle with Metal acceleration (macOS)
63//! - `cuda` — Candle with CUDA acceleration (Linux/Windows)
64//! - `scheduler` — Cron-based periodic task scheduler
65
66pub mod agent;
67#[cfg(feature = "profiling-alloc")]
68pub mod alloc_layer;
69pub mod channel;
70pub mod config;
71pub mod config_watcher;
72pub mod context;
73pub mod cost;
74pub mod daemon;
75pub mod debug_dump;
76pub mod file_watcher;
77pub mod instructions;
78pub mod instrumented_channel;
79pub mod metrics;
80#[cfg(feature = "profiling")]
81pub mod metrics_bridge;
82pub mod pipeline;
83pub mod project;
84pub mod provider_factory;
85pub mod redact;
86#[cfg(feature = "sysinfo")]
87pub mod system_metrics;
88
89pub mod http;
90pub mod lsp_hooks;
91pub mod memory_tools;
92pub mod overflow_tools;
93pub mod runtime_layer;
94pub mod skill_loader;
95pub use zeph_common::text;
96
97#[cfg(test)]
98pub mod testing;
99
100pub use agent::Agent;
101pub use agent::error::AgentError;
102pub use agent::session_config::{AgentSessionConfig, CONTEXT_BUDGET_RESERVE_RATIO};
103pub use agent::state::AdversarialPolicyInfo;
104pub use agent::state::ProviderConfigSnapshot;
105pub use channel::{
106    Attachment, AttachmentKind, Channel, ChannelError, ChannelMessage, LoopbackChannel,
107    LoopbackEvent, LoopbackHandle, StopHint, ToolOutputData, ToolOutputEvent, ToolStartData,
108    ToolStartEvent,
109};
110pub use config::{Config, ConfigError};
111pub use skill_loader::SkillLoaderExecutor;
112pub use zeph_common::hash::blake3_hex as content_hash;
113pub use zeph_sanitizer::exfiltration::{
114    ExfiltrationEvent, ExfiltrationGuard, ExfiltrationGuardConfig, extract_flagged_urls,
115};
116pub use zeph_sanitizer::{
117    ContentIsolationConfig, ContentSanitizer, ContentSource, ContentSourceKind, ContentTrustLevel,
118    InjectionFlag, QuarantineConfig, SanitizedContent,
119};
120pub use zeph_tools::executor::DiffData;
121
122// Re-export vault module to preserve internal import paths (e.g., `crate::vault::VaultProvider`).
123pub mod vault {
124    pub use zeph_vault::{
125        AgeVaultError, AgeVaultProvider, ArcAgeVaultProvider, EnvVaultProvider, Secret, VaultError,
126        VaultProvider, default_vault_dir,
127    };
128
129    #[cfg(any(test, feature = "mock"))]
130    pub use zeph_vault::MockVaultProvider;
131}
zeph_core/lib.rs

zeph_core/
lib.rs
