Crate cognis 

cognis

v2-beta umbrella crate. Re-exports cognis-core, cognis-graph, cognis-llm, cognis-rag and adds:

• agent — the standard ReAct agent loop.
• backend — agent workspace (in-memory or sandboxed real FS).
• middleware — composable LLM-call hooks (retry, fallback, caching, redaction, summarization, …).
• retrievers — LLM-driven retrievers (multi-query, contextual compression).

Re-exports

pub use agent::default_react_graph;

pub use agent::default_react_graph_with_limits;

pub use agent::Agent;

pub use agent::AgentBuilder;

pub use agent::AgentHealth;

pub use agent::AgentLifecycle;

pub use agent::AgentPlugin;

pub use agent::AgentResponse;

pub use agent::AgentState;

pub use agent::AgentStateUpdate;

pub use agent::Buffer;

pub use agent::ClosurePlugin;

pub use agent::ConversationMode;

pub use agent::EntityExtractor;

pub use agent::EntityFact;

pub use agent::EntityMemory;

pub use agent::Fact;

pub use agent::FactExtractionInput;

pub use agent::FactExtractor;

pub use agent::FactExtractorBuilder;

pub use agent::FactKind;

pub use agent::FnPlugin;

pub use agent::HybridMemory;

pub use agent::KnowledgeGraphMemory;

pub use agent::LifecyclePlugin;

pub use agent::LlmExtractor;

pub use agent::LlmExtractorBuilder;

pub use agent::Memory;

pub use agent::OnStart;

pub use agent::PluginRegistry;

pub use agent::SummaryBufferMemory;

pub use agent::SummaryMemory;

pub use agent::ThinkNode;

pub use agent::TokenBufferMemory;

pub use agent::ToolDispatchNode;

pub use agent::Triple;

pub use agent::TripleExtractor;

pub use agent::VectorMemory;

pub use agent::Window;

pub use agent::Workflow;

pub use agent::WorkflowState;

pub use agent::WorkflowStateUpdate;

pub use agent_bus::AgentBus;

pub use agent_bus::SubscribeError;

pub use agent_bus::Subscription;

pub use agent_events::AgentEvent;

pub use agent_events::AgentEventBus;

pub use agent_events::EventSubscription;

pub use agent_events::DEFAULT_EVENTS_TOPIC;

pub use backend::Backend;

pub use backend::Blob;

pub use backend::GrepHit;

pub use backend::InMemoryStateBackend;

pub use backend::InMemoryStorageBackend;

pub use backend::LocalFsStorageBackend;

pub use backend::MemoryBackend;

pub use backend::SandboxedFsBackend;

pub use backend::StateBackend;

pub use backend::StorageBackend;

pub use conversation::summarize;

pub use conversation::turns_from_messages;

pub use conversation::ConversationSummary;

pub use conversation::ConversationTurn;

pub use eval::Contains;

pub use eval::EvalCase;

pub use eval::EvalReport;

pub use eval::EvalRow;

pub use eval::EvalRunner;

pub use eval::Evaluator;

pub use eval::ExactMatch;

pub use eval::LlmJudge;

pub use history::HistoryStore;

pub use history::HistoryTrimmer;

pub use history::InMemoryHistory;

pub use history::RunnableWithMessageHistory;

pub use history::SessionKey;

pub use history::SessionResolver;

pub use middleware::AlwaysSkip;

pub use middleware::ApprovalGate;

pub use middleware::AutoApproveAll;

pub use middleware::AutoRejectAll;

pub use middleware::CapMessageLength;

pub use middleware::ChatApproval;

pub use middleware::ChatApprover;

pub use middleware::ContextEditing;

pub use middleware::ContextInjection;

pub use middleware::ContextProvider;

pub use middleware::DropMatching;

pub use middleware::EditPolicy;

pub use middleware::EmulatorSource;

pub use middleware::FilesystemMiddleware;

pub use middleware::FixedRecovery;

pub use middleware::FnContextProvider;

pub use middleware::FnRecovery;

pub use middleware::FnToolCallPatcher;

pub use middleware::HumanDecision;

pub use middleware::HumanInTheLoop;

pub use middleware::HumanResponder;

pub use middleware::LimitTools;

pub use middleware::MapEmulator;

pub use middleware::Middleware;

pub use middleware::MiddlewareCtx;

pub use middleware::MiddlewarePipeline;

pub use middleware::ModelCallLimit;

pub use middleware::ModelFallback;

pub use middleware::ModelRetry;

pub use middleware::Next;

pub use middleware::PatchToolCalls;

