klieo 3.3.1

#![deny(missing_docs)]
#![deny(rust_2018_idioms)]
#![deny(rustdoc::broken_intra_doc_links)]

//! `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`:
//!
//! ```toml
//! [dependencies]
//! klieo = { version = "1", features = ["all-foundation"] }
//! ```
//!
//! Then build an agent:
//!
//! ```no_run
//! 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](https://github.com/mohrimic/klieo/blob/main/docs/adr/adr-039-graphrag-1-0-promotion.md).
//!
//! | 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 |

// ── core ──────────────────────────────────────────────────────────────────────

/// Re-exports every public item from `klieo-core`.
pub use klieo_core::*;

/// Re-exports the runtime crates that `klieo-macros`-emitted code
/// references via absolute paths. Marked `#[doc(hidden)]`: end-user
/// code should never reference these by hand.
///
/// The `#[klieo::tool]` proc-macro emits paths like
/// `::klieo::__private::klieo_core::__macro_support::Tool`, so
/// downstream crates need only `klieo` as a direct dependency —
/// `klieo-core` is no longer required in the user's `Cargo.toml`.
#[doc(hidden)]
pub mod __private {
    pub use klieo_core;

    // Gated behind `macros` so a non-`macros` downstream never links schemars.
    #[cfg(feature = "macros")]
    pub use {schemars, serde, serde_json};
}

/// Re-exported `klieo_core::test_utils` (in-memory fakes for the
/// memory traits, fake LLM client, fake tool invoker).
///
/// Enabled by the `test-utils` feature flag. The glob re-export
/// above transitively exposes this module, but an explicit `pub use`
/// pins the contract so future `klieo-core` reorganisations cannot
/// accidentally hide it from downstream consumers.
#[cfg(feature = "test-utils")]
pub use klieo_core::test_utils;

/// Common imports for klieo agent authors.
///
/// `use klieo::prelude::*;` brings in `Agent`, `AgentContext`,
/// `Error`, `LlmClient`, `Message`, `Role`, `RunId`, `ThreadId`,
/// `ToolDef`, `ToolInvoker`, `Tool`, `ToolCtx`, `Episode`,
/// `ToolResult`, `RunOptions`.
pub mod prelude;

/// Fluent assembler that collapses the 13-field `AgentContext` into
/// a one-call wiring surface. See [`App`] for the entry point.
pub mod app;
pub use app::{App, AppBuilder};

/// Recall-recording wrapper that redacts and length-bounds GraphRAG
/// recall queries before they reach durable episodic storage. See
/// [`RecallRecorder`] for the entry point.
pub mod recall_recorder;
pub use recall_recorder::RecallRecorder;

/// 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.
///
/// Downstream consumers that interact with any klieo crate accepting
/// credentials can `use klieo::SecretString;` instead of pinning the
/// `secrecy` crate directly — preventing version skew like the
/// 0.8 ↔ 0.10 incompatibility surfaced in adoption eval Plan 02.
#[cfg(feature = "secrecy")]
pub use secrecy::SecretString;

/// Re-exported `bytes` crate. Activated by the `bytes` feature,
/// which `bus-nats` auto-enables (klieo-bus-nats's `Job` payload is
/// `bytes::Bytes`).
#[cfg(feature = "bytes")]
pub use bytes;

// ── tools ─────────────────────────────────────────────────────────────────────

/// Tool dispatch: [`tools::ChainedInvoker`], [`tools::validate_args`].
///
/// Enabled by the `tools` feature flag.
#[cfg(feature = "tools")]
pub mod tools {
    pub use klieo_tools::*;
}

// ── macros ────────────────────────────────────────────────────────────────────

/// Procedural macros: the `#[macros::tool]` attribute.
///
/// Enabled by the `macros` feature flag.
#[cfg(feature = "macros")]
pub mod macros {
    pub use klieo_macros::*;
}

/// Re-export of the [`#[tool]`][macros::tool] attribute at crate root
/// so `#[klieo::tool(...)]` works without an extra `use`. The full
/// `klieo::macros::tool` path remains valid.
#[cfg(feature = "macros")]
pub use klieo_macros::tool;

/// Re-export of the [`#[derive(KlieoResponse)]`][macros::KlieoResponse]
/// derive at crate root so `#[derive(klieo::KlieoResponse)]` works
/// without an extra `use`.
#[cfg(feature = "macros")]
pub use klieo_macros::KlieoResponse;

// ── llm ───────────────────────────────────────────────────────────────────────

/// Ollama LLM client: [`llm::OllamaClient`].
///
/// Enabled by the `llm-ollama` feature flag.
///
/// For symmetric access alongside other providers, see
/// [`llm_openai`], [`llm_anthropic`], [`llm_gemini`].
#[cfg(feature = "llm-ollama")]
pub mod llm {
    pub use klieo_llm_ollama::*;
}

