Crate klieo

Expand description

klieo — open-source Rust agent framework.

This umbrella crate re-exports klieo_core unconditionally and exposes each implementation crate behind a Cargo feature flag so users can start with just the trait surfaces and opt into concrete implementations one at a time.

§Quickstart

Add to Cargo.toml:

[dependencies]
klieo = { version = "1", features = ["all-foundation"] }

Then build an agent:

use klieo::{RunOptions, Error};
let opts = RunOptions::default();
let _ = opts;

§Feature flags

§Foundation

Feature	Crate enabled
(none)	`klieo-core` trait surfaces only
`tools`	`klieo-tools` — `ChainedInvoker`, schema validation
`macros`	`klieo-macros` — `#[tool]` proc-macro
`llm-ollama`	`klieo-llm-ollama` — Ollama HTTP client
`memory-sqlite`	`klieo-memory-sqlite` — SQLite-backed memory
`bus-memory`	`klieo-bus-memory` — in-process bus
`bus-nats`	`klieo-bus-nats` — NATS JetStream bus
`mcp`	`klieo-tools-mcp` — MCP adapter (implies `tools`)
`all-foundation`	All foundation features above

§LLM providers

Feature	Crate enabled
`llm-openai`	`klieo-llm-openai`
`llm-anthropic`	`klieo-llm-anthropic`
`llm-gemini`	`klieo-llm-gemini` (Google Gemini)
`all-llm`	All LLM providers (incl. Ollama)

§Memory backends

Feature	Crate enabled
`memory-neo4j`	`klieo-memory-neo4j`
`memory-qdrant`	`klieo-memory-qdrant`
`embed-common`	`klieo-embed-common` — shared `Embedder` trait
`memory-fastembed`	`memory-sqlite` + real CPU embeddings
`memory-sqlite-vec`	`memory-sqlite` + k-NN sqlite-vec index
`all-memory`	All memory backends (incl. GraphRAG cluster)

§GraphRAG cluster

Stable at 1.x per ADR-039.

Feature	Crate enabled
`memory-graph`	`klieo-memory-graph` — `KnowledgeGraph` trait + `InMemoryGraph`
`memory-graph-neo4j`	`klieo-memory-graph-neo4j` — Neo4j-backed `KnowledgeGraph` (implies `memory-graph` + `memory-neo4j`)
`memory-graph-rag`	`klieo-memory-graph-rag` — graph-first RAG composer (implies `memory-graph` + `memory-qdrant`)
`graph-projector`	`klieo-graph-projector` — Episode→Graph projector (implies `memory-graph`)

§Composition + protocol

Feature	Crate enabled
`flows`	`klieo-flows` — Sequential/Parallel/Loop/Graph
`workflow`	`klieo-workflow` — declarative no-code workflow substrate
`a2a`	`klieo-a2a` — durable Agent-to-Agent v1.0
`spec`	`klieo-spec` — quality-loop runner
`hitl`	`klieo-hitl` — human-in-the-loop review gate

§Observability + provenance

Feature	Crate enabled
`runlog`	`klieo-runlog` — RunLog projection + replay
`runlog-sqlite`	`runlog` + SQLite store
`runlog-compaction-llm`	`runlog` + LLM-summarise compaction
`provenance`	`klieo-provenance` — Merkle hash chain
`otel`	`klieo-otel` — OpenTelemetry OTLP exporter
`all-observability`	`runlog` + `provenance` + `otel`

§Aggregates

Feature	Enables
`full`	Every impl crate — heavy build, for integration tests
`test-utils`	`klieo-core/test-utils` for downstream test deps

Re-exports§

pub use app::App;
pub use app::AppBuilder;
pub use recall_recorder::RecallRecorder;
pub use graph_rag::ExtractorMode;
pub use graph_rag::GraphRagConfig;
pub use bytes;

Modules§

