---
title: "orchid"
description: "The core Python library: ABCs, agents, graph builder, RAG, and persistence."
package: orchid
section: packages
html_url: https://orchestratorindex.com/packages/orchid
markdown_url: https://orchestratorindex.com/packages/orchid.md
---

# orchid

`orchid-ai` is the distributable Python library at the heart of the Orchid framework. It provides the abstract base classes, the LangGraph graph builder, the hierarchical RAG pipeline, and pluggable chat persistence — everything your agents and consumers need, with no API server, no CLI, and no vendor-specific code. Deploy it anywhere Python runs.

## Installation

```bash
pip install orchid-ai

# Backends are separate plugin packages — install what you need:
pip install orchid-storage-sqlite    # SQLite chat storage + MCP stores + checkpointer
pip install orchid-storage-postgres  # PostgreSQL chat storage + checkpointer
pip install orchid-rag-qdrant         # Qdrant vector + doc store
pip install orchid-rag-chroma         # ChromaDB on-disk vector store
pip install orchid-rag-neo4j          # Neo4j graph store
```

## Public API: two tiers

The library exposes two distinct surfaces — and `Orchid` is the front door.

**Run** — the single facade `Orchid` bootstraps config, wires the graph, and runs turns. `orchid-api`, `orchid-cli`, and in-process integrators all route through it:

```python
from orchid_ai import Orchid

async with Orchid.from_config_path("orchid.yml") as orchid:
    result = await orchid.invoke("Hello!", user_id="alice", tenant_id="acme")
    print(result.response)
```

`Orchid` owns construction (`from_config_path` / `from_md_config`), execution (`invoke` / `stream` / `resume`), lifecycle (`close` / `reload_config` / `async with`), and read-only accessors (`graph`, `runtime`, `config`, `chat_repo`, …).

**Extend** — subclass the ABCs and call the `register_*` hooks exported at the top level (`OrchidAgent`, `OrchidIdentityResolver`, `OrchidChatStorage`, `OrchidVectorReader`, the guardrail / ingestion / retrieval contracts, …). These are *import-time* extension points: you subclass or register them **before** an `Orchid` instance exists, so they sit alongside the facade rather than behind it.

Pipelines are the second run mode on the same facade: `await orchid.run_pipeline(name, input, ...)` executes a typed, run-scoped DAG without creating a chat row or a checkpoint. Define it under `pipelines:` in `agents.yaml`; see [Data Pipelines](/concepts/pipelines).

Lower-level plumbing (the `build_*` factories, concrete built-in backends, LangChain adapters, observability handlers) is intentionally **not** re-exported at the top level — import it from its submodule when you need it:

```python
from orchid_ai.checkpointing import build_checkpointer
from orchid_ai.rag.factory import build_reader
from orchid_ai.persistence.factory import build_chat_storage
```

> **Auth is execution context, not graph state.** It travels in the LangGraph `RunnableConfig` (`config["configurable"]["auth_context"]`), never in `OrchidAgentState`, so it is never written to a checkpoint. Inside a custom agent, read it via `self._current_auth`; entry points attach it with `with_auth(...)`.

## Module map

### `core/`

Pure Python abstractions with zero external dependencies beyond the standard library. Every other module in the package depends on `core/` — never the reverse. This is where the ABCs live: `OrchidAgent`, `OrchidIdentityResolver`, `OrchidMCPClient`, and the vector-store interfaces. See [Agents](/concepts/agents) and [Persistence](/concepts/persistence).

### `agents/`

`GenericAgent` — the concrete, YAML-driven agent — and its three collaborators: `SkillDetector` (skill matching), `MCPDispatcher` (MCP tool routing), and `SkillExecutor` (multi-step skill pipelines). Most deployments never need to subclass `GenericAgent`; the YAML surface covers the common case. See [Agents](/concepts/agents) and [Tool Strategies](/concepts/tool-strategies).

### `graph/`

LangGraph wiring: `build_graph()` factory, the supervisor node, and state definitions. The graph is assembled once at startup from `OrchidAgentsConfig` and reused for every request. See [Supervisor](/concepts/supervisor).

### `pipelines/`

The typed DAG runtime: `config/schema_pipeline.py` for the YAML contract, `pipeline/schema.py` for shape compilation, `pipeline/graph.py` and `session.py` for the run-scoped information graph and atomic commits, `pipeline/definition.py` and `registry.py` for compilation, `pipeline/builder.py` and `runner.py` for execution, and `pipeline/steps/` for the seven built-in job kinds plus custom steps. See [Data Pipelines](/concepts/pipelines).

### `config/`

YAML schema (`OrchidAgentsConfig`, `OrchidAgentConfig`, `OrchidMCPServerConfig`) validated by Pydantic, plus the tool-parameter registry. Use `load_config(path)` to load and validate `agents.yaml`. Also contains `OrchidConfigStorage` (ABC for database-backed agent configs), `build_config_storage()` factory, and `OrchidConfigStorageConfig` schema.

### `rag/`

Five-level hierarchical RAG: scoping (`OrchidRAGScope`), indexer, embedding factory, and pluggable backends. The library ships a `null` vector backend plus in-memory doc-store and graph-store backends; Qdrant, ChromaDB, and Neo4j backends are separate plugin packages that auto-register via entry points. All vector access goes through `OrchidVectorReader` / `OrchidVectorWriter` / `OrchidVectorStoreAdmin` — never through backend-specific imports outside `rag/backends/`. See [RAG](/concepts/rag).

