<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/10.2-praisonai-package -->

# praisonai Package

- .gitignore
- docker/Dockerfile
- docker/Dockerfile.chat
- docker/Dockerfile.dev
- docker/Dockerfile.ui
- docker/README.md
- src/praisonai-agents/pyproject.toml
- src/praisonai-agents/uv.lock
- src/praisonai/praisonai.rb
- src/praisonai/praisonai/cli/main.py
- src/praisonai/praisonai/deploy.py
- src/praisonai/praisonai/version.py
- src/praisonai/pyproject.toml
- src/praisonai/uv.lock

The `praisonai` package is the application layer of PraisonAI, providing user-facing interfaces and deployment tools. It wraps the core `praisonaiagents` framework with command-line interfaces, web UIs, browser automation capabilities, and cloud deployment utilities. This package serves as the primary entry point for end users interacting with the PraisonAI system.

For information about the core agent framework and internal APIs, see [praisonaiagents Package](/MervinPraison/PraisonAI/10.1-praisonaiagents-package). For deployment configurations, see [Docker Deployment](/MervinPraison/PraisonAI/9.1-docker-deployment) and [Cloud Deployment](/MervinPraison/PraisonAI/9.2-cloud-deployment).

## Package Architecture

The `praisonai` package is organized into several major subsystems, each providing distinct functionality for different deployment and interaction scenarios.

### Package Structure

```

```

