# pfnet/plamo-translate-cli architecture

> Architecture diagram of the GitHub repository pfnet/plamo-translate-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pfnet/plamo-translate-cli
- Repository: https://github.com/pfnet/plamo-translate-cli

## Overview

plamo-translate-cli accepts text through its CLI or MCP interface, prepares a translation request, and dispatches it to an MLX or llama.cpp server for local model inference. The MLX path supports PLaMo 2 and PLaMo 3 checkpoint loading, prompting, and streaming; llama.cpp resolves GGUF models and serves translations through its local process. The README also documents MCP-client use and model selection. Arrows are limited to relationships shown in excerpts, the source index, or README; some backend internals are represented by their exact source paths because their full implementations were not sampled.

Main entry points: [`src/plamo_translate/main.py`](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/main.py) (CLI entrypoint), [`src/plamo_translate/servers/mlx/server.py`](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/server.py) (MLX backend), [`src/plamo_translate/servers/llama_cpp/server.py`](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/llama_cpp/server.py) (llama.cpp backend), [`src/plamo_translate/servers/mlx/loader.py`](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/loader.py) (MLX checkpoint loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and MCP"]
  node_main["CLI entrypoint<br/>[main.py]"]
  node_mcp_client["MCP client<br/>[translate.py]"]
end

subgraph group_backend["Inference servers"]
  node_translation_server["MCP translation server<br/>[server.py]"]
  node_mlx_server["MLX backend<br/>[server.py]"]
  node_llama_server["llama.cpp backend<br/>[server.py]"]
  node_mock_server["Mock backend<br/>[server.py]"]
  node_server_utils["Server configuration<br/>[utils.py]"]
  node_warning_filters["Optional dependency warnings<br/>[warnings.py]"]
end

subgraph group_mlx["MLX models"]
  node_mlx_loader["MLX checkpoint loader<br/>[loader.py]"]
  node_mlx_model["PLaMo 2 model setup<br/>[model.py]"]
  node_plamo3_prompt["PLaMo 3 prompts<br/>[pfml3.py]"]
  node_plamo3_runtime["PLaMo 3 runtime<br/>[plamo3_runtime.py]"]
  node_plamo3_model["PLaMo 3 architecture<br/>[plamo3.py]"]
  node_metal_kernels["Metal acceleration<br/>[plamo3_metal.py]"]
end

subgraph group_models["Model assets"]
  node_release_assets["MLX release assets<br/>[release.py]"]
  node_gguf_resolver["GGUF model resolver<br/>[model.py]"]
end

node_user(("CLI user"))
node_model_hub[("Hugging Face Hub")]
node_llama_process["llama-server process"]
node_mcp_app(("MCP client application"))

node_user -->|"submits text"| node_main
node_main -->|"invokes"| node_mcp_client
node_main -->|"starts backend"| node_mlx_server
node_main -->|"starts backend"| node_llama_server
node_main -->|"starts backend"| node_mock_server
node_mcp_client -->|"calls MCP tool"| node_translation_server
node_translation_server -->|"serves MCP"| node_mcp_app
node_mlx_server -->|"loads model"| node_mlx_loader
node_mlx_server -->|"builds prompts"| node_plamo3_prompt
node_mlx_server -->|"generates with"| node_plamo3_runtime
node_mlx_loader -->|"configures model"| node_mlx_model
node_mlx_loader -->|"suppresses warnings"| node_warning_filters
node_plamo3_runtime -->|"runs model"| node_plamo3_model
node_plamo3_runtime -->|"uses kernels"| node_metal_kernels
node_llama_server -->|"resolves model"| node_gguf_resolver
node_llama_server -->|"starts and queries"| node_llama_process
node_mlx_server -->|"uses configuration"| node_server_utils
node_llama_server -->|"uses configuration"| node_server_utils
node_mlx_loader -->|"downloads checkpoints"| node_model_hub
node_gguf_resolver -->|"downloads GGUF"| node_model_hub
node_release_assets -.->|"packages checkpoints"| node_model_hub

click node_main "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/main.py"
click node_mcp_client "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/clients/translate.py"
click node_translation_server "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/server.py"
click node_mlx_server "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/server.py"
click node_llama_server "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/llama_cpp/server.py"
click node_mock_server "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mock/server.py"
click node_mlx_loader "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/loader.py"
click node_mlx_model "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/model.py"
click node_plamo3_prompt "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/pfml3.py"
click node_plamo3_runtime "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/plamo3_runtime.py"
click node_plamo3_model "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/plamo3.py"
click node_metal_kernels "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/plamo3_metal.py"
click node_release_assets "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/release.py"
click node_gguf_resolver "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/llama_cpp/model.py"
click node_server_utils "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/utils.py"
click node_warning_filters "https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/warnings.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_main,node_mcp_client,node_user,node_mcp_app toneBlue
class node_translation_server,node_mlx_server,node_llama_server,node_mock_server,node_server_utils,node_warning_filters,node_model_hub toneAmber
class node_mlx_loader,node_mlx_model,node_plamo3_prompt,node_plamo3_runtime,node_plamo3_model,node_metal_kernels,node_llama_process toneMint
class node_release_assets,node_gguf_resolver toneRose
```

## Components

### CLI and MCP

- [CLI entrypoint](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/main.py): `src/plamo_translate/main.py`
- [MCP client](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/clients/translate.py): `src/plamo_translate/clients/translate.py`

### Inference servers

- [MCP translation server](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/server.py): `src/plamo_translate/servers/mlx/server.py`
- [MLX backend](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/server.py): `src/plamo_translate/servers/mlx/server.py`
- [llama.cpp backend](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/llama_cpp/server.py): `src/plamo_translate/servers/llama_cpp/server.py`
- [Mock backend](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mock/server.py): `src/plamo_translate/servers/mock/server.py`
- [Server configuration](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/utils.py): `src/plamo_translate/servers/utils.py`
- [Optional dependency warnings](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/warnings.py): `src/plamo_translate/servers/warnings.py`

### MLX models

- [MLX checkpoint loader](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/loader.py): `src/plamo_translate/servers/mlx/loader.py`
- [PLaMo 2 model setup](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/model.py): `src/plamo_translate/servers/mlx/model.py`
- [PLaMo 3 prompts](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/pfml3.py): `src/plamo_translate/servers/mlx/pfml3.py`
- [PLaMo 3 runtime](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/plamo3_runtime.py): `src/plamo_translate/servers/mlx/plamo3_runtime.py`
- [PLaMo 3 architecture](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/plamo3.py): `src/plamo_translate/servers/mlx/plamo3.py`
- [Metal acceleration](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/plamo3_metal.py): `src/plamo_translate/servers/mlx/plamo3_metal.py`

### Model assets

- [MLX release assets](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/mlx/release.py): `src/plamo_translate/servers/mlx/release.py`
- [GGUF model resolver](https://github.com/pfnet/plamo-translate-cli/blob/main/src/plamo_translate/servers/llama_cpp/model.py): `src/plamo_translate/servers/llama_cpp/model.py`

### Other components

- **CLI user**
- **Hugging Face Hub**
- **llama-server process**
- **MCP client application**

## Connections

- CLI user → CLI entrypoint: submits text (evidence: `README.md`)
- CLI entrypoint → MCP client: invokes (evidence: `src/plamo_translate/main.py`)
- CLI entrypoint → MLX backend: starts backend (evidence: `src/plamo_translate/main.py`)
- CLI entrypoint → llama.cpp backend: starts backend (evidence: `src/plamo_translate/main.py`)
- CLI entrypoint → Mock backend: starts backend (evidence: `src/plamo_translate/main.py`)
- MCP client → MCP translation server: calls MCP tool (evidence: `src/plamo_translate/clients/translate.py`)
- MCP translation server → MCP client application: serves MCP (evidence: `README.md`)
- MLX backend → MLX checkpoint loader: loads model (evidence: `src/plamo_translate/servers/mlx/server.py`)
- MLX backend → PLaMo 3 prompts: builds prompts (evidence: `src/plamo_translate/servers/mlx/server.py`)
- MLX backend → PLaMo 3 runtime: generates with (evidence: `src/plamo_translate/servers/mlx/server.py`)
- MLX checkpoint loader → PLaMo 2 model setup: configures model (evidence: `src/plamo_translate/servers/mlx/loader.py`)
- MLX checkpoint loader → Optional dependency warnings: suppresses warnings (evidence: `src/plamo_translate/servers/mlx/loader.py`)
- PLaMo 3 runtime → PLaMo 3 architecture: runs model (evidence: `src/plamo_translate/servers/mlx/plamo3_runtime.py`)
- PLaMo 3 runtime → Metal acceleration: uses kernels (evidence: `src/plamo_translate/servers/mlx/plamo3_runtime.py`)
- llama.cpp backend → GGUF model resolver: resolves model (evidence: `src/plamo_translate/servers/llama_cpp/server.py`)
- llama.cpp backend → llama-server process: starts and queries (evidence: `src/plamo_translate/servers/llama_cpp/server.py`)
- MLX backend → Server configuration: uses configuration (evidence: `src/plamo_translate/servers/mlx/server.py`)
- llama.cpp backend → Server configuration: uses configuration (evidence: `src/plamo_translate/servers/llama_cpp/server.py`)
- MLX checkpoint loader → Hugging Face Hub: downloads checkpoints (evidence: `README.md`)
- GGUF model resolver → Hugging Face Hub: downloads GGUF (evidence: `README.md`)
- MLX release assets → Hugging Face Hub: packages checkpoints
