Documentation Style Guide

Every PraisonAI documentation page follows the same structure, component set, and visual language — this guide is both the reference and the example.

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Research and summarise topics clearly.",
)

agent.start("What is agentic AI?")

The user copies the opening example, runs the agent, then follows the page structure below.

Documentation Creation Process

Read the SDK source before writing anything — documentation must reflect SDK ground truth, not assumptions.

Read SDK source

Open and read the actual SDK implementation file in praisonaiagents/ before writing a single word of documentation.

# Example: reading agent source before documenting
# praisonaiagents/agent/agent.py  ← read this first
from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Research and summarize topics"
)
agent.start("What is agentic AI?")

Extract all parameters

Pull every parameter, type, default value, and description from the SDK source or config class.

# praisonaiagents/config/feature_configs.py
@dataclass
class CachingConfig:
    enabled: bool = True          # Extract: enabled, bool, True
    ttl: int = 3600               # Extract: ttl, int, 3600
    backend: str = "memory"       # Extract: backend, str, "memory"

Check existing docs

Search docs/ for related pages before creating a new one — avoid duplication, ensure consistency.

Write the page

Follow the Page Structure Template and every rule in this guide.

SDK-First Cycle

Never batch-update multiple pages without reading source for each.

Step	Action
READ	Open the actual SDK source file
UNDERSTAND	Comprehend the implementation, APIs, and behaviour
DOCUMENT	Write documentation based on SDK truth
REPEAT	Move to the next feature and restart

File Locations

Content Type	SDK Location	Docs Location
Feature configs	`praisonaiagents/config/feature_configs.py`	`docs/concepts/*.mdx`
Agent class	`praisonaiagents/agent/agent.py`	`docs/concepts/agents.mdx`
MCP integration	`praisonaiagents/mcp/mcp.py`	`docs/concepts/mcp.mdx`
Skills	`praisonaiagents/skills/`	`docs/concepts/skills.mdx`
Memory	`praisonaiagents/memory/`	`docs/concepts/memory.mdx`
Knowledge	`praisonaiagents/knowledge/`	`docs/concepts/knowledge.mdx`

Multi-SDK Reference

SDK	Source Code Path	Documentation Path	Parity Tracker
Python	Repo root `praisonaiagents/` (synced copy; upstream: `praisonai-package/src/praisonai-agents/`)	`docs/concepts/`, `docs/features/`	`docs/features/DOCS_PARITY.md`
TypeScript/JS	`praisonai-package/src/praisonai-ts/src/`	`docs/js/`	`docs/js/DOCS_PARITY.md`
Rust	`praisonai-package/src/praisonai-rust/praisonai/src/`	`docs/rust/`	`docs/rust/DOCS_PARITY.md`

The Rust crate is at praisonai-rust/praisonai/src/, not praisonai-rust/src/. The src/praisonai-rust/src/** path does not exist and was previously wired into the parity workflows — see upstream PR #4689.

Two parity trackers, two questions.PraisonAI uses two distinct parity systems — do not conflate them.

DOCS_PARITY.md (this repo, one per SDK) answers: “Does documentation exist for each SDK feature category?” Labels: ✅ Documented, ⚠️ Stub, ❌ Undocumented.
PARITY.md (main PraisonAI repo, one per non-Python SDK) answers: “Does a matching exported symbol name exist in this SDK for each Python export?” Labels: ✅ exported, ⏳ missing.

PARITY.md counts exported symbol names, not behaviour. An ✅ exported cell means the name is present in the SDK’s public surface — it does not verify the capability is reachable, wired up, or behaves like its Python counterpart. Counts include barrel re-exports, so raw totals are not directly comparable across SDKs. For capabilities with a testable contract, rely on their conformance suite rather than the PARITY.md table.

TypeScript SDK Structure
Rust SDK Structure

praisonai-ts/src/
├── agents/           # Agent implementations
├── tools/            # Tool definitions
├── memory/           # Memory implementations
├── mcp/              # MCP protocol support
├── observability/    # Tracing integrations
└── index.ts          # Main exports

praisonai-rust/praisonai/src/
├── agents/           # Agent implementations and builders
├── llm/              # LLM providers
├── tools/            # Tool system
├── memory/           # Memory stores
├── mcp/              # MCP client
├── parity/           # Parity-shim modules (config, telemetry, plugins, param_resolver)
├── display/          # Display and callbacks
├── planning/         # Planner and PlanStep
├── session/          # Session
├── streaming/        # Streaming metrics
├── sandbox/          # Sandbox config
├── embedding/        # Embedding config
├── error.rs          # Result/error helpers
└── lib.rs            # Main exports

Folder Placement Rules

Where a file lives determines who can change it — AI agents have write access to most folders but never docs/concepts/.

Critical folder rules — violations cause PRs to be rejected:

docs/concepts/ is HUMAN ONLY — requires explicit human approval. Never create or modify files here.
docs/js/ and docs/rust/ are auto-generated by the parity system — never edit manually.
If an issue mentions “concepts”, still place the file in docs/features/.

Folder	Who Can Write	Purpose
`docs/concepts/`	HUMAN ONLY	Core architecture concepts
`docs/features/`	AI agents + humans	Feature documentation, guides, integrations
`docs/tools/`	AI agents + humans	Tool-specific documentation
`docs/guides/`	AI agents + humans	How-to guides and tutorials
`docs/js/`, `docs/rust/`	Auto-generated ONLY	Managed by parity system

AI Agent Behavioural Rules

Mandatory for all AI agents working in this repository:

ALWAYS read AGENTS.md before starting work
ALWAYS read the SDK source code before documenting a feature
NEVER guess API signatures — read the actual code
NEVER create placeholder content or stub pages
NEVER modify docs.json “Concepts” group entries
ALWAYS create a feature branch (never commit to main)
ALWAYS create a PR with gh pr create
ALWAYS verify docs.json is valid JSON after modifications
ALWAYS use Mintlify components (Steps, AccordionGroup, CardGroup)
ALWAYS include a hero Mermaid diagram with the standard colour scheme

Page Structure Template

Every documentation page follows this exact skeleton.

---
title: "Feature Name"
sidebarTitle: "Feature Name"
description: "One-line description of what this feature does"
icon: "icon-name"
---

{/* One sentence explaining the feature — what it does, not how */}

