> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Architecture

> Three-tier Python package model (C7.1), SDK structure, and design methodology

## Three-Tier Package Model (C7.1)

**Current release:** v4.6.110 · `praisonaiagents` 1.6.110 · `praisonai-code` 0.0.8 · `praisonai` 4.6.110

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph tier1 ["Tier 1 — praisonaiagents (Core SDK)"]
        PROTO[Protocols]
        HOOKS[Hooks and Events]
        BASE[Base Classes]
        AGENT[Agent / Tools / Memory]
    end

    subgraph tier2 ["Tier 2 — praisonai-code (Terminal CLI)"]
        RUN[run / chat / code]
        TYPER[Typer CLI]
        RUNTIME[Runtime / LLM / Tools]
    end

    subgraph tier3 ["Tier 3 — praisonai (Wrapper)"]
        CLI[Gateway / Bots / Serve]
        ADAPT[framework_adapters]
        INT[Integrations]
    end

    subgraph external ["External"]
        TOOLS[praisonai-tools]
    end

    AGENT --> RUN
    AGENT --> CLI
    PROTO --> RUN
    PROTO --> CLI
    RUN -.->|"lazy bridge only"| CLI
    TOOLS --> PROTO

    classDef core fill:#8B0000,color:#fff
    classDef code fill:#189AB4,color:#fff
    classDef wrapper fill:#4a5568,color:#fff
    classDef external fill:#4a4a4a,color:#fff

    class PROTO,HOOKS,BASE,AGENT core
    class RUN,TYPER,RUNTIME code
    class CLI,ADAPT,INT wrapper
    class TOOLS external
```

<Note>
  **Dependency rule:** `praisonai-code` does **not** declare `praisonai` in `pyproject.toml`.
  Standalone `pip install praisonai-code` runs `run`/`chat`/`code` without the wrapper.
  Optional wrapper features use lazy imports via `_wrapper_bridge` only.
</Note>

| Tier | Package           | Install                       | Owns                                            |
| ---- | ----------------- | ----------------------------- | ----------------------------------------------- |
| 1    | `praisonaiagents` | `pip install praisonaiagents` | Agent, tools, memory, hooks, protocols          |
| 2    | `praisonai-code`  | `pip install praisonai-code`  | Terminal CLI, runtime, LLM, tool resolution     |
| 3    | `praisonai`       | `pip install praisonai`       | Gateway, bots, framework adapters, train, serve |

**Publish order:** `praisonaiagents` → `praisonai-code` → `praisonai`

<CardGroup cols={2}>
  <Card title="C7.1 Boundaries" icon="shield" href="https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/tests/C7.1_BOUNDARIES.md">
    Full boundary spec, invocation matrix, sign-off
  </Card>

  <Card title="C8+ Backlog" icon="road" href="https://github.com/MervinPraison/PraisonAI/blob/main/src/praisonai/tests/C8_BACKLOG.md">
    Future package splits and import reduction plan
  </Card>
</CardGroup>

***

## CLI routing

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart LR
    User[User] --> Entry{Entry point}
    Entry -->|praisonai-code| CodeCLI["run / chat / code"]
    Entry -->|praisonai| WrapperCLI["Full CLI"]
    WrapperCLI --> Router["Typer-first router"]
    Router --> CodePath["praisonai_code.cli.app"]
    Router --> Legacy["Legacy YAML / frameworks"]
    CodePath --> HotPath["Agentic hot path"]
    CodePath --> Bridge{"Wrapper installed?"}
    Bridge -->|yes| BotCmds["bot, gateway, pairing, …"]
    Bridge -->|no| Hidden["Wrapper commands hidden"]
```

| Command                                               | `praisonai-code` only | Full `praisonai` |
| ----------------------------------------------------- | --------------------- | ---------------- |
| `praisonai-code run "prompt"`                         | Yes                   | Yes              |
| `praisonai gateway …`                                 | No                    | Yes              |
| `praisonai run --file agents.yaml --framework crewai` | No                    | Yes              |

***

