michiyomi Design Principles

1. Abstract

2. Background and problem

Maps know the shape of a road, but rarely its visible condition: worn lane markings, sidewalk width, tactile paving, blocked sightlines, and how these change over time. For local roads—which make up most of the network—understanding those conditions still often requires a site visit.

The raw material already exists. Mapillary contains vast quantities of street imagery published by citizens and organizations, and VLMs can now read it. What is missing is a design that makes the results trustworthy enough to cite. A fluent AI description does not, by itself, make clear where fact ends and interpretation begins, where the data came from, or how to represent something outside the frame. Administrative triage and research require those ambiguities to be resolved structurally.

People are not the only clients. If geospatial AI agents can ask “what did this place look like?”, verbalized street data can support dialog, navigation, and analysis. The API was therefore designed from the outset with AI agents as first-class users.

3. Design principles

The implementation follows five principles.

3.1Separate observation, computation, and interpretation

Each scene is delivered as three distinct layers: observed facts (capture year, position, and bearing metadata); deterministic features (travel bearing and image-color analysis, reproducible from the same input); and model interpretation (the VLM verbalization). The layers live in separate namespaces and never overwrite one another.

The purpose is to make the boundary between fact and interpretation visible in the data structure, rather than relying on the reader’s vigilance. This enables auditing and internal cross-checks. For example, a VLM’s Japanese description of continuous roadside trees can be compared with the machine layer’s green-view ratio. Every description is traceable through its image ID to the source photograph.

3.2Implement honesty as a specification

The most dangerous mistake is treating a location with no data as a location with nothing there. To prevent it, the coverage endpoint reports the available evidence before content is requested. The MCP tool definitions encode the workflow itself: check coverage first, then retrieve descriptions.

When honesty is part of the specification, automated tests and consistency checks can continuously verify whether the implementation still honors it.

3.3Record generation provenance for every scene

A verbalization is generated output, so a model change can change the result. Every one of the 1,914,490 scenes therefore records which model family produced it, under which output contract, and when. This provenance bundle is called a generation.

Generation is an origin label, not a quality ranking. The cloud-VLM gen1 (77,676 scenes) and home-GPU local-VLM gen2 (1,836,814 scenes, thirty-nine quarantined from search) are both adopted for serving. The local generation contains multiple models and inference settings; equivalent judgment criteria across all of those configurations have not been established.

Model migration becomes an explicit governance event. A new family may run alongside existing output, pass the gate, and then join the released set. Earlier output is retained rather than discarded or overwritten. Local-VLM counterparts also exist for gen1-selected scenes, enabling generation-to-generation comparison.

3.4Require falsification-oriented adjudication for change claims

Longitudinal change is among the most error-prone forms of verbalization. A viewpoint shift of a few meters or a seasonal difference can make an unchanged object appear to have changed. We therefore insert adjudication between detection and publication.

First, the system selects only image pairs from the same road group with compatible viewing directions. A VLM describes the apparent difference. Then a separate, context-isolated session is asked to falsify that claim. Only claims that survive as supported are published: currently 3,618. In October 2026 the pairs were re-selected so that photos match by position and heading and re-compared with GPT-6.1 Sol; 2,963 of the 3,025 claims put to the checker survived. High-confidence claims from the August 2026 set (gpt-5.6-sol, first pass) were re-judged blind by the newer model on the same photos, and only the 655 that survived both are kept. About 20% of the 2,522 August claims previously published turned out not to match the photos in this review and were removed. Rejected findings are not included.

3.5Compute geometry deterministically; do not ask the VLM to guess

We want data capable of saying “a fire hydrant is 30 m northeast.” But north is not visible in an image, so the VLM should not infer it.

The VLM reports only image-relative position, such as “a fire hydrant in the right foreground.” Travel bearing is computed geometrically from neighboring frames in the capture sequence and combined with the corrected camera bearing to derive absolute eight-way directions. The computation is deterministic and available for 99.7% of scenes. Note (2026-10-03): 99.6% in release 2026-09-13-r1 (travel_bearing in /v1/meta).

The same reasoning excludes momentary counts such as “three pedestrians” at prompt time. Descriptions focus on equipment, structures, surfaces, and other features that are more stable over time. Choosing what not to generate extends the useful life of the data.

4. Architecture

4.1Four verbalization layers

A single frame cannot resolve every question. The pipeline therefore organizes verbalization into four levels.

Keeping external knowledge out of L1 is important: an image-only description remains an independent source when later compared with official data.

4.2Releases and delivery

Data is not published immediately after generation. It is frozen into a versioned release and promoted through raw SQLite, a production-equivalent preview, and production. The same 96 consistency checks—counts, orphan records, coordinate ranges, duplicates, and statistic agreement—run in all three environments. The API is covered by automated regression tests. Every response carries the release ID as snapshot, so a query can later be reproduced against the same version.

Delivery runs on Cloudflare Workers and two shards of the SQLite-based distributed D1 database. Note (2026-10-03): four shards since release 2026-09-13-r1. REST and MCP share the same database, quality contract, read-only posture, and rate limits. Operational lessons are codified too: after a missing ANALYZE step degraded geospatial queries to tens of seconds, mandatory post-import analysis became part of the runbook.

5. Quality assurance and known limitations

Quality assurance rests on four reproducible controls: (1) regression-comparison and calibration gates for generations, (2) 96 consistency checks across three environments, (3) automated API regression tests, and (4) falsification-oriented adjudication for longitudinal changes.

The following limitations are permanent parts of API responses, tool definitions, and public documentation—not footnotes.

6. Operating model

michiyomi is a personal project designed to remain operable after the event.

• Delivery: Edge and serverless infrastructure avoids ongoing server administration.
• Generation: The main L1 pipeline uses local VLMs on home GPUs. Initial L1 records, L2, L3 and adjudication have used cloud models. Local L2 processing is under evaluation.
• Updates: New data enters through the existing release and generation mechanisms, making incremental updates routine.

Unauthenticated access is deliberate. People and AI agents should be able to submit coordinates and retrieve street evidence without registration. Rate limiting and read-only design provide the guardrails.

7. Roadmap

At this edition, the platform has completed the target scene set across all of Tokyo: 1,914,490 processed scenes and 3,618 adjudicated changes. Coverage density still reflects the uneven distribution of source Mapillary imagery.

8. Conclusion

michiyomi is intended to demonstrate not only individual verbalization accuracy, but a way to circulate generative-AI output as public data: three-layer separation, specified honesty, generations as provenance, falsification-oriented adjudication, and deterministic division of labor. These are data-platform disciplines independent of any particular model.

Models will continue to change. The center of this project is building the data platform so that those changes do not break its auditability.