pyproject.toml

[build-system]
requires = ["setuptools>=78.1.1", "setuptools-rust>=1.11", "wheel"]
build-backend = "setuptools.build_meta"

[project]
# Distribution name is "mstar-ai". The bare "mstar" is taken on PyPI and its
# similarity rule (separators are dropped before names are compared) also
# refuses "m-star" while that project exists. The import package is still
# `mstar` and the console scripts are unchanged, so `pip install mstar-ai`
# then `import mstar` works as expected.
name = "mstar-ai"
version = "0.2.1"
description = "Multimodal inference engine"
readme = "README.md"
license = {file = "LICENSE"}
requires-python = ">=3.12"
authors = [{name = "mstar-project"}]
keywords = ["inference", "multimodal", "llm", "serving", "engine"]
classifiers = [
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Operating System :: POSIX :: Linux",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
    "Environment :: GPU :: NVIDIA CUDA",
]
dependencies = [
    "fastapi",
    # floors for the HTTP stack: the first releases with the published
    # parser and form-limit fixes
    "starlette>=1.3.1",
    "h11>=0.16.0",
    "numpy",
    "PyYAML",
    "pyzmq",
    "msgpack",
    "python-multipart>=0.0.31",
    "requests",
    "torch>=2.10.0,<2.13.0",
    "torchvision>=0.25.0",
    "torchaudio>=2.10.0",
    "uvicorn",
    # uvicorn serves WebSockets (/v1/realtime) only with a ws library installed
    "websockets",
    "gdown",
    # Floor only: every release from 2.14.5 caps fsspec, so once a newer fsspec
    # is picked, an unbounded datasets backtracks to 1.2.1, whose tqdm<4.50 pulls
    # transformers back to 5.10, which then fails to import GenerationMixin.
    # 3.0 also needs tqdm>=4.66.3.
    "datasets>=3",
]

[project.urls]
Homepage = "https://github.com/mstar-project/mstar"
Repository = "https://github.com/mstar-project/mstar"
Issues = "https://github.com/mstar-project/mstar/issues"

[project.scripts]
mstar = "mstar.cli.main:main"
mstar-serve = "mstar.api_server.entrypoint:main"

[project.optional-dependencies]
# OmniVoice reuses the reference package for weight loading, the rule-based
# duration estimator, language/instruct validation and the pydub silence
# trim; mstar owns the graph.
#
# Deliberately not pinned here: the PyPI release has no
# `omnivoice.models.omnivoice_flashinfer`, which is the forward this graph
# calls, so it has to come from git. A direct URL in requires_dist would make
# PyPI reject the mstar upload, so it is an install step instead — see
# docs/installation.rst, same as flash-attn.
omnivoice = []
command_a_plus = [
    "flashinfer-python>=0.6.18",
    "huggingface-hub>=1.5",
    "mooncake-transfer-engine>=0.3.13.post1",
    "ninja",
    "safetensors",
    "transformers>=5.17",
]

dev = [
    "ruff<=0.16",
    "pytest>=9.0.3",
]

# Optional: non-WAV audio containers (mp3/flac/...) for the OpenAI audio API
# and SDK. WAV/PCM work without this.
audio = [
    "soundfile",
]

# Optional: Prometheus metrics at /metrics (``mstar serve --enable-metrics``).
metrics = [
    "prometheus-client>=0.20",
]

# Optional: the eval framework (`python -m benchmark.eval`, docs/evaluation.rst).
# The runner, metrics and reports need only aiohttp and numpy; the judges
# (Whisper, WavLM speaker similarity, UTMOS via torch.hub), the dataset
# builders, compare's media inputs and PSNR checks (PyAV, Pillow) and the
# charts import the rest lazily. Install it in a separate client environment
# if the server's should stay lean.
eval = [
    "aiohttp",
    "av",
    "datasets",
    "huggingface-hub",
    "matplotlib",
    "Pillow>=12.3.0",
    "soundfile",
    "transformers",
]

# Optional: the opt-in AudioSeal watermark on generated speech
# (``audio_watermark`` in a deployment's model_kwargs; MIT code and weights).
# 0.3 may change the streaming layers mstar.model.audio_watermark drives.
audioseal = [
    "audioseal>=0.2,<0.3",
]

