michiyomi Design Principles
White paper · 2026-08-23 edition. For usage, see the API wiki.
1. Abstract
michiyomi is an open-data platform that converts citizen-published Mapillary street imagery into structured text with vision-language models (VLMs), making physical street conditions searchable by coordinate. It has processed 588,220 scenes concentrated in 13 of Tokyo’s 23 wards (588,214 searchable); its 2,522 longitudinal-change records include only claims that survived falsification-oriented adjudication. REST and MCP provide unauthenticated, read-only access under CC BY-SA 4.0.
One policy runs through the design: beyond maximizing generation accuracy, build provenance, verification, and limitations into the system itself. We believe that is essential if generative-AI output is to become citable public data.
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.
- The generation prompt must distinguish absent, unknown, and outside the frame; it must not infer what is not visible.
- Capture timestamps are not accepted uncritically. After encountering a daylight image timestamped near 23:00, the visual estimate became authoritative for time-of-day description.
- Six anomalous-timestamp scenes are quarantined from search, and both the quarantine and its count are disclosed through the API.
The user-facing rules are consolidated in Important limitations.
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 588,220 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 (510,544 scenes, six quarantined from search) both passed adoption gates based on regression comparisons and calibration on the same image set.
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 2,522, a 94.8% survival rate. 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.6% of scenes.
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.
| Level | Problem addressed |
|---|---|
| L1 point — 588,220 scenes | Physical state in one image. Input is the image alone: no place name, map, earlier output, or other external knowledge. |
| L2 segment — about 100 m of sequential frames | Resolve occlusion, distinguish moving from stationary objects, and understand the extent of damage. |
| L3 time — same place × different year | Describe differences between two views, then send claims to the adjudication in principle 3.4. |
| L4 context — public-data joins | Join schools, zoning, and other official data in the database without showing them to the VLM, preserving accountability between “what AI saw” and mapped facts. |
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 has 296 automated 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 the SQLite-based distributed D1 database (about 5.2 GB). 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) 296 automated API 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.
| Limitation | Implication |
|---|---|
| Descriptions are estimates from a captured image | They do not establish current conditions or safety. Widths are monocular estimates, not survey measurements. |
| Adjudication is not independent verification | It uses context-separated sessions from the same model family; family-wide errors can remain. |
| Coverage depends on available imagery | An unphotographed road is absent from the dataset, so coverage should be disclosed before interpretation. |
| Color features depend on capture conditions | Green-view and related metrics include camera and lighting effects; aggregate analysis should stratify by capture conditions. |
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: A local VLM runs on a home GPU, keeping images out of external inference APIs while reducing large-scale per-image cost by roughly two orders of magnitude.
- 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 reached 588,220 processed scenes concentrated in 13 wards and 2,522 adjudicated changes.
through Aug 2026
within 2026
2. Publish bulk data. Make the complete dataset available under CC BY-SA 4.0 for research and analysis in addition to online API access.
3. Extend the time axis. Expand road-level change visualization and longitudinal coverage using multi-year imagery.
2. Expand geographically. The pipeline has no Tokyo-specific architectural requirement and can be applied wherever open street imagery exists.
3. Establish an update cycle. Reduce the time from citizen capture to searchable description, and test wearable uses such as real-time pedestrian audio guidance.
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.