SDK Architecture

Package Hierarchy

Core SDK Modules

agent/

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

tools/

Purpose: Tool SDK and registry

File	Description
`base.py`	BaseTool class
`decorator.py`	@tool decorator
`registry.py`	ToolRegistry
`protocols/tool_protocol.py`	ToolProtocol

memory/

Purpose: Memory persistence

File	Description
`protocols.py`	MemoryProtocol, DeletableMemoryProtocol
`memory.py`	Memory implementation
`file_memory.py`	File-based adapter

hooks/

Purpose: Hook system and middleware

File	Description
`events.py`	Hook event types
`registry.py`	Hook registration
`middleware.py`	Middleware chains

workflows/

Purpose: Multi-agent coordination

File	Description
`workflows.py`	Workflow engine
Patterns	Route, Parallel, Loop, Repeat

bus/

Purpose: Event bus for pub/sub

File	Description
`bus.py`	EventBus class
`event.py`	Event types

Data Flow

Extension Points

Tools

Add capabilities via @tool decorator or BaseTool

Hooks

Intercept events with before_tool, after_tool, etc.

Memory

Custom adapters implementing MemoryProtocol

Workflows

Multi-agent patterns with Route, Parallel, Loop

Repository Map

Core SDK
Wrapper
Examples
Documentation

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

praisonai-package/src/praisonai/
├── praisonai/
│   ├── cli/           # CLI commands
│   ├── integrations/  # External integrations
│   ├── ui/            # UI components
│   ├── deploy/        # Deployment tools
│   └── api/           # API server
└── pyproject.toml

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)

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

Design Methodology

Protocol First

Define abstract interfaces before implementations

class MemoryProtocol(Protocol):
    def store(self, text: str) -> str: ...
    def search(self, query: str) -> List: ...

Lightweight Core

Keep praisonaiagents minimal - protocols, hooks, base classes only

Heavy in Wrapper

Database integrations, CLI, UI go in praisonai wrapper

Optional Dependencies

Use pip install praisonaiagents[memory] for extras

Lazy Loading

Import heavy deps inside functions, not at module level

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`

Getting Started

Core Concepts

Guides

Memory

Knowledge

RAG

Features

Image Agents

Video Agents

Audio Agents

OCR

Models

Persistence

Databases

Observability

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Package Hierarchy

Core SDK Modules

Data Flow

Extension Points

Tools

Hooks

Memory

Workflows

Repository Map

Design Methodology

Key Files Reference

Getting Started

Core Concepts

Guides

Memory

Knowledge

RAG

Features

Image Agents

Video Agents

Audio Agents

OCR

Models

Persistence

Databases

Observability

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

​Package Hierarchy

​Core SDK Modules

​Data Flow

​Extension Points

Tools

Hooks

Memory

Workflows

​Repository Map

​Design Methodology

​Key Files Reference

Package Hierarchy

Core SDK Modules

Data Flow

Extension Points

Repository Map

Design Methodology

Key Files Reference