/// OpenAI Chat Completions client.
///
/// Enabled by the `llm-openai` feature flag.
#[cfg(feature = "llm-openai")]
pub mod llm_openai {
    pub use klieo_llm_openai::*;
}

/// Anthropic Messages client.
///
/// Enabled by the `llm-anthropic` feature flag.
#[cfg(feature = "llm-anthropic")]
pub mod llm_anthropic {
    pub use klieo_llm_anthropic::*;
}

/// Google Gemini client.
///
/// Enabled by the `llm-gemini` feature flag.
#[cfg(feature = "llm-gemini")]
pub mod llm_gemini {
    pub use klieo_llm_gemini::*;
}

// ── memory ────────────────────────────────────────────────────────────────────

/// SQLite-backed memory: [`memory_sqlite::MemorySqlite`], [`memory_sqlite::DummyEmbedder`].
///
/// Enabled by the `memory-sqlite` feature flag.
#[cfg(feature = "memory-sqlite")]
pub mod memory_sqlite {
    pub use klieo_memory_sqlite::*;
}

/// Neo4j-backed memory: short-term + episodic.
///
/// Enabled by the `memory-neo4j` feature flag.
#[cfg(feature = "memory-neo4j")]
pub mod memory_neo4j {
    pub use klieo_memory_neo4j::*;
}

/// Qdrant-backed long-term memory (vector recall).
///
/// Enabled by the `memory-qdrant` feature flag.
#[cfg(feature = "memory-qdrant")]
pub mod memory_qdrant {
    pub use klieo_memory_qdrant::*;
}

/// Qdrant connection config — re-exported at the crate root so callers
/// configuring [`AppBuilder::qdrant_with`](app::AppBuilder::qdrant_with)
/// reach it as `klieo::QdrantConfig` without a direct dependency on the
/// `klieo-memory-qdrant` adapter crate.
///
/// Enabled by the `memory-qdrant` feature flag.
#[cfg(feature = "memory-qdrant")]
pub use klieo_memory_qdrant::QdrantConfig;

/// Neo4j connection config — re-exported at the crate root so callers
/// configuring [`AppBuilder::neo4j_with`](app::AppBuilder::neo4j_with)
/// reach it as `klieo::Neo4jConfig`. Under the `graph-rag` feature the
/// same type is re-exported via the GraphRAG facade (see below); this
/// arm covers `memory-neo4j` without `graph-rag`.
#[cfg(all(feature = "memory-neo4j", not(feature = "graph-rag")))]
pub use klieo_memory_neo4j::Neo4jConfig;

/// Shared `Embedder` trait + dummy/fake impls.
///
/// Enabled by the `embed-common` feature flag.
#[cfg(feature = "embed-common")]
pub mod embed_common {
    pub use klieo_embed_common::*;
}

/// GraphRAG trait surface — `KnowledgeGraph`, `FilterableLongTermMemory`,
/// `EntityExtractor`, `EntityRef`, `EntityType`, `RecallMetrics`,
/// `InMemoryGraph`, `known_epoch`.
///
/// Enabled by the `memory-graph` feature flag. Stable at 1.0 per ADR-039.
#[cfg(feature = "memory-graph")]
pub mod memory_graph {
    pub use klieo_memory_graph::*;
}

/// Neo4j-backed `KnowledgeGraph` impl: `Neo4jKnowledgeGraph`, `ScopedQuery`.
///
/// Enabled by the `memory-graph-neo4j` feature flag (depends on
/// `memory-graph` and `memory-neo4j`).
#[cfg(feature = "memory-graph-neo4j")]
pub mod memory_graph_neo4j {
    pub use klieo_memory_graph_neo4j::*;
}

/// Graph-first RAG composer: `GraphAwareLongTerm` + extractors +
/// `KnowledgeIngestionPipeline` + `ImportSource`.
///
/// Enabled by the `memory-graph-rag` feature flag (depends on
/// `memory-graph` and `memory-qdrant`).
#[cfg(feature = "memory-graph-rag")]
pub mod memory_graph_rag {
    pub use klieo_memory_graph_rag::*;
}

/// Episode-to-knowledge-graph projector bridge.
///
/// Enabled by the `graph-projector` feature flag (depends on
/// `memory-graph`). Stable at 1.0 per ADR-039.
#[cfg(feature = "graph-projector")]
pub mod graph_projector {
    pub use klieo_graph_projector::*;
}

/// One-line GraphRAG facade configuration — [`graph_rag::GraphRagConfig`].
///
/// Enabled by the `graph-rag` feature flag. Aggregates the full GraphRAG
/// cluster (knowledge graph + vector recall + episode projector + provenance)
/// behind two constructors: [`graph_rag::GraphRagConfig::in_memory`] for
/// zero-infra dev and [`graph_rag::GraphRagConfig::remote`] for production.
#[cfg(feature = "graph-rag")]
pub mod graph_rag;

