cognis

The high-level umbrella crate for the Cognis v2 framework, providing advanced agentic capabilities, middleware, and a unified API.

Purpose

cognis is the primary entry point for developers building AI-powered applications with Cognis. It re-exports all core sub-crates (core, llm, rag, graph) and adds high-level abstractions like ReAct agents, composable middleware, and execution backends.

Key Features

• ReAct Agents: Out-of-the-box support for "Reason + Act" agent loops with flexible planning and tool usage.
• Middleware Pipeline: A powerful hook system for adding cross-cutting concerns like caching, rate limiting, human-in-the-loop approvals, and PII redaction.
• Backends: Unified interface for managing agent workspaces, supporting both in-memory and sandboxed filesystem storage.
• Telemetry & Observability: Integrated tracing and event logging to monitor agent behavior and performance.
• Unified Prelude: A single prelude module that brings in the most commonly used types and traits from across the entire framework.

Usage

Add this to your Cargo.toml:

[dependencies]
cognis = "0.1.0"

Basic Example: A Five-Line ReAct Agent

use cognis::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let client = Client::from_env()?;
    let agent = Agent::builder()
        .client(client)
        .build();

    let response = agent.invoke("Explain quantum entanglement in one sentence.").await?;
    println!("Agent: {}", response.content);
    Ok(())
}

Advanced Example: Agent with Middleware and Tools

use cognis::prelude::*;
use cognis_macros::tool;

#[tool]
/// Multiply two numbers.
async fn multiply(a: i32, b: i32) -> Result<i32> {
    Ok(a * b)
}

#[tokio::main]
async fn main() -> Result<()> {
    let client = Client::from_env()?
        .with_middleware(ModelRetry::default())
        .with_middleware(PromptCaching::default());

    let agent = Agent::builder()
        .client(client)
        .with_tool(multiply)
        .build();

    let response = agent.invoke("What is 15 * 42?").await?;
    println!("Agent: {}", response.content);
    Ok(())
}