a2a: Durable Agent-to-Agent v1.0 protocol layer.
agent: Re-exports every public item from klieo-core. Agent trait and AgentContext.
app: Fluent assembler that collapses the 13-field AgentContext into a one-call wiring surface. See App for the entry point. App — fluent assembler that collapses the 13-field AgentContext into a one-call wiring surface.
auth_oauth: OAuth 2.0 bearer-token Authenticator for klieo HTTP transports.
bus: Re-exports every public item from klieo-core. Inter-agent bus traits — Pubsub, RequestReply, KvStore, JobQueue.
bus_memory: In-process bus: bus_memory::MemoryBus.
bus_nats: NATS JetStream bus: bus_nats::NatsBus, bus_nats::NatsBusConfig.
cancel: Re-exports every public item from klieo-core. Per-replica registry of in-flight cancellation tokens.
checkpoint: Re-exports every public item from klieo-core. Durable continuation state for a suspended run (ADR-045).
embed_common: Shared Embedder trait + dummy/fake impls.
error: Re-exports every public item from klieo-core. Error types used across klieo-core.
eval: Recall-quality metrics — hit_rate, MRR, precision@k, recall@k, NDCG@k — for klieo memory pipelines.
flows: Multi-agent composition shapes: Sequential / Parallel / Loop / Graph.
graph_projector: Episode-to-knowledge-graph projector bridge.
graph_rag: One-line GraphRAG facade configuration — graph_rag::GraphRagConfig.
guardrail: Re-exports every public item from klieo-core. Pre/post-LLM validation hooks for refuse + handoff workflows.
hitl: Durable human-in-the-loop run driver — suspend a run for operator approval, resume on decision (ADR-045).
ids: Re-exports every public item from klieo-core. Strongly-typed IDs used throughout the framework.
leader: Re-exports every public item from klieo-core. Per-replica leader claim + liveness probe for orphan detection.
llm: Ollama LLM client: llm::OllamaClient.
llm_anthropic: Anthropic Messages client.
llm_gemini: Google Gemini client.
llm_openai: OpenAI Chat Completions client.
macros: Procedural macros: the #[macros::tool] attribute.
mcp: MCP adapter: mcp::McpToolset, mcp::StdioConnectOptions.
mcp_server: MCP server: publish this process’s tools to MCP clients via mcp_server::McpServer. Pairs with App::serve_mcp_stdio.
memory: Re-exports every public item from klieo-core. Memory traits — short-term, long-term, episodic.
memory_graph: GraphRAG trait surface — KnowledgeGraph, FilterableLongTermMemory, EntityExtractor, EntityRef, EntityType, RecallMetrics, InMemoryGraph, known_epoch.
memory_graph_neo4j: Neo4j-backed KnowledgeGraph impl: Neo4jKnowledgeGraph, ScopedQuery.
memory_graph_rag: Graph-first RAG composer: GraphAwareLongTerm + extractors + KnowledgeIngestionPipeline + ImportSource.
memory_neo4j: Neo4j-backed memory: short-term + episodic.
memory_qdrant: Qdrant-backed long-term memory (vector recall).
memory_sqlite: SQLite-backed memory: memory_sqlite::MemorySqlite, memory_sqlite::DummyEmbedder.
observability: Re-exports every public item from klieo-core. Cluster-0.23 observability primitives — PII-safe principal hashing + helpers for span attribute construction.
otel: OpenTelemetry OTLP exporter wired to tracing spans.
prelude: Common imports for klieo agent authors.
profile: Re-exports every public item from klieo-core. Deployment posture profiles that bundle several fail-open guards into a single fail-closed opt-in. See ADR-022 (tenant binding).
provenance: Append-only Merkle hash chain + signed evidence bundles.
rate_limit: Re-exports every public item from klieo-core. Client-side token-bucket rate limiter for any LlmClient.
reaper: Re-exports every public item from klieo-core. Background task that periodically evicts orphaned entries from cluster-0.20’s klieo-leaders and cluster-0.22’s klieo-tenants KV buckets.
recall_recorder: Recall-recording wrapper that redacts and length-bounds GraphRAG recall queries before they reach durable episodic storage. See RecallRecorder for the entry point. Recall-recording wrapper for LongTermMemory.
redact: Re-exports every public item from klieo-core. Audit-redaction port and the fail-closed opaque-digest fallback.
response: Re-exports every public item from klieo-core. Typed structured-output trait + parser.
resume: Re-exports every public item from klieo-core. Per-stream SSE event buffer used by HTTP/SSE transports for resumption via Last-Event-ID / klieo/tools/resume.
runlog: Tier 2 observability — RunLog projection + replay engine.
runtime: Re-exports every public item from klieo-core. Runtime loop driving an crate::agent::Agent through LLM ↔ tool exchanges.
server_outbound: Re-exports every public item from klieo-core. Server-initiated outbound JSON-RPC primitive — transport-agnostic.
spec: Generic decompose / critique / refine traits + QualityLoop runner.
summarize: Re-exports every public item from klieo-core. Rolling LLM-summary checkpoint for bounding conversation context cost.
tenants: Re-exports every public item from klieo-core. Per-stream ownership claim backed by a dedicated KV bucket.
test_utils: Re-exported klieo_core::test_utils (in-memory fakes for the memory traits, fake LLM client, fake tool invoker).
tool: Re-exports every public item from klieo-core. Tool trait, invoker, and tool context.
tools: Tool dispatch: tools::ChainedInvoker, tools::validate_args.
viz: Embeddable agent-flow visualizer — mount viz::VizRouterBuilder::build in your app’s axum server over your own EpisodicMemory / RunLogStore to see runs, the cross-run flow canvas, per-step detail + cost, and live updates.
workflow: Declarative no-code workflow substrate: lower a WorkflowDef (authored as data) into a runnable flow via workflow::compile.

