# Orchid Documentation

Orchid is a generic, platform-agnostic multi-agent AI framework built on LangGraph (Python) and Next.js.
Agents are configured in YAML, tools come from MCP servers, retrieval is scoped hierarchically, and every internal judgement can be routed to a dedicated decision model with deterministic fallbacks.

Every page below is also available as markdown by appending `.md` to its URL.

## meta

- [Best Practices](https://orchestratorindex.com/best-practices.md) — Recommended patterns for production-grade Orchid deployments.
- [Glossary](https://orchestratorindex.com/glossary.md) — Definitions of key terms used throughout the Orchid documentation.
- [Contact](https://orchestratorindex.com/contact.md) — Get in touch with the Orchid maintainer or open an issue on GitHub.

## concepts

- [Agents](https://orchestratorindex.com/concepts/agents.md) — How OrchidAgent works: YAML configuration, skills, MCP tools, and the run lifecycle.
- [Supervisor](https://orchestratorindex.com/concepts/supervisor.md) — The LangGraph supervisor: routing, history limits, and sliding-window summarisation.
- [Hierarchical RAG](https://orchestratorindex.com/concepts/rag.md) — OrchidRAGScope, the 5-level hierarchy, retrieval strategies, ingestion pipelines, and the parse-once pattern.
- [MCP Integration](https://orchestratorindex.com/concepts/mcp.md) — Connecting MCP servers to Orchid agents: none, passthrough, and OAuth auth modes.
- [OAuth & Dynamic Client Registration](https://orchestratorindex.com/concepts/oauth.md) — How auth.mode: oauth triggers RFC 9728 → 8414 → 7591 discovery and manages per-user tokens.
- [Embeddings](https://orchestratorindex.com/concepts/embeddings.md) — Supported embedding models, dimension differences, and re-indexing requirements.
- [Multi-LLM Support](https://orchestratorindex.com/concepts/multi-llm.md) — Provider agnosticism via LiteLLM: configure any model per agent, swap at runtime.
- [Chat Persistence](https://orchestratorindex.com/concepts/persistence.md) — OrchidChatStorage ABC, the built-in in-memory default, and durable SQLite/PostgreSQL backends via plugins.
- [Tool Call Strategies](https://orchestratorindex.com/concepts/tool-strategies.md) — The all, sequential, and llm_decides strategies and how to register custom ones.
- [Document Parsing](https://orchestratorindex.com/concepts/document-parsing.md) — PDF and image parsing with the parse-once pattern and the pluggable parser registry.
- [Mini-Agents](https://orchestratorindex.com/concepts/mini-agents.md) — Per-agent opt-in fan-out: decompose a multi-part request into parallel sub-agents, each running its own focused agentic loop.
- [Pollen + Bloom](https://orchestratorindex.com/concepts/pollen-bloom.md) — Event-driven AI jobs: Pollen ingests and persists signals; Bloom matches them to triggers and runs them through the supervisor.
- [Chat Summarization](https://orchestratorindex.com/concepts/chat-summarization.md) — Running summaries, structured entity extraction, RAG-augmented conversation memory, and configurable truncation strategies.
- [Decision Models](https://orchestratorindex.com/concepts/decision-models.md) — A dedicated LLM layer that returns typed, calibrated judgements for internal routing, gating and selection seams — with deterministic fallbacks.
- [Data Pipelines](https://orchestratorindex.com/concepts/pipelines.md) — Typed, run-scoped DAGs that combine deterministic code, LLM jobs, agents, decisions, maps and sub-pipelines over a validated information graph.

## configuration

- [Configuration Atlas](https://orchestratorindex.com/configuration.md) — Searchable table of every configuration key across orchid.yml and agents.yaml — filter by name, type, or description.
- [Infrastructure Configuration](https://orchestratorindex.com/configuration-reference/infrastructure.md) — Detailed reference for every orchid.yml property — runtime, auth, LLM, RAG, storage, MCP, tracing.
- [Configuration Reference](https://orchestratorindex.com/configuration-reference.md) — Detailed reference for every configuration property in orchid.yml and agents.yaml — split by file with searchable indexes and deep-links.
- [Agents Configuration](https://orchestratorindex.com/configuration-reference/agents.md) — Detailed reference for every agents.yaml property — defaults, supervisor, agents, tools, skills, guardrails, events.

## ecosystem

- [Ecosystem Overview](https://orchestratorindex.com/ecosystem.md) — Five packages, one coherent framework: library, API, CLI, MCP gateway, and frontend.

## examples

- [Basketball Demo](https://orchestratorindex.com/examples/basketball.md) — Minimal end-to-end Orchid example: GenericAgents with built-in tool classes, PostgreSQL storage, cross-agent skills, and an event-driven trivia agent.
- [Helpdesk Demo](https://orchestratorindex.com/examples/helpdesk.md) — Custom agent class, cross-agent skills, sequential routing, and event-driven ticket triage.
- [Restaurant Demo](https://orchestratorindex.com/examples/restaurant.md) — RAG with dynamic injection, multi-agent sequential routing, custom agent class, and event-driven deep research.
- [Recipes](https://orchestratorindex.com/examples/recipes.md) — Zero-infrastructure RAG cookbook example using ChromaDB and Ollama — no Docker, no external services.
- [Education Studio](https://orchestratorindex.com/examples/education.md) — Four-agent teaching workflow with concept extraction, quiz generation, lesson planning, and multi-format export via PDF, DOCX, PPTX, and Markdown.
- [Examples](https://orchestratorindex.com/examples.md) — Working examples showing different Orchid capabilities and integration patterns.
- [Learning Digest Fan-out](https://orchestratorindex.com/examples/learning.md) — Pollen + Bloom event pattern: a weekly cron emits one signal per learner, each running as that user.
- [MCP Authentication Modes](https://orchestratorindex.com/examples/mcp-auth.md) — All three MCP auth modes in one example: none, passthrough, and OAuth 2.0 with dynamic client registration.
- [Orchid Experts](https://orchestratorindex.com/examples/orchid-experts.md) — Fleet of ten RAG-powered GenericAgent experts covering every Orchid concept — pure YAML + Markdown, zero custom agent code.
- [Postgres Storage](https://orchestratorindex.com/examples/postgres-storage.md) — Demonstrates the orchid-storage-postgres plugin: asyncpg chat persistence, PostgreSQL checkpointer, and visibility.
- [Weather Fleet](https://orchestratorindex.com/examples/weather.md) — Three-agent weather fleet: remote MCP server for live forecasts, built-in safety tools, RAG-backed outfit advice, PostgreSQL storage, and sliding-window chat summarization.
- [Custom Storage Backend](https://orchestratorindex.com/examples/custom-storage.md) — Plug in a custom OrchidChatStorage subclass via the storage.class field.
- [Data Pipeline](https://orchestratorindex.com/examples/data-pipeline.md) — Direct typed DAG example: deterministic, LLM, agent, decision, map, sub-pipeline and emit jobs over a synthetic customer-health graph.
- [Event-Driven Data Pipeline](https://orchestratorindex.com/examples/data-pipeline-events.md) — Bloom-triggered typed pipeline: bearer-authenticated webhook, cron schedule, SQLite event storage and chat-bound results.
- [RAG Retrieval Strategies](https://orchestratorindex.com/examples/rag-strategies.md) — Side-by-side comparison of simple, multi_query, hyde, and a custom recency-weighted retrieval strategy.
- [Tool Call Strategies](https://orchestratorindex.com/examples/tool-strategies.md) — all, sequential, llm_decides, and a custom priority strategy in one example.
- [Prompt Customization](https://orchestratorindex.com/examples/prompt-customization.md) — Every supervisor and agent prompt extension point — assistant_name, routing/synthesis prompts, prompt_sections, and transformer prompts.
- [Gallery Curator](https://orchestratorindex.com/examples/gallery-curator.md) — A multi-session art gallery curator that remembers artists, exhibitions, and decisions across sessions using Orchid's full conversation summarization pipeline.
- [Festival Producer](https://orchestratorindex.com/examples/festival-producer.md) — Multi-agent festival planning with artist booking, logistics, and marketing agents — backed by rag_augmented conversation memory, orchestrator skills, and structured entity extraction.
- [Architecture Review Board](https://orchestratorindex.com/examples/architecture-review.md) — Multi-agent design review with structural engineering, cost estimation, and sustainability consulting — orchestrator skills and rag_augmented memory across design iterations.
- [Graph Knowledge Base](https://orchestratorindex.com/examples/graph-kb.md) — GraphRAG retrieval strategy: graph traversal fused with dense vector search for multi-hop relationship queries.
- [Wiki Document Ingestion](https://orchestratorindex.com/examples/wiki.md) — Two-tier corpus ingestion (headered + recursive), hybrid retrieval, and per-tool RAG overrides with the parse-once pattern.

## packages

- [orchid](https://orchestratorindex.com/packages/orchid.md) — The core Python library: ABCs, agents, graph builder, RAG, and persistence.
- [orchid-api](https://orchestratorindex.com/packages/orchid-api.md) — FastAPI server exposing the Orchid framework over HTTP with SSE streaming.
- [orchid-cli](https://orchestratorindex.com/packages/orchid-cli.md) — Command-line interface for interacting with Orchid without running the API.
- [orchid-mcp](https://orchestratorindex.com/packages/orchid-mcp.md) — Node.js MCP gateway that exposes Orchid to any MCP-capable host LLM.
- [orchid-frontend](https://orchestratorindex.com/packages/orchid-frontend.md) — Next.js 16 multi-chat UI with SSE streaming and file upload support.
- [orchid-storage-sqlite](https://orchestratorindex.com/packages/orchid-storage-sqlite.md) — SQLite storage plugin: chat persistence, MCP stores, event storage, migrations, and the sqlite checkpointer.
- [orchid-storage-postgres](https://orchestratorindex.com/packages/orchid-storage-postgres.md) — PostgreSQL storage plugin: chat and config persistence, MCP stores, events, checkpointer, and visibility fragment.
- [orchid-rag-qdrant](https://orchestratorindex.com/packages/orchid-rag-qdrant.md) — Qdrant vector and doc-store plugin for the Orchid AI framework.
- [orchid-rag-chroma](https://orchestratorindex.com/packages/orchid-rag-chroma.md) — ChromaDB vector-backend plugin for on-disk, zero-infrastructure RAG.
- [orchid-rag-neo4j](https://orchestratorindex.com/packages/orchid-rag-neo4j.md) — Neo4j graph-store plugin for knowledge-graph RAG.

## quickstart

- [Quickstart](https://orchestratorindex.com/quickstart.md) — Run Orchid locally in under ten minutes with the basketball demo.

