Skip to content

PAR Documentation

PAR's docs are SDK-first. PAR is an embeddable runtime — production code uses the OCaml SDK directly, and Python code calls the same runtime via ctypes bindings. If you're building an agent, start with the SDK overview and the agent API reference.

The docs are organized by purpose, not by source-tree layout. Four sections follow: Tutorials walk you through a complete task from scratch, How-to guides solve a specific problem, Reference documents every API, and Explanation discusses the design decisions. Pick the section that matches your question; cross-links inside each page point at related material.

Every page in this tree opens with a <!-- language: en --> marker on line 1, ships English only, and preserves OCaml identifiers verbatim (backticks, not code blocks). Contributors should read CONTRIBUTING.md before opening a doc PR — it covers the authoring contract, the identifier list, and the pre-release checklist.

The audience for this tree is two groups: SDK users who embed par in their applications (OCaml or Python), and contributors who extend the runtime with a new provider, tool, or middleware. The four sections below serve both, and each page is written so a fresh reader can act on it without first reading the rest of the tree.

Tutorials

Tutorials walk you through a complete task from scratch. Start here if you're new to PAR. The quickstart below installs the SDK, configures an LLM provider, and runs an agent with a single tool end-to-end; later tutorials build on the same setup.

Document Time What you'll build
Quickstart 30 min An agent with one tool, run end-to-end
01: RAG Q&A Bot 30 min A PDF-style Q&A bot: embed, index, retrieve, answer
02: Streaming UI 25 min Consume invoke_stream into a live-updating TTY UI
04: Multi-Provider Fallback — stub
05: Session Resume — stub

How-to guides

How-to guides solve specific problems. Skip to the one you need. Each guide assumes you have already completed the quickstart and have a working par install, and each one ends with a short checklist you can run to confirm the change took effect.

If you are looking for a one-paragraph answer to a setup or runtime question, the FAQ is the fastest entry point. For deeper recipes, the table below is grouped by topic so you can jump straight to the area that matches your problem.

Concurrency & scaling

Concurrency patterns: 3 layers of parallelism: Runtime, Fiber, Tool.

Provider integration

Custom LLM provider: register Cohere, Mistral, Ollama, or any OpenAI-compatible endpoint.

Operations & reliability

Error handling: error_category classification, recovery strategies, event-bus auditing.

Common questions

FAQ: 6 common questions answered (PAR vs LangChain, picking a surface, streaming behavior, persistence, provider support, the skill system).

Reference

Reference docs are the API source of truth. Look here for type signatures, configuration options, and Python/OCaml binding details. PAR is an SDK — the reference IS the product; there is no separate "user-facing" surface beyond the bindings.

The SDK is the canonical surface. Every page below is marked PRIMARY because it documents a public API of the par package. If a behavior changes in code, these pages are updated first.

Document Description
SDK overview PRIMARY: the SDK hub (architecture, five-minute tour, module map)
Agent API PRIMARY: Agent config, Runtime API, tool registration, ReAct loop
HITL API PRIMARY: Human-in-the-Loop approval (suspend-resume, persistent, cross-process)
Parallel Dispatch PRIMARY: parallel multi-agent dispatch with typed merge
Invoke Context PRIMARY: per-call isolation via Fiber.key binding
Workflow API PRIMARY: workflow JSON, 8 step types, checkpoints
Middleware API PRIMARY: 9 built-in middlewares and how to write your own
Tools API PRIMARY: all 23 built-in tools including type-safe bash
Streaming API PRIMARY: invoke_stream, 5-event tagged union, backpressure, 3 runnable examples
Generate API PRIMARY: invoke_generate, long-output generation mode, auto-continue on truncation
RAG API Embeddings, vector store, chunking, invoke_with_rag
Document Loaders PRIMARY: load text, Markdown, HTML, CSV, PDF into Document.t for RAG
Memory API PRIMARY: cross-session memory with FTS5 + 3 builtin tools
Persistence API PRIMARY: SQLite + Noop backends
MCP Client API PRIMARY: MCP client (stdio + HTTP/SSE), 7 event types, server lifecycle
Skills API Reusable prompt + tool bundles with trigger conditions
Observability Metrics, health endpoints, event bus, structured logging
Prompt Caching Cache system prompts and repeated context to reduce latency and cost
Content Blocks Structured content blocks for multimodal and typed message parts

Explanation

Explanation docs discuss the why behind PAR's design. Read these when you want to understand the type system, concurrency model, or how an invoke flows through the runtime. These pages argue for a design choice; reference pages simply document the current state.

Architecture

Architecture deep dive: core abstractions, module structure, data flow, type system, Eio concurrency, event stream.

Common questions

FAQ: 6 common questions answered (PAR vs LangChain, picking a surface, streaming behavior, persistence, provider support, the skill system).

Doc internals

Documentation maintenance: identifier preservation, language indicator, CJK check, CI integration — see CONTRIBUTING.md.

Project-level documents that live outside the four sections above.