# Optional: server_vad turn detection on /v1/realtime. Silero VAD (MIT) ships
# its 2 MB ONNX weights in the wheel; onnxruntime (MIT) runs them on one thread.
# semantic_vad also runs Pipecat's Smart Turn v3 (BSD-2 weights, fetched
# separately) with onnxruntime on Whisper features from transformers (Apache-2.0).
vad = [
    "silero-vad>=5.1",
    "onnxruntime>=1.17",
    "transformers",
]

# Optional: serve a deployment as a NVIDIA Dynamo backend
# (python -m mstar.integrations.dynamo). Nothing outside
# mstar/integrations/dynamo/ imports these.
dynamo = [
    "ai-dynamo>=1.4.0,<1.5",
    "uvloop",
]

bagel = [
    "einops",
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "Pillow>=12.3.0",
    "regex",
    "safetensors",
    "torchvision",
    "torchaudio",
    "torchcodec",
    "transformers",
]

bagel_xpu = [
    "einops",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "Pillow>=12.3.0",
    "regex",
    "safetensors",
    "torchvision",
    "torchaudio",
    "torchcodec",
    "transformers",
    "vllm-xpu-kernels==0.1.15.4",
]

cosmos3 = [
    # PyAV backs torchvision's write_video, the video-container fallback used
    # when torchcodec is too old to ship VideoEncoder (< 0.9).
    "av",
    # The Cosmos3 reference pipeline (used by the parity tests) landed in
    # diffusers 0.39; serving itself uses AutoencoderKLWan and the scheduler.
    "diffusers>=0.39",
    # bs=1 dense attention fast path. The wheel is ABI-tied to the torch/CUDA
    # build; on a mismatch the engine runs the dense pass on FlashInfer's
    # ragged prefill instead. See docs/models.rst.
    "fa3-fwd",
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "Pillow>=12.3.0",
    "safetensors",
    "torchvision",
    "torchcodec",
    "transformers",
]

qwen3_omni = [
    # NOTE: flash-attn is required by Qwen3-Omni but is NOT listed here — its
    # prebuilt wheels aren't on PyPI, so a plain install compiles from source
    # (and fails on CUDA 13). Install it separately; see docs/installation.rst.
    "einops",
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "Pillow>=12.3.0",
    "regex",
    "qwen-omni-utils",
    # qwen-omni-utils imports audioread for a video's audio track but does not
    # declare it, and librosa no longer pulls it in
    "audioread",
    "numba>=0.61",
    "torchvision",
    "torchaudio",
    "torchcodec",
    # the vision encoder builds its grid inputs with transformers.vision_utils
    "transformers>=5.18",
    "datasets",
    "ninja",  # speeds up the first-use JIT build of the vendored MoE align kernel
]

# qwen-tts is an install step with --no-deps, not a dependency: mstar loads only
# its 12 Hz speech-tokenizer modules (under transformers 4.57.3 or 5.x), but its
# metadata pins transformers==4.57.3 and accelerate==1.12.0. No environment that
# also has diffusers>=0.40 or OmniVoice can satisfy that pin, and installing it
# into one downgrades huggingface-hub under them. See docs/installation.rst.
qwen3_tts = [
    "einops",
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "safetensors",
    "soundfile",  # reference-audio decoding for Base voice cloning
    "transformers>=4.57.3",
]

fish_s2_pro = [
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "safetensors",
    "soundfile",  # reference-audio decoding for voice cloning
    "transformers",
]

kokoro = [
    # misaki is the G2P (lexicon + spaCy tagger); `misaki[en]` additionally
    # bundles espeak-ng (GPL) for out-of-dictionary words and is optional.
    # The spaCy model is fetched on first use: `python -m spacy download en_core_web_sm`.
    "misaki>=0.9.4",
    "spacy>=3.8",
    "num2words",
    "huggingface-hub",
    "transformers",
]

# Chatterbox / Chatterbox-Turbo: resemble-perth (MIT) carries the PerTh
# watermark network applied to every output; pyloudnorm normalises Turbo's
# reference clip like the reference package. Both are imported lazily.
# resemble-perth 1.0.1 (the latest) imports pkg_resources, which setuptools 82
# removed; without it the package hides its watermarker.
chatterbox = [
    "flashinfer-python>=0.6.4",
    "huggingface-hub",
    "librosa",
    "mooncake-transfer-engine>=0.3.13.post1",
    "pyloudnorm",
    "resemble-perth",
    "safetensors",
    "setuptools<82",
    "tokenizers",
    "torchcodec",
    "transformers",
]
chatterbox_multilingual = [
    # Chatterbox Multilingual's Japanese kana reading and Chinese word segmentation
    "pykakasi==2.3.0",
    "spacy-pkuseg",
]

