<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/10.1-praisonaiagents-package -->

# praisonaiagents Package

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

The `praisonaiagents` package is the core framework package that provides the agent system, tools, memory, workflows, and all supporting infrastructure. This document covers the package structure, public API exports, lazy loading architecture, and the organization of 186+ symbols available to users.

For information about the application layer (CLI, deployment, UI systems), see [praisonai Package](/MervinPraison/PraisonAI/10.2-praisonai-package). For detailed lazy loading mechanics, see [Lazy Loading System](/MervinPraison/PraisonAI/10.3-lazy-loading-system).

## Package Purpose and Scope

The `praisonaiagents` package serves as the foundational framework for building AI agent applications. It provides:

- Core Agent System : Agent class with LLM integration, tools, memory, and planning capabilities
- Multi-Agent Orchestration : Agents class for coordinating multiple agents with shared state
- Tool Ecosystem : Decorator-based tool registration, MCP protocol support, and 100+ built-in tools
- Memory & Knowledge : Multiple storage backends (SQLite, Redis, Postgres, MongoDB, Mem0) and RAG pipeline
- Workflow Engine : Control flow operators (Route, Parallel, Loop, Repeat) for complex orchestration
- Safety Systems : Guardrails, reflection, and human-in-the-loop approval workflows

The package is designed with performance in mind, using lazy loading to reduce import time from ~3500ms to ~20ms. All heavy dependencies (LiteLLM, Rich, vector stores) are loaded on-demand when first accessed.

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

## Package Structure

```

```

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

## Public API Design

The package uses a two-tier API design:

1. Minimal __all__ exports (12 items): Core essentials for clean IDE autocomplete
2. Full __getattr__ resolution (186+ items): Complete backward compatibility via lazy loading

### Core Exports ( all )

The `__all__` list defines what appears in IDE autocomplete and `from praisonaiagents import *`:

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py535-560](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L535-L560)

### Import Patterns

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py62-73](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L62-L73) [src/praisonai-agents/praisonaiagents/__init__.py430-437](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L430-L437)

## Lazy Import System

The package uses a centralized lazy loading utility to minimize import time. All 186+ symbols are mapped in `_LAZY_IMPORTS` dictionary:

```

```

The `_LAZY_IMPORTS` mapping contains 186+ entries organized by category:

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py127-384](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L127-L384) [src/praisonai-agents/praisonaiagents/__init__.py101-102](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L101-L102)

### Lazy Import Mapping Structure

Each entry in `_LAZY_IMPORTS` follows the pattern:

```

```

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

## Sub-Package Organization

The package provides organized namespace imports via sub-packages:

```

```

### config Sub-package

Provides configuration classes and utilities:

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py71](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L71-L71)

### tools Sub-package

Provides tool system components:

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py63-67](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L63-L67) [src/praisonai-agents/praisonaiagents/__init__.py72](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L72-L72)

### memory Sub-package

Provides memory system (lazy-loaded via `__getattr__`):

- Memory class with support for 6 backends
- Backend implementations: FileMemory, SQLiteMemory, RedisMemory, PostgresMemory, Mem0Memory, MongoDBMemory

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

### workflows Sub-package

Provides workflow engine components:

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py144-156](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L144-L156)

## Package Initialization

The package performs several initialization steps when imported:

```

```

### Namespace Package Guard

Detects if the package is loaded as a namespace package (stale artifacts in site-packages):

```

```

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

### Warning Patch

Applies warning filters to suppress noisy warnings from dependencies:

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py51](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L51-L51)

### Logging Configuration

Configures centralized logging:

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py53-57](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L53-L57)

### Telemetry Initialization

Optionally initializes telemetry if `TELEMETRY_ENABLED` is set:

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py441-468](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L441-L468)

## Backward Compatibility

The package maintains full backward compatibility with legacy exports:

### Deprecated Imports

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py392-402](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L392-L402)

### Custom Handler

The `_custom_handler` function provides special case handling for:

1. Deprecated imports (e.g., PraisonAIAgents )
2. Module imports (e.g., memory , workflows )

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py387-412](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L387-L412)

## Performance Optimization

The package includes a `warmup()` function to pre-import heavy dependencies:

```

```

Returns timing information:

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py471-524](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L471-L524)

## API Reference Export

The package generates an API reference in `api.md` with 186+ methods organized by category:

**Sources**: [api.md1-146](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L1-L146)

## Usage Examples

### Basic Import

```

```

**Sources**: [examples/consolidated_params/basic_agent.py1-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/basic_agent.py#L1-L19)

### Sub-package Import

```

```

**Sources**: [examples/consolidated_params/README.md1-97](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/examples/consolidated_params/README.md?plain=1#L1-L97)

### Legacy Import (Lazy-loaded)

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py577-593](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L577-L593)

## Thread Safety

The lazy loading system is thread-safe using `threading.local()`:

```

```

**Sources**: [src/praisonai-agents/praisonaiagents/__init__.py107-118](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/__init__.py#L107-L118)

## Summary

The `praisonaiagents` package provides:

1. Minimal Core Exports : 12 essential symbols in __all__ for clean IDE autocomplete
2. Full Lazy Loading : 186+ symbols available via __getattr__ with thread-safe caching
3. Organized Sub-packages : config , tools , memory , workflows for namespace imports
4. Performance Optimized : Import time reduced from ~3500ms to ~20ms via lazy loading
5. Backward Compatible : All legacy imports continue to work with deprecation warnings
6. Production Ready : Namespace package guard, telemetry, logging configuration

The package architecture balances developer experience (clean autocomplete) with backward compatibility (all legacy imports work) while maintaining high performance through intelligent lazy loading.

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