# Zimfo

**Zimfo** is an offline, on-device chat app (iOS + macOS) that answers
questions from locally-loaded [ZIM](https://wiki.openzim.org/) archives —
Wikipedia, OpenStreetMap street data ([streetzim](https://github.com/jasontitus/streetzim)),
and medical ([mdwiki](https://mdwiki.org/)) — using a local fine-tuned LLM
that drives a tool loop over those archives. **Nothing leaves the device.**

Ask *"tell me about the Duchy of Lithuania"*, *"how do solar panels work?"*,
*"what's near me?"*, *"how far is it to the cathedral?"*, or *"compare Musk
and Bezos"* — Zimfo searches the ZIMs, reads the right article, and answers.
Follow-ups (*"tell me more"*, *"yes"*, *"what's near there?"*, *"the second
one"*) resolve against a deterministic on-device conversation focus rather
than the small model's own memory, and a "let's discuss X" mode grounds
multi-turn Q&A in retrieved article passages — so a walking conversation
actually holds together.

**Getting the content is now part of the app.** A fresh install offers two
paths to a working library: **Nearby Sharing** — a friend who already has
Zimfo (the person who recommended it, usually) turns on *Share my library*
and their Wikipedia/StreetZIM files — **and the AI models: chat and
voice** — copy straight to the new device over AWDL / peer-to-peer Wi-Fi,
no router or internet needed, with per-chunk SHA-256 verification,
multi-device parallel pull, and resume (powered by the vendored
[LocalSwarm](https://github.com/jasontitus/localswarm) engine,
`ios/LocalPackages/LocalSwarm/`); the received chat model drops into the
provider's own cache slot and auto-activates, and the Kokoro/Supertonic
voice folders land where the TTS engines look, so the whole bootstrap —
reading *and* speaking — works with zero connectivity — and an **in-app
download catalog**:
Wikipedia editions with and without pictures plus the full StreetZIM region
list, multi-selected and fetched by a background `URLSession` that keeps
going while the app is suspended and keeps the device awake while it's
frontmost. Either way, finished files land in the library and are ready to
chat — and ready to share onward to the next person.

**The shipping model** is a LoRA-fine-tuned
[LFM2.5-8B-A1B](https://huggingface.co/sliderforthewin/lfm2.5-8b-a1b-ft-GGUF)
(8.3B-total / 1.5B-active hybrid MoE) quantized to **IQ3_XS with an
importance matrix** calibrated on the app's own tool-call transcripts:
12/13 on the tool-calling eval grid at **~3.6 GB peak RSS** and ~136 t/s
decode (M2 Max), running through llama.cpp with a **32k context** and
cross-turn KV prefix reuse (follow-up turns prefill ~23 tokens instead of
the whole transcript). How we got here — the full stock-model sweep
(Gemma 3/4, Qwen 3/3.5, Phi, …), the fine-tuning pivot, the Gemma 4 QAT/MTP
investigation, and the quantization frontier — is written up in
[`MODEL_EVALUATION_HISTORY.md`](MODEL_EVALUATION_HISTORY.md).

This repo has three layers, smallest-dependency first:

- **The shared engine — [`swift/MCPZimKit`](swift/)**: a transport-agnostic,
  Foundation-only Swift package. ZIM tool adapter, A\* routing-graph parser +
  router, prefix geocoder, and the conversation-state machine (focus,
  reference resolution, drift threads). Exercised by `swift test`.
- **The app — [`ios/`](ios/)**: the SwiftUI Zimfo app (on-device Gemma 4 /
  fine-tuned LFM2.5 via MLX + llama.cpp). Architecture and the pieces that
  took the most iteration are in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
- **The reusable kernel — the `mcpzim` MCP server (Python)**: the original
  backend, documented below. It exposes the same ZIM tools to *any* agent
  host over [MCP](https://modelcontextprotocol.io), so the engine isn't
  locked to the app.

## The `mcpzim` MCP server (Python)

An [MCP](https://modelcontextprotocol.io) server that makes a group of offline
[ZIM](https://wiki.openzim.org/) files available to local LLM agents. Point it
at a directory of ZIMs and the server will:

- Inventory what's there (`list_libraries`) and advertise aggregate
  capabilities (general knowledge, medical knowledge, maps/routing) based on
  what's loaded.
- Expose search and article retrieval across every ZIM (`search`,
  `get_article`, `get_main_page`).
- When it detects a [streetzim](https://github.com/jasontitus/streetzim) ZIM
  built with `--routing`, it additionally exposes `plan_driving_route`,
  `geocode`, and `route_from_places` so a local agent can ask *"give me a
  driving route from A to B"* and get street-by-street directions, distance,
  and an estimated time.

The design principle is **opportunistic capability**: start with one Wikipedia
ZIM and you get a Wikipedia server. Drop in `mdwiki_en_all_*.zim` and it also
answers medical questions. Drop in a streetzim ZIM and it can also plan driving
routes for the area the ZIM covers. Tools appear only when the underlying data
is present, so the agent's tool list never lies about what the server can do.

## Install

Requires Python 3.10+.

```sh
pip install mcpzim               # once published
# or, from a checkout:
pip install -e .
```

`libzim` is a native wheel; prebuilt wheels exist for macOS (x86_64/arm64),
Linux (x86_64/aarch64, glibc and musl) and Windows x64. On other platforms pip
will build from source and you'll need a C++ toolchain.

## Run

Drop your ZIM files into one directory and run:

```sh
export ZIM_DIR=~/zims
mcpzim                           # stdio transport (Claude Desktop / Code)
mcpzim ~/zims/wikipedia.zim ~/zims/streetzim_ma.zim   # explicit paths
mcpzim --transport streamable-http --host 0.0.0.0 --port 8765  # LAN
```

Add to `~/.config/claude-desktop/claude_desktop_config.json` (or the
equivalent for your MCP client):

```json
{
  "mcpServers": {
    "mcpzim": {
      "command": "mcpzim",
      "env": { "ZIM_DIR": "/Users/me/zims" }
    }
  }
}
```

## Tools

Always available:

| Tool | What it does |
| --- | --- |
| `list_libraries` | Inventory: list every ZIM with kind, title, language, and the aggregate capabilities (`general_knowledge`, `medical`, `maps`, ...). Call this first. |
| `search` | Full-text search across every ZIM (uses libzim's Xapian index when present, falls back to title-prefix suggestions). Accepts an optional `kind` filter. |
| `get_article` | Fetch an entry by path; HTML is stripped of navbox / infobox / script cruft so the LLM sees clean text. |
| `get_main_page` | Main page of one ZIM, or of every loaded ZIM. |

Only present when a streetzim ZIM with routing data is loaded:

| Tool | What it does |
| --- | --- |
| `plan_driving_route` | A* over the streetzim routing graph. Input: two `lat/lon` pairs. Output: total distance, duration, polyline, and a road-segment list coalesced by street name. |
| `geocode` | Resolve a place/address string to coordinates using streetzim's prefix-chunked search index. |
| `route_from_places` | Convenience: geocode both endpoints then plan a route. |

Cost/heuristic in the router match streetzim's JS viewer exactly:
`edge_cost = distance_m / (speed_kmh / 3.6)` and `heuristic =
haversine / (100/3.6)`, so results are identical to what the in-browser
viewer would produce.

## Supported ZIMs

Type detection runs at scan time and uses a combination of filename prefix, the
ZIM's `Name` / `Tags` / `Creator` / `Publisher` metadata, and signature entries
inside the archive. Out of the box:

- **Wikipedia** — any `wikipedia_*.zim` (`Creator: Wikipedia`, tagged
  `wikipedia`).
- **mdwiki** — `mdwiki_*.zim` from the WikiProjectMed Foundation
  (tagged `mdwiki` / `medical`).
- **streetzim** — detected by the presence of `routing-data/graph.bin` or
  `map-config.json` inside the archive.
- **generic** — anything else (a `*.zim` still gets served; only the
  `ZimKind.GENERIC` default toolset applies).

## Example session

```
> list_libraries
{"zims": [
   {"path": ".../wikipedia_en_all_nopic_2026-03.zim", "kind": "wikipedia", ...},
   {"path": ".../mdwiki_en_all_2026-03.zim", "kind": "mdwiki", ...},
   {"path": ".../streetzim_ma.zim", "kind": "streetzim", "has_routing": true, ...}
 ],
 "by_kind": {"wikipedia": 1, "mdwiki": 1, "streetzim": 1},
 "capabilities": ["encyclopedia", "general_knowledge", "geocode",
                  "get_article", "list_libraries", "maps", "medical",
                  "plan_route", "search"]}

> route_from_places {"origin": "Boston Common", "destination": "Fenway Park"}
{"origin_resolved": {"name": "Boston Common", "lat": 42.3554, "lon": -71.0655, ...},
 "destination_resolved": {"name": "Fenway Park", "lat": 42.3467, "lon": -71.0972, ...},
 "distance_km": 3.27, "duration_min": 9.4,
 "roads": [
    {"name": "Beacon Street", "distance_m": 412.3, "duration_s": 44.0},
    ...
 ],
 "turn_by_turn": ["Beacon Street for 0.41 km (~0.7 min)", ...],
 "polyline": [[42.3554, -71.0655], ...]}
```

## Mobile

Concrete paths that actually work, matched to the on-device LLM hosts people
are shipping in 2026:

| Platform | LLM host | Path | Status |
| --- | --- | --- | --- |
| Desktop | Claude Desktop / Code, any MCP client | This Python server via `stdio` or `streamable-http` | **Works today** |
| Android | [Google AI Edge Gallery](https://github.com/google-ai-edge/gallery) (Gemma 4 + LiteRT-LM, Apache 2.0) | Small Kotlin fork — add a `@Tool fun callMcp(...)` that talks JSON-RPC/HTTP to this Python server | **See [`mobile/android/README.md`](mobile/android/README.md)** — ~80 lines of Kotlin + one SKILL.md |
| Android (fully offline) | same | Run `mcpzim` under Termux on the same device | Works; Termux has to build `libzim` from source (`pkg install python clang cmake`) |
| iOS | **The Zimfo app in this repo** ([`ios/`](ios/)) — fine-tuned LFM2.5 via llama.cpp (+ MLX models) | Links **[`swift/MCPZimKit`](swift/)** — pure-Swift routing graph parser, A*, geocoder, transport-agnostic MCP tool adapter, conversation-state machine — with a `ZimReader` backed by `CoreKiwix.xcframework`. | **Works today** — see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
| iOS | Google AI Edge Gallery (closed-source app) | Available on the App Store since 2026-04 with Gemma 4 support — fine for trying models, but no tool-calling hook into this server. | Demo-only |

The short version: on Android the open-source Agent Chat host already knows how
to call a tool, so a short Kotlin patch makes it speak to this Python server.
On iOS, the LLM host has no tool-calling layer yet, so the companion Swift
package ships (a) the same algorithms in pure Swift for in-process use, and (b)
a transport-agnostic MCP adapter you can plug into the official
[`modelcontextprotocol/swift-sdk`](https://github.com/modelcontextprotocol/swift-sdk)
when you want the model to call tools over LAN.

`swift/MCPZimKit`'s SZRG v2 parser, A* router, and prefix geocoder are
line-for-line ports of the Python implementations; the Python test suite and
the Swift test suite in `swift/Tests/MCPZimKitTests/` cover the same cases, so
if both green, you know the two agree.

## Development

```sh
pip install -e '.[dev]'
pytest
```

Tests do not require any real ZIM files; the routing tests build a tiny SZRG v2
graph in-memory using `mcpzim.routing.encode_graph_v2`, and the library tests
exercise the classifier directly.

## License

MIT.