{/* Hero Mermaid diagram showing the concept visually */}

## Quick Start

<Steps>
<Step title="Simple Usage">
{/* Minimal code example — enable with True */}
</Step>

<Step title="With Configuration">
{/* Code example with config class */}
</Step>
</Steps>

---

## How It Works

{/* Sequence diagram or flow diagram */}

{/* Brief explanation table */}

---

## Configuration Options

{/* Link to auto-generated SDK reference — DO NOT duplicate SDK parameters here */}

<Card title="[Feature] API Reference" icon="code" href="/docs/sdk/typescript">
  TypeScript configuration options
</Card>

---

## Common Patterns

{/* 2–3 practical usage patterns */}

---

## Best Practices

<AccordionGroup>
{/* 3–4 best practices as accordions */}
</AccordionGroup>

---

## Related

<CardGroup cols={2}>
{/* 2 related concept pages */}
</CardGroup>

Mermaid Diagram Standards

Every page starts with a hero Mermaid diagram using the standard colour scheme.

Colour Scheme

Colour	Hex	Use
Dark Red	`#8B0000`	Agents, inputs, outputs, tasks
Teal	`#189AB4`	Tools, processes, middleware
Green	`#10B981`	Success, results, completion
Amber	`#F59E0B`	Warnings, planners, intermediate steps
Indigo	`#6366F1`	Configuration, settings, options
White	`#fff`	Text — always white on coloured backgrounds
Grey	`#7C90A0`	Stroke/border colour

Diagram Types by Use Case

Use Case	Diagram Type
Feature overview	`graph LR` — flow left-to-right
Process flow	`graph TB` — steps top-to-bottom
Interactions	`sequenceDiagram` — agent-user-system interactions
Options/modes	`graph TB` with subgraphs

Hero Diagram (rendered)
Hero Diagram (source)

graph LR
    subgraph "Feature Name"
        A[📋 Input] --> B[🧠 Process]
        B --> C[✅ Output]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A input
    class B process
    class C output

Sequence Diagram (rendered)
Sequence Diagram (source)

sequenceDiagram
    participant User
    participant Agent
    participant Feature

    User->>Agent: Request
    Agent->>Feature: Process
    Feature-->>Agent: Result
    Agent-->>User: Response

Mintlify Components Usage

Every page must use <Steps>, <AccordionGroup>, and <CardGroup cols={2}> — these are not optional.

Required Components

Component	Purpose	Required In
`<Steps>`	Sequential flows	Quick Start section
`<AccordionGroup>`	Grouped content	Best Practices section
`<CardGroup cols={2}>`	Related links	Related section
`<Tabs>`	Multi-language examples	Code comparison
`<Note>` / `<Warning>` / `<Tip>`	Callouts	Context-dependent

Component Syntax

Steps:

<Steps>
<Step title="First Step">
Content here.
</Step>
<Step title="Second Step">
Content here.
</Step>
</Steps>

AccordionGroup:

