mere.run / docs

Appearance

Repository tour ​

This page explains the shape of the repository and what each major directory owns. Use it as the bridge between the end-user docs and the source tree.

Top-level layout ​

text
mere-run/
  Package.swift
  Sources/
  Tests/
  apps/
    macos/
    ios/
  docs/
  scripts/
  vendor/

SwiftPM products ​

Package.swift defines these public products:

  • MereRunContract
  • MereRunEvaluation
  • MereRunRelayKit
  • MereRunAdmission
  • MereRunResidency
  • MereRunExecution
  • MereRunModelKit
  • MereRunQwenModel
  • MereRunGemmaModel
  • MereRunLTXModel
  • MereRunH3Model
  • MereRunLagunaModel
  • MereRunAudioModels
  • MereRunDecode
  • MereRunCore
  • MereRunTensor
  • MereRunTextEncoder
  • MereRunImageModels
  • AudioCore
  • AudioCodecs
  • AudioSTT
  • AudioQwen3ASRModel
  • AudioQwen3TTSModel
  • AudioParakeetModel
  • AudioSortformer
  • MereRunKVCache
  • AudioTTS
  • MediaIO (when its source target is available)
  • mere.run (the executable product backed by the MereRunCLI target)
  • mere.run.app (the optional SwiftUI studio backed by the MereRunApp target)

The library products provide shared contracts, model management, and runtime families. The app executable is included on Apple platforms.

The Linux compatibility boundary is the headless mere.run CLI and reusable library code. mere.run.app, SwiftUI views, app bundling, installer behavior, and DMG packaging remain macOS-only.

Linux release packaging follows the same boundary: package artifacts are headless CLI tarballs and Debian packages, not app bundles. Build and validate them on the Linux host class they target.

Source tree ​

The apps/ directory owns the two user-facing Apple clients. Shared runtime and relay behavior remains in SwiftPM library targets under Sources/ so neither app becomes a second backend.

Sources/MereRunCLI ​

The public command-line surface.

  • MereRunCLI.swift: top-level command tree
  • Commands/: modality-scoped subcommands
  • Support/: shared CLI bootstrap, model inventory, output helpers, and local API support

To understand the CLI end to end, start with Sources/MereRunCLI.

apps/macos/StudioKit, apps/macos/StudioUI, apps/macos/MereRunStudio ​

The optional macOS studio, split into a SwiftUI-free model library (StudioKit), the views (StudioUI), and the executable that owns the scenes, menus, and Sparkle wiring (MereRunStudio). It does not own runtime behavior; it turns user-facing studio requests into mere.run arguments, launches the CLI as a child process, streams stdout and stderr, saves local library metadata, and keeps the raw command surface available in the Command view and the Command Console, both rendered from the shared capability contract.

Do not make these targets part of Linux compatibility work. Linux contributors must validate the CLI and local API surfaces directly.

apps/ios ​

The XcodeGen-managed iOS Studio app, widget, unit/UI tests, entitlements, and simulator release gate. It consumes the portable relay client and selected on-device runtime paths from the root package. Maintainer-only provisioning, archive export, and App Store Connect upload automation live outside this public repository.

Sources/MereRunAdmission ​

Machine reservations, request queues, memory-pressure policy, and admission leases without inference, HTTP, or parser dependencies. See Inference admission for ownership and streaming-lifetime rules.

Sources/MereRunModelKit ​

Model identities, manifests, configured paths, registered locations, artifact pins, and installed lookup. This library depends on Foundation and Crypto. Callers supply catalog descriptors and runtime validation for installed lookup.

H3, Laguna, and shared audio model libraries ​

Sources/MereRunH3Model owns H3 model computation. Sources/MereRunLagunaModel owns Laguna target and draft computation. Sources/MereRunAudioModels owns BigVGAN layers shared by H3 and MMAudio. Core retains their runtime adapters. See H3 and Laguna runtime boundaries.

Image model libraries ​

Sources/MereRunTensor owns checkpoint loading and shared tensor kernels. Sources/MereRunTextEncoder owns the shared Qwen text encoder and vision tower. Sources/MereRunImageModels owns FLUX.2 and ZImage transformer layers and the shared VAE. Core re-exports these libraries and owns generation orchestration. See Image runtime boundaries.

Sources/MereRunQwenModel ​

Qwen-family configurations, dense and hybrid attention, expert routing, vision layers, and MTP draft state. Core retains loading, prompts, prefill scheduling, target verification, and request output. See Qwen runtime boundaries.

Sources/MereRunGemmaModel ​

Gemma configurations, text and vision layers, expert routing, attention caches, quantization, and MTP draft computation. Core retains resource loading, templates, generation, and LoRA orchestration. See Gemma runtime boundaries.

Sources/MereRunLTXModel ​

LTX transformer, video and audio VAE, diffusion decoder, upsampling, duration, and model-cache computation. Core retains checkpoint loading, conditioning, generation, and media output. See LTX runtime boundaries.

Sources/MereRunDecode ​

Sources/MereRunDecode owns shared autoregressive token sampling, streaming, and logprob diagnostics. It depends only on MLX and MLXRandom. Core retains model loading, tokenizer adapters, resource cleanup, and family orchestration. See shared decode boundaries for callback contracts and validation.

Sources/MereRunCore ​

The shared inference library. Core owns catalog assembly, runtime-dependent manifest templates, downloads, and family validation. It re-exports ModelKit types and delegates installed lookup through the existing ModelResolver API.

