<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/10-package-system -->

# Package System

- .gitignore
- src/praisonai-agents/praisonaiagents/__init__.py

This document describes the package architecture of PraisonAI, covering the structure of the two main packages (`praisonaiagents` and `praisonai`), the lazy loading system that minimizes import overhead, dependency management with optional feature groups, and the module organization strategy. The package system is designed around three core principles: zero overhead when features are unused, modular installation with optional dependencies, and full backward compatibility through dynamic imports.

For installation instructions and package variants, see [Installation](/MervinPraison/PraisonAI/1.3-installation). For development environment setup, see [Development Environment](/MervinPraison/PraisonAI/9.3-development-environment).

## Package Overview

PraisonAI consists of two separate Python packages with different purposes:

The separation enables users to choose their level of abstraction. Advanced users can use `praisonaiagents` directly for maximum control, while users who prefer declarative configurations can use the `praisonai` wrapper.

```

```

Sources: [src/praisonai-agents/praisonaiagents/__init__.py1-698](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L1-L698)

## Package Structure and Separation

### praisonaiagents (Core Library)

The `praisonaiagents` package provides the core agent execution engine. It is a standalone library that can be used independently of the wrapper package.

**Key characteristics:**

- Minimal core dependencies : pydantic>=2.10.0 , rich , openai>=2.0.0 , litellm>=1.81.0 , aiohttp>=3.8.0
- Optional feature groups : Install only what you need (e.g., pip install praisonaiagents[mcp,memory] )
- Lazy loading : Heavy dependencies load on-demand to minimize startup time
- Sub-package organization : Clean namespace with config , tools , memory , workflows modules

For detailed information about the core library structure, see [praisonaiagents Package](/MervinPraison/PraisonAI/10.1-praisonaiagents-package).

### praisonai (Wrapper Package)

The `praisonai` package provides higher-level abstractions, CLI, UI, and framework integration. It depends on `praisonaiagents`.

**Key characteristics:**

- Framework integration : Supports AutoGen, CrewAI, and native execution
- CLI interface : Command-line tools for common operations
- UI support : Chainlit-based chat and web interfaces
- YAML configuration : Declarative agent definitions via agents.yaml

For detailed information about the wrapper package, see [praisonai Package](/MervinPraison/PraisonAI/10.2-praisonai-package).

```

```

Sources: [src/praisonai-agents/praisonaiagents/__init__.py1-27](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L1-L27)

## Lazy Loading Architecture

The package uses a sophisticated lazy loading system to minimize import time and memory usage. Without lazy loading, importing the package could take 420ms due to heavy dependencies like `litellm` and `rich`. With lazy loading, import time is reduced to ~20ms in silent mode.

### Lazy Loading Mechanism

The lazy loading system is implemented using Python's `__getattr__` protocol at the module level. When an attribute is accessed that hasn't been imported yet, `__getattr__` dynamically imports it on-demand.

```

```

The `_LAZY_IMPORTS` dictionary maps 186+ attribute names to their module paths:

[src/praisonai-agents/praisonaiagents/__init__.py127-473](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L127-L473)

Key components:

For detailed information about the lazy loading implementation, see [Lazy Loading System](/MervinPraison/PraisonAI/10.3-lazy-loading-system).

Sources: [src/praisonai-agents/praisonaiagents/__init__.py94-119](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L94-L119) [src/praisonai-agents/praisonaiagents/__init__.py127-473](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L127-L473) [src/praisonai-agents/praisonaiagents/__init__.py522-528](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L522-L528)

### Namespace Package Guard

The package includes a guard against namespace package issues, which occur when stale artifacts are left in `site-packages` after partial uninstalls:

[src/praisonai-agents/praisonaiagents/__init__.py37-48](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L37-L48)

This check detects when `__file__` is `None`, indicating the package is loaded as a namespace package (directories without `__init__.py`), and provides clear remediation instructions.

Sources: [src/praisonai-agents/praisonaiagents/__init__.py27-48](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L27-L48)

## Dependency Management

### Core Dependencies

Both packages share core dependencies that are always installed:

### Optional Feature Groups

Optional dependencies are organized into logical feature groups that can be installed independently:

**praisonaiagents optional groups:**

**praisonai optional groups:**

**Installation examples:**

```

```

For detailed information about dependency constraints and version management, see [Dependency Management](/MervinPraison/PraisonAI/10.4-dependency-management).