<AccordionGroup>
<Accordion title="Best Practice Title">
Content here.
</Accordion>
<Accordion title="Another Practice">
Content here.
</Accordion>
</AccordionGroup>

CardGroup:

<CardGroup cols={2}>
<Card title="Card Title" icon="icon-name" href="/docs/sdk">
Card description.
</Card>
<Card title="Card Title" icon="icon-name" href="/docs/sdk">
Card description.
</Card>
</CardGroup>

Tabs:

<Tabs>
<Tab title="Python">
```python
code here
```
</Tab>
<Tab title="TypeScript">
```typescript
code here
```
</Tab>
</Tabs>

Code Example Standards

Every example must run without modification — copy-paste success is the bar.

Code Quality Rules

Run without modification (copy-paste success)
Include ALL necessary imports
Use realistic but simple data
Be the shortest way to accomplish the task
Show the feature being documented, not unrelated features

Import Patterns

Use these exact imports — no complex sub-module paths:

# Single agent
from praisonaiagents import Agent

# Agent with planning
from praisonaiagents import Agent, PlanningConfig

# Multi-agent
from praisonaiagents import Agent, Task, PraisonAIAgents

# MCP
from praisonaiagents import Agent
from praisonaiagents.mcp import MCP

# Workflows — use simple import, not sub-module
from praisonaiagents import when, parallel, loop

Simple Quick Start Example

from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Research and summarize topics",
    feature=True
)

agent.start("What is agentic AI?")

Config Class Example

from praisonaiagents import Agent, PlanningConfig

agent = Agent(
    name="Research Agent",
    instructions="Research and summarize topics",
    planning=PlanningConfig(
        model="gpt-4o",
        verbose=True
    )
)

agent.start("Plan a research strategy for AI safety")

Configuration Table Format

