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.
git clone https://github.com/yourusername/praisonAI.git
git checkout -b new-feature
git commit -am "Add some feature"
git push origin new-feature- 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 againstMervinPraison/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.
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.
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:
gh workflow run "Sync to praisonai-js" --repo MervinPraison/PraisonAIDirection 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.
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.
Prerequisites
Install Ollama, start it, and pull the same tool-capable model CI uses.
# 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.6bRun the required contract test only
The TestOllamaCIMinimum class is the one CI treats as required — a tool round-trip must succeed.
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 -vRun the full suite
Some tests are informational rather than required.
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 -vExpected 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.