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

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

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

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

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

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)

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

---

Design Methodology

1. Three Tiers

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

2. Protocol First

   Define abstract interfaces before implementations

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

   Keep praisonaiagents minimal - protocols, hooks, base classes only

4. Heavy in Wrapper

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

5. Optional Dependencies

   Use pip install praisonaiagents[memory] for extras

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