### `persistence/`

`OrchidChatStorage` ABC for chat and message CRUD, plus the framework's dependency-free in-memory backend (`OrchidInMemoryChatStorage`) — the zero-configuration default. Durable persistence lives in plugins: `orchid-storage-sqlite` (chat storage, config storage, MCP stores, event storage, checkpointer) and `orchid-storage-postgres` (the same surface backed by `asyncpg`). The framework never falls back silently: a configured class path that cannot be imported fails at startup with a `pip install` hint. See [Persistence](/concepts/persistence).

### `documents/`

File parsing pipeline: PDF (PyMuPDF), DOCX, XLSX, CSV, and image (via vision LLM). All parsers follow the parse-once pattern — call `extract_text()` once and pass the result to both the prompt builder and `ingest_document(pre_extracted_text=...)`. See [Document Parsing](/concepts/document-parsing).

### `mcp/`

`StreamableHttpMCPClient` — the concrete MCP client that implements the three auth modes (`none`, `passthrough`, `oauth`) and drives capability caching via `OrchidSessionWarmer`. See [MCP](/concepts/mcp).

## Public ABCs

| ABC | Module | Purpose |
|-----|--------|---------|
| `OrchidAgent` | `core.agent` | Agent identity + `run()`, `summarise()`, `fetch_rag_context()`, `extract_conversation_history()` |
| `OrchidIdentityResolver` | `core.identity` | Bearer token → `OrchidAuthContext` (pluggable per deployment) |
| `OrchidMCPToolCaller` | `core.mcp` | Call MCP tools (narrow interface — tool handlers depend on this) |
| `OrchidMCPDiscoverable` | `core.mcp` | Discover MCP server capabilities (separate from tool-calling) |
| `OrchidVectorReader` | `core.repository` | Vector store retrieval (agents depend on this only) |
| `OrchidVectorWriter` | `core.repository` | Vector store indexing (indexers depend on this only) |
| `OrchidVectorStoreAdmin` | `core.repository` | Collection management (admin operations only) |
| `OrchidChatStorage` | `persistence.base` | Chat session + message CRUD |
| `OrchidConfigStorage` | `config.storage` | Database-backed agent config CRUD |

## Writing a custom agent

When YAML alone isn't enough, subclass `OrchidAgent` in your consumer project and reference it by dotted import path in `agents.yaml`:

```python
from __future__ import annotations

from orchid_ai.core.agent import OrchidAgent
from orchid_ai.core.scopes import OrchidRAGScope
from orchid_ai.core.state import OrchidAgentState

class CatalogAgent(OrchidAgent):
    @property
    def name(self) -> str:
        return "catalog"

    @property
    def description(self) -> str:
        return "Searches the product catalog and answers inventory questions."

    async def run(self, state: OrchidAgentState) -> dict:
        query = self.extract_user_query(state)
        history = self.extract_conversation_history(state)

        # Retrieve relevant catalog chunks (scope built from the injected auth)
        auth = self._current_auth
        scope = OrchidRAGScope(tenant_id=auth.tenant_key, user_id=auth.user_id)
        rag_context = await self.fetch_rag_context(query, scope)

        # Synthesise a response using the injected chat model
        response = await self.summarise(
            query,
            mcp_data={},
            rag_data=rag_context,
            system_prompt="You are a catalog specialist...",
            conversation_history=history,
        )
        return {"messages": [response]}
```

Wire it up in config:

```yaml title="agents.yaml"
agents:
  catalog:
    class: myproject.agents.catalog.CatalogAgent
    description: "Searches the product catalog and answers inventory questions."
    prompt: "You are a catalog specialist..."
    rag_namespace: catalog
```

```markdown title="agents/catalog.md"
---
class: myproject.agents.catalog.CatalogAgent
description: "Searches the product catalog and answers inventory questions."
rag_namespace: catalog
---

You are a catalog specialist...
```

The framework resolves the class at startup via `importlib`. The agent inherits `summarise()`, `fetch_rag_context()`, `extract_user_query()`, and `extract_conversation_history()` from the base class — override only what you need.

> `orchid_ai/core/` imports only the Python standard library — including its own dependency-free `OrchidDocument` model (importing `langchain` or any other third-party package there is an architectural bug, enforced by a dependency-boundary test). Concrete implementations — litellm adapters, the Streamable HTTP MCP client — live in `llm_factory.py`, `mcp/`, and `agents/`; external backends (Qdrant, ChromaDB, Neo4j, SQLite, PostgreSQL) ship as separate plugin packages.
> 
> *info note.*

## LLM configuration

Orchid uses LangChain's `BaseChatModel` as its LLM abstraction. The `build_chat_model(model_string)` factory creates one from a LiteLLM-style model string, supporting OpenAI, Anthropic, Google Gemini, Groq, and Ollama out of the box. The model is configured per-agent:

```yaml title="agents.yaml"
agents:
  search:
    llm:
      model: "openai/gpt-4o-mini"
      temperature: 0.1
```

```markdown title="agents/search.md"
---
llm:
  model: "openai/gpt-4o-mini"
  temperature: 0.1
---
```

See [Multi-LLM support](/concepts/multi-llm) for the full provider matrix.

## Running tests

```bash
cd orchid
source .venv/bin/activate
pytest tests/ -x
ruff check orchid_ai/
ruff format orchid_ai/
```