## Package Hierarchy (legacy view)

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "User Code"
        U[Your Application]
    end
    
    subgraph "praisonai (Wrapper)"
        CLI[CLI Commands]
        INT[Integrations]
        HEAVY[Heavy Implementations]
    end
    
    subgraph "praisonaiagents (Core SDK)"
        PROTO[Protocols]
        HOOKS[Hooks & Events]
        BASE[Base Classes]
        DEC[Decorators]
    end
    
    subgraph "praisonai-tools (External)"
        TOOLS[Community Tools]
        PLUGINS[Plugins]
    end
    
    U --> CLI
    U --> PROTO
    CLI --> PROTO
    INT --> PROTO
    HEAVY --> PROTO
    TOOLS --> PROTO
    PLUGINS --> PROTO
    
    classDef core fill:#189AB4,color:#fff
    classDef wrapper fill:#8B0000,color:#fff
    classDef external fill:#4a4a4a,color:#fff
    
    class PROTO,HOOKS,BASE,DEC core
    class CLI,INT,HEAVY wrapper
    class TOOLS,PLUGINS external
```

***

## Core SDK Modules

<AccordionGroup>
  <Accordion title="agent/" icon="robot">
    **Purpose:** Agent class and execution

    | File           | Description                          |
    | -------------- | ------------------------------------ |
    | `agent.py`     | Main Agent class (6549 LOC)          |
    | `protocols.py` | AgentProtocol, RunnableAgentProtocol |
    | `handoff.py`   | Agent-to-agent handoff               |
    | `autonomy.py`  | Autonomous execution                 |
  </Accordion>

  <Accordion title="tools/" icon="wrench">
    **Purpose:** Tool SDK and registry

    | File                         | Description     |
    | ---------------------------- | --------------- |
    | `base.py`                    | BaseTool class  |
    | `decorator.py`               | @tool decorator |
    | `registry.py`                | ToolRegistry    |
    | `protocols/tool_protocol.py` | ToolProtocol    |
  </Accordion>

  <Accordion title="memory/" icon="brain">
    **Purpose:** Memory persistence

    | File             | Description                             |
    | ---------------- | --------------------------------------- |
    | `protocols.py`   | MemoryProtocol, DeletableMemoryProtocol |
    | `memory.py`      | Memory implementation                   |
    | `file_memory.py` | File-based adapter                      |
  </Accordion>

  <Accordion title="hooks/" icon="link">
    **Purpose:** Hook system and middleware

    | File            | Description       |
    | --------------- | ----------------- |
    | `events.py`     | Hook event types  |
    | `registry.py`   | Hook registration |
    | `middleware.py` | Middleware chains |
  </Accordion>

  <Accordion title="workflows/" icon="diagram-project">
    **Purpose:** Multi-agent coordination

    | File           | Description                   |
    | -------------- | ----------------------------- |
    | `workflows.py` | Workflow engine               |
    | Patterns       | Route, Parallel, Loop, Repeat |
  </Accordion>

  <Accordion title="bus/" icon="tower-broadcast">
    **Purpose:** Event bus for pub/sub

    | File       | Description    |
    | ---------- | -------------- |
    | `bus.py`   | EventBus class |
    | `event.py` | Event types    |
  </Accordion>
</AccordionGroup>

***

## Data Flow

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant U as User
    participant A as Agent
    participant L as LLM
    participant T as Tool
    participant M as Memory
    
    U->>A: start(prompt)
    A->>M: search context
    M-->>A: relevant memories
    A->>L: chat completion
    L-->>A: response + tool calls
    A->>T: execute tool
    T-->>A: result
    A->>M: store interaction
    A-->>U: final response
```

***

## Extension Points

<CardGroup cols={2}>
  <Card title="Tools" icon="wrench" href="/docs/tools">
    Add capabilities via @tool decorator or BaseTool
  </Card>

  <Card title="Hooks" icon="link" href="/docs/features/hooks">
    Intercept events with before\_tool, after\_tool, etc.
  </Card>

  <Card title="Memory" icon="brain" href="/docs/memory/overview">
    Custom adapters implementing MemoryProtocol
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/docs/features/workflows">
    Multi-agent patterns with Route, Parallel, Loop
  </Card>
</CardGroup>

***

## Repository Map

