odysseus/CONTRIBUTING.md

Contributing to Odysseus

Thanks for helping. The project is moving quickly, so the best contributions are focused, easy to review, and easy to test.

Before You Start

• Search existing issues and pull requests before opening a new one.
• Prefer one bug fix or feature per pull request.
• Avoid broad rewrites, formatting-only changes, or moving many files unless the issue is specifically about structure.
• If you want to work on a large feature, open an issue first and describe the approach.

Setup

Docker is the recommended path for normal testing:

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

Manual development uses Python 3.11+:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m uvicorn app:app --host 0.0.0.0 --port 7000

Windows is not actively tested. Docker on Linux or a Linux/macOS manual install is the safer path for now.

Running Checks

Run the smallest relevant checks for your change:

python -m pytest
python -m py_compile app.py routes/*.py src/*.py
node --check static/js/<file-you-changed>.js

For Docker-related changes:

docker compose config
docker compose up -d --build
docker compose logs --tail=120 odysseus

Mention what you ran in the pull request description. If you could not run a check, say so.

Pull Requests

Good pull requests usually include:

• A short explanation of the bug or feature.
• The files or areas changed.
• Manual test steps or automated test results.
• Screenshots or short recordings for UI changes.
• Links to related issues, for example Fixes #123.

Please keep PRs small. Large PRs that mix unrelated cleanup, formatting, refactors, and behavior changes are much harder to review.

Issue Reports

For bugs, include:

• Install method: Docker, manual Python, WSL, etc.
• OS, browser, and device if relevant.
• Exact steps to reproduce.
• Expected behavior and actual behavior.
• Logs, screenshots, or terminal output.

For model-serving issues, include:

• Backend: Ollama, vLLM, SGLang, llama.cpp, LM Studio, etc.
• Model name.
• GPU/CPU and operating system.
• Cookbook task logs or server logs.

Issues with only "help", "does not work", or a screenshot without context may be closed as not actionable.

Security

Do not post secrets, API keys, private logs, personal documents, or public IPs in issues or pull requests.

For security reports, follow SECURITY.md.