Documentation Style Guide

from praisonaiagents import Agent

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

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

---
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/reference/typescript/classes/[FeatureConfig]">
  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>

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

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

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

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

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

✅ 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."

# 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)

@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

---
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
---

---
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>