# cognis

> Rust-native LLM framework. Type-safe Runnable, agent loop, graph state, RAG pipeline, and observability.

## Docs

- [Human-in-the-loop](https://cognis.vasanth.xyz/building-agents/hitl.md): Pause an agent before sensitive actions, show a human what's about to happen, and let them approve, edit, or reject.
- [System prompts and memory](https://cognis.vasanth.xyz/building-agents/memory.md): Make your agent remember. Pin a system prompt, pick a memory variant, decide what survives between turns.
- [Middleware](https://cognis.vasanth.xyz/building-agents/middleware.md): Cross-cutting policies that wrap LLM calls. Retry, fallback, redaction, prompt caching, summarization, planning — composable, and agent-friendly via a custom provider.
- [Models and providers](https://cognis.vasanth.xyz/building-agents/models.md): Pick a provider, configure a Client, and switch between OpenAI, Anthropic, Google, Ollama, Azure, and OpenRouter without changing your agent code.
- [Multi-agent orchestration](https://cognis.vasanth.xyz/building-agents/multi-agent.md): When one agent isn't enough. Sequential, Supervisor, ParallelVote, RoundRobin, or your own handoff strategy.
- [Streaming](https://cognis.vasanth.xyz/building-agents/streaming.md): Two streams: tokens for the user, structured events for your tooling. Same Runnable, two windows.
- [Structured output](https://cognis.vasanth.xyz/building-agents/structured-output.md): Get a typed Rust struct back from the LLM. Three parsers, three failure-recovery strategies, one consistent pattern.
- [Tools](https://cognis.vasanth.xyz/building-agents/tools.md): Give your agent things to do — search the web, query a database, call your code. Three ways to define them, all type-safe.
- [Documents and splitters](https://cognis.vasanth.xyz/building-rag/documents.md): Turn raw inputs into Documents, then chunk them into pieces an embedder can fit in its context.
- [Embeddings and vector stores](https://cognis.vasanth.xyz/building-rag/embeddings.md): Turn text into vectors, store them, search them. Six vector stores, four embedding providers, one trait.
- [Indexing pipeline](https://cognis.vasanth.xyz/building-rag/indexing.md): Keep your vector store in sync with the source of truth. Incremental indexing only re-embeds what changed.
- [Reranking and compression](https://cognis.vasanth.xyz/building-rag/reranking.md): Make retrieved context better — rerank with a cross-encoder, compress with a pipeline, fight lost-in-the-middle.
- [Retrievers](https://cognis.vasanth.xyz/building-rag/retrievers.md): A retriever turns a query into ranked Documents. Vector, keyword, hybrid, multi-query — pick or compose.
- [Adding a new LLM provider](https://cognis.vasanth.xyz/contribute/adding-a-provider.md): A walkthrough for plugging a new vendor into cognis-llm.
- [Adding a new built-in tool](https://cognis.vasanth.xyz/contribute/adding-a-tool.md): Contribute a generally-useful tool that ships with the cognis crate.
- [Adding a new vector store](https://cognis.vasanth.xyz/contribute/adding-a-vector-store.md): Plug a new backend into cognis-rag — local store or hosted service.
- [Architecture and conventions](https://cognis.vasanth.xyz/contribute/architecture.md): Crate boundaries, design rules, what goes where, what NOT to port from Python.
- [Code of conduct](https://cognis.vasanth.xyz/contribute/code-of-conduct.md): How we work together. Be kind, assume good faith, focus on the work.
- [Development setup](https://cognis.vasanth.xyz/contribute/development-setup.md): Clone, build, test, lint. The local loop.
- [Pull request guidelines](https://cognis.vasanth.xyz/contribute/pull-requests.md): Title format, description checklist, sign-off — what makes a PR easy to review.
- [Ways to contribute](https://cognis.vasanth.xyz/contribute/ways-to-contribute.md): Bugs, features, integrations, docs, examples — every contribution lane.
- [Agents and the loop](https://cognis.vasanth.xyz/core-ideas/agents.md): What an agent is in Cognis: a graph with a model node, a tool node, and a stop condition. AgentBuilder wires it for you.
- [Graphs and state](https://cognis.vasanth.xyz/core-ideas/graphs.md): Stateful workflows in Cognis — typed state, reducers, conditional control flow, and Pregel execution.
- [Messages and content](https://cognis.vasanth.xyz/core-ideas/messages.md): The Message enum and ContentPart variants — the shape of every chat-style payload.
- [Runnables](https://cognis.vasanth.xyz/core-ideas/runnables.md): The contract every Cognis primitive wears. Pipe, branch, retry, and stream — all type-checked.
- [Agents](https://cognis.vasanth.xyz/examples/agents.md): ReAct loops, multi-agent orchestration, planning, lifecycle, plugins, AgentBus pub/sub.
- [Chains](https://cognis.vasanth.xyz/examples/chains.md): Composing primitives with pipe, branch, parallel, lambda. Output parsers, structured extraction, typed runnables.
- [Graphs](https://cognis.vasanth.xyz/examples/graphs.md): Graph<S>, state machines, checkpoints, interrupts, visualization, routers, message graphs.
- [Examples](https://cognis.vasanth.xyz/examples/index.md): 100+ runnable demos covering every part of Cognis. Pick a category, run with one cargo command.
- [Memory](https://cognis.vasanth.xyz/examples/memory.md): Buffer, Window, TokenBuffer, SummaryBuffer, Entity, KnowledgeGraph — side by side.
- [Models](https://cognis.vasanth.xyz/examples/models.md): LLM clients, streaming, embeddings, similarity, model routing, multimodal content.
- [Observability](https://cognis.vasanth.xyz/examples/observability.md): Callbacks, tracing, health checks, evaluation framework, evaluation pipelines.
- [Parsers](https://cognis.vasanth.xyz/examples/parsers.md): Output-fixing and retry parsers for robust structured output.
- [Quickstart V2 examples](https://cognis.vasanth.xyz/examples/quickstart.md): Eight numbered demos that walk the V2 surface — Runnable, agents, graphs, streaming, checkpoints, multi-agent.
- [Resilience](https://cognis.vasanth.xyz/examples/resilience.md): Retries, fallbacks, rate limiters, error recovery, SSRF protection, caching.
- [Retrieval (RAG)](https://cognis.vasanth.xyz/examples/retrieval.md): Splitters, vector stores, retrievers, indexing pipeline, rerankers, document transformers.
- [Tools](https://cognis.vasanth.xyz/examples/tools.md): Tool definitions, derive macros, schema-based tools, ToolOrchestrator DAG, stateful HTTP, file tools.
- [Installation](https://cognis.vasanth.xyz/get-started/installation.md): Add cognis to a Cargo project, pick the features you need, and configure credentials safely.
- [Quickstart](https://cognis.vasanth.xyz/get-started/quickstart.md): From zero to a running agent in five minutes.
- [Checkpointing and time travel](https://cognis.vasanth.xyz/graph-workflows/checkpointing.md): Persist state, rewind, edit, resume. The foundation for human-in-the-loop, debugging, and durability.
- [Control flow](https://cognis.vasanth.xyz/graph-workflows/control-flow.md): Goto, edges, parallel fan-out, subgraphs. The choreography of a graph.
- [State and reducers](https://cognis.vasanth.xyz/graph-workflows/state.md): Define a state struct, decide how updates apply. The compiler does the rest.
- [Streaming graph events](https://cognis.vasanth.xyz/graph-workflows/streaming.md): Filter graph events by mode, write custom progress signals, build live UIs.
- [Visualization](https://cognis.vasanth.xyz/graph-workflows/visualization.md): Render a compiled graph as DOT, Mermaid, or ASCII. Paste into a viewer or commit to your repo.
- [Cognis](https://cognis.vasanth.xyz/introduction.md): Build LLM agents in Rust without the duct tape. Typed Runnables, an agent loop, a stateful graph engine, and production-grade RAG — all in one workspace.
- [Callbacks and observers](https://cognis.vasanth.xyz/observability/callbacks.md): How Cognis surfaces what's happening at runtime. Two interfaces, one event stream, infinite consumers.
- [Cost tracking](https://cognis.vasanth.xyz/observability/cost.md): Token usage and USD cost on every LLM call. Default pricing for the major providers, overridable per model.
- [Evaluation](https://cognis.vasanth.xyz/observability/evaluation.md): Run datasets through any Runnable, score the outputs, ship results to your trace backend.
- [Trace with Langfuse](https://cognis.vasanth.xyz/observability/langfuse.md): Production observability in three steps. Spans, generations, sessions, users, and pricing — all wired.
- [Prompts and scores](https://cognis.vasanth.xyz/observability/prompts-scores.md): Pull versioned prompts from Langfuse, push numeric or categorical scores back. Close the eval loop without leaving Cognis.
- [Code-aware Q&A over a repo](https://cognis.vasanth.xyz/patterns/code-qa.md): RAG over a Rust codebase. Index files, retrieve relevant chunks, answer questions with citations.
- [Tool calling with human approval](https://cognis.vasanth.xyz/patterns/hitl-approval.md): An agent that pauses before sensitive actions and waits for a human to approve, edit, or reject.
- [Local-only with Ollama](https://cognis.vasanth.xyz/patterns/local-ollama.md): Build agents that run entirely on your machine. No API keys, no provider bills, fast iteration.
- [Long-context summarization](https://cognis.vasanth.xyz/patterns/long-context.md): Compress a 200k-token document into a useful summary without losing the threads. Map-reduce, hierarchical summaries, and reorder.
- [Multi-agent debate](https://cognis.vasanth.xyz/patterns/multi-agent-debate.md): A proposer and a critic argue for N rounds. Better answers from disagreement.
- [Research assistant](https://cognis.vasanth.xyz/patterns/research-assistant.md): Build an agent that takes a topic, searches the web, and writes a sourced report. Sequential planner → researcher → writer.
- [Stateful chat with memory](https://cognis.vasanth.xyz/patterns/stateful-chat.md): A multi-turn chatbot that remembers across messages — and across processes if you wire persistence.
- [Streaming UI backend](https://cognis.vasanth.xyz/patterns/streaming-ui.md): An HTTP endpoint that streams agent tokens and tool events to a browser. SSE-shaped, framework-agnostic.
- [Caching](https://cognis.vasanth.xyz/production/caching.md): Don't pay twice for the same call. In-memory, SQLite, and provider-side prompt caches.
- [Going to production](https://cognis.vasanth.xyz/production/going-to-production.md): A checklist. Resilience, observability, security, persistence, cost. The things you'd add to a prototype before showing it to real users.
- [Resilience](https://cognis.vasanth.xyz/production/resilience.md): Retries, fallbacks, rate limits, recovery. Production patterns for keeping an LLM app up when the providers wobble.
- [Security](https://cognis.vasanth.xyz/production/security.md): PII redaction, tool deny-lists, SSRF protection, sandboxing. Patterns for keeping an LLM app from making you the news.
- [cognis](https://cognis.vasanth.xyz/reference/api/cognis.md): Umbrella crate. Re-exports the foundation, LLM, RAG, and graph layers, plus the agent layer.
- [cognis-core](https://cognis.vasanth.xyz/reference/api/cognis-core.md): The foundation. Runnable, Message, prompts, output parsers, callbacks, composition. Zero internal dependencies.
- [cognis-graph](https://cognis.vasanth.xyz/reference/api/cognis-graph.md): Stateful Graph<S>, Pregel engine, channels, checkpointers, visualization.
- [cognis-llm](https://cognis.vasanth.xyz/reference/api/cognis-llm.md): LLM clients and providers, tool calling, structured output, streaming.
- [cognis-macros](https://cognis.vasanth.xyz/reference/api/cognis-macros.md): Proc macros: #[cognis::tool] and #[derive(GraphState)] / #[derive(GraphStateV2)].
- [cognis-rag](https://cognis.vasanth.xyz/reference/api/cognis-rag.md): Embeddings, vector stores, retrievers, splitters, document loaders, indexing pipeline.
- [cognis-trace](https://cognis.vasanth.xyz/reference/api/cognis-trace.md): Pluggable LLM-aware observability. Langfuse-first, OTel-friendly via custom exporters.
- [Changelog](https://cognis.vasanth.xyz/reference/changelog.md): Versioned releases. The full text lives on GitHub.
- [Environment variables](https://cognis.vasanth.xyz/reference/env-vars.md): What Client::from_env() reads and which env vars Cognis honors at runtime.
- [Feature flags](https://cognis.vasanth.xyz/reference/feature-flags.md): Every feature flag in the workspace, what it pulls in, and where it lives.

## OpenAPI Specs

- [openapi](https://cognis.vasanth.xyz/api-reference/openapi.json)

## Optional

- [GitHub](https://github.com/0xvasanth/cognis)
- [crates.io](https://crates.io/crates/cognis)