Skip to main content

Crate zeph_core

Crate zeph_core 

Source
Expand description

Zeph core agent: multi-model inference, semantic memory, skills orchestration, and tool execution.

This crate provides the Agent struct — the autonomous AI system at the heart of Zeph. It integrates LLM providers (Claude, OpenAI, Ollama, Candle), semantic memory (Qdrant), skill registry and matching, tool execution (shell, web, custom), MCP client support, and security/compliance subsystems into a single composable agent framework.

§Usage

The main entry point is Agent::new or Agent::new_with_registry_arc. After creating an agent, call Agent::run to execute the main loop. Always call Agent::shutdown before dropping to persist state.

See the bootstrap module in the zeph binary crate for config loading and provider setup examples.

§Key Components

  • Agent — Main struct that runs the agent loop
  • Channel — Abstraction for user interaction (send/receive messages and events)
  • channel::ChannelMessage — Structured messages flowing to/from the user
  • config — Configuration schema (LLM providers, memory, skills, etc.)
  • agent::session_config — Per-session configuration (budget, timeouts, etc.)
  • agent::context — Context assembly and token budgeting utilities
  • pipeline — Structured execution pipelines for complex workflows
  • project — Project indexing and semantic retrieval
  • memory_tools — Memory search and management utilities

Note: The bootstrap module (AppBuilder, provider setup, etc.) lives in the zeph binary crate.

§Architecture

The agent operates as a single-turn finite state machine that processes each user message through a series of stages:

  1. Input — Receive user message via channel
  2. Context assembly — Build prompt from conversation history, memory, and skills
  3. LLM inference — Call the model with multi-tool calling support
  4. Tool execution — Run tool calls concurrently with streaming output
  5. Feedback loop — Feed tool results back to LLM for synthesis
  6. Output — Send agent response via channel
  7. Persistence — Save messages and state (async, deferred)

All async operations (await points) are bounded with timeouts to prevent stalls.

§Channel Contract

Implementing the Channel trait allows the agent to integrate with any I/O system:

  • CLI — cargo run -- --config config.toml
  • Telegram — Bot interface with streaming updates
  • TUI — Multi-panel dashboard with real-time metrics
  • HTTP gateway — Webhook ingestion and agent event streaming
  • Custom — Implement Channel for domain-specific systems

§Feature Flags

  • candle — Local inference via Candle (default off, requires CUDA/Metal)
  • classifiers — ML-based content classification and trust scoring
  • metal — Candle with Metal acceleration (macOS)
  • cuda — Candle with CUDA acceleration (Linux/Windows)
  • scheduler — Cron-based periodic task scheduler

Re-exports§

pub use agent::Agent;
pub use agent::error::AgentError;
pub use agent::session_config::AgentSessionConfig;
pub use agent::session_config::CONTEXT_BUDGET_RESERVE_RATIO;
pub use channel::Attachment;
pub use channel::AttachmentKind;
pub use channel::Channel;
pub use channel::ChannelError;
pub use channel::ChannelMessage;
pub use channel::LoopbackChannel;
pub use channel::LoopbackEvent;
pub use channel::LoopbackHandle;
pub use channel::StopHint;
pub use channel::ToolOutputData;
pub use channel::ToolOutputEvent;
pub use channel::ToolStartData;
pub use channel::ToolStartEvent;
pub use skill_loader::SkillLoaderExecutor;

Modules§

agent
channel
config
Extension trait for resolving vault secrets into a Config.
config_watcher
context
cost
daemon
Daemon supervisor for component lifecycle management.
debug_dump
Debug dump writer for a single agent session.
file_watcher
http
Shared HTTP client construction for consistent timeout and TLS configuration.
instructions
instrumented_channel
Instrumented wrappers around tokio channels.
lsp_hooks
LSP context injection hooks.
memory_tools
metrics
overflow_tools
pipeline
project
provider_factory
Pure provider factory helpers: build AnyProvider instances from config entries.
redact
runtime_layer
RuntimeLayer trait: middleware hooks for LLM calls and tool dispatch (#2286).
skill_loader
text
String utility functions for Unicode-safe text manipulation.
vault

Structs§

AdversarialPolicyInfo
Snapshot of adversarial policy gate configuration for status display.
Config
Top-level agent configuration.
ContentIsolationConfig
Configuration for the content isolation pipeline, nested under [security.content_isolation] in the agent config file.
ContentSanitizer
Stateless pipeline that sanitizes untrusted content before it enters the LLM context.
ContentSource
Provenance metadata attached to a piece of untrusted content.
DiffData
Data for rendering file diffs in the TUI.
ExfiltrationGuard
Stateless exfiltration guard covering three outbound leak vectors.
ExfiltrationGuardConfig
Configuration for exfiltration guards, nested under [security.exfiltration_guard] in the agent config file.
InjectionFlag
A single detected injection pattern match in sanitized content.
ProviderConfigSnapshot
Minimal config snapshot needed to reconstruct a provider at runtime via /provider <name>.
QuarantineConfig
Configuration for the quarantine summarizer, nested under [security.content_isolation.quarantine] in the agent config file.
SanitizedContent
Result of the sanitization pipeline for a single piece of content.

Enums§

ConfigError
Error type for configuration operations.
ContentSourceKind
All known content source categories.
ContentTrustLevel
Trust tier assigned to content entering the agent context.
ExfiltrationEvent
An exfiltration event detected by ExfiltrationGuard.

Functions§

content_hash
Returns the BLAKE3 hex digest of arbitrary bytes.
extract_flagged_urls
Extract all http/https URLs from content into a HashSet for later URL validation.