**Sources:** [src/praisonai/pyproject.toml1-121](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L1-L121) [src/praisonai/praisonai/cli/main.py1-1000](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L1-L1000) [src/praisonai/praisonai/deploy.py1-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L1-L186) [src/praisonai/praisonai/browser/agent.py1-100](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/agent.py#L1-L100)

## Package Metadata and Dependencies

The `praisonai` package is defined in `pyproject.toml` with a modular dependency structure using optional extras.

### Core Dependencies

**Sources:** [src/praisonai/pyproject.toml11-22](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L11-L22)

### Core Dependencies

**Sources:** [src/praisonai/pyproject.toml11-22](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L11-L22)

### Entry Points

The package defines three command-line entry points:

**Sources:** [src/praisonai/pyproject.toml24-27](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L24-L27)

## CLI System

The CLI is the primary interface for interacting with PraisonAI, providing 50+ commands organized into 10 major categories.

### CLI Architecture

```

```

**Sources:** [src/praisonai/praisonai/cli/main.py214-248](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L214-L248) [src/praisonai/praisonai/cli/main.py289-407](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L289-L407)

### Lazy Loading Implementation

The CLI uses extensive lazy loading to optimize startup time, reducing import time from ~3500ms to ~20ms:

```

```

The lazy loading is implemented through helper functions that import modules only when specific features are accessed:

**Key Lazy Loaders:**

- _get_auto_generator() - Defers AutoGenerator import for auto-generation features
- _get_agents_generator() - Defers AgentsGenerator import for agent execution
- _get_inbuilt_tools() - Defers inbuilt_tools import (~3200ms) for CrewAI/AutoGen
- _get_generate_config() - Defers config generation import (~3500ms) for training
- _get_chainlit_run() - Defers Chainlit import for UI commands

**Sources:** [src/praisonai/praisonai/cli/main.py64-159](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L64-L159)

### Optional Feature Detection

The CLI detects available optional dependencies at runtime without importing them:

```

```

These flags enable graceful degradation when optional dependencies are not installed.

**Sources:** [src/praisonai/praisonai/cli/main.py92-131](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L92-L131)

### Configuration Management

The `PraisonAI` class manages configuration with AutoGen compatibility:

```

```

**Sources:** [src/praisonai/praisonai/cli/main.py215-247](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L215-L247)

### Warning Suppression

The CLI implements comprehensive warning suppression to prevent LiteLLM Pydantic serialization warnings from cluttering output:

```

```

**Sources:** [src/praisonai/praisonai/cli/main.py8-51](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L8-L51)

## Cloud Deployment

The `CloudDeployer` class provides automated deployment to Google Cloud Platform (GCP) Cloud Run.

### CloudDeployer Class Architecture

```

```

**Sources:** [src/praisonai/praisonai/deploy.py1-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L1-L186)

### Deployment Pipeline

The deployment process follows a 6-step pipeline:

1. Configure Docker Registry : gcloud auth configure-docker us-central1-docker.pkg.dev
2. Create Artifact Repository : gcloud artifacts repositories create praisonai-repository
3. Build Docker Image : docker build --platform linux/amd64 -t gcr.io/{project}/praisonai-app:latest
4. Tag for Artifact Registry : docker tag ... us-central1-docker.pkg.dev/{project}/praisonai-repository/praisonai-app:latest
5. Push to Registry : docker push us-central1-docker.pkg.dev/{project}/praisonai-repository/praisonai-app:latest
6. Deploy to Cloud Run : gcloud run deploy praisonai-service --image ... --set-env-vars ...

**Sources:** [src/praisonai/praisonai/deploy.py98-180](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L98-L180)

### Dynamic File Generation

`CloudDeployer` generates deployment artifacts dynamically:

```

```

This version is:

- Imported by CLI for --version flag
- Referenced in pyproject.toml via {attr = "praisonai.version.__version__"}
- Used in Docker image builds (pinned at 4.4.11 in deployment)
- Displayed in Homebrew formula (v4.4.11 tag)

**Sources:** [src/praisonai/praisonai/version.py1](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/version.py#L1-L1) [src/praisonai/pyproject.toml155](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L155-L155) [src/praisonai/praisonai.rb6](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai.rb#L6-L6)

**Generated api.py:**

```

```

**Sources:** [src/praisonai/praisonai/deploy.py36-90](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L36-L90)

### Environment Variable Propagation

Environment variables are propagated from local `.env` to Cloud Run:

```

```

These are then passed to `gcloud run deploy` via `--set-env-vars`:

```

```

**Sources:** [src/praisonai/praisonai/deploy.py92-149](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L92-L149)

## Browser Automation System

The browser automation system provides AI-driven web automation through multiple engine modes: Chrome Extension, CDP, Playwright, and Hybrid.

### Browser System Architecture

```

```

**Sources:** [src/praisonai/praisonai/browser/agent.py1-100](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/agent.py#L1-L100) [src/praisonai/praisonai/browser/server.py1-300](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/server.py#L1-L300) [src/praisonai/praisonai/browser/cdp_agent.py1-200](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/cdp_agent.py#L1-L200)

### BrowserAgent Class

The `BrowserAgent` class uses `praisonaiagents` to make intelligent browser automation decisions:

**Key Features:**

- Structured Actions : Uses Pydantic BrowserAction model for typed responses
- Action Normalization : Maps LLM freeform actions to valid CDP actions via ACTION_MAPPING
- Error Detection : Tracks input garbling, wrong pages, and blockers
- Anti-Loop Logic : Prevents repeated failed actions

**Action Types:**

- type - Type text into INPUT element
- submit - Press Enter to submit form
- click - Click BUTTON or LINK
- scroll - Scroll page (up/down)
- navigate - Go to URL directly
- clear_input - Clear garbled input text
- done - Mark task complete

**Sources:** [src/praisonai/praisonai/browser/agent.py12-169](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/agent.py#L12-L169)

### BrowserServer WebSocket Protocol

The `BrowserServer` provides a WebSocket interface on port 8765 for Chrome Extension communication:

**Message Types:**

**Connection Flow:**

```

```

**Sources:** [src/praisonai/praisonai/browser/server.py23-204](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/server.py#L23-L204)

### CDPBrowserAgent Direct Control

The `CDPBrowserAgent` provides headless automation without requiring the Chrome Extension:

**Features:**

- Direct CDP : WebSocket connection to Chrome DevTools Protocol
- Retry Logic : Automatic retry with fallback selectors on failures
- Vision Mode : Optional screenshot analysis for element detection
- Video Recording : Real-time screen capture via CDP screencast
- Session Recording : Full action logging to SQLite

**Initialization Parameters:**

```

```

**Sources:** [src/praisonai/praisonai/browser/cdp_agent.py92-158](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/cdp_agent.py#L92-L158)

### BrowserLauncher Chrome Management

The `BrowserLauncher` automates Chrome startup with extension loading:

**Chrome Discovery:**

```

```

**Profile Management:**

- Default : Persistent profile at ~/.praisonai/browser_profile
- Temporary : Per-run temp profile (deleted after completion)

**Launch Flags:**

```

```

**Sources:** [src/praisonai/praisonai/browser/launcher.py20-149](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/launcher.py#L20-L149)

### SessionManager Persistence

The `SessionManager` provides thread-safe SQLite persistence for browser sessions:

**Database Schema:**

```

```

**Thread Safety:**

- Thread-local connections via threading.local()
- Context manager for transaction management
- Connection pooling per thread

**Sources:** [src/praisonai/praisonai/browser/sessions.py19-231](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/sessions.py#L19-L231)

### Browser CLI Commands

The browser CLI provides Typer-based commands:

**Commands:**

**Engine Modes:**

- extension - Chrome Extension mode (default)
- cdp - Direct CDP mode (headless-friendly)
- playwright - Playwright automation (requires playwright extra)
- hybrid - Automatic engine selection

**Sources:** [src/praisonai/praisonai/browser/cli.py1-227](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/browser/cli.py#L1-L227)

## Docker Deployment Configurations

The `praisonai` package includes 4 specialized Docker configurations for different deployment scenarios.

### Docker Image Types

```

```

**Sources:** [docker/Dockerfile1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L47) [docker/Dockerfile.ui1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L1-L47) [docker/Dockerfile.chat1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L1-L47) [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47)

**Generated Dockerfile:**

```

```

</old_str>

<old_str>

### Shared Configuration

All Docker images share common configuration for directory management:

**Environment Variables:**

```

```

**Directory Structure:**

```
/root/.praison/
|-- database.sqlite      # Chainlit database
|-- chainlit.md         # Chainlit configuration
|-- .chainlit/          # Chainlit runtime files
`-- config/             # PraisonAI configuration
```

**Sources:** [docker/README.md54-74](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L54-L74)
</old_str>
<new_str>

### Shared Configuration

All Docker images share common configuration for directory management, solving the issue of configuration files cluttering the root directory:

**Environment Variables:**

```

```

**Directory Structure:**

```
/root/.praison/
|-- database.sqlite      # Chainlit database
|-- chainlit.md         # Chainlit configuration
|-- .chainlit/          # Chainlit runtime files
`-- config/             # PraisonAI configuration
```

This centralized directory approach prevents `chainlit.md`, `.chainlit/`, and `public/` from cluttering the application root directory.

**Sources:** [docker/README.md54-74](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L54-L74) [docker/Dockerfile.dev26-30](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L26-L30) [docker/Dockerfile.ui26-30](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L26-L30) [docker/Dockerfile.chat26-30](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L26-L30)

### Service-Specific Configurations

**Basic API Service** (`Dockerfile`):

- Base: python:3.11-slim
- Installs: flask , praisonai , praisonai[api] , gunicorn , markdown
- Port: 8080
- Command: gunicorn -b 0.0.0.0:8080 api:app
- Auto-generates health check endpoint if api.py missing
- Config directory: /root/.praison

**UI Service** (`Dockerfile.ui`):

- Base: python:3.11-slim
- Installs: praisonai_tools , praisonai>=4.4.11 , praisonai[ui] , praisonai[crewai]
- Port: 8082
- Command: praisonai ui
- Environment: CHAINLIT_PORT=8082 , CHAINLIT_HOST=0.0.0.0
- Config directory: /root/.praison

**Chat Service** (`Dockerfile.chat`):

- Base: python:3.11-slim
- Installs: praisonai_tools , praisonai>=4.4.11 , praisonai[chat] , embedchain[github,youtube]
- Port: 8083
- Command: praisonai chat
- Environment: CHAINLIT_PORT=8083 , CHAINLIT_HOST=0.0.0.0
- Config directory: /root/.praison

**Development Service** (`Dockerfile.dev`):

- Base: python:3.11-slim
- System packages: gcc , python3-dev , portaudio19-dev , curl , git , vim , nano
- Python packages: praisonai_tools , praisonai>=4.4.11 , praisonai[ui] , praisonai[chat] , praisonai[realtime] , praisonai[code] , embedchain[github,youtube] , jupyter , jupyterlab , notebook , pytest , pytest-asyncio , mkdocs , mkdocs-material
- Includes: Audio support for realtime features
- Config directory: /root/.praison
- Default command: praisonai ui

**Sources:** [docker/Dockerfile1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L47) [docker/Dockerfile.ui1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L1-L47) [docker/Dockerfile.chat1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L1-L47) [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47)

## Version Management

The package version is centrally managed in `praisonai/version.py`:

### Optional Extras

The package provides 14 optional dependency groups for different features:

```

```

**Key Extras:**

- UI/UX : ui , gradio , chat , realtime for different interface modes
- APIs : api , os , call for server and telephony deployment
- Frameworks : crewai , autogen , autogen-v4 for framework integration
- Bots : bot , bot-whatsapp-web for messaging platform integration
- Protocols : acp for Agent-Client Protocol support
- Code : code for browser automation and crawling
- Development : dev for testing and development tools
- Lite : Minimal installation without TUI or LiteLLM dependencies

**Sources:** [src/praisonai/pyproject.toml29-145](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L29-L145)

## TypeScript CLI Specification

The TypeScript SDK includes a parallel CLI implementation with structured command specifications.

### CLI Specification Structure

```

```

**Command Categories:**

- chat - Chat with AI agent
- run - Run agent with task
- workflow - Execute multi-agent workflow
- agents - Multi-agent orchestration
- eval - Agent performance evaluation
- providers - LLM provider management
- tools - Tool management
- memory - Memory operations
- session - Session management
- knowledge - Knowledge base
- skills - Skill management
- mcp - Model Context Protocol

**Sources:** [src/praisonai-ts/src/cli/spec/cli-spec.ts1-260](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-ts/src/cli/spec/cli-spec.ts#L1-L260)

### Memory Command Implementation

The TypeScript CLI includes persistent memory with database backing:

**Memory Options:**

```

```

**Persistent Storage:**

```

```

**Usage:**

```

```

**Sources:** [src/praisonai-ts/src/cli/commands/memory.ts1-264](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-ts/src/cli/commands/memory.ts#L1-L264)

## Summary

The `praisonai` package serves as the application layer, providing:

1. CLI System : 50+ commands with lazy loading for fast startup (~20ms)
2. Cloud Deployment : Automated GCP Cloud Run deployment via CloudDeployer
3. Browser Automation : 4-engine system (Extension, CDP, Playwright, Hybrid) with session persistence
4. Docker Configurations : 4 specialized images for different deployment scenarios
5. Optional Dependencies : 12 extras for modular feature installation
6. TypeScript SDK : Parallel CLI implementation with structured specifications

The package is tightly coupled with `praisonaiagents` (core framework) but maintains clean separation through lazy loading and optional dependencies, enabling lightweight deployments when only core functionality is needed.
