Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
241 lines (161 loc) · 6.23 KB

CONTRIBUTING.md

File metadata and controls

241 lines (161 loc) · 6.23 KB
Raw

Contributing to SentinelAI

Thanks for your interest in contributing to SentinelAI. This project is a full-stack AI safety platform with a Python backend, a Next.js dashboard, and a Python SDK. We welcome bug reports, feature ideas, documentation improvements, and code contributions.

Before you start, please read this guide and the project README so you understand the architecture and expected workflows.

Project overview

This repository is organized as follows:

  • Backend/ — FastAPI API, database models, business logic, and service integrations
  • Frontend/ — Next.js dashboard for monitoring and management
  • sentinelai-sdk/ — Python SDK published as sentinelai-risk
  • docs-site/ — documentation site
  • Docs/ — project docs and design notes

Prerequisites

You will need:

  • Git
  • Python 3.12 (recommended; the backend runtime file is set to python-3.12.8)
  • Node.js 18+ and npm 9+
  • Docker and Docker Compose (optional but recommended for local database and infra services)

If you are working on backend logic, you should also have PostgreSQL available locally or use Docker to run the included services.

1) Fork and clone

git clone https://github.com/<your-user>/Sentinel-AI.git
cd Sentinel-AI

If you are contributing from a branch in your own fork, make sure you keep your work isolated and rebase regularly against main.

2) Local setup

There are three common ways to run the project locally:

  • Backend only
  • Frontend only
  • Full stack with Docker services

Option A: Backend setup

From the repository root:

cd Backend
python -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
# .\.venv\Scripts\Activate.ps1

pip install --upgrade pip
pip install -r api/requirements.txt

Create your environment file:

cp .env.example .env

Then edit .env and fill in the values required for your local run. At minimum, ensure the following are set appropriately:

  • DATABASE_URL
  • CLERK_SECRET_KEY
  • CLERK_PUBLISHABLE_KEY
  • SENTINELAI_API_KEYS
  • SMTP_HOST, SMTP_PORT, FROM_EMAIL
  • FRONTEND_BASE_URL

For a quick local dev setup, the repository includes a Postgres and Mailpit stack in Backend/docker-compose.yml. You can bring up just those support services:

cd Backend
docker compose up -d sentinelai-db mailpit

Then run the API:

cd Backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

After the app starts, check:

If you are on Windows, the project also includes a helper script:

cd Backend
run_dev.bat

Option B: Frontend setup

From the repository root:

cd Frontend
npm install

Then start the app in development mode:

npm run dev

The frontend should be available at:

If the app depends on auth or deployment-specific configuration, create a local .env.local file with the required public and private keys used by the app. Keep these values out of source control.

Option C: Full local stack with Docker

This is the easiest way to run the full application environment:

cd Backend
docker compose up --build

This starts the backend, Postgres database, Mailpit email capture, NGINX, Prometheus, and Grafana. It is especially useful when validating end-to-end flows or service integration.

3) Running tests

Before opening a pull request, run the relevant checks for the area you changed.

Backend validation

cd Backend
python -m pytest

If you are working on a subset of tests, target them explicitly:

python -m pytest tests/ -q

Frontend validation

cd Frontend
npm run lint
npm run type-check
npm run build

SDK validation

cd sentinelai-sdk
python -m pytest

4) Contribution workflow

We prefer small, focused contributions.

Good contribution patterns

  • Keep each PR focused on one feature, bug fix, or documentation improvement
  • Prefer readable, maintainable code over clever shortcuts
  • Add or update tests when you change behavior
  • Update docs if you add user-facing configuration, endpoints, or workflow changes
  • Document environment variables or setup changes clearly

Branch naming

Use clear branch names such as:

  • feature/add-risk-dashboard-filter
  • fix/auth-session-expiry
  • docs/contributing-guide
  • chore/update-sdk-versioning

Pull request checklist

Before submitting a PR:

  • Rebase or update from main
  • Run the relevant lint/test/build checks
  • Confirm no secrets or local env files are included
  • Explain the problem and the fix in the PR description
  • Link the related issue if one exists

5) Coding standards

Please follow the conventions used in the surrounding codebase.

  • Keep code readable and consistent with the existing style
  • Use clear variable names and concise comments only where needed
  • Avoid committing debug scripts, temporary files, or personal credentials
  • Do not include generated build artifacts or local environment files in your commits
  • Prefer minimal, well-scoped changes

6) Reporting bugs and requesting features

If you find a bug or have a feature request:

  • Search the open issues first to avoid duplication
  • Open a new issue with a clear title and reproduction steps
  • Include the relevant environment details, logs, and expected vs. actual behavior
  • For security issues, do not open a normal public issue. Use a private reporting path or contact the maintainers directly.

7) Security and sensitive data

Do not commit:

  • API keys
  • tokens
  • private credentials
  • .env files
  • database dumps
  • user data or screenshots containing sensitive content

If you need to test with real credentials, keep them local to your machine and never push them to the repo.

8) Community expectations

We expect contributors to be respectful, constructive, and collaborative. Please keep discussions focused on improving the project and maintain a professional, helpful tone in issues, PRs, and code reviews.

Questions?

If you are unsure where to start, open an issue or ask in the repository discussion area. We are happy to help new contributors get set up and find a good first task.

Thank you for helping improve SentinelAI.