Sources: [src/praisonai-agents/praisonaiagents/__init__.py1-6](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L1-L6)

## Module Organization

### Sub-package Structure

The `praisonaiagents` package is organized into logical sub-packages that can be imported directly:

```

```

**Import patterns:**

```

```

Sources: [src/praisonai-agents/praisonaiagents/__init__.py69-73](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L69-L73)

### Key Module Locations

Sources: [src/praisonai-agents/praisonaiagents/__init__.py127-473](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L127-L473)

## Export Strategy

The package uses a dual export strategy to balance clean IDE autocomplete with full backward compatibility:

### all List (Primary Exports)

The `__all__` list contains only the most essential exports that appear in IDE autocomplete:

[src/praisonai-agents/praisonaiagents/__init__.py626-664](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L626-L664)

**Design rationale:**

- Clean IDE experience : Only 20-30 essential items in autocomplete
- Discoverability : Most important classes are immediately visible
- Sub-package organization : Encourages organized imports like pa.config.MemoryConfig

### getattr (Full Compatibility)

All 186+ symbols are still accessible via `__getattr__` for backward compatibility:

[src/praisonai-agents/praisonaiagents/__init__.py522-528](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L522-L528)

This enables legacy code to continue working:

```

```

### Custom Handlers

Special cases require custom logic in `_custom_handler`:

[src/praisonai-agents/praisonaiagents/__init__.py476-503](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L476-L503)

**Examples:**

- Aliases : Agents -> AgentManager (with deprecation warning)
- Module imports : memory -> returns module object, not function
- Removed items : Task -> raises clear migration error

Sources: [src/praisonai-agents/praisonaiagents/__init__.py476-528](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L476-L528) [src/praisonai-agents/praisonaiagents/__init__.py626-664](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L626-L664) [src/praisonai-agents/praisonaiagents/__init__.py667-678](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L667-L678)

## Configuration System

### Centralized Configuration

Configuration is managed through `_config` module, imported early before any heavy dependencies:

[src/praisonai-agents/praisonaiagents/__init__.py59-60](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L59-L60)

### Telemetry Initialization

Telemetry is opt-in and only initialized when explicitly enabled:

[src/praisonai-agents/praisonaiagents/__init__.py532-559](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L532-L559)

The initialization:

1. Checks _config.TELEMETRY_ENABLED flag
2. Loads telemetry module lazily (only if enabled)
3. Auto-instruments if configured
4. Silently fails if any errors occur (never breaks user applications)

Sources: [src/praisonai-agents/praisonaiagents/__init__.py51-60](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L51-L60) [src/praisonai-agents/praisonaiagents/__init__.py532-559](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L532-L559)

## Performance Optimization

### Warmup Function

The `warmup()` function pre-imports heavy dependencies to reduce first-call latency:

[src/praisonai-agents/praisonaiagents/__init__.py562-615](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L562-L615)

**Key points:**

- Not needed for default usage : OpenAI SDK (~100ms) is fast enough
- Beneficial for LiteLLM : Pre-loads LiteLLM (~2-3s) for multi-provider support
- Returns timing information : Helps users measure impact

**Usage:**

```

```

### Import Time Breakdown

Sources: [src/praisonai-agents/praisonaiagents/__init__.py562-615](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L562-L615)

## Function Overrides

Some subpackage names conflict with function names. These are explicitly overridden:

[src/praisonai-agents/praisonaiagents/__init__.py507-518](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L507-L518)

This ensures that `from praisonaiagents import embedding` imports the function, not the subpackage module.

Sources: [src/praisonai-agents/praisonaiagents/__init__.py507-518](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L507-L518)

## Naming Conventions

The package follows consistent naming patterns for API design:

[src/praisonai-agents/praisonaiagents/__init__.py8-25](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L8-L25)

Sources: [src/praisonai-agents/praisonaiagents/__init__.py8-25](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L8-L25)

## Package Dependencies

```

```

Sources: [src/praisonai-agents/praisonaiagents/__init__.py1-6](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L1-L6)

## Related Pages

- For detailed praisonaiagents structure: praisonaiagents Package
- For detailed praisonai structure: praisonai Package
- For lazy loading implementation: Lazy Loading System
- For dependency specifications: Dependency Management
- For installation instructions: Installation
- For configuration system: Configuration System