Key subdirectories:

  • Flux2Klein/: Klein image-family runtime
  • ZImageTurbo/: ZImage image-family runtime
  • HiDreamO1/: HiDream O1 image-family runtime
  • SenseNovaU15/: native SenseNova U1.5 raw-pixel generation and editing runtime
  • Krea2/: Krea 2 image-family runtime and Raw LoRA training
  • QwenImageEdit/: image editing flow
  • Gemma4/, Q35/, LFM2/, Psi/, MeBot/: text/chat model families
  • Embeddings/: embedding-generation support
  • LightOnOCR/: OCR runtime
  • Asset3D/, TripoSR/, InstantMesh/, Trellis2/: canonical mesh export plus native single-view and multiview object reconstruction
  • VLM/: vision-language model helpers
  • ACEStep/: music generation pipeline
  • Woosh/: sound-effect generation pipeline
  • LTX/: video generation pipeline
  • Cosmos3/: Cosmos3-Edge image/video generation, vision reasoning, learned-action prediction, and persistent world simulation
  • LoRA/: LoRA loading and application support
  • Support/: manifests, model resolution, model paths, and Hub snapshot helpers
  • Training/, Quantization/: advanced model-training and quantization utilities kept in the package tree

Sources/AudioCore ​

Audio-oriented shared types and common utilities used by both speech synthesis and transcription.

AudioCore/SpeechTranscriptionOperation.swift owns file transcription plans, validation, events, and outcomes. AudioSTT/SpeechTranscriptionResolver.swift resolves native backend and model inputs for CLI and API adapters.

Sources/AudioCodecs ​

Audio conversion and low-level codec support used by speech runtimes and some tests. Linux media compatibility should use ffmpeg and ffprobe discovery, including MERERUN_FFMPEG and MERERUN_FFPROBE overrides, instead of depending on Apple media frameworks.

Sources/AudioSTT ​

Speech transcription orchestration, native executors, and compatibility exports.

  • Qwen3ASR/: Qwen3 model loading, tokenization, transcription, and streaming
  • Parakeet/: Parakeet transcription path

Public Qwen ASR, Parakeet, and Sortformer types are re-exported from their owning libraries.

Speech model libraries ​

Sources/AudioQwen3ASRModel, Sources/AudioQwen3TTSModel, and Sources/AudioParakeetModel own configuration and tensor computation. Sources/AudioSortformer owns the diarization runtime. These libraries build without MereRunCore, audio codecs, or model downloads. Qwen uses the same attention caches as Core through Sources/MereRunKVCache. Sortformer uses MereRunModelKit for directory traversal. See Speech runtime boundaries.

Sources/AudioTTS ​

Text-to-speech orchestration, audio-input adapters, and compatibility exports.

  • Qwen3TTS/: native Qwen TTS loading, prompts, token generation, and audio output
  • TTS/: shared TTS support types

Tests ​

Tests/MereRunCoreTests ​

Core runtime, resolver, model, and subsystem tests. This is where most behavioral validation lives.

Tests/MereRunCLITests ​

Command parsing and CLI-facing behavior tests. When you change the public surface or command semantics, this is where you should add or update coverage.

Scripts ​

scripts/check.sh ​

The main repo validation entrypoint. It runs:

  • Build and unit tests.
  • CLI help smoke for the public command tree.
  • Output-format and hygiene checks.
  • Optional end-to-end smoke runs.

scripts/e2e_smoke.sh ​

Sequential real-world smoke tests for installed models. Use this when you want to validate actual runtime paths in addition to build and parse coverage.

scripts/package-linux.sh ​

Builds Linux release artifacts for the headless CLI on Linux:

  • dist/linux/mere-run-<version>-linux-<arch>.tar.gz
  • dist/linux/mere-run_<version>_<deb-arch>.deb
  • CUDA variants with --artifact-suffix cuda, such as mere-run-<version>-linux-x86_64-cuda.tar.gz
  • dist/linux/SHA256SUMS

Run the package script on the Linux host class you intend to validate. CUDA package artifacts need matching CUDA hardware for meaningful runtime smoke coverage.

Vendor artifacts ​

vendor/llama.xcframework ​

Vendored llama.cpp runtime used by the local code path and API serving.

The repo expects this artifact to live inside vendor/; it is intentionally part of the standalone package layout so the package does not depend on the old monorepo payload structure.

vendor/mlx-swift_Cmlx.bundle ​

Vendored MLX shader resources used by the macOS runtime.

Linux hosted CI should stay CPU MLX-oriented and fixture-sized. CUDA-specific runtime smokes are required for meaningful Linux arm64 packages, but they run on real CUDA hosts rather than the public pull-request gate.

THIRD_PARTY_NOTICES.md ​

Tracks provenance and license notices for vendored artifacts and other bundled third-party materials that ship with the public repo.

Docs ​

The docs are layered intentionally:

  • user-facing setup and reference in docs/
  • runtime-family guides in docs/runtime/
  • contributor/source-reading material in docs/internals/

Start at the mere.run documentation home to navigate by audience.

  1. Read the architecture map.
  2. Open Sources/MereRunCLI/MereRunCLI.swift.
  3. Pick one command family in Sources/MereRunCLI/Commands.
  4. Jump to the matching runtime family in Sources/MereRunCore, Sources/AudioSTT, or Sources/AudioTTS
  5. Use the runtime family documentation to follow the load, prepare, generate, decode, and output path.

Released under the MIT License.

Copyright © 2026 Sawfwair Inc. and mere.run contributors