klieo 0.6.0

#![deny(missing_docs)]
#![deny(rust_2018_idioms)]

//! `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 = "0.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-genai` | `klieo-llm-genai` (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 |
//!
//! ## Composition + protocol
//!
//! | Feature | Crate enabled |
//! |---------|---------------|
//! | `flows` | `klieo-flows` — Sequential/Parallel/Loop/Graph |
//! | `a2a` | `klieo-a2a` — durable Agent-to-Agent v1.0 |
//! | `spec` | `klieo-spec` — quality-loop runner |
//!
//! ## 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::*;

// ── 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::*;
}

// ── 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_genai`].
#[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-genai` feature flag.
#[cfg(feature = "llm-genai")]
pub mod llm_genai {
    pub use klieo_llm_genai::*;
}

// ── 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::*;
}

/// 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::*;
}

// ── 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::StdioTransport`].
///
/// Enabled by the `mcp` feature flag (implies `tools`).
#[cfg(feature = "mcp")]
pub mod mcp {
    pub use klieo_tools_mcp::*;
}

// ── 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::*;
}

/// 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::*;
}

// ── 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::*;
}

// ── 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));
    }
}