Document every SDK option in this format:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option_name` | `type` | `default` | What it does |

Writing Style

Concise, active voice, direct — after reading a page, users should think “is it really this easy?”

Do / Don’t

Principle	Do	Don’t
Concise	”Planning breaks tasks into steps"	"Planning is a feature that allows agents to break down complex tasks into smaller, more manageable steps”
Active voice	”Enable planning with `planning=True`"	"Planning can be enabled by setting the planning parameter to True”
Direct	”Use `gpt-4o` for planning"	"It is recommended that you consider using gpt-4o for planning”
Specific	”Set `timeout=60` for slow servers"	"Increase the timeout if needed”

Section Introductions

Each section starts with exactly one sentence — no multi-sentence preamble.

✅ Good: "Planning enables agents to think before acting."
❌ Bad:  "Planning is a powerful feature that enables agents to think before acting.
          It allows them to break down complex tasks into smaller steps."

Forbidden phrases — never use these:

“In this section, we will…”
“As you can see…”
“It’s important to note that…”
“Please note that…”
“Let’s take a look at…”
“The following example shows…”

Configuration Documentation Pattern

Features support multiple configuration levels — document each level the feature actually supports. Precedence ladder: Instance > Config > Array > Dict > String > Bool > Default

# Level 1: Bool (simplest)
agent = Agent(feature=True)

# Level 2: String
agent = Agent(feature="option_name")

# Level 3: Dict
agent = Agent(feature={"option": "value", "enabled": True})

# Level 4: Array
agent = Agent(feature=["option1", "option2"])

# Level 5: Config class
agent = Agent(feature=FeatureConfig(option="value"))

# Level 6: Instance (full control)
feature_instance = Feature(option="value")
agent = Agent(feature=feature_instance)

SDK Config Extraction

When reading feature_configs.py, extract every field:

@dataclass
class FeatureConfig:
    option1: str = "default"       # Extract: option1, str, "default"
    option2: bool = False          # Extract: option2, bool, False
    option3: Optional[int] = None  # Extract: option3, int, None

Convert to documentation table:

Option	Type	Default	Description
`option1`	`str`	`"default"`	Description from docstring
`option2`	`bool`	`False`	Description from docstring
`option3`	`int`	`None`	Description from docstring

Mintlify Frontmatter

All four fields are required on every page.

---
title: "Feature Name"           # Display title
sidebarTitle: "Feature Name"    # Sidebar title (usually same as title)
description: "One-line desc"    # Meta description
icon: "icon-name"               # Lucide icon name
---

Icon Selection

Feature Type	Icon
Planning	`list-check`
Reflection	`rotate`
Skills	`puzzle-piece`
Hooks	`webhook`
Autonomy	`robot`
Output	`display`
Execution	`play`
Caching	`database`
Templates	`file-code`
Web	`globe`
MCP	`plug`
Memory	`brain`
Knowledge	`book`
Tools	`wrench`
Agents	`user`

Quality Checklist

Run through this before submitting any documentation page.

Structure

Frontmatter complete (title, sidebarTitle, description, icon)
Hero Mermaid diagram present
Quick Start uses <Steps> component
Configuration Options table complete
Best Practices uses <AccordionGroup>
Related section uses <CardGroup cols={2}>

SDK Accuracy

Code Quality

All examples run without modification
All imports included
Examples are minimal (shortest way to accomplish the task)
No placeholder values like "your-key-here"

Diagrams

Colour scheme matches standard (#8B0000, #189AB4, #10B981, #F59E0B, #6366F1)
White text on coloured backgrounds (color:#fff)
classDef declarations present
Diagram explains the concept visually

Writing

One-sentence section intros
No forbidden phrases
Active voice throughout
Concise explanations

Complete Page Example

A full Caching page demonstrating every rule in this guide.

---
title: "Caching"
sidebarTitle: "Caching"
description: "Cache LLM responses to reduce costs and latency"
icon: "database"
---

Caching stores LLM responses to avoid redundant API calls, reducing costs and improving response times.

````mermaid
graph LR
    subgraph "Caching Flow"
        Request[📝 Request] --> Check{🔍 Cache?}
        Check -->|Hit| Return[⚡ Return]
        Check -->|Miss| LLM[🤖 LLM]
        LLM --> Store[💾 Store]
        Store --> Return
    end

    classDef request fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef cache fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Request request
    class Check,Store cache
    class LLM,Return result
````

## Quick Start

<Steps>
<Step title="Enable Caching">
````python
from praisonaiagents import Agent

agent = Agent(
    name="Research Agent",
    instructions="Answer questions concisely",
    cache=True
)

agent.start("What is machine learning?")
````
</Step>

<Step title="Configure Cache">
````python
from praisonaiagents import Agent, CachingConfig

agent = Agent(
    name="Research Agent",
    instructions="Answer questions concisely",
    cache=CachingConfig(
        ttl=3600,
        backend="memory"
    )
)

agent.start("What is machine learning?")
````
</Step>
</Steps>

---

## How It Works

````mermaid
sequenceDiagram
    participant User
    participant Agent
    participant Cache
    participant LLM

    User->>Agent: Request
    Agent->>Cache: Check cache
    Cache-->>Agent: Miss
    Agent->>LLM: Send prompt
    LLM-->>Agent: Response
    Agent->>Cache: Store response
    Agent-->>User: Response

    User->>Agent: Same request
    Agent->>Cache: Check cache
    Cache-->>Agent: Hit
    Agent-->>User: Cached response
````

---

## Best Practices

<AccordionGroup>
<Accordion title="Set TTL based on data freshness">
Use short TTL (300s) for frequently changing data, longer TTL (3600s) for stable content.
</Accordion>
<Accordion title="Use disk backend for persistence">
Memory cache resets on restart — use `backend="disk"` to persist across sessions.
</Accordion>
</AccordionGroup>

---

## Related

<CardGroup cols={2}>
<Card title="Planning" icon="list-check" href="/docs/features/planning-mode">
  Plan before executing to improve accuracy.
</Card>
<Card title="Memory" icon="brain" href="/docs/features/advanced-memory">
  Store and retrieve long-term information.
</Card>
</CardGroup>

Contributing Guide

How to fork, clone, and submit pull requests to PraisonAI.

AGENTS.md on GitHub

The source-of-truth instructions file this guide mirrors.

​Documentation Creation Process

​SDK-First Cycle

​File Locations

​Multi-SDK Reference

​Folder Placement Rules

​AI Agent Behavioural Rules

​Page Structure Template

​Mermaid Diagram Standards

​Colour Scheme

​Diagram Types by Use Case

​Mintlify Components Usage

​Required Components

​Component Syntax

​Code Example Standards

​Configuration Table Format

​Writing Style

​Do / Don’t

​Section Introductions

​Configuration Documentation Pattern

​SDK Config Extraction

​Mintlify Frontmatter

​Icon Selection

​Quality Checklist

​Complete Page Example

​Related

Contributing Guide

AGENTS.md on GitHub

Documentation Creation Process

SDK-First Cycle

File Locations

Multi-SDK Reference

Folder Placement Rules

AI Agent Behavioural Rules

Page Structure Template

Mermaid Diagram Standards

Colour Scheme

Diagram Types by Use Case

Mintlify Components Usage

Required Components

Component Syntax

Code Example Standards

Configuration Table Format

Writing Style

Do / Don’t

Section Introductions

Configuration Documentation Pattern

SDK Config Extraction

Mintlify Frontmatter

Icon Selection

Quality Checklist

Complete Page Example

Related