Praison AI

praisonai-code package migration

Where the agentic terminal CLI lives during the incremental C0–C6 extraction from the praisonai wrapper.

praisonai-code is a new sibling package that will host the agentic terminal CLI, extracted incrementally from the praisonai wrapper without breaking any existing install or import path.

python
from praisonaiagents import Agent

agent = Agent(
    name="CLI Assistant",
    instructions="Answer prompts from the terminal CLI.",
)

agent.start("Say hello from praisonai run")

The user keeps using pip install praisonai; the extracted praisonai-code package powers the same CLI entry points.

Diagram

praisonaiagents
SDK

praisonai-code
terminal CLI

praisonai
wrapper + shims

Quick Start

  1. Nothing changes for users
    bash
    pip install praisonai
praisonai "say hello"
  2. Optional: install praisonai-code for development

    From the PraisonAI monorepo root:

    bash
    pip install -e src/praisonai-code
python -c "import praisonai_code; print(praisonai_code.__version__)"

How It Works

Dependency flow is one-way: praisonai → praisonai-code → praisonaiagents. The praisonai-code package never declares a dependency on praisonai, which avoids a PyPI cycle. Bot, gateway, and daemon code moved to praisonai-bot in C9.

Diagram
praisonaiagents.Agentpraisonai_code.clipraisonai CLIUserpraisonaiagents.Agentpraisonai_code.clipraisonai CLIUserFuture state (after C5)praisonai “say hello”delegate agentic terminal pathrun agentresponseoutputterminal result
LayerPackageRole
SDKpraisonaiagentsAgents, tools, memory, workflows
Terminal CLIpraisonai-code`run –output actionsjsonstreamstream-json, warm runtime, CLI backends. Default run “…” is fully standalone; chat / code` open their resident interactive TUI standalone (PR #3818) and gain the richer legacy dispatch when the wrapper is installed — see the standalone-limits table.
User installpraisonaipip install praisonai, PEP 562 shims (bots/gateway/daemon moved to praisonai-bot in C9)

Where should I work?

Diagram

End user

Contributor on runtime / cli_backends

Contributor on bots / gateway / daemon

Library using PraisonAI class

Who are you?

pip install praisonai
No change

After C1: praisonai_code.runtime
praisonai_code.cli_backends

Use praisonai-bot package
praisonai_bot.bots / gateway / daemon

from praisonai.cli.main import PraisonAI
Keeps working via PEP 562 shim after C5

Roadmap

StepScopeFilesStatus
C0Scaffold (this PR)5✅ PR #2539
C1runtime/ + cli_backends/8⏳
C2interactive/, execution/, ui/, output/, state/30⏳
C380 agentic commands (9 bot-channel commands stay in main)80⏳
C4158 agentic features (5 bot-channel features stay in main)158⏳
C5main.py, app.py, config/session/utils + PEP 562 shims26⏳
C6Integration gate (smoke tests, import graph assertions, real agentic run)—⏳

Tracking issue: PraisonAI#2512.

Compatibility guarantees

  • pip install praisonai remains the only user-facing install. praisonai-code is not published to PyPI standalone during migration.
  • Existing import paths keep working — PEP 562 shims at old praisonai.* paths land as code moves in C1–C5. from praisonai.cli.main import PraisonAI continues unchanged (154+ tests depend on it).
  • Console entry unchanged — praisonai = "praisonai.__main__:main".
  • One-way dependencies — praisonai → praisonai-code → praisonaiagents; praisonai-code never depends on praisonai.
  • Scope split — praisonai-code covers the agentic terminal product; bots/, gateway/, and daemon/ moved to praisonai-bot in C9 (see praisonai-bot Migration). praisonai-code hosts the chat, code, and run entry points: default run "…" and every --output text mode run in-process (PR #2853 for --output *, PR #5687 for default run "…"); --image is the one text-mode feature that still routes through the wrapper’s vision ImageHandler. chat / code open their resident interactive TUI standalone (PR #3818). The wrapper adds the richer legacy dispatch for code, gateway, and channel bots.

Best Practices

Do not import praisonai_code in library code (during migration)

Application and library code should keep using import praisonai and from praisonaiagents import Agent. Direct praisonai_code imports are for contributors working inside the monorepo until the public surface is explicitly documented after C5.

Bot-channel modules moved to praisonai-bot (C9)

As of C9, the following CLI commands and features live in praisonai-bot, not praisonai-code: gateway, bot, onboard, pairing, identity, kanban, mint_link, claw. The praisonai.bots, praisonai.gateway, and praisonai.daemon paths remain as alias_package shims. See praisonai-bot Migration.

New agentic CLI features go into praisonai_code.cli.* (after C5)

Once C5 lands the layout, new terminal-agent commands and features belong under praisonai_code.cli., with shims left at the old praisonai.cli. paths for compatibility.

PEP 562 shims are load-bearing

Removing shims would break 154+ tests and every from praisonai.cli.main import PraisonAI importer. Shim removal is tracked as a 5.0.0-track breaking change on issue #2512.

Related

Python wrapper

Public praisonai.run, PraisonAI, and praisonai.arun surface

 Development setup

Clone the monorepo and install editable packages with uv

 praisonai-bot Migration

The sibling extraction that moves bots/gateway/daemon out of the wrapper