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_context;
94pub mod runtime_layer;
95pub mod skill_loader;
96pub mod task_supervisor;
97pub use zeph_common::text;
98
99#[cfg(test)]
100pub mod testing;
101
102pub use agent::Agent;
103pub use agent::error::AgentError;
104pub use agent::session_config::{AgentSessionConfig, CONTEXT_BUDGET_RESERVE_RATIO};
105pub use agent::state::AdversarialPolicyInfo;
106pub use agent::state::ProviderConfigSnapshot;
107pub use channel::{
108    Attachment, AttachmentKind, Channel, ChannelError, ChannelMessage, LoopbackChannel,
109    LoopbackEvent, LoopbackHandle, StopHint, ToolOutputData, ToolOutputEvent, ToolStartData,
110    ToolStartEvent,
111};
112pub use config::{Config, ConfigError};
113pub use runtime_context::RuntimeContext;
114pub use skill_loader::SkillLoaderExecutor;
115pub use task_supervisor::{
116    BlockingError, BlockingHandle, MAX_RESTART_DELAY, RestartPolicy, TaskDescriptor, TaskHandle,
117    TaskSnapshot, TaskStatus, TaskSupervisor,
118};
119pub use zeph_common::hash::blake3_hex as content_hash;
120pub use zeph_sanitizer::exfiltration::{
121    ExfiltrationEvent, ExfiltrationGuard, ExfiltrationGuardConfig, extract_flagged_urls,
122};
123pub use zeph_sanitizer::{
124    ContentIsolationConfig, ContentSanitizer, ContentSource, ContentSourceKind, ContentTrustLevel,
125    InjectionFlag, QuarantineConfig, SanitizedContent,
126};
127pub use zeph_tools::executor::DiffData;
128
129// Re-export vault module to preserve internal import paths (e.g., `crate::vault::VaultProvider`).
130pub mod vault {
131    pub use zeph_vault::{
132        AgeVaultError, AgeVaultProvider, ArcAgeVaultProvider, EnvVaultProvider, Secret, VaultError,
133        VaultProvider, default_vault_dir,
134    };
135
136    #[cfg(any(test, feature = "mock"))]
137    pub use zeph_vault::MockVaultProvider;
138}
zeph_core/lib.rs

zeph_core/
lib.rs
