SDK Architecture - PraisonAI

Three-Tier Package Model (C7.1)

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

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.

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

C7.1 Boundaries

Full boundary spec, invocation matrix, sign-off

C8+ Backlog

Future package splits and import reduction plan

CLI routing

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)

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
Terminal CLI (praisonai-code)
Wrapper (praisonai)
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-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

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

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

Three Tiers

praisonaiagents (core) → praisonai-code (terminal CLI) → praisonai (wrapper). Code tier must not PyPI-depend on the wrapper.

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

Gateway, bots, framework adapters, and heavy integrations stay in praisonai

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`

Core Principles

Configuration Reference

​Three-Tier Package Model (C7.1)

C7.1 Boundaries

C8+ Backlog

​CLI routing

​Package Hierarchy (legacy view)

​Core SDK Modules

​Data Flow

​Extension Points

Tools

Hooks

Memory

Workflows

​Repository Map

​Design Methodology

​Key Files Reference

Three-Tier Package Model (C7.1)

CLI routing

Package Hierarchy (legacy view)

Core SDK Modules

Data Flow

Extension Points

Repository Map

Design Methodology

Key Files Reference