<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/9.3-development-environment -->

# Development Environment

- .github/workflows/build-image.yml
- .github/workflows/coverage.yml
- .github/workflows/python-package.yml
- .github/workflows/test-comprehensive.yml
- .github/workflows/test-core.yml
- .github/workflows/test-extended.yml
- .github/workflows/test-frameworks.yml
- .github/workflows/test-real.yml
- .github/workflows/unittest.yml
- .gitignore
- src/praisonai/praisonai/README.md
- src/praisonai/tests/test.py
- src/praisonai/tests/test_runner.py
- src/praisonai/tests/unit/test_cli_features.py

This document provides a comprehensive guide for setting up a local development environment for PraisonAI, including installation from source, using development containers, configuring development tools, and understanding the build system. This page focuses specifically on the developer experience for contributors and maintainers.

For Docker deployment options, see [Docker Deployment](/MervinPraison/PraisonAI/9.1-docker-deployment). For cloud deployment, see [Cloud Deployment](/MervinPraison/PraisonAI/9.2-cloud-deployment). For package architecture details, see [Package System](/MervinPraison/PraisonAI/10-package-system).

## Package Architecture

PraisonAI consists of two primary Python packages that must be understood for effective development:

The `praisonai` package depends on `praisonaiagents` as specified in [src/praisonai/pyproject.toml15](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L15-L15):

```

```

**Development Setup Flow**

```

```

Sources: [src/praisonai-agents/pyproject.toml1-95](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L95) [src/praisonai/pyproject.toml1-121](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L1-L121)

## Installing from Source

### Prerequisites

- Python 3.10 or higher
- pip 20.0 or higher
- git
- Virtual environment tool (venv, conda, or similar)

### Step-by-Step Installation

**1. Clone the Repository**

```

```

**2. Create Virtual Environment**

```

```

**3. Install Core Framework (praisonaiagents)**

The core agent framework must be installed first as it's a dependency for the application layer:

```

```

The `-e` flag creates an editable installation, meaning changes to the source code take effect immediately without reinstalling. The package configuration is defined in [src/praisonai-agents/pyproject.toml1-95](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L95)

**4. Install Application Layer (praisonai)**

```

```

The `[dev]` extra installs development dependencies including:

- textual-dev>=1.0.0 - TUI development tools
- pytest>=7.0.0 - Testing framework
- pytest-asyncio>=0.21.0 - Async test support

As specified in [src/praisonai/pyproject.toml101-105](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L101-L105)

**5. Verify Installation**

```

```

### Optional Feature Installation

Install additional features based on development needs:

```

```

**Optional Dependencies Table**

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

## Development Container

PraisonAI provides a pre-configured development container that includes all necessary tools and dependencies.

**Development Container Architecture**

```

```

### Building the Development Container

```

```

The development Dockerfile installs:

- System tools: gcc, git, vim, nano, curl
- Core packages with all extras: [ui] , [chat] , [realtime] , [code]
- Development tools: jupyter, jupyterlab, notebook
- Testing framework: pytest, pytest-asyncio
- Documentation: mkdocs, mkdocs-material
- Additional: embedchain with GitHub and YouTube support

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

### Running the Development Container

**Interactive Development Session**

```

```

This mounts your local directory into `/app` for live code editing and exposes ports for:

- 8082: UI service
- 8083: Chat service
- 8888: Jupyter notebook

**Running Jupyter Lab**

```

```

**Running Tests**

```

```

### Container Environment Variables

The development container sets the following environment variables to manage configuration directories:

Sources: [docker/Dockerfile.dev41-44](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L41-L44)

## Development Tools and Workflow

### Testing Framework

PraisonAI uses pytest with async support for testing. The test configuration is minimal, with pytest markers defined via command line.

**Running Tests Locally**

```

```

**Test Dependencies**

Installed via the `[dev]` extra in [src/praisonai/pyproject.toml101-105](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L101-L105):

- pytest>=7.0.0 - Testing framework
- pytest-asyncio>=0.21.0 - Async test support

For the comprehensive testing system and CI/CD pipeline, see [Testing Framework](/MervinPraison/PraisonAI/11.1-testing-framework).

### Documentation Generation

PraisonAI uses MkDocs with the Material theme for documentation.

**Building Documentation Locally**

```

```

The documentation dependencies are included in the development container as specified in [docker/Dockerfile.dev34-35](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L34-L35)

### Interactive Development with Jupyter

The development container includes JupyterLab for interactive development and experimentation.

**Starting Jupyter**

```

```

Jupyter packages installed: `jupyter`, `jupyterlab`, `notebook` as specified in [docker/Dockerfile.dev29-31](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L29-L31)

### TUI Development