orpheus = [
    "einops",
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "safetensors",
    "transformers",
]

pi05 = [
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "safetensors",
    "transformers",
    "triton",
]

vjepa2 = [
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "safetensors",
    "torchcodec",
]

wan22 = [
    # 0.39 is the diffusers release the Wan2.2 golden-reference oracle ran on;
    # the wrapped AutoencoderKLWan/UMT5 components are equivalence-tested
    # against it (floor only — an upper cap would block installs without
    # preventing breakage). accelerate is required by the HF loaders
    # (transformers' UMT5 path) to honor _keep_in_fp32_modules at load.
    "accelerate",
    "diffusers>=0.39",
    "huggingface-hub",
    "transformers",
    # mp4 encode for the video output. PyAV bundles its own FFmpeg libs;
    # torchcodec is unusable here without a system FFmpeg install.
    "av",
]

waypoint = [
    # mp4 encode for benchmark_streaming.py --save-videos.
    "av",
    "huggingface-hub",
    "safetensors",
    # TAEHV is installed separately at a pinned revision. PyPI rejects project
    # metadata containing direct-URL dependencies; see docs/installation.rst.
    # Only the reference needs this: world_engine passes pos_ids as a TensorDict,
    # so the parity tests import it. Serving does not — components/dit.py uses a
    # NamedTuple to keep tensordict out of the serving path.
    "tensordict==0.10.0",
    # flash-attn-4 (flash_attn.cute, the default flex attention backend) is not
    # on PyPI; install it separately, see docs/installation.rst.
]

lingbot_world = [
    # UMT5 and the Wan2.1 VAE load through transformers / diffusers (see [wan22]);
    # scipy resamples the camera trajectory (Slerp) as the reference does;
    # ftfy and regex clean the prompt as the reference's T5 tokenizer does.
    # The engine's ragged attention runs on FlashInfer; flash-attn (FA2 varlen,
    # what the reference attends with under reference_numerics) is installed
    # separately, see docs/installation.rst.
    "accelerate",
    "diffusers>=0.39",
    "einops",
    "flashinfer-python>=0.6.14",
    "ftfy",
    "huggingface-hub",
    "regex",
    "safetensors",
    "scipy",
    "transformers",
]

flux2_klein = [
    # FLUX.2 [klein] 4B/9B: diffusers is the parity oracle in the tests only; serving
    # runs the native ports. transformers provides the Qwen3 tokenizer (chat template).
    "diffusers>=0.39",
    "flashinfer-python>=0.6.4",
    "huggingface-hub",
    "Pillow>=12.3.0",
    "safetensors",
    "torchvision",
    "transformers",
]

vjepa2_ac = [
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "safetensors",
    "torchcodec",
]

# ASR models: Whisper-large-v3, Higgs Audio
asr = [
    "einops",
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "safetensors",
    # decodes WAV / FLAC / OGG / MP3 uploads without FFmpeg (torchcodec takes the rest)
    "soundfile",
    # torchcodec doesn't declare its torch requirement and loads only next to the torch
    # it was built for, so the extra pins the pair the Dockerfiles ship (torch 2.10 with 0.10)
    "torch>=2.10.0,<2.11",
    "torchcodec==0.10.*",
    "transformers",
    "datasets",
    "jiwer",  # WER computation for asr_eval.py
    "numba>=0.61",  # Whisper word timestamps' DTW (components/alignment.py)
]

# GLM-5.x
glm = [
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "ninja",  # speeds up the first-use JIT build of the vendored MoE align kernel
    "safetensors",
    "transformers",
    "triton",
]