pub use middleware::PiiRedactor;

pub use middleware::PipelinedClient;

pub use middleware::Planning;

pub use middleware::PromptCaching;

pub use middleware::RateLimit;

pub use middleware::RateLimiter;

pub use middleware::Recovery;

pub use middleware::RecoveryStrategy;

pub use middleware::RegexRedactor;

pub use middleware::SubagentMiddleware;

pub use middleware::SubagentRouter;

pub use middleware::Summarization;

pub use middleware::TodoMiddleware;

pub use middleware::TokenBucket;

pub use middleware::TokenCounter;

pub use middleware::ToolAllowList;

pub use middleware::ToolCallLimit;

pub use middleware::ToolCallPatcher;

pub use middleware::ToolDenyList;

pub use middleware::ToolEmulator;

pub use middleware::ToolFilter;

pub use middleware::ToolRetry;

pub use middleware::ToolRetryClassifier;

pub use middleware::ToolSelection;

pub use middleware::WorkspaceLister;

pub use multi_agent::sort_by_priority;

pub use multi_agent::AgentMessage;

pub use multi_agent::Consensus;

pub use multi_agent::HandoffStrategy;

pub use multi_agent::Hierarchical;

pub use multi_agent::InMemoryMessageBus;

pub use multi_agent::MessageBus;

pub use multi_agent::MultiAgentOrchestrator;

pub use multi_agent::ParallelVote;

pub use multi_agent::Priority;

pub use multi_agent::RoundRobin;

pub use multi_agent::Sequential;

pub use multi_agent::Supervisor;

pub use observers::TracingObserver;

pub use retrievers::ContextualCompressionRetriever;

pub use retrievers::MultiQueryRetriever;

pub use retrievers::RerankingRetriever;

pub use retrievers::SearchSpec;

pub use retrievers::SelfQueryRetriever;

pub use retrievers::TimeWeightedRetriever;

pub use session::InMemorySessionStore;

pub use session::Session;

pub use session::SessionStore;

pub use session::SessionStoreHandle;

pub use skills::AllSkills;

pub use skills::BuiltSkill;

pub use skills::KeywordSelector;

pub use skills::Skill;

pub use skills::SkillBuilder;

pub use skills::SkillRegistry;

pub use skills::SkillSelector;

pub use telemetry::InMemoryTelemetry;

pub use telemetry::TelemetryEvent;

pub use telemetry::TelemetryHandle;

pub use telemetry::TelemetrySink;

pub use telemetry::TelemetrySnapshot;

pub use tools::register_filesystem_tools;

pub use tools::AllowList;

pub use tools::ApprovalGatedTool;

pub use tools::Approver;

pub use tools::AutoApprove;

pub use tools::CachedTool;

pub use tools::Calculator;

pub use tools::CodeSanitizer;

pub use tools::Decision;

pub use tools::DotPathEngine;

pub use tools::ExecutionPlan;

pub use tools::FileEditTool;

pub use tools::FileExistsTool;

pub use tools::FileGlobTool;

pub use tools::FileGrepTool;

pub use tools::FileListTool;

pub use tools::FileReadTool;

pub use tools::FileWriteTool;

pub use tools::HumanTool;

pub use tools::JsonQueryTool;

pub use tools::OrchestratorResult;

pub use tools::PythonReplConfig;

pub use tools::PythonReplTool;

pub use tools::QueryEngine;

pub use tools::RejectAll;

pub use tools::RetrieverTool;

pub use tools::SanitizationError;

pub use tools::ShellTool;

pub use tools::StaticResponder;

pub use tools::SubAgentTool;

pub use tools::ToolHumanResponder;

pub use tools::ToolOrchestrator;

pub use tools::ToolStep;

pub use cognis_core;

pub use cognis_graph;

pub use cognis_llm;

pub use cognis_rag;

Modules

agent

Thin agent layer: AgentState + Memory + AgentBuilder + Agent.

agent_bus

Topic-based pub/sub for inter-agent broadcast.

agent_events

Typed lifecycle events layered over AgentBus.

backend

Agent workspace backend: file ops + sandboxing.

conversation

Typed value types over Vec<Message> history.

eval

Lightweight evaluation harness for any Runnable<I, O>.

history

RunnableWithMessageHistory — wrap a Runnable<Vec<Message>, Message> so it carries conversation history per session ID.

middleware

Agent middleware — hooks that wrap an LLM call.

multi_agent

Multi-agent orchestration — dispatch a single user request across a fleet of agents and merge their outputs via a pluggable handoff strategy.