For developing the Terminal UI components, use the `textual-dev` package:

```

```

The `textual-dev` dependency is included in [src/praisonai/pyproject.toml102](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L102-L102)

## Build System Configuration

### Build Backend

Both packages use setuptools as the build backend, as specified in their respective `pyproject.toml` files.

**praisonaiagents Build Configuration**

```

```

Source: [src/praisonai-agents/pyproject.toml1-3](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L3)

**praisonai Build Configuration**

```

```

Source: [src/praisonai/pyproject.toml111-113](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L111-L113)

### Dynamic Versioning

Version numbers are dynamically loaded from version files:

**praisonaiagents**: Version defined in code as `version = "0.13.23"` in [src/praisonai-agents/pyproject.toml7](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L7-L7)

**praisonai**: Version dynamically loaded from `praisonai.version.__version__` as specified in [src/praisonai/pyproject.toml116](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L116-L116) which references [src/praisonai/praisonai/version.py1](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/version.py#L1-L1):

```

```

### Package Discovery

**praisonaiagents Package Discovery**

```

```

Source: [src/praisonai-agents/pyproject.toml92-94](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L92-L94)

**praisonai Package Discovery**

```

```

Source: [src/praisonai/pyproject.toml118-120](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L118-L120)

### Building Distribution Packages

```

```

This creates distribution packages in the `dist/` directory (excluded from git via [.gitignore8](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/.gitignore#L8-L8)).

## Configuration and Environment

### Configuration Directory Structure

PraisonAI uses a unified configuration directory structure to avoid cluttering the workspace:

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

This structure is enforced via environment variables in both development and production deployments.

### Environment Variables

**Core Configuration Variables**

**Model Configuration Variables**

**Logging Configuration**

Source: [src/praisonai/praisonai/cli/main.py173-184](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L173-L184)

### .gitignore Configuration

The repository excludes development artifacts and local configuration:

**Key Excluded Paths**

- __pycache__/ - Python bytecode
- dist/ - Build distributions
- .venv/ - Virtual environments
- .praison/ - Local configuration directory
- *.log - Log files
- .env - Environment variables
- .cache/ , .pytest_cache/ - Cache directories

Sources: [.gitignore1-87](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/.gitignore#L1-L87)

## Development Workflow

**Contributing Workflow Diagram**

```

```

### Step-by-Step Contribution Guide

**1. Fork and Clone**

```

```

**2. Set Up Development Environment**

```

```

**3. Create Feature Branch**

```

```

**4. Make Changes and Test**

```

```

**5. Commit and Push**

```

```

**6. Create Pull Request**

Create a pull request on GitHub. The CI/CD pipeline will automatically run tests as described in [CI/CD Pipeline](/MervinPraison/PraisonAI/11.2-cicd-pipeline).

### Code Quality Standards

- Follow existing code style and patterns
- Add tests for new features
- Update documentation for API changes
- Ensure all tests pass locally before pushing
- Use descriptive commit messages

### Testing Before Contribution

```

```

For detailed testing information, see [Testing Framework](/MervinPraison/PraisonAI/11.1-testing-framework) and [CI/CD Pipeline](/MervinPraison/PraisonAI/11.2-cicd-pipeline).

Sources: [src/praisonai/pyproject.toml101-105](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L101-L105) [src/praisonai-agents/pyproject.toml1-95](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L95) [docker/Dockerfile.dev1-47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L1-L47)

## Alternative Development Setup with Homebrew

For macOS users, PraisonAI provides a Homebrew formula for easier installation. The formula is defined in [src/praisonai/praisonai.rb1-20](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai.rb#L1-L20):

```

```

**Installation via Homebrew**

```

```

This is primarily for end-user installation rather than development, but can be useful for testing distribution packages.

Sources: [src/praisonai/praisonai.rb1-20](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai.rb#L1-L20)

## Summary

This development environment guide covers:

1. Two-Package Architecture : Understanding praisonaiagents (core) and praisonai (application) separation
2. Source Installation : Step-by-step editable installation for development
3. Development Container : Pre-configured Docker environment with all tools
4. Testing and Tools : pytest, mkdocs, jupyter, textual-dev integration
5. Build System : setuptools configuration and dynamic versioning
6. Configuration : Environment variables and directory structure
7. Workflow : Git workflow and contribution guidelines

For deployment of development work, see [Docker Deployment](/MervinPraison/PraisonAI/9.1-docker-deployment) and [Cloud Deployment](/MervinPraison/PraisonAI/9.2-cloud-deployment). For understanding the package internals, see [Package System](/MervinPraison/PraisonAI/10-package-system). For testing strategies, see [Testing and Quality Assurance](/MervinPraison/PraisonAI/11-testing-and-quality-assurance).
