pooolify 0.3.0

pooolify: Code-centric Python framework for multi-agent LLM orchestration with FastAPI + SSE and PostgreSQL persistence

pooolify — Code‑Centric Multi‑Agent AI Framework (Python)

Overview

• Purpose: Orchestrate multiple LLM‑powered agents to collaboratively solve complex tasks.
• Focus: Developer Experience (DX), extensibility, and installable Python package.
• Core: FastAPI + SSE, PostgreSQL persistence, code‑declared agents and tools, provider‑agnostic LLM layer with cost tracking.

Key Features

• Manager‑Agent driven orchestration with DAG planning and parallel execution (asyncio).
• Code‑declared Agents (pydantic) and Tools (Python classes) with a simple runtime.
• FastAPI endpoints with Server‑Sent Events for plan/route/thought summaries/tool traces.
• PostgreSQL persistence for sessions, messages, costs, plans, tool calls, and feedback.
• Limits per request (steps, depth, duration) configured in code.

Repository Layout

pooolify-project/ ├─ pyproject.toml ├─ README.md ├─ pooolify/ # Framework core │ ├─ init.py │ ├─ config.py │ ├─ api/ │ ├─ core/ │ ├─ agents/ │ ├─ tools/ │ ├─ llm/ │ └─ persistence/ ├─ examples/ │ └─ 01_basic_chatbot/ │ ├─ main.py │ ├─ my_agents.py │ ├─ my_tools.py │ ├─ .env │ └─ prompts/ │ └─ my_agent.prompt │ └─ 02_multi_agent/ │ ├─ main.py │ ├─ agents.py │ ├─ tools.py │ ├─ data/kb.json │ └─ prompts/ │ ├─ researcher.prompt │ ├─ calculator.prompt │ └─ writer.prompt └─ tests/

Install (dev)

• Editable install to dogfood the framework while building examples.

  pip install -e .

Env setup

• Copy and adjust the environment file:

  cp .env.example .env

  then edit .env as needed (API_TOKEN, DATABASE_URL, etc.)

Environment

• Use uv (recommended) or regular venv. Configure env via .env or real env vars:
  • APP_ENV=dev|staging|prod
  • DATABASE_URL=postgresql+psycopg://user:pass@host:5432/db
  • API_TOKEN=your_api_token
  • LLM_OPENAI_API_KEY=sk-...

Run the example

• Start example 01 (basic):

  uvicorn examples.01_basic_chatbot.main:app --reload

• Test health:

  curl http://localhost:8000/v1/healthz

• Stream chat (SSE):

  curl -H "Accept: text/event-stream" -H "Authorization: Bearer $API_TOKEN"
  -N http://localhost:8000/v1/chat/stream -d '{"session_id":"demo","query":"안녕?"}'

• Start example 02 (multi-agent):

  uvicorn examples.02_multi_agent.main:app --reload

• Stream multi-agent (SSE):

  curl -H "Accept: text/event-stream"
  -N http://localhost:8000/v1/chat/stream -d '{"session_id":"demo2","query":"SSE가 뭐야? 2+2는?"}'

Manager limits in code

• Set request limits when instantiating the core app:

  from pooolify.core import PooolifyApp from pooolify.core import ManagerLimits

  core = PooolifyApp(limits=ManagerLimits(max_steps=20, max_depth=4, max_duration_s=120))

  register agents ...

FastAPI Endpoints

• POST /v1/chat/stream (SSE): main streaming interface.
• POST /v1/chat: non‑streaming response.
• POST /v1/sessions: create a session id.
• GET /v1/sessions/{id}/messages: public conversation messages.
• GET /v1/healthz, GET /v1/readyz: health endpoints.

Security

• Simple bearer token via Authorization: Bearer <token>; wire to API_TOKEN.

Persistence

• Tables are created on startup if missing (see pooolify/persistence/schema.py for DDL).

Notes

• Supported models are 'gpt-5' and 'gpt-5-high'. Gemini is temporarily unsupported.
• SSE Thought summaries are structured; raw chain‑of‑thought is never emitted.