Contributing to Omni-Rewriter

August 9, 2026 · View on GitHub

Thanks for improving a general, open prompt-expansion framework for multimodal generators. Contributions of all sizes are welcome.

Mission reminder

Omni-Rewriter separates transport-neutral intent, typed PE profiles, deterministic validation, dialect rendering, and optional generation adapters. H3 and the initial image profiles are examples, not the framework boundary. It is intentionally not a claim to reverse-engineer any vendor. Prefer durable public contracts, validators, tests, and docs.

Quick start for contributors

python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"
ruff check .
mypy src
pytest
python scripts/check_model_contribution.py

Lean clone (skip heavy site demos)

Demo GIFs for the H3 PE site live on GitHub Pages / gh-pages, not on main. Prefer a partial + sparse clone so you do not pull those trees into your working copy. See site/README.md.

git clone --filter=blob:none --sparse https://github.com/WayneJin0918/Omni-Rewriter.git
cd Omni-Rewriter
git sparse-checkout set \
  '/*' \
  '!/docs/day2-h3-pe/assets/demos' \
  '!/docs/h3-pe-showcase/thumbs' \
  '!/docs/promo/out'

Tip deletions shrink future tip clones; history still holds older blobs until a history rewrite (not done by default).

What to work on

See ROADMAP.md. High-value areas:

  • New PE dialects / stricter validators
  • Generation adapters (expand ≠ generate)
  • Runtime compatibility fixtures with pinned public evidence
  • Low-res gallery assets under docs/assets/gallery/
  • Docs, translations, and request fixtures under tests/fixtures/ / examples/requests/
  • Future SFT / RL data pipelines (design first)

The model backlog is deliberately split into Video, Image, and Unified boards. Before starting a model-family PR, use the project skill omni-rewriter-model-contribution. It provides the implementation order, category-specific checks, and a copyable contribution template.

Model contribution contract

Every PR must select exactly one model category in the PR template. Select Not applicable for changes unrelated to a model family.

Model contributions must:

  1. Name the model/family and link its public upstream contract.
  2. State the exact scope: routing, schema, profile, validator, renderer, fixtures, or adapter.
  3. Report PE, adapter, and live-runtime status separately.
  4. Add focused tests and RAW/expanded fixtures for behavior changes.
  5. Keep runtime claims versioned and evidence-backed; mark untested compatibility unverified.

The Model Contribution Check workflow validates this contract deterministically. An optional AI review may add advisory feedback when maintainers configure a review endpoint, but it is not a substitute for tests, evidence, or human review.

Optional advisory AI review

The Advisory AI Model Review workflow accepts any OpenAI-compatible chat-completions endpoint. Enable it with repository configuration:

  • variable OMNI_AI_REVIEW_ENABLED=true
  • variable OMNI_AI_REVIEW_BASE_URL (including /v1 when required)
  • variable OMNI_AI_REVIEW_MODEL
  • secret OMNI_AI_REVIEW_API_KEY

For fork safety, the workflow runs trusted base-branch code under pull_request_target, fetches the proposed diff only as inert text, exposes no tools to the model, and treats the result as advisory. Endpoint failure does not bypass or fail the deterministic contribution contract.

Pull request format

PR reception follows a vLLM-style title and description contract so reviews stay fast and consistent.

Title prefixes

Only these prefixes are reviewed by default. Put the model name in [Model] titles:

  • [BugFix] bug fixes
  • [CI/Build] CI, packaging, or build tooling
  • [Doc] documentation, README, skills, or examples
  • [Model][Video] / [Model][Image] / [Model][Unified] new or improved model support
  • [Profile] PE dialect / validator / renderer / repair-rule changes
  • [Adapter] generation adapter or runner wiring
  • [Core] shared request/output contracts or agent harness behavior
  • [Misc] everything else; use sparingly

Examples:

  • [Model][Video] Add Wan2.2 PE profile and fixtures
  • [Profile] Tighten Seedream quote validation
  • [Doc] Clarify expand vs generate boundary

Description

Use the repository PR template and fill Purpose, Test Plan, and Test Result before requesting review. Model-family PRs must also complete the model contribution contract fields.

Before review

  1. Branch from main; keep the PR focused on one category when possible.
  2. Run ruff check ., mypy src, pytest, and python scripts/check_model_contribution.py.
  3. Update docs or the matching README model-ecosystem card when support status changes.
  4. Do not commit secrets, .env, full-resolution videos, or huge binaries. Bounded low-resolution gallery media under docs/assets/gallery/ are fine.
  5. Link related issues. Prefer Fixes #NN when the PR fully resolves an issue.

Commit style

Prefer short imperative subjects. Model PRs may use the same prefix in the commit subject when helpful:

  • fix: require <d> tags for dialogue scenes
  • feat: add seedream image PE schema
  • docs: add harness flowchart
  • [Model][Image] add FLUX.1 Kontext profile scaffolding

Code review expectations

  • Public models stay backward compatible unless the PR clearly documents a breaking change.
  • Prompt-rule edits should cite the profile/dialect and public evidence, then add a test.
  • Adapter PRs must distinguish PE support from generation support, pin the tested runtime/API, and label untested routes as unverified.
  • Do not infer stock vLLM compatibility from a custom fork, or vLLM-Omni compatibility from an upstream support table without an end-to-end repository test.
  • Agent / Cursor skills under .cursor/skills/ should stay actionable and short.

Community

  • Be respectful (see CODE_OF_CONDUCT.md).
  • Open an issue before large refactors when possible.
  • Questions about PE quality vs vendor demos belong in issues with reproducible fixtures.

Welcome aboard — the harness gets better when more people stress it against real generators.