all = [
    "ruff",
    "pytest>=9.0.3",
    "soundfile",
    "silero-vad>=5.1",
    "onnxruntime>=1.17",
    "av",
    "diffusers>=0.39",
    "fa3-fwd",
    "einops",
    "flashinfer-python>=0.6.14",
    "huggingface-hub",
    "mooncake-transfer-engine>=0.3.13.post1",
    "Pillow>=12.3.0",
    "regex",
    "safetensors",
    "torchvision",
    "torchaudio",
    "torchcodec",
    # Qwen3-TTS's speech tokenizer (qwen-tts, installed --no-deps) needs check_model_inputs,
    # and Qwen3-Omni's vision encoder needs transformers.vision_utils
    "transformers>=5.18",
    "safetensors",
    "triton",
    "qwen-omni-utils",
    "audioread",  # see the qwen3_omni extra
    # qwen-tts is installed separately with --no-deps; see the [qwen3_tts] extra.
    "numba>=0.61",
    "ninja",  # speeds up the first-use JIT build of the vendored MoE align kernel
    # wan22 (see the [wan22] extra for the rationale; av / diffusers already above)
    "accelerate",
    # waypoint. TAEHV is intentionally installed separately because PyPI rejects
    # direct-URL dependencies in project metadata; see docs/installation.rst.
    "tensordict==0.10.0",
    # lingbot_world: camera trajectory resampling and prompt cleaning
    "scipy",
    "ftfy",
    # flash-attn is intentionally omitted (Qwen3-Omni needs it) — install it
    # separately, see docs/installation.rst.
    # flash-attn-4 (waypoint's default flex attention backend) is also installed
    # separately, see docs/installation.rst.
    "jiwer",
    # kokoro's G2P (see the [kokoro] extra). The Docker images also install the
    # spaCy tagger it loads, en_core_web_sm.
    "misaki>=0.9.4",
    "spacy>=3.8",
    "num2words",
    "audioseal>=0.2,<0.3",  # see the audioseal extra
    # omnivoice is intentionally omitted for the same reason as flash-attn: it
    # has to come from git, which PyPI will not accept in requires_dist.
    # See docs/installation.rst.
]

[tool.setuptools.packages.find]
where = ["."]
include = ["mstar*"]
exclude = ["tests*", "benchmark*", "examples*"]

# Ship the vendored CUDA source so it can be JIT-compiled on first use, and the
# default deployment configs (copied from repo-root configs/ into
# mstar/default_configs/ at build time; see setup.py) so `mstar serve <model>`
# works from a pip install.
[tool.setuptools.package-data]
"mstar.utils.fused_moe" = ["csrc/*.cu", "csrc/*.cuh", "csrc/*.h", "csrc/*.cpp", "configs/*.json"]
"mstar.default_configs" = ["*.yaml"]

[tool.ruff]
exclude = [".git", ".ruff_cache", ".venv", "ref"]
line-length = 120
target-version = "py312"

[tool.ruff.lint]
fixable = ["ALL"]
unfixable = []
select = ["F", "E", "W", "I", "B", "PL", "N"] 
ignore = [
    "B006",    # Do not use mutable data structures for argument defaults
    "B008",    # Do not perform function call in argument defaults
    "E741",    # Ambiguous variable name
    "F841",    # Local variable is assigned to but never used
    "N801",    # Class name should be in CamelCase
    "N802",    # Function name should be lowercase
    "N803",    # Argument name should be lowercase
    "N806",    # Variable in function should be lowercase
    "N812",    # Lowercase imported as non-lowercase
    "PLC0415", # `import` should be at the top-level of a file
    "PLR0911", # Too many return statements
    "PLR0912", # Too many branches
    "PLR0913", # Too many arguments in function definition
    "PLR0915", # Too many statements
    "PLR2004", # Magic value used in comparison
    "PLW0603", # Using the global statement
    "PLW2901", # Loop variable overwritten by assignment target
    "PLR0917", # Too many positional arguments
]

[tool.ruff.lint.per-file-ignores]
# Intentional star-import re-export of the graph base API.
"mstar/graph/graph_io.py" = ["F403", "F405"]
# Imports are deliberately placed after a module-level pytest.skip().
"test/modular/test_phase1.py" = ["E402"]
# Imports are deliberately placed after module-level pytest.importorskip().
"test/rust/*.py" = ["E402"]
# Vendored from vLLM and kept diffable against upstream; see its docstring.
"mstar/utils/causal_conv1d/kernels.py" = ["B007", "F841", "PLR5501"]

[tool.ruff.format]
quote-style = "double"
line-ending = "auto"
docstring-code-format = true