# pipenetwork/kimi-k3-mlx architecture

> Architecture diagram of the GitHub repository pipenetwork/kimi-k3-mlx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pipenetwork/kimi-k3-mlx
- Repository: https://github.com/pipenetwork/kimi-k3-mlx

## Overview

This repository is an Apple-Silicon MLX port of Kimi-K3, with a text model, a video-capable vision tower, and a multimodal wrapper that expands each image placeholder into its full feature block before text inference. A second product workflow streams the enormous source checkpoint into MLX-compatible artifacts, with optional REAP calibration for smaller tiers. The graph distinguishes documented runtime wiring from conversion and calibration; some internal model and processor details are described only in the README, so those links cite it.

Main entry points: [`kimi_k3_vl/kimi_k3_vl.py`](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/kimi_k3_vl.py) (Multimodal model), [`scripts/convert.py`](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/convert.py) (Streaming converter), [`reference/modeling_kimi_k3.py`](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/modeling_kimi_k3.py) (Reference multimodal model), [`kimi_k3_vl/language.py`](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/language.py) (Text adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MLX inference"]
  node_vlmodel["Multimodal model<br/>[kimi_k3_vl.py]"]
  node_config["Wrapper config<br/>[config.py]"]
  node_language["Text adapter<br/>[language.py]"]
  node_textmodel["Text tower<br/>[kimi_k3.py]"]
  node_merge["Image expansion<br/>[kimi_k3_vl.py]"]
end

subgraph group_vision["Vision processing"]
  node_visionadapter["Vision adapter<br/>[vision.py]"]
  node_visionmodel["MoonViT tower<br/>[kimi_k3_vision.py]"]
  node_projector["Patch merger<br/>[kimi_k3_vision.py]"]
end

subgraph group_reference["Reference implementation"]
  node_processor["Prompt processor"]
  node_refconfig["Reference config"]
  node_reftext["Reference text model"]
  node_refmultimodal["Reference multimodal model"]
end

subgraph group_artifacts["Model artifacts"]
  node_converter["Streaming converter<br/>[convert.py]"]
  node_memory["Memory wiring<br/>[mlxmem.py]"]
end

subgraph group_calibration["Tier calibration"]
  node_calibrator["REAP calibration<br/>[reap_calibrate.py]"]
  node_calibbuilder["Calibration builder<br/>[make_calib.py]"]
end

node_user(("Prompting user"))
node_sourceweights[("Source checkpoint")]
node_mlxartifact[("MLX model artifact")]
node_calibdata["Calibration data"]

node_user -->|"provides prompt"| node_processor
node_processor -->|"formats image prompt"| node_vlmodel
node_vlmodel -->|"uses config"| node_config
node_vlmodel -->|"dispatches text"| node_language
node_vlmodel -->|"dispatches images"| node_visionadapter
node_vlmodel -->|"expands features"| node_merge
node_language -->|"wraps model"| node_textmodel
node_visionadapter -->|"wraps tower"| node_visionmodel
node_visionmodel -->|"projects features"| node_projector
node_sourceweights -->|"streams weights"| node_converter
node_converter -->|"writes artifact"| node_mlxartifact
node_calibdata -.->|"provides samples"| node_calibbuilder
node_calibbuilder -.->|"prepares calibration"| node_calibrator
node_calibrator -.->|"supplies tier plan"| node_converter
node_mlxartifact -.->|"measures inference"| node_memory
node_refmultimodal -->|"uses configuration"| node_refconfig
node_refmultimodal -->|"uses text components"| node_reftext

click node_vlmodel "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/kimi_k3_vl.py"
click node_config "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/config.py"
click node_language "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/language.py"
click node_textmodel "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3.py"
click node_merge "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/kimi_k3_vl.py"
click node_processor "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/kimi_k3_processor.py"
click node_visionadapter "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/vision.py"
click node_visionmodel "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vision.py"
click node_projector "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vision.py"
click node_converter "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/convert.py"
click node_calibrator "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/reap_calibrate.py"
click node_calibbuilder "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/make_calib.py"
click node_memory "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/mlxmem.py"
click node_refconfig "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/configuration_kimi_k3.py"
click node_reftext "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/modeling_kimi_linear.py"
click node_refmultimodal "https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/modeling_kimi_k3.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vlmodel,node_config,node_language,node_textmodel,node_merge,node_user toneBlue
class node_visionadapter,node_visionmodel,node_projector,node_sourceweights,node_mlxartifact toneAmber
class node_processor,node_refconfig,node_reftext,node_refmultimodal toneMint
class node_converter,node_memory toneRose
class node_calibrator,node_calibbuilder,node_calibdata toneIndigo
```

## Components

### MLX inference

- [Multimodal model](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/kimi_k3_vl.py): `kimi_k3_vl/kimi_k3_vl.py`
- [Wrapper config](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/config.py): `kimi_k3_vl/config.py`
- [Text adapter](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/language.py): `kimi_k3_vl/language.py`
- [Text tower](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3.py): `kimi_k3.py`
- [Image expansion](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/kimi_k3_vl.py): `kimi_k3_vl/kimi_k3_vl.py`

### Vision processing

- [Vision adapter](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vl/vision.py): `kimi_k3_vl/vision.py`
- [MoonViT tower](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vision.py): `kimi_k3_vision.py`
- [Patch merger](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/kimi_k3_vision.py): `kimi_k3_vision.py`

### Reference implementation

- [Prompt processor](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/kimi_k3_processor.py): `reference/kimi_k3_processor.py`
- [Reference config](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/configuration_kimi_k3.py): `reference/configuration_kimi_k3.py`
- [Reference text model](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/modeling_kimi_linear.py): `reference/modeling_kimi_linear.py`
- [Reference multimodal model](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/reference/modeling_kimi_k3.py): `reference/modeling_kimi_k3.py`

### Model artifacts

- [Streaming converter](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/convert.py): `scripts/convert.py`
- [Memory wiring](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/mlxmem.py): `scripts/mlxmem.py`

### Tier calibration

- [REAP calibration](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/reap_calibrate.py): `scripts/reap_calibrate.py`
- [Calibration builder](https://github.com/pipenetwork/kimi-k3-mlx/blob/main/scripts/make_calib.py): `scripts/make_calib.py`

### Other components

- **Prompting user**
- **Source checkpoint**
- **MLX model artifact**
- **Calibration data**

## Connections

- Prompting user → Prompt processor: provides prompt (evidence: `README.md`)
- Prompt processor → Multimodal model: formats image prompt (evidence: `README.md`)
- Multimodal model → Wrapper config: uses config (evidence: `kimi_k3_vl/kimi_k3_vl.py`)
- Multimodal model → Text adapter: dispatches text (evidence: `kimi_k3_vl/kimi_k3_vl.py`)
- Multimodal model → Vision adapter: dispatches images (evidence: `kimi_k3_vl/kimi_k3_vl.py`)
- Multimodal model → Image expansion: expands features (evidence: `kimi_k3_vl/kimi_k3_vl.py`)
- Text adapter → Text tower: wraps model (evidence: `kimi_k3_vl/language.py`)
- Vision adapter → MoonViT tower: wraps tower (evidence: `kimi_k3_vl/vision.py`)
- MoonViT tower → Patch merger: projects features (evidence: `README.md`)
- Source checkpoint → Streaming converter: streams weights (evidence: `scripts/convert.py`)
- Streaming converter → MLX model artifact: writes artifact (evidence: `README.md`)
- Calibration data → Calibration builder: provides samples
- Calibration builder → REAP calibration: prepares calibration (evidence: `scripts/make_calib.py`)
- REAP calibration → Streaming converter: supplies tier plan (evidence: `scripts/reap_calibrate.py`)
- MLX model artifact → Memory wiring: measures inference
- Reference multimodal model → Reference config: uses configuration (evidence: `reference/modeling_kimi_k3.py`)
- Reference multimodal model → Reference text model: uses text components (evidence: `reference/modeling_kimi_k3.py`)
