Contributing

Guide for contributing to PraisonAI through GitHub, including forking, cloning, and submitting pull requests

Fork the repo, make your change on a branch, and open a pull request for review.

bash
git clone https://github.com/yourusername/praisonAI.git
git checkout -b new-feature
git commit -am "Add some feature"
git push origin new-feature
Diagram

Contribution Flow

📋 Fork

🤖 Branch

🧠 Pull Request

✅ Merged

  • Fork on GitHub: Use the “Fork” button on the repository page.
  • Clone your fork: git clone https://github.com/yourusername/praisonAI.git
  • Create a branch: git checkout -b new-feature
  • Make changes and commit: git commit -am "Add some feature"
  • Push to your fork: git push origin new-feature
  • Submit a pull request via GitHub’s web interface.
  • Await feedback from project maintainers.
  • TypeScript / JavaScript changes: develop in src/praisonai-ts/ inside the monorepo. Do not open PRs against MervinPraison/praisonai-js — that repo is an npm mirror updated from the monorepo. See the JS Development Setup page.

TypeScript / JavaScript SDK

TypeScript and JavaScript SDK code lives inside the main MervinPraison/PraisonAI monorepo at src/praisonai-ts/ — file issues and open pull requests there.

The MervinPraison/praisonai-js repo is only the npm mirror, auto-written from src/praisonai-ts/ by the Sync to praisonai-js workflow. Do not open issues or PRs against praisonai-js; they will not be merged.

Diagram

Where TS/JS contributions go

Sync workflow

👤 Contributor

📦 MervinPraison/PraisonAI
src/praisonai-ts/

🪞 MervinPraison/praisonai-js
npm mirror

⬇️ npm install praisonai

Running Platform Tests

TypeScript SDK Contributions

File TypeScript SDK issues on the monorepo, fix them under src/praisonai-ts/, and let maintainers sync the npm mirror.

Diagram

TypeScript Contribution Flow

🐛 Report issue

📦 PraisonAI monorepo

🔧 Fix in src/praisonai-ts/

✅ PR merged

⚙️ Sync workflow

📤 praisonai-js npm mirror

Where to file TypeScript issues

File every TypeScript SDK bug or feature request on MervinPraison/PraisonAI using the bug or feature template. Do not open TypeScript issues on praisonai-js.

Where to fix TypeScript code

All TypeScript source lives in src/praisonai-ts/ inside the PraisonAI monorepo. Fork the monorepo, branch off main, and open your PR there.

What is praisonai-js on GitHub?

MervinPraison/praisonai-js is a one-way, downstream mirror. It exists so the praisonai npm package can be published from a standalone repo. It is not a fix target — do not open code PRs against it.

After a TypeScript PR merges on the monorepo, a maintainer syncs the mirror:

bash
gh workflow run "Sync to praisonai-js" --repo MervinPraison/PraisonAI

Direction is monorepo → praisonai-js only.

How It Works

You open a pull request, maintainers review it, and once approved it merges into the main branch.

Diagram
MaintainerGitHubContributorMaintainerGitHubContributorPush branch and open PRRequest reviewFeedback or approvalAddress feedback, PR merges

Live model tests

Since PR #4803, a nightly extended-ollama CI job runs tests/integration/test_ollama_tool_calling_live.py against a real local Ollama. Run the same suite before opening a PR that touches Ollama, LiteLLM adapters, or tool-call handling.

Diagram
PytestOllamaContributorPytestOllamaContributorollama serve && ollama pull qwen3:0.6bPRAISONAI_TEST_OLLAMA=1 pytest …::TestOllamaCIMinimumAgent.chat(“Compute 17 + 25 …”)tool call {a: 17, b: 25}assert invocations == [(17, 25)] and “42” in result1 passed

Prerequisites

Install Ollama, start it, and pull the same tool-capable model CI uses.

bash
# Install Ollama and start it
curl -fsSL https://ollama.com/install.sh | sh
ollama serve &

# Pull the same model CI uses (522 MB, tool-capable)
ollama pull qwen3:0.6b

Run the required contract test only

The TestOllamaCIMinimum class is the one CI treats as required — a tool round-trip must succeed.

bash
cd src/praisonai
PRAISONAI_TEST_OLLAMA=1 \
PRAISONAI_OLLAMA_TEST_MODEL=qwen3:0.6b \
python -m pytest tests/integration/test_ollama_tool_calling_live.py::TestOllamaCIMinimum -v

Run the full suite

Some tests are informational rather than required.

bash
cd src/praisonai
PRAISONAI_TEST_OLLAMA=1 \
PRAISONAI_OLLAMA_TEST_MODEL=qwen3:0.6b \
python -m pytest tests/integration/test_ollama_tool_calling_live.py -v

Expected on qwen3:0.6b: 7 passed, 1 failed — the failure is test_multi_step_arithmetic, which small local models handle unreliably. The nightly CI job places this in an informational step for exactly that reason.

Bring your own model

PRAISONAI_OLLAMA_TEST_MODEL defaults to olmo-3 for the local developer workflow. Any tools-capable Ollama model works; qwen3:0.6b is what CI verifies.

Best Practices

Branch per change

Create a focused branch (git checkout -b new-feature) for each contribution so reviews stay small and clear.

Read the style guide first

For docs changes, follow the Documentation Style Guide before editing any page.

Run tests locally

Install the test extras and run pytest before opening a PR to catch failures early.

Run live model tests locally

Live-model suites (tests/integration/test_ollama_tool_calling_live.py etc.) are env-gated and skip by default. To run them, install and start Ollama, pull the model, then export the gate. See the Live model tests section above for the full recipe.

Related