observers

Observer implementations that bridge cognis’s [Event] stream to the surrounding ecosystem.

prelude

Common imports for v2 user code building agents.

presets

Named AgentBuilder presets for common agent shapes.

retrievers

LLM-driven retrievers — live in cognis (not cognis-rag) because they depend on cognis-llm’s Client.

session

Session — a long-lived conversation with metadata, optional expiry, and a pluggable backing store.

skills

Skills — coherent bundles of (system-prompt fragment, tools, activation predicate) that the agent installs at build time.

telemetry

Telemetry — typed counters / events emitted alongside agent runs.

tools

Built-in tools shipped with cognis.

Structs

ActiveSnapshot

Snapshot of one active task at an interrupt boundary. Used for point-of-interrupt resume.

Aggregated

Output of StreamAggregator::finalize.

AuditEntry

One audit row.

AuditLogObserver

Bridges cognis Events into an AuditLog.

CachingRetriever

Wraps any Runnable<String, Vec<Document>> so identical query strings return cached document lists.

CharTokenizer

Trivial char-as-token implementation. Conservative upper bound on real tokenizer counts; useful as a default for budgeting.

ChatOptions

Per-call options that override ClientConfig defaults.

ChatResponse

Response payload from chat_completion.

Client

Top-level LLM client. Cheap to clone.

ClientBuilder

Fluent builder for Client.

CompiledGraph

A validated, ready-to-run graph. Cheap to clone (the underlying nodes are Arc<dyn Node<S>>).

CompressorPipeline

Chain N doc-list transformers back-to-back. Each stage’s output feeds the next.

CrossEncoderReranker

Wraps an inner retriever, then reranks its hits via a CrossEncoder.

DedupVectorStore

A VectorStore decorator that silently skips documents whose normalised content fingerprint is already in the seen-set.

Document

A piece of text that flows through loaders → splitters → embeddings → vector store → retrievers.

EventStream

A stream of structured events. Same shape as RunnableStream<Event>, but named separately to make stream-of-events vs stream-of-output distinguishable at the type level.

Extensions

A typed map indexed by TypeId. Each T: Any + Send + Sync + 'static can have at most one value stored.

FakeEmbeddings

Produces deterministic dim-length f32 vectors via repeated hashing of the input text. Same input always yields the same vector.

Filter

Metadata filter applied to similarity search.

FnCrossEncoder

Closure-backed cross-encoder. Useful for tests; in production use a real impl that calls a hosted scorer.

FnTokenizer

Closure-backed tokenizer.

Graph

A graph under construction. Generic over the state type S. Convert to an executable [CompiledGraph] via .compile().

GraphMetrics

Per-node execution counts and error counts.

GraphSnapshot

Serializable shape of a CompiledGraph<S>.

InMemoryAuditLog

In-process audit log.

InMemoryCheckpointer

Stores (run_id, namespace, step) -> S in a Mutex-protected HashMap. State must be Clone because saving stores a clone and loading returns one.

InMemoryDocstore

In-process Docstore backed by a Mutex<HashMap>.

InMemoryRecordManager

In-process record manager. Suitable for tests and single-process apps.

InMemoryVectorStore

Linear-scan in-memory vector store.

IncrementalReport

Result of an IndexingPipeline::run_incremental call.

Loader

Reconstructs runnables from definitions. Caller registers factories by name for each Lambda / Opaque kind they expect to load.

LongContextReorder

Reorder retrieved documents so the most-relevant ones sit at the head and tail of the list. LLMs attend better to ends than to the middle of long contexts; this is the classic “lost in the middle” fix.

MetricsObserver

Observer that maintains a GraphMetrics under a Mutex.

MultiVectorIndexer

Indexes a parent doc under N text representations.

MultiVectorRetriever

One type that handles both indexing (multi-rep per parent) and retrieval (parent-doc).

NodeCtx

Per-superstep context handed to every Node::execute call. Carries run-correlation metadata and the active RunnableConfig. The lifetime is the superstep — don’t hold across awaits beyond execute returning.

NodeOut

Output of a node’s execute: a typed state delta + where to go next.

NodeRetryPolicy

Per-task retry policy. The engine wraps Node::execute calls in a retry loop when the node returns a Some policy and the call fails with a cognis_core::CognisError whose is_retryable() is true.

NodeTiming

One node’s timing aggregate.

OllamaEmbeddings

Ollama embeddings client.

OpenAIEmbeddings

OpenAI Embeddings API client.

ParentDocumentRetriever

Wraps a vector index of small chunks + a doc-id keyed parent docstore.