#[cfg(feature = "graph-rag")]
pub use graph_rag::{ExtractorMode, GraphRagConfig, Neo4jConfig};

// ── bus ───────────────────────────────────────────────────────────────────────

/// In-process bus: [`bus_memory::MemoryBus`].
///
/// Enabled by the `bus-memory` feature flag.
#[cfg(feature = "bus-memory")]
pub mod bus_memory {
    pub use klieo_bus_memory::*;
}

/// NATS JetStream bus: [`bus_nats::NatsBus`], [`bus_nats::NatsBusConfig`].
///
/// Enabled by the `bus-nats` feature flag.
#[cfg(feature = "bus-nats")]
pub mod bus_nats {
    pub use klieo_bus_nats::*;
}

// ── mcp ───────────────────────────────────────────────────────────────────────

/// MCP adapter: [`mcp::McpToolset`], [`mcp::StdioConnectOptions`].
///
/// Enabled by the `mcp` feature flag (implies `tools`).
#[cfg(feature = "mcp")]
pub mod mcp {
    pub use klieo_tools_mcp::*;
}

/// MCP server: publish this process's tools to MCP clients via
/// [`mcp_server::McpServer`]. Pairs with [`App::serve_mcp_stdio`].
///
/// Enabled by the `mcp-server` feature flag.
#[cfg(feature = "mcp-server")]
pub mod mcp_server {
    pub use klieo_mcp_server::*;
}

// ── composition + protocol ────────────────────────────────────────────────────

/// Multi-agent composition shapes: `Sequential` / `Parallel` / `Loop` / `Graph`.
///
/// Enabled by the `flows` feature flag.
#[cfg(feature = "flows")]
pub mod flows {
    pub use klieo_flows::*;
}

/// Declarative no-code workflow substrate: lower a `WorkflowDef` (authored
/// as data) into a runnable flow via [`workflow::compile`].
///
/// Enabled by the `workflow` feature flag.
#[cfg(feature = "workflow")]
pub mod workflow {
    pub use klieo_workflow::*;
}

/// Durable Agent-to-Agent v1.0 protocol layer.
///
/// Enabled by the `a2a` feature flag.
#[cfg(feature = "a2a")]
pub mod a2a {
    pub use klieo_a2a::*;
}

/// Generic decompose / critique / refine traits + `QualityLoop` runner.
///
/// Enabled by the `spec` feature flag.
#[cfg(feature = "spec")]
pub mod spec {
    pub use klieo_spec::*;
}

/// Recall-quality metrics — `hit_rate`, MRR, `precision@k`,
/// `recall@k`, `NDCG@k` — for klieo memory pipelines.
///
/// Enabled by the `eval` feature flag.
#[cfg(feature = "eval")]
pub mod eval {
    pub use klieo_eval::*;
}

/// Durable human-in-the-loop run driver — suspend a run for operator
/// approval, resume on decision (ADR-045).
///
/// Enabled by the `hitl` feature flag.
#[cfg(feature = "hitl")]
pub mod hitl {
    pub use klieo_hitl::*;
}

// ── auth ──────────────────────────────────────────────────────────────────────

/// OAuth 2.0 bearer-token Authenticator for klieo HTTP transports.
///
/// Enabled by the `oauth` feature flag.
#[cfg(feature = "oauth")]
pub mod auth_oauth {
    pub use klieo_auth_oauth::*;
}

// ── observability + provenance ────────────────────────────────────────────────

/// Tier 2 observability — RunLog projection + replay engine.
///
/// Enabled by the `runlog` feature flag.
#[cfg(feature = "runlog")]
pub mod runlog {
    pub use klieo_runlog::*;
}

/// Append-only Merkle hash chain + signed evidence bundles.
///
/// Enabled by the `provenance` feature flag.
#[cfg(feature = "provenance")]
pub mod provenance {
    pub use klieo_provenance::*;
}

/// OpenTelemetry OTLP exporter wired to `tracing` spans.
///
/// Enabled by the `otel` feature flag.
#[cfg(feature = "otel")]
pub mod otel {
    pub use klieo_otel::*;
}

/// 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.
///
/// Enabled by the `observability-viz` feature flag.
#[cfg(feature = "observability-viz")]
pub mod viz {
    pub use klieo_ops_viz::*;
}

// ── lib tests ─────────────────────────────────────────────────────────────────

#[cfg(test)]
mod lib_tests {
    use super::*;

    #[test]
    fn core_types_always_visible() {
        // RunOptions and Error::Cancelled must resolve through the crate root.
        let opts = RunOptions::default();
        assert_eq!(opts.max_steps, 16);

        let err = Error::Cancelled;
        assert!(matches!(err, Error::Cancelled));
    }
}