How sawfwair/mere-run works
Purpose and entry points
mere.run is a Swift local-first multimodal inference runtime for Apple Silicon and headless Linux. Its public entry point is the mere.run CLI, built from Sources/MereRunCLI/MereRunCLI.swift; command registration and modality dispatch live in Sources/MereRunCLI/Commands/. An optional macOS SwiftUI Studio is a second client over the same CLI/model-store/run concepts, rooted at Sources/MereRunApp/MereRunApp.swift and Sources/MereRunApp/MereRunController.swift.
Command orchestration and durable runs
CLI commands translate user requests into model resolution, preflight, inference, artifact writing, and structured output. Shared CLI support includes progress, admission, plans, and runtime pools: Sources/MereRunCLI/Support/ImageGenerationRunPlan.swift, Sources/MereRunCLI/Support/StructuredRunOutput.swift, and Sources/MereRunCLI/Support/RuntimeModelPool.swift. The boundary is deliberately command-facing: modality commands own user contracts while MereRunCore owns model-specific execution.
Model lifecycle and storage
Managed model IDs resolve through catalogs, manifests, component pins, local storage, and validation before inference. Central ownership is in Sources/MereRunCore/ManagedModelCatalog.swift, Sources/MereRunCore/ModelStorageManager.swift, and Sources/MereRunCore/MereRunModelManifest.swift. Models are pulled from Hugging Face-backed snapshot caches and materialized into the local model store; storage locking and content sharing protect concurrent pull/remove/GC operations. Adapters follow a parallel managed catalog path (Sources/MereRunCore/ManagedAdapterCatalog.swift).
Native inference families
Sources/MereRunCore contains the primary MLX-backed implementations for text, image, video, music, sound, vision, 3D, and training. Each family generally encapsulates resource resolution, weight loading, preprocessing, model layers, generation/sampling, and artifact export. Representative execution roots are Sources/MereRunCore/Gemma4/Gemma4Generator.swift, Sources/MereRunCore/ZImageTurbo/ZImageTurboGenerator.swift, and Sources/MereRunCore/Wan2/Wan2Generation.swift. Shared decode and quantization layers—Sources/MereRunCore/Decode/AutoregressiveDecodeEngine.swift and Sources/MereRunCore/Quantization/QuantizationIO.swift—cross-cut text and other autoregressive paths.
Audio and media boundary
Audio is split from general model code into codecs/DSP, STT, and TTS modules: Sources/AudioCodecs/PCMStreamConverter.swift, Sources/AudioSTT/Parakeet/ParakeetASRLiveSession.swift, and Sources/AudioTTS/Qwen3TTS/Qwen3TTSTalker.swift. Sources/AudioCore/ASRBackendRouting.swift selects speech-recognition backends. Media ingestion/export is abstracted behind Sources/MediaIO/MediaIO.swift, with Apple-native and FFmpeg implementations (Sources/MediaIO/AppleMediaVideoIO.swift, Sources/MediaIO/FFmpegMediaIO.swift); FFmpeg/ffprobe are required external executables on relevant paths.
Serving, workflows, and remote execution
The CLI can host an OpenAI-compatible local API through Sources/MereRunCLI/Commands/APIServeCommand.swift, with preflight and sidecar model-pool support in Sources/MereRunCLI/Support/APIServePreflight.swift and Sources/MereRunCLI/Support/APISidecarModelPool.swift. Portable workflow graphs are typed, preflighted, bundled, and run locally or via configured remote executors through Sources/MereRunCLI/Support/WorkflowGraph.swift, Sources/MereRunCLI/Support/WorkflowRunner.swift, and Sources/MereRunCLI/Support/WorkflowRemoteExecutors.swift. Relay/node services and plugins are external repositories, not hosted inference infrastructure here.
Runtime and platform dependencies
The principal runtime is Swift 6 with MLX/Metal on Apple Silicon; Linux is headless CLI-oriented, with CUDA-supported release lanes. Native bridges include ONNX/CoreML (Sources/COnnxRuntimeCoreML/COnnxRuntimeCoreML.c, Sources/MereRunCore/ONNX/ONNXMLXInitializerLoader.swift) and a llama shim (Sources/llama/shim.h) used by code/API paths. macOS-specific UI, media, Quick Look, and deep-link integration remain isolated in Sources/MereRunApp/.
Main entry points: MereRunCore MereRunCore · ManagedModelCatalog.swift Managed model catalog · Gemma4Generator.swift Generation families · ModelStorageManager.swift Local model store
Components 22
Clients
- mere.run CLI · Primary local-first runtime entry point.
Sources/MereRunCLI/MereRunCLI.swift - macOS Studio · Optional graphical client over shared run and model concepts.
Sources/MereRunApp/MereRunApp.swift - Studio controller
Sources/MereRunApp/MereRunController.swift
CLI orchestration
- Modality commands · Own user-facing modality contracts and dispatch.
- Run plans & output · Builds durable plans and structured results.
Sources/MereRunCLI/Support/ImageGenerationRunPlan.swift - Runtime model pool · Shares loaded runtime models across runs.
Sources/MereRunCLI/Support/RuntimeModelPool.swift - OpenAI-compatible API · CLI-hosted serving endpoint with preflight and sidecar pooling.
Sources/MereRunCLI/Commands/APIServeCommand.swift - Workflow runner · Runs typed, preflighted workflows locally or remotely.
Sources/MereRunCLI/Support/WorkflowRunner.swift - Remote executors · Configured external workflow execution targets.
Sources/MereRunCLI/Support/WorkflowRemoteExecutors.swift
Model lifecycle
- Managed model catalog · Resolves managed IDs, manifests, and component pins.
Sources/MereRunCore/ManagedModelCatalog.swift - Managed adapter catalog · Parallel managed lifecycle for adapters.
Sources/MereRunCore/ManagedAdapterCatalog.swift - Local model store · Materializes, validates, locks, shares, and garbage-collects models.
Sources/MereRunCore/ModelStorageManager.swift - Model manifests
Sources/MereRunCore/MereRunModelManifest.swift - Hugging Face snapshots · Snapshot cache backing model pulls.
Inference runtime
- MereRunCore · Model-specific resource resolution, loading, generation, and export.
Sources/MereRunCore - Generation families · Text, image, video, music, sound, vision, 3D, and training implementations.
Sources/MereRunCore/Gemma4/Gemma4Generator.swift - Decode & quantization · Cross-cutting autoregressive decoding and quantization I/O.
Sources/MereRunCore/Decode/AutoregressiveDecodeEngine.swift - Native ML bridges · ONNX/CoreML and llama bridge paths.
Sources/COnnxRuntimeCoreML/COnnxRuntimeCoreML.c - MLX/Metal or CUDA · Apple Silicon MLX/Metal runtime with headless Linux CUDA release lanes.
Audio & media
- Audio STT/TTS · Speech backend routing, live ASR, and TTS.
Sources/AudioCore/ASRBackendRouting.swift - Media I/O · Apple-native and FFmpeg-based media ingestion and export.
Sources/MediaIO/MediaIO.swift - FFmpeg / ffprobe · Required for relevant media paths.
Connections 22
- mere.run CLI → Modality commands: registers
- macOS Studio → Studio controller: coordinates through
- Studio controller → Modality commands: shares run concepts
- Modality commands → Run plans & output: builds plans and output
- Modality commands → Runtime model pool: uses
- Modality commands → Managed model catalog: resolves models
- Modality commands → MereRunCore: executes
- Modality commands → OpenAI-compatible API: hosts
- Modality commands → Workflow runner: runs
- Workflow runner → Remote executors: dispatches remotely
- Managed model catalog → Model manifests: reads
- Managed model catalog → Local model store: materializes into
- Managed adapter catalog → Local model store: manages in
- Local model store → Hugging Face snapshots: pulls snapshots from
- Runtime model pool → MereRunCore: reuses loaded models
- MereRunCore → Generation families: contains
- Generation families → Decode & quantization: uses
- MereRunCore → Audio STT/TTS: routes audio inference
- MereRunCore → Media I/O: ingests and exports media
- Generation families → Native ML bridges: uses
- MereRunCore → MLX/Metal or CUDA: runs on
- Media I/O → FFmpeg / ffprobe: invokes when needed