ProfilingObserver

Per-node timing aggregator. Pairs OnNodeStart / OnNodeEnd events keyed by (run_id, step, node) to compute durations.

QueryTranslatorRetriever

query → translator → retriever.

RunnableConfig

Per-invocation configuration. Defaults are sensible; override only what you need.

RunnableStream

A stream of Result<O> items — the canonical output stream type for Runnable::stream. Wraps Pin<Box<dyn Stream>> for trait-object flexibility, with helper combinators on the wrapper.

SearchResult

One document returned by a similarity search.

StreamAggregator

Accumulates a streaming response into a final Message plus aggregated metadata. Chunk ordering matters for text content and for tool-call argument deltas — feed chunks in the order they arrive.

StreamChunk

One chunk of a streaming response.

Subgraph

Adapter Node that runs a child graph and projects its state into a parent update.

ToolCall

One tool invocation requested by the LLM in an AiMessage.

ToolDefinition

Serializable form of a tool — what gets sent to the LLM API.

ToolRegistry

HashMap-backed tool registry. The agent layer uses this to dispatch tool calls returned by the LLM.

Usage

Token usage report.

UsageTracker

Aggregates Usage across many ChatResponses. Cheap to share via Arc.

Enums

AuditKind

What an audit entry records.

CognisError

All errors produced by cognis-core and downstream v2 crates.

Distance

How to score similarity between two vectors. Each variant carries its mathematical meaning into Distance::compute and Distance::similarity.

Event

A structured event emitted by stream_events() — exposes per-step graph activity, tool calls, token deltas, and errors.

Goto

Routing instruction returned by a node, telling the engine which node(s) to schedule next. Branching/looping is data: a node decides at runtime where to send execution.

Message

A single message in an LLM conversation.

Provider

Closed set of supported providers.

RunnableDefinition

Serializable description of a runnable’s shape.

ToolInput

Input to a tool’s _run method.

ToolOutput

Output from a tool’s _run method.

Traits

AuditLog

Pluggable audit log.

BaseTool

Tier-1 tool trait. The most general contract — manual JSON schema, serde_json::Value arg deserialization is the tool’s responsibility.

Checkpointer

Trait for storing & retrieving graph state at superstep boundaries.

CrossEncoder

Scores (query, doc) pairs.

Docstore

Pluggable id-keyed document store.

Embeddings

A model that converts text into vector embeddings. Implementations MUST return vectors of consistent dimensionality across calls — the dimensions() accessor (when known) reports it.

GraphState

Trait implemented by structs that hold graph state. The Update type is generated by #[derive(GraphState)] and represents a partial delta; apply merges a delta into self via per-field reducers.

JsonSchema

A type which can be described as a JSON Schema document.

LLMProvider

Trait every concrete provider implementation satisfies. The Client holds an Arc<dyn LLMProvider> and dispatches through it.

Node

The unit of computation in a graph. Async, takes a &S snapshot of state

Observer

Pluggable event sink. Multiple observers can subscribe to a single run.

RecordManager

Per-key indexing state. Each key is a stable identifier for a document (path, URL, primary key); the fingerprint is whatever the caller computes from the doc — usually a content hash.

Runnable

The unified contract every cognis primitive implements.

SchemaBasedTool

Tier-2 tool: typed args + auto-derived JSON Schema. Implementers only write execute_typed; deserialization, schema, and the Tool surface come for free via the blanket impl below.

Serializable

Trait runnables implement to participate in dump/load. Default is Opaque { name = type name } — override to capture useful structure.

Tokenizer

Counts tokens in a piece of text.

Tool

Tier-1 tool trait. The most general contract — manual JSON schema, serde_json::Value arg deserialization is the tool’s responsibility.

VectorStore

A vector store: holds documents + their embeddings, supports add + similarity search + delete.

Functions

node_fn

Build a NodeFn from a closure. The closure receives (&S, &NodeCtx) and returns Future<Output = Result<NodeOut<S>>>.

normalized_fingerprint

Normalise text (lowercase + collapse whitespace) then fingerprint with FNV-1a 128-bit. Two pieces of text that differ only in case or spacing produce the same fingerprint and are treated as duplicates.

Type Aliases

Result

Result alias used throughout cognis.

Derive Macros

GraphState

#[derive(GraphStateV2)] — v2-shape state derive that emits a typed sibling <Name>Update struct and an impl GraphState for <Name>. Use in v2 code via the re-export cognis_core::GraphState (the rename happens in cognis-core’s lib.rs in Plan #2).

JsonSchema