openmoderate 1.0.1__tar.gz

openmoderate-1.0.1/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.venv
+venv
+dist
+build
+**/__pycache__
+**/*.pyc
+.pytest_cache
+.ruff_cache
+tests
+examples
+*.omh

openmoderate-1.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Something crashes, errors or behaves differently from the docs
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Code or commands we can run. Use a harmless placeholder image.
+      render: python
+  - type: input
+    id: version
+    attributes:
+      label: openmoderate version
+      placeholder: python -c "import openmoderate; print(openmoderate.__version__)"
+    validations:
+      required: true
+  - type: input
+    id: env
+    attributes:
+      label: Python version and OS
+      placeholder: Python 3.11, Ubuntu 24.04

openmoderate-1.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/karammm/openmoderate-image-moderation/security/advisories/new
+    about: Please report security problems privately, not as a public issue.

openmoderate-1.0.1/.github/ISSUE_TEMPLATE/misclassification.yml

@@ -0,0 +1,39 @@
+name: Misclassification (false positive / missed content)
+description: The model flagged something harmless, or missed something it should catch
+labels: [accuracy]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Never attach or link harmful images** (nudity, gore, abuse, extremist material)
+        in this public tracker. Describe them in words instead. For harmless false
+        positives (e.g. a kitchen knife flagged as a weapon), attaching the image is
+        welcome if you have the right to share it.
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Kind
+      options:
+        - False positive (harmless content was flagged)
+        - Missed content (violating content was not flagged)
+    validations:
+      required: true
+  - type: input
+    id: category
+    attributes:
+      label: Category
+      placeholder: e.g. weapons
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the image
+      description: What does the image show? Include the scores from result.to_dict().
+    validations:
+      required: true
+  - type: textarea
+    id: pattern
+    attributes:
+      label: Is it systematic?
+      description: Does it happen across many similar images? Have you tried a policy change (thresholds, negatives) or a trained head?

openmoderate-1.0.1/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: monthly

openmoderate-1.0.1/.github/pull_request_template.md

@@ -0,0 +1,15 @@
+## What does this change?
+
+<!-- One or two sentences, and link the issue it addresses. -->
+
+## How was it tested?
+
+<!-- Commands you ran; for prompt or threshold changes, before/after numbers from
+     `python benchmark/run.py` or your own evaluation set (describe it, don't commit it). -->
+
+## Checklist
+
+- [ ] `ruff check`, `ruff format --check`, `mypy src/openmoderate` and `pytest` pass
+- [ ] Tests added or updated for behaviour changes
+- [ ] `CHANGELOG.md` updated under "Unreleased"
+- [ ] No harmful images committed (tests use synthetic images)

openmoderate-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "release/**"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install (CPU-only torch)
+        run: |
+          python -m pip install --upgrade pip
+          pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[dev]" pytest-github-actions-annotate-failures
+      - name: Check the model stack imports (catches torch/torchvision mismatches)
+        run: python -c "import open_clip, torchvision; print(open_clip.__version__, torchvision.__version__)"
+      - run: ruff check src tests scripts examples benchmark
+      - run: ruff format --check src tests scripts examples benchmark
+      - name: Type check
+        run: |
+          pip install "mypy>=1.10" types-PyYAML
+          mypy src/openmoderate --ignore-missing-imports
+      - run: pytest -q
+      - run: python -m build
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build image
+        run: |
+          set -o pipefail
+          if ! docker build --progress=plain -t openmoderate:ci . 2>&1 | tee build.log; then
+            msg=$(tail -c 4000 build.log | python3 -c "import sys; print(sys.stdin.read().replace('%','%25').replace('\\r','').replace('\\n','%0A'))")
+            echo "::error title=docker build failed::$msg"
+            exit 1
+          fi
+      - name: Smoke test the container
+        run: |
+          docker run -d --name om -p 8000:8000 -e OPENMODERATE_API_KEY=ci-key openmoderate:ci
+          for i in $(seq 1 60); do curl -sf localhost:8000/health && break; sleep 2; done
+          curl -sf localhost:8000/health | grep '"model_loaded":true'
+          python3 -c "import zlib,struct; raw=b''.join(b'\x00'+b'\x40\x90\xd0'*64 for _ in range(64)); c=lambda t,d: struct.pack('>I',len(d))+t+d+struct.pack('>I',zlib.crc32(t+d)); open('blue.png','wb').write(b'\x89PNG\r\n\x1a\n'+c(b'IHDR',struct.pack('>IIBBBBB',64,64,8,2,0,0,0))+c(b'IDAT',zlib.compress(raw))+c(b'IEND',b''))"
+          test "$(curl -s -o /dev/null -w '%{http_code}' -F file=@blue.png localhost:8000/v1/moderate)" = 401
+          curl -sf -H 'X-API-Key: ci-key' -F file=@blue.png localhost:8000/v1/moderate | tee out.json
+          grep '"is_safe":true' out.json
+          # Video support works end to end: build a 3 s clip inside the container (which has
+          # OpenCV) and moderate it. Without OpenCV the endpoint would return 501.
+          docker exec om python -c "import cv2, numpy as np; w = cv2.VideoWriter('/tmp/v.mp4', cv2.VideoWriter_fourcc(*'mp4v'), 10, (64, 64)); [w.write(np.full((64, 64, 3), (208, 144, 64), np.uint8)) for _ in range(30)]; w.release()"
+          docker cp om:/tmp/v.mp4 v.mp4
+          curl -sf -H 'X-API-Key: ci-key' -F file=@v.mp4 localhost:8000/v1/moderate/video | tee video.json
+          grep '"frames_analyzed":3' video.json
+          grep '"segments":\[\]' video.json
+      - name: Container logs
+        if: always()
+        run: docker logs om || true

openmoderate-1.0.1/.github/workflows/docker.yml

@@ -0,0 +1,90 @@
+name: Docker image
+
+# Publishes ghcr.io/<owner>/openmoderate:<version>, :<major>.<minor> and :latest.
+# Runs on every version tag; run it manually ("Run workflow") to (re)publish an existing tag.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to publish, e.g. v1.0.0"
+        required: true
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REF: ${{ inputs.tag || github.ref_name }}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ env.REF }}
+
+      - name: Read the package version
+        id: version
+        run: |
+          version=$(python3 -c "import re; print(re.search(r'__version__ = \"(.+?)\"', open('src/openmoderate/__init__.py').read()).group(1))")
+          if [ "v$version" != "$REF" ]; then
+            echo "::error::Tag $REF does not match package version $version"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "minor=${version%.*}" >> "$GITHUB_OUTPUT"
+
+      - id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/openmoderate
+          tags: |
+            type=raw,value=${{ steps.version.outputs.version }}
+            type=raw,value=${{ steps.version.outputs.minor }}
+            type=raw,value=latest
+          labels: |
+            org.opencontainers.image.title=openmoderate
+            org.opencontainers.image.description=Open-source, self-hosted image and video content moderation REST API
+            org.opencontainers.image.licenses=Apache-2.0
+            org.opencontainers.image.version=${{ steps.version.outputs.version }}
+
+      - uses: docker/setup-buildx-action@v4
+
+      - name: Build
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          load: true
+          tags: openmoderate:test
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Smoke test the image before publishing
+        run: |
+          docker run -d --name om -p 8000:8000 -e OPENMODERATE_API_KEY=ci-key openmoderate:test
+          for i in $(seq 1 60); do curl -sf localhost:8000/health && break; sleep 2; done
+          curl -sf localhost:8000/health | grep '"model_loaded":true'
+          docker exec om python -c "from PIL import Image; Image.new('RGB', (64, 64), (64, 144, 208)).save('/tmp/blue.png')"
+          docker cp om:/tmp/blue.png blue.png
+          curl -sf -H 'X-API-Key: ci-key' -F file=@blue.png localhost:8000/v1/moderate | grep '"is_safe":true'
+          docker rm -f om
+
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Publish
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha

openmoderate-1.0.1/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - run: pip install -r docs/requirements.txt
+      - name: Build (strict, so broken links fail the build)
+        run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/
+
+  deploy:
+    # One-time setup: Settings -> Pages -> Source: "GitHub Actions", then set the repository
+    # variable DOCS_DEPLOY=true. Until then the site is only built (and checked), not deployed.
+    if: vars.DOCS_DEPLOY == 'true' && github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

openmoderate-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+# Push a version tag (git tag v1.2.3 && git push --tags) to:
+#   1. check the tag matches the package version,
+#   2. build the sdist and wheel,
+#   3. create the GitHub release with notes from CHANGELOG.md (and backfill release pages
+#      for any older tags that lack one),
+#   4. publish to PyPI through trusted publishing (no tokens stored in the repository).
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - name: Check the tag matches the package version
+        run: |
+          version=$(python -c "import re; print(re.search(r'__version__ = \"(.+?)\"', open('src/openmoderate/__init__.py').read()).group(1))")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match package version $version"
+            exit 1
+          fi
+      - name: Check the changelog has an entry for this version
+        run: python scripts/changelog_section.py "$GITHUB_REF_NAME" > /dev/null
+      - run: pip install build && python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create the release for this tag
+        run: |
+          python scripts/release_notes.py "$GITHUB_REF_NAME" > notes.md
+          if gh release view "$GITHUB_REF_NAME" > /dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber
+            gh release edit "$GITHUB_REF_NAME" --notes-file notes.md
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file notes.md --verify-tag
+          fi
+      - name: Backfill release pages for older tags
+        run: |
+          for tag in $(git tag --list 'v*' --sort=version:refname); do
+            [ "$tag" = "$GITHUB_REF_NAME" ] && continue
+            gh release view "$tag" > /dev/null 2>&1 && continue
+            python scripts/changelog_section.py "$tag" > old.md || continue
+            gh release create "$tag" --title "$tag" --notes-file old.md --verify-tag --latest=false
+          done
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

openmoderate-1.0.1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+*.omh
+.idea/
+.vscode/
+benchmark/data/
+site/

openmoderate-1.0.1/CHANGELOG.md

@@ -0,0 +1,134 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-10-14
+
+First release on PyPI: `pip install openmoderate`.
+
+### Added
+- Docker image published to `ghcr.io/karammm/openmoderate` on every release, smoke-tested
+  before it is pushed.
+- Release pages now start with copy-paste install commands and link to the docs,
+  benchmarks and the full diff.
+- README badges, `CITATION.cff`, `CODE_OF_CONDUCT.md`, Dependabot updates and a social
+  preview card.
+
+### Changed
+- GitHub Actions updated to their current major versions.
+- Releases publish to PyPI through trusted publishing on every version tag.
+
+## [1.0.0] - 2026-10-14
+
+First stable release. The public API (everything importable from `openmoderate`, the
+integration modules, CLI flags, REST endpoints and the `.omh` format) now follows semantic
+versioning; default prompts and thresholds may still be tuned in minor releases.
+
+### Added
+- Public, reproducible benchmark (`benchmark/`): 475 hand-reviewed, openly licensed
+  Wikimedia Commons photos across weapons, hate symbols, alcohol, tobacco, drugs, violence,
+  safe images and look-alikes, with a dev/test split. `python benchmark/run.py` reproduces
+  the published numbers.
+- Documentation site (MkDocs) with guides, benchmarks and an API reference generated from
+  the docstrings, deployed to GitHub Pages.
+- Release automation: pushing a `vX.Y.Z` tag builds the package, creates the GitHub
+  release from the changelog and (once enabled) publishes to PyPI.
+- Type information (`py.typed`) and `mypy` in CI.
+- Top-level exports: `LabelSpec`, `LinearHead`, `ImageLoadError`, `VideoLoadError`,
+  `VideoModerationResult`, `VideoSegment`, `SAFE_PROMPTS`.
+- `SECURITY.md`, issue templates (including a misclassification report that asks people
+  not to attach harmful images) and a pull-request template.
+
+### Changed
+- More complete default prompts, measured on the held-out test half: `drugs` recall 15% →
+  85%, `alcohol` 53% → 84%, `tobacco` 44% → 59%, `hate_symbols` 50% → 61%, with the safe
+  false-positive rate at 6% (was 5%). New safe look-alikes: milk, juice, coffee; kitchen
+  knives are now a `weapons` negative.
+- `integrations.configure()` takes the moderator as a positional-only argument.
+- The README is now an overview; detailed guides moved to the docs site.
+
+## [0.5.0] - 2026-10-14
+
+### Added
+- Video moderation (`pip install "openmoderate[video]"`): `Moderator.analyze_video()` samples
+  frames, scores them in batches and returns timestamped `segments` per violated label, with
+  `fps`, `min_frames`, `stop_on_violation`, `max_duration` and `keep_frame_scores` options.
+- `openmoderate scan` handles video files (`--fps`, `--min-frames`, `--max-duration`).
+- REST endpoint `POST /v1/moderate/video`, streamed to disk with size and duration limits
+  (`OPENMODERATE_MAX_VIDEO_BYTES`, `OPENMODERATE_MAX_VIDEO_SECONDS`). Docker image includes
+  video support.
+- Decoding limits enforced while decoding (frame size, decoded frames, duration), not taken
+  from the file's metadata.
+- Border trimming (`trim_borders`, on by default): letterbox bars and uniform padding are
+  cropped before scoring, for images, video frames, training and evaluation alike.
+
+### Changed
+- Border trimming changes some scores. On our test set it removed a false `sexual_activity`
+  detection on letterboxed video and turned a missed `alcohol` detection (a glass of wine on
+  a plain background, 0.54) into a hit (0.78). Set `trim_borders: false` to keep the old
+  behaviour.
+
+## [0.4.0] - 2026-10-14
+
+### Added
+- Framework integrations under `openmoderate.integrations`:
+  - FastAPI: `ModeratedFile` / `ModeratedFiles` and `moderated()` / `moderated_files()`
+    dependencies, with moderation off the event loop.
+  - Flask: `@moderate_uploads(...)` decorator and an `OpenModerate` extension that can check
+    every request.
+  - Django: `ModerationValidator` (models, forms, admin, DRF; migration-safe) and
+    `ModerationMiddleware` for URL prefixes, configured via `settings.OPENMODERATE`.
+- One shared model per process; per-endpoint policies reuse it instead of loading another copy.
+- Uploads are rewound after checking so applications can save them normally.
+- Error responses hide confidence scores by default (`include_scores=True` to show them).
+- Extras: `openmoderate[fastapi]`, `[flask]`, `[django]`; runnable example apps for each.
+- README infographic (`docs/assets/how-it-works.svg`) and animated terminal demo
+  (`docs/assets/demo.svg`), both following GitHub's light/dark theme. Regenerate with
+  `python scripts/make_readme_graphics.py`.
+
+### Changed
+- The test suite's fake engine uses exactly orthogonal text vectors, making multi-label
+  assertions deterministic.
+
+## [0.3.0] - 2026-10-14
+
+### Added
+- REST API server (`pip install "openmoderate[server]"`, `openmoderate serve`), built on FastAPI:
+  `GET /health`, `GET /v1/categories`, `POST /v1/moderate` (multipart), `POST /v1/moderate/batch`
+  (multipart, per-file errors) and `POST /v1/moderate/json` (base64 or URL).
+- Optional API-key authentication via `OPENMODERATE_API_KEY` (constant-time comparison).
+- URL fetching, off by default (`OPENMODERATE_ALLOW_URLS`), with SSRF protection: http(s) only,
+  no private, loopback or link-local addresses, every redirect re-validated, size and time limits.
+- Upload size and batch limits, model preloading at startup, and a warning when serving on a public
+  interface without an API key.
+- Dockerfile (CPU torch, non-root user, model weights baked in, healthcheck) and a CI job that
+  builds and smoke-tests the image.
+- CI also runs on `release/**` branches, checks that the model stack imports, and reports
+  failures as annotations.
+
+### Fixed
+- Docker image and CI now install `torch` and `torchvision` from the same CPU index (a mismatch
+  broke `import open_clip`).
+
+## [0.2.0] - 2026-10-14
+
+### Added
+- `openmoderate` command-line tool with `scan`, `train`, `evaluate`, `categories` and `download` commands.
+- `scan` supports files, recursive folders and URLs, JSON-lines output, policy flags and `--fail-on-violation` for CI.
+- Training on your own data: folder datasets (`dataset/<label>/`, `safe/`), a class-balanced linear head on frozen CLIP embeddings, held-out precision/recall/F1, then a refit on all data.
+- `Moderator(head=..., head_weight=...)` adds trained labels and blends them with zero-shot categories.
+- `.omh` head format (NumPy archive plus JSON metadata, no pickle), with a check that the head's model matches the moderator's.
+- `Moderator.label_specs` and `Moderator.thresholds` properties.
+- `train` warns when the `safe/` folder is too small to teach the head what normal traffic looks like.
+
+## [0.1.0] - 2026-10-14
+
+### Added
+- `Moderator` with zero-shot image moderation powered by OpenCLIP (`ViT-B-32`, LAION-2B).
+- 11 default categories: nudity, sexual_activity, suggestive, violence, gore, weapons, hate_symbols, drugs, self_harm, alcohol, tobacco.
+- Calibrated per-category scores with configurable thresholds, plus category-specific `negatives` (benign look-alikes).
+- Policy configuration from kwargs, dict or YAML, including custom categories.
+- Image loading from paths, URLs, bytes, file objects and PIL images, with EXIF rotation, transparency flattening and size limits.
+- `analyze_batch()` for efficient multi-image scoring.

openmoderate-1.0.1/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use openmoderate in research or a product evaluation, please cite it as below."
+title: "openmoderate: open-source, self-hosted image and video content moderation"
+type: software
+authors:
+  - name: "openmoderate contributors"
+repository-code: "https://github.com/karammm/openmoderate-image-moderation"
+url: "https://karammm.github.io/openmoderate-image-moderation/"
+license: Apache-2.0
+version: 1.0.1
+date-released: "2026-10-14"
+keywords:
+  - content moderation
+  - trust and safety
+  - computer vision
+  - CLIP
+  - zero-shot classification

openmoderate-1.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be welcoming and respectful, assume good intent, critique ideas rather than
+people, and do not harass anyone. Because this project deals with harmful content, one
+extra rule applies everywhere in this repository (issues, pull requests, discussions):
+**never post or link harmful images** such as sexual content, gore, abuse or extremist
+material. Describe them in words instead.
+
+Report unacceptable behaviour privately to the maintainers through a
+[GitHub security advisory](https://github.com/karammm/openmoderate-image-moderation/security/advisories/new)
+(it is private and reaches the maintainers directly). Reports are handled confidentially,
+and maintainers may remove content or ban participants who violate this code.

openmoderate-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to openmoderate
+
+Thanks for helping make open moderation better!
+
+## Development setup
+
+```bash
+git clone https://github.com/karammm/openmoderate-image-moderation.git
+cd openmoderate-image-moderation
+python -m venv .venv && source .venv/bin/activate   # Python 3.9+
+pip install -e ".[dev]"
+```
+
+## Running checks
+
+```bash
+ruff check src tests      # lint
+ruff format src tests     # format
+pytest                    # fast unit tests (uses a fake engine, no model download)
+pytest -m slow            # smoke test against the real CLIP model (~600 MB download)
+```
+
+## Guidelines
+
+- Keep pull requests focused; add tests for behaviour changes.
+- **Never commit explicit, violent or otherwise harmful images** to the repository. Unit tests use synthetic images and a fake engine. If you improve prompts or thresholds, describe your evaluation set in the PR (source, size, licence) instead of committing it.
+- Prompt and threshold changes should include before/after numbers on the images you evaluated.
+- Update `CHANGELOG.md` under "Unreleased".
+
+## Releasing (maintainers)
+
+1. Bump `__version__` in `src/openmoderate/__init__.py` and move the "Unreleased" notes in
+   `CHANGELOG.md` under a new `## [X.Y.Z] - YYYY-MM-DD` heading.
+2. Merge to `main` once CI is green.
+3. Tag and push: `git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z`.
+
+The `Release` workflow then checks the tag matches `__version__`, builds the package,
+creates the GitHub release (install instructions, the changelog section and links, with
+the wheel and sdist attached), backfills release pages for older tags, and publishes to
+PyPI. The `Docker image` workflow smoke-tests the server image and publishes it to
+`ghcr.io/karammm/openmoderate` as `X.Y.Z`, `X.Y` and `latest`.
+
+### One-time setup
+
+**PyPI publishing** uses [trusted publishing](https://docs.pypi.org/trusted-publishers/):
+the `openmoderate` project on PyPI trusts the `release.yml` workflow of this repository
+(environment `pypi`), so no API token is stored anywhere. To move the project, update the
+publisher under the project's *Settings → Publishing* on PyPI.
+
+**Docs site:** in the GitHub repo, *Settings → Pages → Build and deployment → Source*,
+choose **GitHub Actions**, then add the repository variable `DOCS_DEPLOY` = `true`. The
+`Docs` workflow then deploys on every push to `main` (re-run it once to publish now).
+
+**Social preview:** upload `docs/assets/social-preview.png` under *Settings → General →
+Social preview* (GitHub has no API for this). Regenerate it with
+`python scripts/make_readme_graphics.py` and a headless browser screenshot of the SVG.
+
+## Benchmark
+
+`python benchmark/run.py` measures accuracy on openly licensed Wikimedia Commons images
+(see [`benchmark/README.md`](benchmark/README.md)). Run it before and after any change to
+prompts, thresholds or scoring, and include both tables in your pull request.