<Tabs>
  <Tab title="Core SDK">
    ```
    praisonai-package/src/praisonai-agents/
    ├── praisonaiagents/
    │   ├── agent/         # Agent execution
    │   ├── agents/        # Multi-agent (Agents class)
    │   ├── tools/         # Tool SDK
    │   ├── memory/        # Memory adapters
    │   ├── hooks/         # Hook system
    │   ├── workflows/     # Workflow engine
    │   ├── bus/           # Event bus
    │   ├── policy/        # Policy engine
    │   ├── knowledge/     # RAG/Knowledge
    │   ├── context/       # Context management
    │   ├── trace/         # Tracing
    │   └── eval/          # Evaluation
    ├── tests/             # Test suite
    └── AGENTS.md          # This guide
    ```
  </Tab>

  <Tab title="Terminal CLI (praisonai-code)">
    ```
    praisonai-package/src/praisonai-code/
    ├── praisonai_code/
    │   ├── cli/             # Typer app, run/chat/code commands
    │   ├── llm/             # Credentials, catalogue, config
    │   ├── _wrapper_bridge.py  # Lazy wrapper access
    │   └── tool_resolver.py
    └── pyproject.toml       # No praisonai PyPI dependency
    ```
  </Tab>

  <Tab title="Wrapper (praisonai)">
    ```
    praisonai-package/src/praisonai/
    ├── praisonai/
    │   ├── cli/commands/    # bot, gateway, pairing, …
    │   ├── framework_adapters/  # CrewAI, AutoGen, PraisonAI
    │   ├── bots/            # BotOS platform adapters
    │   ├── gateway/         # WebSocket gateway
    │   └── integrations/    # External integrations
    └── pyproject.toml       # Depends on praisonai-code + praisonaiagents
    ```
  </Tab>

  <Tab title="Examples">
    ```
    praisonai-package/examples/
    ├── agent_tools/       # Tool examples
    ├── async_runs/        # Async patterns
    ├── background/        # Background tasks
    ├── checkpoints/       # State checkpoints
    ├── eval/              # Evaluation
    ├── guardrails/        # Safety examples
    ├── hooks/             # Hook examples
    ├── knowledge/         # RAG examples
    ├── memory/            # Memory examples
    ├── multi_agent/       # Multi-agent
    ├── observability/     # Monitoring
    ├── policy/            # Policy examples
    ├── streaming/         # Streaming
    ├── workflows/         # Workflow patterns
    └── ... (65+ categories)
    ```
  </Tab>

  <Tab title="Documentation">
    ```
    PraisonAIDocs/docs/
    ├── agents/            # Agent guides
    ├── api/               # API reference
    ├── capabilities/      # Features
    ├── cli/               # CLI reference
    ├── concepts/          # Core concepts
    ├── features/          # Feature guides
    ├── guides/            # How-to guides
    ├── knowledge/         # Knowledge/RAG
    ├── memory/            # Memory guides
    ├── models/            # LLM configuration
    ├── observability/     # Monitoring
    ├── sdk/               # SDK reference
    ├── tools/             # Tool guides
    └── tutorials/         # Tutorials
    ```
  </Tab>
</Tabs>

***

## Design Methodology

<Steps>
  <Step title="Three Tiers">
    `praisonaiagents` (core) → `praisonai-code` (terminal CLI) → `praisonai` (wrapper).
    Code tier must not PyPI-depend on the wrapper.
  </Step>

  <Step title="Protocol First">
    Define abstract interfaces before implementations

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    class MemoryProtocol(Protocol):
        def store(self, text: str) -> str: ...
        def search(self, query: str) -> List: ...
    ```
  </Step>

  <Step title="Lightweight Core">
    Keep praisonaiagents minimal - protocols, hooks, base classes only
  </Step>

  <Step title="Heavy in Wrapper">
    Gateway, bots, framework adapters, and heavy integrations stay in `praisonai`
  </Step>

  <Step title="Optional Dependencies">
    Use `pip install praisonaiagents[memory]` for extras
  </Step>

  <Step title="Lazy Loading">
    Import heavy deps inside functions, not at module level
  </Step>
</Steps>

***

## Key Files Reference

| What             | Location                                 |
| ---------------- | ---------------------------------------- |
| Agent class      | `praisonaiagents/agent/agent.py`         |
| Tool decorator   | `praisonaiagents/tools/decorator.py`     |
| BaseTool         | `praisonaiagents/tools/base.py`          |
| Memory protocols | `praisonaiagents/memory/protocols.py`    |
| Hook events      | `praisonaiagents/hooks/events.py`        |
| Event bus        | `praisonaiagents/bus/bus.py`             |
| Workflow engine  | `praisonaiagents/workflows/workflows.py` |
| Policy engine    | `praisonaiagents/policy/engine.py`       |
| Package exports  | `praisonaiagents/__init__.py`            |
| AGENTS guide     | `praisonai-agents/AGENTS.md`             |