Structs§

AckHandle: Re-exports every public item from klieo-core. Acknowledgement handle attached to a delivered Msg.
AgentContext: Re-exports every public item from klieo-core. Borrow-free agent execution context. Holds Arc<dyn …> so it can be cloned freely across tokio::spawn boundaries ('static requirement).
AgentContextBuilder: Re-exports every public item from klieo-core. Fluent builder for AgentContext.
BusHandles: Re-exports every public item from klieo-core. Resolved bundle of bus handles ready to drop into an crate::agent::AgentContext or an App.
CancelRegistry: Re-exports every public item from klieo-core. Per-replica registry mapping in-flight stream ids to their CancellationToken. Cloning the registry yields a handle that shares the same underlying map, so the wildcard cancel-subject subscription task and the invoke-handling task can both hold one.
Capabilities: Re-exports every public item from klieo-core. Provider capability declaration.
CapabilitiesBuilder: Re-exports every public item from klieo-core. Fluent builder for Capabilities. Build via Capabilities::builder.
ChatChunk: Re-exports every public item from klieo-core. One chunk of a streaming response.
ChatRequest: Re-exports every public item from klieo-core. Chat completion request.
ChatResponse: Re-exports every public item from klieo-core. Chat completion response.
CheckpointGcHandle: Re-exports every public item from klieo-core. Handle for the spawned checkpoint-GC task; its Drop aborts the task.
ClaimHandle: Re-exports every public item from klieo-core. Handle the impl uses to resolve a claim.
ClaimedJob: Re-exports every public item from klieo-core. Job claimed by a worker.
DurableName: Re-exports every public item from klieo-core. Durable consumer name for a JetStream-style subscription.
Fact: Re-exports every public item from klieo-core. One stored fact in long-term memory.
FactId: Re-exports every public item from klieo-core. Identifier for a stored fact in LongTermMemory.
Job: Re-exports every public item from klieo-core. Job enqueued for durable processing.
JobId: Re-exports every public item from klieo-core. Identifier for an enqueued job in JobQueue.
KeyPage: Re-exports every public item from klieo-core. One page of bucket keys plus an opaque cursor for the next page.
KvEntry: Re-exports every public item from klieo-core. One KV entry.
KvReaperHandle: Re-exports every public item from klieo-core. Per-server reaper handle. Drop aborts the scan task.
LeaderEntry: Re-exports every public item from klieo-core. Persisted leader claim envelope.
LeaderHandle: Re-exports every public item from klieo-core. Drop-guard for a leader claim. Aborts the internal heartbeat task + spawns a best-effort delete of the KV key. Operators that need synchronous cleanup should drop early and let the spawned delete settle (a few KV round-trips at most).
LeaderRegistry: Re-exports every public item from klieo-core. Per-replica leader claim handle. Backed by a KvStore bucket dedicated to leader entries; both transports share one bucket keyed by {kind}.{id} (e.g. a2a.t-1, mcp.tok-1).
Lease: Re-exports every public item from klieo-core. Lease handle. Heartbeat to extend; drop to release.
MaxResponseLengthGuardrail: Re-exports every public item from klieo-core. Refuses if the assistant response content is longer than max_chars characters.
MemoryHandles: Re-exports every public item from klieo-core. Resolved trio of memory handles ready to drop into an crate::agent::AgentContext or an App.
Message: Re-exports every public item from klieo-core. One message in a chat conversation.
Msg: Re-exports every public item from klieo-core. One message delivered to a subscriber.
Neo4jConfig: Neo4j connection config for GraphRagConfig::remote, re-exported so callers configure the remote backend through klieo without taking a direct dependency on the klieo-memory-neo4j adapter crate. Configuration for MemoryNeo4j.
NeverReview: Re-exports every public item from klieo-core. The additive default: existing RunOptions callers keep their prior non-pausing behaviour without opting into HITL.
OwnershipHandle: Re-exports every public item from klieo-core. Drop-guard for an ownership claim. Spawns a best-effort kv.delete on Drop; runtime guard mirrors crate::LeaderHandle from cluster 0.20 — degrades to warn-log when no tokio runtime is active during Drop (synchronous shutdown paths).
OwnershipRegistry: Re-exports every public item from klieo-core. Per-replica ownership registry. Stores {stream_id} -> principal mappings in a dedicated KV bucket (typically klieo-tenants).
QdrantConfig: Qdrant connection config — re-exported at the crate root so callers configuring AppBuilder::qdrant_with reach it as klieo::QdrantConfig without a direct dependency on the klieo-memory-qdrant adapter crate.
RefusalKeywordGuardrail: Re-exports every public item from klieo-core. Refuses if any deny-keyword (case-insensitive) appears in the outgoing user message or the assistant response content.
RunCheckpoint: Re-exports every public item from klieo-core. Minimal state required to resume a suspended run. Excludes the Agent (its Arc<dyn _> ports are not serializable) — only the conversation and the tool calls awaiting approval are captured.
RunFilter: Re-exports every public item from klieo-core. Filter passed to EpisodicMemory::list_runs.
RunId: Re-exports every public item from klieo-core. Unique identifier for a single agent run.
RunOptions: Re-exports every public item from klieo-core. Tunables for super::run_steps and super::run_steps_streaming.
RunSummary: Re-exports every public item from klieo-core. Index-row summary returned by list_runs.
SimpleAgent: Re-exports every public item from klieo-core. Canonical Agent implementation for the String → String case.
SummarizeOptions: Re-exports every public item from klieo-core. Tunables for summarize_history.
ThreadId: Re-exports every public item from klieo-core. Identifies a conversation thread for short-term memory scoping.
ToolCall: Re-exports every public item from klieo-core. One tool call requested by the assistant.
ToolCtx: Re-exports every public item from klieo-core. Narrowed slice of AgentContext (see agent.rs) passed to tools.
ToolDef: Re-exports every public item from klieo-core. Tool catalogue entry shown to the LLM.
Usage: Re-exports every public item from klieo-core. Token usage report.

Enums§

AgentContextBuilderError: Re-exports every public item from klieo-core. Error returned when a required field is missing from AgentContextBuilder.
AgentEvent: Re-exports every public item from klieo-core. Step-level event emitted by the runtime during Agent::run. Wire shape is transport-agnostic; MCP HTTP maps each variant to a notifications/progress JSON-RPC notification.
ApprovalDecision: Re-exports every public item from klieo-core. Operator decision delivered to resume_from_checkpoint.
BusError: Re-exports every public item from klieo-core. Inter-agent bus errors.
ConfigError: Re-exports every public item from klieo-core. Configuration validation errors.
DeploymentProfile: Re-exports every public item from klieo-core. Bundles several individually-opt-in tenant-isolation guards into one fail-closed posture. The default (Unprofiled) leaves each guard’s fail-open default in place (ADR-022 partial-deployment posture); RegulatedMultiTenant flips them closed and refuses to build if a prerequisite is missing.
Episode: Re-exports every public item from klieo-core. One event in the episodic event stream of a single agent run.
Error: Re-exports every public item from klieo-core. Top-level error returned by klieo-core runtime calls.
FinishReason: Re-exports every public item from klieo-core. Reason the provider stopped generating.
GuardrailOutcome: Re-exports every public item from klieo-core. Validator outcome returned by Guardrail::pre_llm and Guardrail::post_llm.
LlmError: Re-exports every public item from klieo-core. LLM provider errors.
MemoryError: Re-exports every public item from klieo-core. Memory persistence errors.
OwnershipCheck: Re-exports every public item from klieo-core. Verdict of OwnershipRegistry::check_owner for an enforcement gate, with the fail-open/closed policy already applied so every transport resolves a store error the same way.
OwnershipClaim: Re-exports every public item from klieo-core. Outcome of OwnershipRegistry::claim_guarded at a stream-open gate, with the fail-open/closed policy already applied so neither transport re-derives it. (No Debug — OwnershipHandle wraps a non-Debug Arc<dyn KvStore>.)
OwnershipRecord: Re-exports every public item from klieo-core. Outcome of OwnershipRegistry::record_owner — a persistent ownership claim for a task whose lifetime outlives the request that created it (a non-streaming invoke), with the fail-open/closed policy already applied.
ProfileViolation: Re-exports every public item from klieo-core. A way a builder’s configuration fails to satisfy its DeploymentProfile. Transports wrap this in their own build-error type.
ResponseFormat: Re-exports every public item from klieo-core. Output format hint passed to the provider.
Role: Re-exports every public item from klieo-core. Speaker role.
Scope: Re-exports every public item from klieo-core. Namespacing for long-term memory facts.
ServerOutboundError: Re-exports every public item from klieo-core. Failure modes for a ServerOutbound::outbound_request call.
ToolError: Re-exports every public item from klieo-core. Tool invocation errors.
ToolResult: Re-exports every public item from klieo-core. Outcome of a tool invocation as recorded in the episodic event stream.

Constants§

CHECKPOINT_BUCKET: Re-exports every public item from klieo-core. Bucket under which suspended-run checkpoints persist in KvStore.
FAILOVER_ATTEMPT_CAP: Re-exports every public item from klieo-core. Hard cap on the number of failover re-invoke attempts per stream.

Traits§

AckHandleImpl: Re-exports every public item from klieo-core. Implementor side of an ack handle. Exposed so impls can supply backend behaviour without callers reaching into private types.
Agent: Re-exports every public item from klieo-core. One agent — a typed function from Input to Output plus prompt configuration.
AuditRedactor: Re-exports every public item from klieo-core. Injectable redaction port.
ClaimHandleImpl: Re-exports every public item from klieo-core. Implementor side of a claim handle.
EpisodicMemory: Re-exports every public item from klieo-core. Append-only event log of agent runs.
Guardrail: Re-exports every public item from klieo-core. Pre/post-LLM validator. Implementors decide whether to allow, refuse, or hand off based on the outgoing request and incoming response.
JobQueue: Re-exports every public item from klieo-core. Durable competing-consumer job queue. No ordering guarantee — workloads requiring order must use Pubsub on a partitioned subject with one consumer per partition instead.
KlieoResponse: Re-exports every public item from klieo-core. Trait implemented by types that can be parsed from a structured LLM response.
KvStore: Re-exports every public item from klieo-core. Bucket-keyed durable KV store with CAS.
LeaseImpl: Re-exports every public item from klieo-core. Implementor side of a lease.
LlmClient: Re-exports every public item from klieo-core. LLM provider trait.
LongTermMemory: Re-exports every public item from klieo-core. Long-term semantic memory.
Pubsub: Re-exports every public item from klieo-core. Pub/sub interface (subject-based, durable consumers).
RequestReply: Re-exports every public item from klieo-core. Synchronous request/response over the bus.
ReviewPolicy: Re-exports every public item from klieo-core. Decides whether a run must pause for human approval after an LLM step, before its tool calls are dispatched. Ok(None) proceeds; Ok(Some(reason)) suspends the run with reason recorded on the checkpoint.
ServerOutbound: Re-exports every public item from klieo-core. Transport-agnostic surface for issuing a JSON-RPC request from the server back to its peer.
ShortTermMemory: Re-exports every public item from klieo-core. Conversation buffer scoped to a single thread.
Tool: Re-exports every public item from klieo-core. One executable tool.
ToolInvoker: Re-exports every public item from klieo-core. Dispatches tool calls by name.

Functions§

extract_traceparent: Re-exports every public item from klieo-core. Extract a W3C tracecontext from headers. Returns the default empty Context when no headers are set; callers should set the result as the parent of subsequent spans only if they care about cross-replica stitching.
gc_checkpoints: Re-exports every public item from klieo-core. Reap abandoned suspended-run checkpoints, returning the count deleted. An entry whose created_at is at or before cutoff is removed; the bound is inclusive. Best-effort throughout: a checkpoint that fails to read or deserialize, or whose delete fails, is logged and skipped so one bad entry never stalls the sweep. The cutoff is typically Utc::now() - ttl.
inject_traceparent: Re-exports every public item from klieo-core. Inject the current OpenTelemetry context’s tracecontext into headers under the standard W3C keys (traceparent, optionally tracestate).
opaque_digest: Re-exports every public item from klieo-core. Fail-closed total-opacity fallback used when no AuditRedactor is wired on a redaction-flagged tool.
parse_structured: Re-exports every public item from klieo-core. Parse an LLM reply (raw text content) into a typed T.
principal_hash: Re-exports every public item from klieo-core. PII-safe principal identifier for span attributes.
resume_from_checkpoint: Re-exports every public item from klieo-core. Resume a run suspended via the review gate (ADR-045).
run_steps: Re-exports every public item from klieo-core. Drive the agent’s LLM/tool loop until completion. Caller is responsible for appending the user message before invoking — this function only consumes / extends short-term memory.
run_steps_streaming: Re-exports every public item from klieo-core. Drive the agent’s LLM/tool loop the same way super::run_steps does, but expose the underlying provider chunks as they arrive.
spawn_checkpoint_gc: Re-exports every public item from klieo-core. Spawn the opt-in background task that reaps abandoned suspended-run checkpoints every interval, deleting any older than ttl. Key the ttl to the review-item timeout SLA so a checkpoint never outlives the review it backs (ADR-045 item 7) — without it, abandoned suspensions leak KvStore entries forever. Memory-bounded via gc_checkpoints (page-walk, one checkpoint resident at a time). A ttl too large to represent skips that sweep rather than reaping everything. Returns a CheckpointGcHandle whose Drop aborts the task.
spawn_kv_reaper: Re-exports every public item from klieo-core. Spawn a reaper task that scans buckets every interval and evicts entries whose corresponding resume buffer is terminal.
summarize_history: Re-exports every public item from klieo-core. Run a rolling summarization checkpoint against the thread’s short-term history.
validate_subject_token: Re-exports every public item from klieo-core. Validate that token is safe to embed as a single NATS subject segment.

Type Aliases§

ChunkStream: Re-exports every public item from klieo-core. Streaming response handle.
Embedding: Re-exports every public item from klieo-core. Vector embedding for one input text.
Headers: Re-exports every public item from klieo-core. Opaque headers accompanying a bus message.
MsgStream: Re-exports every public item from klieo-core. Stream of messages delivered to a subscriber.
Revision: Re-exports every public item from klieo-core. CAS revision returned by KV writes.
SecretString: Re-exported secrecy::SecretString. Activated by the secrecy feature, which bus-nats, llm-anthropic, llm-openai, llm-genai, memory-neo4j, and memory-qdrant auto-enable.

Attribute Macros§

tool: Re-export of the #[tool] attribute at crate root so #[klieo::tool(...)] works without an extra use. The full klieo::macros::tool path remains valid. Turn an async fn into a klieo_core::Tool implementation.

Derive Macros§

KlieoResponse: Re-export of the #[derive(KlieoResponse)] derive at crate root so #[derive(klieo::KlieoResponse)] works without an extra use. Derive klieo_core::KlieoResponse for a struct so it can be the typed payload of a structured LLM response.

Crate klieo

Crate klieo Copy item path

§Quickstart

§Feature flags

§Foundation

§LLM providers

§Memory backends

§GraphRAG cluster

§Composition + protocol

§Observability + provenance

§Aggregates

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Attribute Macros§

Derive Macros§

Crate klieo