<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>kuan butts</title>
    <description>Personal web page for Kuan Butts.</description>
    <link>http://kuanbutts.com/</link>
    <atom:link href="http://kuanbutts.com/feed.xml" rel="self" type="application/rss+xml" />
    
      <item>
        <title>Building an eval harness for model selection and regression monitoring</title>
        <description>&lt;p&gt;I have a simple analysis chatbot on my &lt;a href=&quot;https://ac-transit.com/&quot;&gt;AC Transit performance site&lt;/a&gt;, and it uses Gemini. This post covers the exercise of determining whether I could replace it with a less expensive, open-weight model without making the product worse.&lt;/p&gt;

&lt;p&gt;I have experimented enough with different language models to know that published benchmark metrics generally do not map cleanly to domain-specific tasks. The chatbot here does a pretty specific job: a visitor asks about AC Transit performance; the model selects from a small set of read-only data tools, as described in my post on &lt;a href=&quot;/2026/11/06/rapid-agent-chat-interface-prototyping-with-fastmcp/&quot;&gt;prototyping agent chat interfaces with FastMCP&lt;/a&gt;; and the interface returns a short answer, timeframe, and sometimes a map, chart, or table. It is a good setting for a small, practical evaluation because the question paths and breadth of accepted response behavior are fairly constrained.&lt;/p&gt;

&lt;h2 id=&quot;evals-overview&quot;&gt;Evals overview&lt;/h2&gt;

&lt;p&gt;An evaluation, or eval, is a repeatable test of whether a model does the work an application expects. This is not an attempt to measure general intelligence or declare one model universally better than another. Instead, it is scoped to the pattern check of, given this prompt, this tool catalog, this policy, and this synthetic tool result, does the model take the expected path and produce the required evidence? It runs this through a series of “stories” to make sure the flows go as expected.&lt;/p&gt;

&lt;p&gt;The cases were hand-curated from three sources:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;Representative questions from developing and using the chatbot, such as “How is Route 1T performing?” and “Which hours tend to have the most dropped trips?”&lt;/li&gt;
  &lt;li&gt;Self-defined product boundaries, including route-page scope, separate route service groups, off-topic questions, and prompt-injection attempts.&lt;/li&gt;
  &lt;li&gt;Real failures promoted into regression cases. One example came from asking which routes had the most dropped trips and which had improved or worsened over four weeks. In this case, I had personally noticed that an early Gemma deployment refused to do the comparison even though the available tools could support it.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Gemini provided a decent behavioral baseline for the conversational flows used to build a reference dataset. From this, I extracted patterns rather than using the results verbatim. The reference set includes things such as the required tool, important arguments, resolved dates, facts that must appear, facts that must not appear, and required visual artifacts. I still manually curate whether each contract represents the product we want. So Gemini remains a competitor in the test, not an infallible model everything else is compared to.&lt;/p&gt;

&lt;p&gt;Here is a shortened version of the four-week trend case:&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;prompt&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Over the past 4 weeks, which regular routes had the most dropped trips, which got worse, and which got better?&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;expected_calls&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;name&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;rank_route_trends&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;arguments&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;metric&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;dropped_trips&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;period&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;week&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;order&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;worsened&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;route_group&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;regular&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;name&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;rank_route_trends&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;arguments&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;metric&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;dropped_trips&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;period&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;week&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;order&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;improved&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
        &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;route_group&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;regular&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;expected_timeframe&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;start_date&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;2026-10-12&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;end_date&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;2026-11-08&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;required_artifacts&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;chart_count&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;tables&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;answer_contains_all&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;1T&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;180&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;210&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;45&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;6&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;50&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;answer_forbidden&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;cannot&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;can&apos;t&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;impossible&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;max_calls&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The fixture says, among other things, that Route 1T has the highest four-week total at 180 dropped trips, Route 210 worsens from 20 to 45, and Route 6 improves from 50 to 20. Those are intentionally synthetic values, not claims about actual AC Transit service. Distinct numbers make it possible to check whether the final prose is grounded in the tool results rather than merely plausible-sounding.&lt;/p&gt;

&lt;p&gt;Each turn gets diagnostic scores for:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;exact tool selection and ordering;&lt;/li&gt;
  &lt;li&gt;required tool arguments and resolved timeframe;&lt;/li&gt;
  &lt;li&gt;answer policy, expressed as required and forbidden terms;&lt;/li&gt;
  &lt;li&gt;required maps, chart types, chart counts, and tables; and&lt;/li&gt;
  &lt;li&gt;efficiency, including the call limit and whether every tool call succeeded.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The weighted diagnostic score is 40% tool selection, 25% arguments, 20% answer policy, 10% artifacts, and 5% efficiency. For overall pass score, every dimension must pass. This provides both a binary regression signal and enough detail to see why a model failed. No second language model needs to act as a subjective judge in this harness.&lt;/p&gt;

&lt;p&gt;Multi-turn cases preserve the prior questions and answers just as the application does. For example:&lt;/p&gt;

&lt;div class=&quot;language-text highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;User: How is Route 1T performing?
User: What about last month?
User: And how many trips were dropped by day and hour?
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The second turn must retain Route 1T while resolving “last month” to exact dates. The third must re-query the correct service-profile tool with the same route and dates, then retain both the daily bar chart and hourly heatmap. Each turn is scored independently, so a good first answer cannot hide a broken follow-up.&lt;/p&gt;

&lt;p&gt;The harness uses the production agent loop and model adapters but swaps production data access for a deterministic fixture gateway. Tool descriptions and JSON schemas are derived directly from the MCP server source, so changing the interface becomes part of the next evaluation. A manually triggered &lt;a href=&quot;https://github.com/kuanb/actransit_perf_v2/blob/main/.github/workflows/model-eval.yml&quot;&gt;GitHub Actions workflow&lt;/a&gt; runs the paid comparison when needed, writes detailed JSONL plus summary CSV/JSON, and can fail against configurable overall and critical thresholds. It does not run on every commit.&lt;/p&gt;

&lt;h2 id=&quot;general-passes-versus-critical-passes&quot;&gt;General passes versus critical passes&lt;/h2&gt;

&lt;p&gt;The &lt;strong&gt;general pass rate&lt;/strong&gt; is the strict pass rate across every evaluated turn. The &lt;strong&gt;critical pass rate&lt;/strong&gt; applies the same all-or-nothing test, but only to the subset that has been set as must-not-break behavior: system and route overviews, relative-date resolution, dropped-trip analysis, route-group boundaries, prompt-injection and off-topic refusals, route-page scope, required caveats, and follow-up context.&lt;/p&gt;

&lt;p&gt;Critical is not necessarily harder and does not mean a higher weighted score: a formatting miss on a secondary query and a scope leak should not have equal influence on a deployment decision. But it does provide an explicit check on required behavior.&lt;/p&gt;

&lt;h2 id=&quot;results-from-comparison-runs&quot;&gt;Results from comparison runs&lt;/h2&gt;

&lt;p&gt;I ran a suite of 16 scenarios and 18 total turns on November 20, 2026. “Cost per turn” includes all model calls needed for that user turn, including the tool-selection and post-tool answer rounds. Partner-model prices are pulled from published rates as of November 19.&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Model&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Broad pass&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Critical pass&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;p95 latency&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Input / output / cache-hit price per 1M tokens&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Observed cost per completed turn&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Cost vs. Gemini&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Gemini 3.5 Flash-Lite&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;77.8%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;76.9%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;3.00s&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.30 / $2.50 / $0.03&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.001463&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;baseline&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Gemma 4 26B&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;94.4%&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;92.3%&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;11.88s&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.15 / $0.60 / $0.015&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.000667&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;54.4% less&lt;/strong&gt;&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;GPT-OSS 120B&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;38.9%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;38.5%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;3.78s&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.09 / $0.36 / $0.09&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.000467&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;68.1% less&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;DeepSeek V4.1 Flash&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;61.1%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;61.5%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;17.63s&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.30 / $1.20 / $0.03&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.001569&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;7.2% more&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Mistral Small 3.1&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;61.1%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;61.5%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;2.85s&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.10 / $0.30 / $0.10&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.000453&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;69.0% less&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Grok 4.7&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;83.3%&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;92.3%&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;26.99s&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$2.00 / $6.00 / $0.50&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.004695&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;220.9% more&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/ac-transit-model-eval/quality-cost-latency.png&quot; alt=&quot;A bubble chart comparing broad strict pass rate and estimated model cost per completed turn. Bubble size represents p95 latency and color represents the critical-case pass rate. Gemma has the highest pass rate at lower cost than Gemini, while Grok is more expensive and slower.&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Gemma sits on the quality-and-cost frontier for this evaluation. Grok passed the hardest trend case consistently, but at substantially higher cost and latency.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Overall, Gemma was the best value: it had the highest pass rate and cost about 54% less per evaluated turn than Gemini. GPT-OSS and Mistral were cheaper, but their strict pass rates were too low. Grok performed well but was much slower and more costly.&lt;/p&gt;

&lt;p&gt;I repeated the hardest trend case three times to expose nondeterminism:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Model&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Strict passes&lt;/th&gt;
      &lt;th style=&quot;text-align: right&quot;&gt;Estimated cost per turn&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Gemini 3.5 Flash-Lite&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;0/3&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.001903&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Gemma 4 26B&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;1/3&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.001196&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;GPT-OSS 120B&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;0/3&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.000492&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;DeepSeek V4.1 Flash&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;1/3&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.002609&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Mistral Small 3.1&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;0/3&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.000724&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Grok 4.7&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;&lt;strong&gt;3/3&lt;/strong&gt;&lt;/td&gt;
      &lt;td style=&quot;text-align: right&quot;&gt;$0.010195&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Only Grok reliably made both trend calls, preserved all three charts and tables, used the exact 28-day range, and grounded the narrative in the supplied values. Gemma was still reasonable as a default, but this also highlights why observed failures should be registered in tests so these cases get promoted from mere anecdotes to permanent regression checks.&lt;/p&gt;

&lt;h2 id=&quot;where-savings-come-from&quot;&gt;Where savings come from&lt;/h2&gt;

&lt;p&gt;Across the 18-turn broad run, Gemini’s corrected estimated total was $0.02634: $0.02161 for input and $0.00473 for output. Gemma’s total was $0.01200: $0.01073 for ordinary input, $0.00019 for cache-hit input, and $0.00107 for output.&lt;/p&gt;

&lt;p&gt;The net savings were $0.01434, or 54.4%. About $0.01068 came from input and cache pricing, and $0.00366 came from output pricing. The providers reported 12,894 cached Gemma input tokens and no cached Gemini tokens in this run. The harness charges reported cache hits at each model’s cache-hit rate.&lt;/p&gt;

&lt;p&gt;That cache result is not guaranteed: the application does not create a long-lived prompt cache. So to fully evaluate the price comparison, we should remove any cache benefit. Doing so results in the savings dropping from 54.4% to about 47.8%. Gemma still wins, regardless. All the models considered here are managed, serverless Model Garden APIs, so we just pay for token spend—there is no idling of GPUs in our case.&lt;/p&gt;

&lt;h2 id=&quot;managing-the-different-provider-protocols&quot;&gt;Managing the different provider protocols&lt;/h2&gt;

&lt;p&gt;Vertex AI is Google Cloud’s unified machine learning and generative AI platform for building, training, tuning, evaluating, and deploying models and AI agents. Unfortunately, it does not expose every managed model through exactly the same request and response shape. For example, the current Gemini adapter uses Google’s native Gen AI SDK and &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;generateContent&lt;/code&gt;. Meanwhile, most of the managed open models use Vertex’s OpenAI-compatible chat-completions endpoint. Mistral uses a publisher-specific &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;rawPredict&lt;/code&gt; endpoint. What a mess.&lt;/p&gt;

&lt;p&gt;The differences include tool-schema encoding, how tool results are appended to a conversation, and where token and cache usage appear in the response.&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TD
    U[Browser question] --&amp;gt; A[AnalysisAgent&amp;lt;br/&amp;gt;shared prompt, policy, and tool loop]
    A --&amp;gt; F{ANALYSIS_MODEL_PROVIDER}

    F --&amp;gt;|gemini| G[GeminiModelProvider&amp;lt;br/&amp;gt;Google Gen AI SDK / generateContent]
    F --&amp;gt;|vertex_open| O[VertexOpenModelProvider&amp;lt;br/&amp;gt;OpenAI-compatible chat completions]
    F --&amp;gt;|vertex_mistral| M[VertexMistralModelProvider&amp;lt;br/&amp;gt;Mistral rawPredict endpoint]

    G --&amp;gt; GM[Gemini 3.5 Flash-Lite]
    O --&amp;gt; OM[Gemma, GPT-OSS, DeepSeek,&amp;lt;br/&amp;gt;Llama, or Grok]
    M --&amp;gt; MM[Mistral]

    G --&amp;gt; R[Normalized ModelReply&amp;lt;br/&amp;gt;text, tool calls, usage]
    O --&amp;gt; R
    M --&amp;gt; R
    R --&amp;gt; P{Tool call?}
    P --&amp;gt;|yes| B[Policy validation]
    B --&amp;gt; MCP[Private read-only MCP tools]
    MCP --&amp;gt; D[(GCS, GTFS, BigQuery)]
    MCP --&amp;gt; A
    P --&amp;gt;|no| S[Structured answer&amp;lt;br/&amp;gt;text, timeframe, maps, charts, tables]
    S --&amp;gt; U
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;The application hides those differences behind a small internal &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ModelProvider&lt;/code&gt; / &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;ModelSession&lt;/code&gt; protocol. Each adapter returns the same normalized reply containing text, tool calls, provider state, and token usage. The production selection is therefore two environment values—provider and model—while the policy, MCP tools, UI, and evaluation logic remain unchanged.&lt;/p&gt;

&lt;h2 id=&quot;testing-harness-for-long-term-confidence&quot;&gt;Testing harness for long-term confidence&lt;/h2&gt;

&lt;p&gt;Gemma won the broad comparison, but the more important output here over the long term is our scoring mechanism for making model selections in the future. I can rerun the same cases after changing a prompt, tool description, MCP schema, response format, or model. This will help ensure stability as I tweak this tool and its functionality in the future.&lt;/p&gt;

&lt;p&gt;This evaluation is intentionally small and application-specific. It is also now part of the application’s maintenance loop: collect representative questions, turn failures into deterministic cases, compare quality, latency, and cost, and keep the deployment choice easy to reverse.&lt;/p&gt;

&lt;hr /&gt;

&lt;p&gt;&lt;strong&gt;Pricing note:&lt;/strong&gt; Partner-model prices were pinned in the harness on November 19, 2026. Gemini figures in this post use the Standard on-demand tier after correcting a harness constant that used the Flex/Batch rate. See Google Cloud’s &lt;a href=&quot;https://cloud.google.com/model-garden/pricing&quot;&gt;Gemini pricing&lt;/a&gt; and &lt;a href=&quot;https://cloud.google.com/model-garden/partner-models/pricing&quot;&gt;partner-model pricing&lt;/a&gt; for current rates. The result files and scorer live in the &lt;a href=&quot;https://github.com/kuanb/actransit_perf_v2/tree/main/services/agent/evals&quot;&gt;open-source project&lt;/a&gt;.&lt;/p&gt;
</description>
        <pubDate>Fri, 20 Nov 2026 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2026/11/20/can-a-cheaper-open-model-replace-gemini-in-a-transit-data-chatbot/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2026/11/20/can-a-cheaper-open-model-replace-gemini-in-a-transit-data-chatbot/</guid>
      </item>
    
      <item>
        <title>Stateless map matching</title>
        <description>&lt;p&gt;&lt;em&gt;HTTP range requests, a temporary road graph, and browser-native RPC&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;A map matcher normally begins with a road graph. Before the first GPS observation can snap to a street, someone has to download the source data, normalize intersections, assign durable edge identifiers, build spatial indexes, and deploy a service that keeps the graph available. The matching request may be small, but the system behind it usually is not.&lt;/p&gt;

&lt;p&gt;Projects such as &lt;a href=&quot;https://project-osrm.org/&quot;&gt;OSRM&lt;/a&gt; and &lt;a href=&quot;https://valhalla.github.io/valhalla/&quot;&gt;Valhalla&lt;/a&gt; show the moving pieces involved. Both projects make local and embedded use possible. OSRM includes a &lt;a href=&quot;https://github.com/Project-OSRM/osrm-backend/blob/master/docs/nodejs/api.md&quot;&gt;Node.js API&lt;/a&gt;, for example, and Valhalla offers local bindings and packaged deployment options. A user still has to download OpenStreetMap data, transform it into optimized routing data, version the resulting graph, and keep it available to the application. The data management side often carries much of the operational weight.&lt;/p&gt;

&lt;p&gt;For this post, I want to see how much of that machinery I can avoid.&lt;/p&gt;

&lt;p&gt;The result is a &lt;a href=&quot;https://kuanbutts.com/stateless-router/map-match-v1/&quot;&gt;browser-only map-matching experiment&lt;/a&gt; that runs as a static site on GitHub Pages. It takes a sequence of longitude-latitude observations, fetches nearby road geometry from a remote Protomaps archive, selects a locally consistent sequence of road matches, and returns render-ready JSON. This service has no application server and no persistent global routing graph.&lt;/p&gt;

&lt;p&gt;The project does build a graph. It builds a small, temporary one from the geometry around each request and discards it with the page. “Stateless” means that the service keeps no authoritative world graph between requests. Each request has working state while the calculation runs, and that is it.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;/images/posts/stateless-map-matching/app-overview.png&quot; alt=&quot;The stateless-router browser demo showing an Oakland probe trace, direct matches, and purple inferred route segments.&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The complete experiment runs in the browser. The static page fetches Protomaps road tiles, performs sequence-aware matching, and returns JSON.&lt;/em&gt;&lt;/p&gt;

&lt;h2 id=&quot;pmtiles-as-an-on-demand-geometry-store&quot;&gt;PMTiles as an on-demand geometry store&lt;/h2&gt;

&lt;p&gt;&lt;a href=&quot;https://docs.protomaps.com/pmtiles/&quot;&gt;PMTiles&lt;/a&gt; is a single-file archive format for tiled data. A reader asks for a tile using its &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;z/x/y&lt;/code&gt; address, consults the archive directory, and uses HTTP Range requests to retrieve only the relevant bytes from the remote file. The archive can live in object storage or behind an ordinary static host that supports byte serving.&lt;/p&gt;

&lt;p&gt;Protomaps publishes a basemap in this format. Its vector tiles include a &lt;a href=&quot;https://docs.protomaps.com/basemaps/layers&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;roads&lt;/code&gt; layer&lt;/a&gt; derived from OpenStreetMap, with line geometry and useful attributes such as road class, name, reference, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;oneway&lt;/code&gt;, and structure or layer information. These features are intended primarily for cartography, but they contain enough local geometry to make a map-matching experiment possible.&lt;/p&gt;

&lt;p&gt;The pipeline for creating and hosting a network of your own is also straightforward and inexpensive. I cover that setup in an earlier post about &lt;a href=&quot;https://kuanbutts.com/2023/06/13/protomaps-simple-gh-page-service/&quot;&gt;building and serving Protomaps from GitHub Pages&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;For each trace, the prototype converts the observations and search radius into a set of z15 tile addresses. The PMTiles reader resolves those addresses to byte ranges, the browser decodes the selected vector tiles, and the matcher filters the resulting road lines to plausible drivable candidates.&lt;/p&gt;

&lt;p&gt;The browser does not download a planet-sized road graph. It limits the working set to local geometry around the trace.&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
    subgraph request[Locate the required bytes]
        direction LR
        A[GPS observations] --&amp;gt; B[Buffered z15 tile addresses]
        B --&amp;gt; C[PMTiles directory lookup]
    end

    subgraph match[Build the local candidate set]
        direction LR
        D[HTTP Range reads] --&amp;gt; E[Decode nearby road geometry]
        E --&amp;gt; F[Generate match candidates]
    end

    C --&amp;gt; D
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;This changes the operational shape of the problem. The basemap still requires preprocessing and hosting. PMTiles is a processed archive, not raw OpenStreetMap data. The map-matching application, however, does not need to build, deploy, or hold its own global graph. It assembles the local geometry it needs on demand for each match request.&lt;/p&gt;

&lt;h2 id=&quot;a-sequence-aware-matcher&quot;&gt;A sequence-aware matcher&lt;/h2&gt;

&lt;p&gt;For every observation, the matcher projects the point onto nearby road segments and keeps a small number of candidates. The default demo searches within 70 meters, which is tunable, and retains up to six candidates per observation.&lt;/p&gt;

&lt;p&gt;A candidate scores better when it is close to the observation and when the direction of its road geometry is compatible with the apparent direction of travel. Choosing the nearest road independently for every point is not enough. Parallel streets, divided roads, frontage roads, and noisy observations can all produce locally plausible but globally strange results.&lt;/p&gt;

&lt;p&gt;The matcher uses a Viterbi-style dynamic program to choose a consistent sequence. Its transition cost penalizes implausible changes in distance, unnecessary road changes, wrong-way movement on one-way features, and U-turns. This handles an early failure mode in which the first observation lands on the opposite carriageway from the rest of the trace and produces an unlikely U-turn at the beginning of the result.&lt;/p&gt;

&lt;p&gt;I describe the matcher as “HMM-shaped” rather than as a calibrated hidden Markov model. The structure is familiar: candidate states, per-observation costs, transition costs, and dynamic programming. The current emission and transition values are hand-tuned scores rather than learned or statistically calibrated probabilities. I discuss HMM map matching in more detail in my post about a &lt;a href=&quot;https://kuanbutts.com/2025/12/25/lightweight-go-router/&quot;&gt;lightweight Go router&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;That approach is sufficient for the question I want to test with this project: can a browser obtain the right local geometry on demand and choose a useful sequence of road matches without a massive preprocessed world graph?&lt;/p&gt;

&lt;h2 id=&quot;cartographic-features-are-not-routing-edges&quot;&gt;Cartographic features are not routing edges&lt;/h2&gt;

&lt;p&gt;The first visual problem is overshoot on edge matches. A probe can match a road near an intersection while the selected Protomaps feature continues well past the turn. Vector tiles are processed for cartography, so a feature is not necessarily a clean routing edge that runs from one intersection to the next. Rendering the complete source feature can make it look as if the matched route continues through the intersection before doubling back.&lt;/p&gt;

&lt;p&gt;This is not necessarily a matching error. It is a mismatch between the unit returned by the vector tile and the portion of that geometry supported by the observations.&lt;/p&gt;

&lt;p&gt;The response preserves both forms:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sourceGeometry&lt;/code&gt; contains the original Protomaps line used by the matcher.&lt;/li&gt;
  &lt;li&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;geometry&lt;/code&gt; contains a probe-relevant fragment trimmed around the matched positions.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The trimming is deliberately conservative. It does not claim that the endpoints are verified intersections. The response labels them as synthetic fragment endpoints and sets &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;intersectionInferred: false&lt;/code&gt;. They make the result easier to render and consume without pretending that a cartographic vector tile supplies authoritative routing topology.&lt;/p&gt;

&lt;p&gt;This is also why z15 should not be treated as a universal accuracy guarantee. It is the tile-request level used by this experiment, not a promise that every intersection, lane, or legal maneuver is encoded as a routable node. In downtown Oakland, the geometry is detailed enough for this prototype to produce useful matches. That is an empirical result, not a general contract.&lt;/p&gt;

&lt;h2 id=&quot;direct-matches-can-still-leave-holes&quot;&gt;Direct matches can still leave holes&lt;/h2&gt;

&lt;p&gt;Trimming fixes overshoot, but it exposes a new problem. If the observations directly support fragments on either side of an intersection, or disappear for a block, the set of matched fragments can look like a checkered line. Matched edges continue and then suddenly disappear. We know that a trajectory continues between two matched positions, but no observation directly selects the intervening portion.&lt;/p&gt;

&lt;p&gt;Drawing a straight line between those positions hides the gap, but it can cut a corner, cross a building, or imply travel on a road the vehicle never uses. Adding synthetic observations every ten meters has the same weakness. The interpolated chord becomes evidence even though the algorithm invents it.&lt;/p&gt;

&lt;p&gt;This version separates direct matching from route inference.&lt;/p&gt;

&lt;figure class=&quot;post-image-comparison&quot;&gt;
  &lt;div class=&quot;post-image-comparison__grid&quot;&gt;
    &lt;div&gt;
      &lt;p class=&quot;post-image-comparison__label&quot;&gt;Directly supported matches&lt;/p&gt;
      &lt;img src=&quot;/images/posts/stateless-map-matching/direct-match-gap.png&quot; alt=&quot;A close view of direct map matches along Broadway in Oakland.&quot; /&gt;
    &lt;/div&gt;
    &lt;div&gt;
      &lt;p class=&quot;post-image-comparison__label&quot;&gt;Inferred route connector&lt;/p&gt;
      &lt;img src=&quot;/images/posts/stateless-map-matching/inferred-route-gap.png&quot; alt=&quot;A close view of a dashed purple inferred route connector through an Oakland intersection.&quot; /&gt;
    &lt;/div&gt;
  &lt;/div&gt;
  &lt;figcaption&gt;Direct matches may not cover every part of a continuous trajectory. The dashed purple geometry is inferred by routing through the temporary local graph and is returned separately from observation-supported matches.&lt;/figcaption&gt;
&lt;/figure&gt;

&lt;p&gt;After matching the real observations, the browser constructs a directed graph from the road geometry it already has. It splits line segments at snapped probe positions and at compatible geometric crossings, then adds directed arcs according to the available one-way tags. Explicitly incompatible layer or structure information prevents some false connections at grade-separated crossings.&lt;/p&gt;

&lt;p&gt;The browser then runs a bounded shortest-path search between each pair of consecutive matched observations. Travel along the same source road uses the direct slice of that road. Other transitions use the local directed graph. The matcher rejects paths that are implausibly long relative to the observation spacing.&lt;/p&gt;

&lt;p&gt;Only the uncovered portions of successful paths become &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;inferredEdges&lt;/code&gt;. They appear as dashed purple lines and carry explicit metadata:&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;id&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;inferred:001&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;fromProbe&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;toProbe&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;4&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;provenance&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;inferred_transition&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;confidence&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;geometry_only&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;sourceRoadIds&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;startNode&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;node:...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;endNode&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;node:...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;geometry&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;type&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;LineString&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;coordinates&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The color and the contract preserve an important difference. A teal fragment is supported by a direct match. A purple fragment is required to connect matches through the temporary geometry graph.&lt;/p&gt;

&lt;p&gt;If the browser cannot find a plausible path, it leaves the transition unresolved. The included Oakland example currently reports four inferred connectors and one unresolved transition. I prefer that visible failure to a silently drawn straight line. The unresolved transition shows where a cartographic working set stops short of a routing database.&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
    A[Real observations] --&amp;gt; B[Viterbi-style matching]
    B --&amp;gt; C[Direct matched fragments]
    B --&amp;gt; D[Temporary directed graph]
    D --&amp;gt; E[Shortest paths between matches]
    C --&amp;gt; F[Assemble route response]
    E --&amp;gt; F
    F --&amp;gt; G[Direct edges + inferred edges + unresolved transitions]
&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;a-service-boundary-without-an-application-server&quot;&gt;A service boundary without an application server&lt;/h2&gt;

&lt;p&gt;The visual map and the matcher are separate even though both run in the browser. The map loads &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;/map-match-api-v1/&lt;/code&gt; in a hidden iframe and sends it versioned messages with &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;window.postMessage&lt;/code&gt;. The endpoint page owns the PMTiles reads, decoding, candidate matching, local cache, route inference, and response serialization. The visible map renders only the returned GeoJSON.&lt;/p&gt;

&lt;p&gt;The request payload is intentionally small:&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;coordinates&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;-122.2727&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;37.8009&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;-122.2712&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;37.8044&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;options&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;radiusMeters&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;70&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;candidateCount&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;6&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;sequenceAware&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;edgePaddingMeters&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;inferRoute&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;kc&quot;&gt;true&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The parent page wraps this object in a message with a protocol type and request ID:&lt;/p&gt;

&lt;div class=&quot;language-js highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;nx&quot;&gt;iframe&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;contentWindow&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;postMessage&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;stateless-router:match:v1&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;id&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;request-1&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;request&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;coordinates&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;options&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
  &lt;span class=&quot;k&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;URL&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;iframe&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;src&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;).&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;origin&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The endpoint emits progress messages and eventually returns either &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stateless-router:response:v1&lt;/code&gt; or &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stateless-router:error:v1&lt;/code&gt; with the same request ID. This gives the frontend a service-like boundary without requiring a deployable backend.&lt;/p&gt;

&lt;p&gt;The response contains:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;The input and snapped position for every probe, including match error.&lt;/li&gt;
  &lt;li&gt;Direct-match edges with geometry ordered in the selected travel direction.&lt;/li&gt;
  &lt;li&gt;Original source geometry for debugging.&lt;/li&gt;
  &lt;li&gt;Synthetic start and end nodes for each returned fragment.&lt;/li&gt;
  &lt;li&gt;Separately identified geometry-only inferred edges.&lt;/li&gt;
  &lt;li&gt;Ordered edge sequences and per-probe-pair transition results.&lt;/li&gt;
  &lt;li&gt;GeoJSON collections ready for rendering.&lt;/li&gt;
  &lt;li&gt;Tile, cache, error, and elapsed-time statistics.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is page-backed RPC, not an HTTP JSON endpoint. GitHub Pages cannot accept an application &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;POST&lt;/code&gt;, and requesting the URL with &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;curl&lt;/code&gt; downloads the HTML and JavaScript rather than executing a match. A caller loads the endpoint in a browser context and communicates with it through the message contract.&lt;/p&gt;

&lt;p&gt;The separation is still useful. The protocol is independent of the visible map, so another browser frontend can reuse the matcher without importing its UI. The computation can later move from the endpoint page into a Web Worker without changing the public message shapes.&lt;/p&gt;

&lt;h2 id=&quot;trying-it&quot;&gt;Trying it&lt;/h2&gt;

&lt;p&gt;The &lt;a href=&quot;https://kuanbutts.com/stateless-router/map-match-v1/&quot;&gt;interactive map matcher&lt;/a&gt; lets you click a trace onto the map, load the included Oakland example, adjust matcher settings, and inspect the direct and inferred route geometry.&lt;/p&gt;

&lt;p&gt;The lighter &lt;a href=&quot;https://kuanbutts.com/stateless-router/run-map-match/&quot;&gt;JSON runner&lt;/a&gt; accepts a coordinate array and shows the complete response. It also supports a URL-encoded &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;coordinates&lt;/code&gt; query parameter, which makes a short browser-executed request shareable as a link.&lt;/p&gt;

&lt;p&gt;The full matcher is embedded below. On a narrow screen, the preview stays interactive but uses a shorter viewport. Open it full-screen when you want more room for the map and controls.&lt;/p&gt;

&lt;div class=&quot;post-interactive-embed&quot;&gt;
  &lt;p class=&quot;post-interactive-embed__label&quot;&gt;Interactive preview&lt;/p&gt;
  &lt;iframe src=&quot;https://kuanbutts.com/stateless-router/map-match-v1/&quot; title=&quot;Browser-only Protomaps map matcher&quot; loading=&quot;lazy&quot;&gt;&lt;/iframe&gt;
&lt;/div&gt;

&lt;p class=&quot;post-interactive-fallback&quot;&gt;&lt;a href=&quot;https://kuanbutts.com/stateless-router/map-match-v1/&quot;&gt;Open the interactive map matcher full-screen &lt;span aria-hidden=&quot;true&quot;&gt;→&lt;/span&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The source for the experiment is available in the &lt;a href=&quot;https://github.com/kuanb/stateless-router&quot;&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;stateless-router&lt;/code&gt; repository&lt;/a&gt;.&lt;/p&gt;

&lt;h2 id=&quot;ids-direction-and-what-the-response-does-not-promise&quot;&gt;IDs, direction, and what the response does not promise&lt;/h2&gt;

&lt;p&gt;The response has identifiers because a consumer needs to refer to nodes and edges within a result. Those identifiers should not be confused with durable road references.&lt;/p&gt;

&lt;p&gt;Direct edges currently receive request-local IDs such as &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;edge:001&lt;/code&gt;. A &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;sourceRoadId&lt;/code&gt; combines tile and vector-feature information, so it is useful for debugging within the current Protomaps dataset but is not guaranteed to survive a new archive build. Synthetic node IDs are made from coordinates rounded to seven decimal places. Inferred edges receive request-local sequential IDs.&lt;/p&gt;

&lt;p&gt;None of these identifiers is OpenLR. They are not currently intended to join the match result to another routing, traffic, or asset-management system.&lt;/p&gt;

&lt;p&gt;Direction has a similar boundary. The matcher reads available &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;oneway&lt;/code&gt; attributes and orders returned geometry in the selected direction of travel. Bidirectional features can be traversed in either direction. This prevents many obvious wrong-way paths, but it does not reproduce the legal model of a production router. There are no turn restrictions, conditional access rules, lane movements, or complete intersection semantics.&lt;/p&gt;

&lt;p&gt;For that reason, the response reports &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;route.connectivityInferred&lt;/code&gt; separately and always leaves &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;route.connectivityVerified&lt;/code&gt; as &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;false&lt;/code&gt;.&lt;/p&gt;

&lt;h2 id=&quot;sparse-data-and-other-failure-modes&quot;&gt;Sparse data and other failure modes&lt;/h2&gt;

&lt;p&gt;The prototype works best when observations are frequent enough for their search areas to cover the roads that connect them. Sparse observations create two related risks.&lt;/p&gt;

&lt;p&gt;First, the correct connecting road can lie in a tile that is never fetched. The current implementation selects tiles around the real observations, not around every possible corridor between them. Interpolated positions can help select additional tiles without becoming fake observations, but a robust implementation needs a principled corridor-fetch strategy and hard request limits.&lt;/p&gt;

&lt;p&gt;Second, a longer gap admits more plausible routes. The local graph can find a geometrically valid path that is not the path actually traveled. A production matcher normally addresses this with a richer routable graph, better-calibrated transition probabilities, speed and timing information, road-class priors, and sometimes additional sensor data.&lt;/p&gt;

&lt;p&gt;Geometry-derived topology introduces its own ambiguity. Two lines that cross on a map are not necessarily connected on the ground. Layer and structure tags help, but missing or simplified attributes can still create false intersections. Tile boundaries and generalized features can also make connected roads appear separate.&lt;/p&gt;

&lt;p&gt;Finally, this page is a public experiment, not an operated API. It has no authentication, rate limits, uptime contract, or server-side control over resource use. The default public PMTiles source is appropriate for low-volume exploration. A serious deployment still needs to host and version its own archive, but that is easier than managing a stateful matching engine. Capacity is primarily bounded by static-data read rates rather than application-server compute, which is also more accommodating of bursty utilization.&lt;/p&gt;

&lt;h2 id=&quot;thinking-ahead-to-what-comes-next&quot;&gt;Thinking ahead to what comes next&lt;/h2&gt;

&lt;p&gt;The post-match router is intentionally a second phase. A more complete matcher uses network distance during the Viterbi transition itself. Instead of first choosing candidate roads and then asking how to connect them, each candidate-to-candidate transition considers the shortest legal path through the local graph. Route continuity then influences the match rather than merely repairing its output.&lt;/p&gt;

&lt;p&gt;I also want to separate tile acquisition from observation generation. For a large gap, intermediate points can identify PMTiles cells worth fetching, but the matcher should not score those generated points as if they came from the GPS device.&lt;/p&gt;

&lt;p&gt;The larger opportunity is a purpose-built PMTiles archive for routing rather than cartography. Such an archive could provide:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;Edges normalized at authoritative intersection nodes.&lt;/li&gt;
  &lt;li&gt;Durable source identifiers across tile boundaries.&lt;/li&gt;
  &lt;li&gt;Complete direction and access attributes.&lt;/li&gt;
  &lt;li&gt;Turn restrictions and grade-separated connectivity.&lt;/li&gt;
  &lt;li&gt;Optional OpenLR references or another interoperable location scheme.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The browser can retain the same range-request pattern while operating on data designed for routing. A result can then identify plausible geometry and the durable network edges used by other internal systems.&lt;/p&gt;

&lt;h2 id=&quot;current-limitations&quot;&gt;Current limitations&lt;/h2&gt;

&lt;p&gt;This experiment shows that the graph used for matching does not always need to be global, resident, or served by an application backend.&lt;/p&gt;

&lt;p&gt;For relatively short traces, rather than routes that extend for many miles, PMTiles can act as an on-demand geometry store. The browser retrieves a small spatial working set, runs a sequence-aware matcher, constructs a temporary local graph, and clearly distinguishes direct evidence from inferred connectivity. It exposes that computation behind a reusable RPC contract while remaining a collection of static files.&lt;/p&gt;

&lt;p&gt;The unresolved issues around edge ID transmission, pure-geometry matching, and the lack of an authoritative graph are reminders of the limits of using cartographic geometry as a stand-in for a routable network. A production system may need source data that encodes authoritative topology, stable identity, and clearly marked allowed maneuvers. This project still demonstrates the viability of range-based lookup and the serverless potential it unlocks.&lt;/p&gt;
</description>
        <pubDate>Wed, 11 Nov 2026 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2026/11/11/stateless-map-matching/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2026/11/11/stateless-map-matching/</guid>
      </item>
    
      <item>
        <title>Rapid Agent Chat Interface Prototyping with FastMCP</title>
        <description>&lt;p&gt;&lt;em&gt;Generating highly customized chat workflows with tightly curated data models.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;I just returned from the OutpostAI conference, where I noticed a pattern across several talks: there is more data than ever, but the path from a person’s question to a useful answer still depends heavily on one person who knows the warehouse, the metric definitions, and how to turn the results into something people can use, usually a dashboard.&lt;/p&gt;

&lt;p&gt;One presenter described a hardware company where many people wanted to understand simulation results, but only one person knew the data warehouse well enough to write the queries and generate dashboards. That person had effectively become the interface to the data. Each new question became a ticket, and each new dashboard added to the maintenance burden.&lt;/p&gt;

&lt;p&gt;This discussion also made me think about friction I have encountered while presenting AC Transit performance statistics in the &lt;a href=&quot;https://ac-transit.com/report-card/&quot;&gt;report card project&lt;/a&gt;. People want to know where the problems are in a route or the system, but they may not know the terminology needed to find the right metric. They may say that a bus route feels unreliable without knowing whether to look at trip delivery, a rider-window measure, median delay, long gaps, or dropped trips. Making them navigate a dashboard assumes they already understand the data model well enough to choose the correct chart.&lt;/p&gt;

&lt;p&gt;I wanted to try a different interface against my &lt;a href=&quot;https://ac-transit.com/ask/&quot;&gt;independent AC Transit performance project&lt;/a&gt;: let somebody ask the question to the extent they understand it, translate that question into a tightly bounded analytical operation, and return the text and graphics that fit the question.&lt;/p&gt;

&lt;p&gt;The resulting prototype is not an agent with open access to a database. Instead, it is a small public chat service built around an explicit read-only tool boundary.&lt;/p&gt;

&lt;h2 id=&quot;the-fastmcp-idea-that-unlocked-the-prototype&quot;&gt;The FastMCP idea that unlocked the prototype&lt;/h2&gt;

&lt;p&gt;The conference session that helped me shape this idea was about &lt;a href=&quot;https://gofastmcp.com/&quot;&gt;FastMCP&lt;/a&gt;. The basic demonstration was simple: put a decorator on a normal Python function and it becomes a discoverable MCP tool.&lt;/p&gt;

&lt;p&gt;The analogy I wrote down was Flask’s &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;@app.route&lt;/code&gt;. The function already exists, but the decorator makes it part of a public interface without requiring me to hand-write all of the protocol plumbing.&lt;/p&gt;

&lt;p&gt;More importantly, the decorator is opt-in. An agent does not get “the repository” or “the database.” It gets a small list of functions that I deliberately exposed. FastMCP derives a schema from the function signature, uses the docstring as tool guidance, validates arguments, and serializes the result back through MCP.&lt;/p&gt;

&lt;p&gt;Here is a shortened version of one of the tools in the project:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;typing&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Literal&lt;/span&gt;
&lt;span class=&quot;kn&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;nn&quot;&gt;fastmcp&lt;/span&gt; &lt;span class=&quot;kn&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;FastMCP&lt;/span&gt;

&lt;span class=&quot;n&quot;&gt;mcp&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;FastMCP&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;AC Transit performance data&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;

&lt;span class=&quot;o&quot;&gt;@&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mcp&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tool&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;rank_routes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;metric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Literal&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;on_time_service_delivered&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;trip_delivery&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;median_delay&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;dropped_trips&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;long_gaps&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;start_date&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;end_date&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;|&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;bp&quot;&gt;None&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;order&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Literal&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;worst&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;best&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;worst&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;limit&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;int&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;10&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;route_group&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Literal&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;regular&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;school&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;all_nighter&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;transbay&quot;&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;]&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;regular&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;dict&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;
    &lt;span class=&quot;s&quot;&gt;&quot;&quot;&quot;Rank at most ten routes within one service group.&quot;&quot;&quot;&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;data&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;rank_routes&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;metric&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;start_date&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;end_date&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;order&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;limit&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;route_group&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Those &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Literal&lt;/code&gt; types are doing real product work. The model cannot invent a metric or accidentally mix regular local service with school, All Nighter, or Transbay routes. Those service types should be analyzed separately, but a visitor may not know that the distinction matters. A request outside the enum is rejected before it reaches the query code.&lt;/p&gt;

&lt;p&gt;I currently expose only a handful of tools: route and system summaries, same-group route comparisons, route rankings, hourly profiles, a bounded scheduled-arrival list, and public metric definitions. Undecorated helpers and raw query methods stay invisible.&lt;/p&gt;

&lt;h2 id=&quot;the-workflow&quot;&gt;The workflow&lt;/h2&gt;

&lt;p&gt;I kept the architecture entirely in GCP except for the static site. The page is hosted on GitHub Pages, the analysis service and MCP run on Cloud Run, the model is accessed through Vertex AI, and the tools read published JSON summaries from Cloud Storage or bounded data from BigQuery.&lt;/p&gt;

&lt;p&gt;This makes the prototype a tool-driven form of &lt;a href=&quot;https://en.wikipedia.org/wiki/Retrieval-augmented_generation&quot;&gt;retrieval-augmented generation (RAG)&lt;/a&gt;, although it is not the usual document-and-vector-database version. RAG supplements a language model’s trained knowledge with information retrieved from an external source when it answers a question.&lt;/p&gt;

&lt;p&gt;Here, the retrieval step is a bounded MCP tool call rather than a semantic search over document chunks. The tools query published JSON summaries or BigQuery, Gemini uses the returned data to write a short answer, and the same tool results supply the charts and tables. The model therefore generates from current AC Transit data instead of relying only on facts stored in its weights.&lt;/p&gt;

&lt;p&gt;The important parts of the architecture are the two sets of gates: one before the model sees a request, and another before a response reaches the browser.&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
  User[&quot;Public user&amp;lt;br/&amp;gt;asks in their own language&quot;]
  UI[&quot;Static GitHub Pages UI&amp;lt;br/&amp;gt;question + optional route context&quot;]
  Input[&quot;Input gates&amp;lt;br/&amp;gt;length, cooldown, concurrency,&amp;lt;br/&amp;gt;daily budget, follow-up limit&quot;]
  Agent[&quot;Gemini on Vertex AI&amp;lt;br/&amp;gt;read-only system policy&quot;]
  MCP[&quot;Private Cloud Run&amp;lt;br/&amp;gt;FastMCP server&quot;]
  Tools[&quot;Curated read-only tools&amp;lt;br/&amp;gt;typed enums + bounded parameters&quot;]
  Cache[(&quot;Published daily/weekly JSON&amp;lt;br/&amp;gt;Cloud Storage&quot;)]
  Warehouse[(&quot;Deduplicated observations&amp;lt;br/&amp;gt;BigQuery read-only&quot;)]
  Output[&quot;Response gates&amp;lt;br/&amp;gt;allowlisted fields + size caps&quot;]
  Browser[&quot;Browser rendering&amp;lt;br/&amp;gt;Chart.js + accessible heatmap&quot;]
  Result[&quot;Customized answer&amp;lt;br/&amp;gt;text + charts + tables&quot;]
  PrivateLogs[(&quot;Private UTC trace archive&quot;)]
  PublicLogs[(&quot;Redacted public chat archive&quot;)]
  Evals[&quot;Future eval datasets&amp;lt;br/&amp;gt;patterns + regression checks&quot;]

  User --&amp;gt; UI --&amp;gt; Input --&amp;gt; Agent --&amp;gt; MCP --&amp;gt; Tools
  Tools --&amp;gt; Cache
  Tools --&amp;gt; Warehouse
  Cache --&amp;gt; Output
  Warehouse --&amp;gt; Output
  Output --&amp;gt; Browser --&amp;gt; Result --&amp;gt; User
  Agent -. tool trace .-&amp;gt; PrivateLogs
  Output -. successful public fields .-&amp;gt; PublicLogs
  PrivateLogs --&amp;gt; Evals
  PublicLogs --&amp;gt; Evals
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;The FastMCP service is private to the analysis agent. The public browser never calls it directly and never receives database credentials. The model can only select among the tools the MCP advertises, and the MCP service account has read-only access to the relevant data.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/07b0674a913011796318a17bebe1c84fecfeeb9c/images/_posts/rapid-agent-chat-fastmcp/chat-thread.png&quot; alt=&quot;The live prompt interface showing rate limits, the retained question thread, and a follow-up field&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The public interface makes the cost controls visible and keeps follow-up questions attached to the latest answer.&lt;/em&gt;&lt;/p&gt;

&lt;h2 id=&quot;input-hardening-is-the-first-half-of-the-lifecycle&quot;&gt;Input hardening is the first half of the lifecycle&lt;/h2&gt;

&lt;p&gt;Because this is a public service, I assume people will eventually send requests that are irrelevant, adversarial, or simply much larger than I intended. I also want a brief burst of attention to remain cheap.&lt;/p&gt;

&lt;p&gt;The current request gates are intentionally aggressive because this is still a prototype:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;500 characters per prompt&lt;/li&gt;
  &lt;li&gt;one request every 20 seconds per browser&lt;/li&gt;
  &lt;li&gt;two concurrent queries across the service&lt;/li&gt;
  &lt;li&gt;ten questions per browser per day&lt;/li&gt;
  &lt;li&gt;a shared daily question budget&lt;/li&gt;
  &lt;li&gt;no more than three follow-ups in a thread&lt;/li&gt;
  &lt;li&gt;no more than four tool calls and two tool rounds per answer&lt;/li&gt;
  &lt;li&gt;at most 31 calendar days for the heavier analytical tools, with plans to extend this window&lt;/li&gt;
  &lt;li&gt;at most four hours and 250 rows for a scheduled-arrival listing&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;These are configuration values, not magic numbers. They can change as I observe real use. The point is that cost and abuse controls are part of the interface, not an invisible emergency measure. The page tells a visitor why they are waiting and how much shared capacity remains.&lt;/p&gt;

&lt;p&gt;Prompt rules are useful, but I do not treat them as a reliable security boundary. The harder boundary is that every callable function is read-only, bounded, and typed. There is no general SQL tool and no write tool, which sharply limits the available abuse paths. Row and date limits also block bulk extraction; there is no way to ask for an unbounded table dump.&lt;/p&gt;

&lt;h2 id=&quot;constraining-the-response-is-just-as-important&quot;&gt;Constraining the response is just as important&lt;/h2&gt;

&lt;p&gt;I also do not want the agent to return arbitrary HTML, JavaScript, images, or a giant JSON blob. The server normalizes every successful result into a small response protocol:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;tool_result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;answer_context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;timeframe&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;charts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;tables&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;sources&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;warnings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;):&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;answer_context&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;answer_context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;timeframe&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;timeframe&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;charts&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;charts&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[:&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;3&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;tables&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;
            &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;**&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;table&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;&quot;rows&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;table&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;get&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;rows&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[])[:&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;250&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]}&lt;/span&gt;
            &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;table&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tables&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[:&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;2&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;sources&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;sources&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[:&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
        &lt;span class=&quot;s&quot;&gt;&quot;warnings&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;warnings&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[:&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The final response permits text plus a few structured building blocks:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;up to three charts&lt;/li&gt;
  &lt;li&gt;up to two tables with 250 rows each&lt;/li&gt;
  &lt;li&gt;up to five series per standard chart&lt;/li&gt;
  &lt;li&gt;up to 500 chart points across the answer&lt;/li&gt;
  &lt;li&gt;24 by 7 cells for an hourly heatmap&lt;/li&gt;
  &lt;li&gt;eight source records and eight warnings&lt;/li&gt;
  &lt;li&gt;a total serialized response cap&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The chart vocabulary is deliberately tiny: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;bar&lt;/code&gt;, &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;line&lt;/code&gt;, and &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;heatmap&lt;/code&gt;. Adding a format is a conscious frontend and backend change rather than something the model improvises.&lt;/p&gt;

&lt;p&gt;A simplified response looks like this:&lt;/p&gt;

&lt;div class=&quot;language-json highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;answer&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Route 1T had 221 scheduled trips...&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;timeframes&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;start_date&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;2026-11-03&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;end_date&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;2026-11-03&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;assumed&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;kc&quot;&gt;false&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;disclosure&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Analyzed published service dates...&quot;&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;charts&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;type&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;bar&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;title&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Route 1T scheduled and dropped trips by day&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;labels&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;2026-11-03&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;series&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;name&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Scheduled trips&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;values&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;221&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]},&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
      &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;name&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;Dropped / not observed trips&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;values&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;19&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
    &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;tables&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;warnings&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[],&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
  &lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;sources&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[{&lt;/span&gt;&lt;span class=&quot;nl&quot;&gt;&quot;kind&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;w&quot;&gt; &lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;&quot;daily_stats&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}]&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;w&quot;&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;The model writes only the short narrative. It does not write chart JSON or Markdown tables. The structured visuals come from the tools and pass through a deterministic merger with the limits above.&lt;/p&gt;

&lt;p&gt;This also shifts work off the server. The response contains labels, values, series names, and axis names. The browser turns those building blocks into Chart.js bar or line charts and an accessible HTML heatmap. The server does not render a PNG for every request, run a headless browser, or store a generated graphic.&lt;/p&gt;

&lt;p&gt;The same payload can be rendered responsively, inspected with assistive technology, and restyled without calling the model again.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/07b0674a913011796318a17bebe1c84fecfeeb9c/images/_posts/rapid-agent-chat-fastmcp/structured-response-charts.png&quot; alt=&quot;A generated answer with daily trip bars and a 24-by-7 dropped-trip heatmap rendered in the browser&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The server returned chart primitives; the browser rendered the two bar charts and the hourly heatmap.&lt;/em&gt;&lt;/p&gt;

&lt;h2 id=&quot;the-data-model-still-matters&quot;&gt;The data model still matters&lt;/h2&gt;

&lt;p&gt;A chat box does not remove the need for a semantic layer.&lt;/p&gt;

&lt;p&gt;For example, the project distinguishes &lt;strong&gt;On Time Service Delivered&lt;/strong&gt;, a stop-level rider-window measure, from &lt;strong&gt;Trip delivery&lt;/strong&gt;, which measures whether scheduled trips were observed running. A casual question about buses “not showing up” could refer to either one. The tool descriptions, metric registry, and system policy help the agent select the right operation and explain the caveat.&lt;/p&gt;

&lt;p&gt;The same applies to route groups. AC Transit’s 600-series school service and 800-series All Nighter service should not be ranked as peers against regular local routes. That rule now exists in the tool schema, the tool implementation, the response policy, and regression tests.&lt;/p&gt;

&lt;p&gt;This is the part that makes the interface useful to somebody who is not a subject-matter expert. They can ask in their own language. The system translates that request into domain-specific choices while still disclosing the timeframe, metric, and data limitations it used.&lt;/p&gt;

&lt;h2 id=&quot;logs-are-the-beginning-of-the-evaluation-loop&quot;&gt;Logs are the beginning of the evaluation loop&lt;/h2&gt;

&lt;p&gt;One of the other conference sessions covered &lt;a href=&quot;https://www.braintrust.dev/blog/active-observability-loop-patterns&quot;&gt;Braintrust’s active observability loop&lt;/a&gt;. The useful idea was not merely “log everything.” It was a workflow:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;Observe production traces.&lt;/li&gt;
  &lt;li&gt;Find repeated topics, failure patterns, and unusual successes.&lt;/li&gt;
  &lt;li&gt;Curate important traces into a dataset.&lt;/li&gt;
  &lt;li&gt;Turn the expected behavior into a scorer or regression test.&lt;/li&gt;
  &lt;li&gt;Compare a prompt, tool, model, or policy change against the baseline.&lt;/li&gt;
  &lt;li&gt;Monitor so the fixed behavior does not drift back.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;I am not operating at a volume that justifies a full trace-intelligence platform yet. I can still make sure the raw material exists.&lt;/p&gt;

&lt;p&gt;Every request writes a private JSON record partitioned by UTC date and hour. It includes the question, thread and turn position, structured response, prompt features, tool-call trace, model, status, and latency. Successful conversations also get a separate public record with an opaque conversation identifier and automated redaction; request identifiers, session identifiers, tool traces, latency, and errors do not enter the public archive.&lt;/p&gt;

&lt;p&gt;The logs have already been useful. A follow-up asking for the number of trips that did not run by day and the worst hours initially returned a generic trend line. That production example became an eval case requiring an absolute daily bar chart and a 24-by-7 heatmap. A route-comparison mistake became another case requiring service-group separation.&lt;/p&gt;

&lt;p&gt;Those fixtures are a small version of the Braintrust loop: a real confusing answer becomes a test that defines what the feature is supposed to do from then on.&lt;/p&gt;

&lt;p&gt;Later, I can classify the archive by question type, inspect recurring unanswered requests, find expensive tool paths, or cluster failures that I did not anticipate. At this project’s current traffic level, a periodic manual review and a focused regression set are enough. The important thing is that adding more tools does not mean giving up the ability to detect performance drift.&lt;/p&gt;

&lt;h2 id=&quot;what-i-like-about-this-pattern&quot;&gt;What I like about this pattern&lt;/h2&gt;

&lt;p&gt;Dashboards are not going away, and well-curated ones remain critical. The chat interface is useful for the space before a question has become stable enough to deserve one. Patterns in logged requests can show which information my pre-built dashboards surface poorly. They can also help translate questions from people who understand the service problem but do not know the system’s metric names, making the existing metrics easier to use.&lt;/p&gt;

&lt;p&gt;FastMCP made the last mile of this workflow quick by turning existing Python functions into an explicit agent-facing interface. The harder work was curation: deciding what not to expose, which metrics are valid, which route groups are comparable, how much data a tool may return, and which response shapes the frontend will accept. That curation still has to leave the tool flexible and useful for a general audience.&lt;/p&gt;

&lt;p&gt;The user gets a customized answer without needing to know the warehouse or dashboard taxonomy. The agent gets flexibility in choosing among a few useful operations. The data service remains read-only and bounded. The browser does the presentation work. The traces left behind can become the tests that keep the interface from getting worse as it grows.&lt;/p&gt;
</description>
        <pubDate>Fri, 06 Nov 2026 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2026/11/06/rapid-agent-chat-interface-prototyping-with-fastmcp/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2026/11/06/rapid-agent-chat-interface-prototyping-with-fastmcp/</guid>
      </item>
    
      <item>
        <title>Talking a Map Into Existence with Squidmaps</title>
        <description>&lt;h1 id=&quot;talking-a-map-into-existence-with-squidmaps&quot;&gt;Talking a Map Into Existence with Squidmaps&lt;/h1&gt;

&lt;p&gt;The online geo world is relatively small, and &lt;a href=&quot;https://chriswhong.com/&quot;&gt;Chris Whong&lt;/a&gt; has long been one of the people making interesting things in it. He recently wrapped up a couple years at Mapbox and, shortly afterward, launched the public beta of &lt;a href=&quot;https://squidmaps.io/&quot;&gt;squidmaps&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;When I first saw it, I was reminded of Felt in its early days; not because the products are the same, but because both make web mapping feel unusually lightweight and approachable. Felt has since moved toward the more sophisticated features and larger customers needed to sustain a growing company, leaving “small-time” mapmakers with few good options. Google My Maps exists, but has always felt clunky. The hard part for any alternative is paying for a service aimed at people who may make only an occasional simple map. AI changes that equation: a natural-language interface can support many basic mapping needs without a sprawling product surface, creating room for a low- or no-cost tool that still produces polished maps with guardrails for legibility.&lt;/p&gt;

&lt;p&gt;So, back to squidmaps: What really caught my attention was the &lt;a href=&quot;https://squidmaps.io/docs/api/ephemeral-maps&quot;&gt;ephemeral maps API&lt;/a&gt;. An agent can send squidmaps a complete map document without an account or API key and receive a temporary URL in return. It can then replace the map as the conversation continues. Once the map is useful, a person can claim it and keep it.&lt;/p&gt;

&lt;p&gt;That creates a very natural conversational mapping loop: describe a map, look at it, ask for a change, and repeat.&lt;/p&gt;

&lt;h2 id=&quot;moving-the-complexity-behind-the-agent&quot;&gt;Moving the complexity behind the agent&lt;/h2&gt;

&lt;p&gt;The important change is not that geoprocessing disappears. It is that the client no longer has to understand and orchestrate every operation. In a traditional web mapping tool, the person making the map often has to locate the data, choose a conversion, run each spatial operation in the right order, and carry the result from one provider-side tool to the next.&lt;/p&gt;

&lt;h4 id=&quot;legacy-web-geo-tools-the-client-orchestrates-each-operation&quot;&gt;Legacy web geo tools: the client orchestrates each operation&lt;/h4&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
  Client[&quot;Client&amp;lt;br/&amp;gt;chooses tools, formats and sequence&quot;]
  Import[&quot;Provider&amp;lt;br/&amp;gt;data import&quot;]
  Convert[&quot;Provider&amp;lt;br/&amp;gt;format conversion&quot;]
  Process[&quot;Provider&amp;lt;br/&amp;gt;buffer, clip, join or route&quot;]
  Publish[&quot;Style and publish&quot;]
  Map[&quot;Map view&quot;]

  Client &amp;lt;--&amp;gt;|&quot;manage&quot;| Import
  Client &amp;lt;--&amp;gt;|&quot;manage&quot;| Convert
  Client &amp;lt;--&amp;gt;|&quot;manage&quot;| Process
  Client --&amp;gt; Publish --&amp;gt; Map --&amp;gt; Client
&lt;/code&gt;&lt;/pre&gt;

&lt;h4 id=&quot;agentic-map-tools-the-client-communicates-intent&quot;&gt;Agentic map tools: the client communicates intent&lt;/h4&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
  Client[&quot;Client&amp;lt;br/&amp;gt;describes intent&quot;]
  Agent[&quot;AI agent&quot;]
  Sources[&quot;Open-ended&amp;lt;br/&amp;gt;data sources&quot;]
  Methods[&quot;Format conversion&amp;lt;br/&amp;gt;methods&quot;]
  GeoOps[&quot;Geoprocessing&amp;lt;br/&amp;gt;and routing&quot;]
  Handoff[&quot;Clean GeoJSON&amp;lt;br/&amp;gt;and map specification&quot;]
  API[&quot;Squidmaps&amp;lt;br/&amp;gt;ephemeral maps API&quot;]
  View[&quot;Clean&amp;lt;br/&amp;gt;Squidmaps view&quot;]

  Client &amp;lt;--&amp;gt;|&quot;request and feedback&quot;| Agent
  Agent &amp;lt;--&amp;gt;|&quot;discover and retrieve&quot;| Sources
  Agent &amp;lt;--&amp;gt;|&quot;convert&quot;| Methods
  Agent &amp;lt;--&amp;gt;|&quot;run&quot;| GeoOps
  Agent --&amp;gt; Handoff --&amp;gt; API --&amp;gt; View --&amp;gt; Client
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;In the agentic version, the client describes the desired map and responds to what they see. The agent can reach into an open-ended set of datasets, conversion methods, and spatial processes, but the handoff to squidmaps stays simple: cleaned GeoJSON and a structured map specification. The complexity still exists, but it sits behind the agent instead of inside the conversation the client must have with the mapping software.&lt;/p&gt;

&lt;h2 id=&quot;converting-a-narrated-walk&quot;&gt;Converting a narrated walk&lt;/h2&gt;

&lt;p&gt;I tried this workflow I described in the last section, with a walk I took through Oakland. I described the day more or less as I remembered it: start at the Morcom Rose Garden, walk down Grand Avenue to the farmers market, continue along Lake Merritt for coffee and thrifting, head east for bánh mì and an ube waffle, finish at the Día de los Muertos festival in Fruitvale, and then take the 62 and 57 buses home.&lt;/p&gt;

&lt;p&gt;From that description, the chatbot resolved the stops, calculated street-following geometry from OpenStreetMap data, assembled the features and styles, and sent the resulting map document to squidmaps. I did not draw or style anything manually.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/squidmaps-verbal-mapping/first-map.png&quot; alt=&quot;The first squidmaps rendering of an Oakland walk, with walking and transit routes, nine stops, and a legend&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The first result from the verbal description: a walking route, two transit legs, labeled stops, and a coherent legend.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The result was already quite good. The route was readable, the walking and transit legs were distinct, the stops had a consistent visual language, and the map came back as a real artifact I could inspect and share—not merely some code that I still needed to turn into a map.&lt;/p&gt;

&lt;p&gt;I eventually saved it as a permanent map: &lt;a href=&quot;https://squidmaps.io/kuanbutts/last-weekend-an-oakland-walk-and-the-ride-home&quot;&gt;Last weekend: an Oakland walk and the ride home&lt;/a&gt;.&lt;/p&gt;

&lt;h2 id=&quot;geo-operations-do-not-all-need-to-live-in-the-mapping-product&quot;&gt;Geo operations do not all need to live in the mapping product&lt;/h2&gt;

&lt;p&gt;Next, I wanted to show how long I stayed at each stop. I supplied the dwell times and asked for transparent circles whose areas were proportional to the time spent, plus labels on hover.&lt;/p&gt;

&lt;p&gt;This is where the architecture became particularly interesting to me. A mapping platform does not necessarily need to implement every standard spatial operation itself. If the destination accepts GeoJSON, an agent can write a small Python script and use something like Shapely to calculate a buffer, union geometries, clip a layer, or generate another derived feature. It can then send the result back as ordinary GeoJSON.&lt;/p&gt;

&lt;p&gt;For this map, the chatbot calculated the circle sizes and added the resulting dwell-time features to the existing map document. The same pattern would work for more general geoprocessing outside squidmaps.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/squidmaps-verbal-mapping/dwell-time-map.png&quot; alt=&quot;The updated squidmaps rendering with transparent dwell-time circles, hover labeling, and an expanded legend&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The second iteration added proportional dwell-time circles, a feature group, a size legend, and hover labels.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;This division of labor feels useful. The agent’s working environment can handle common geometry operations, while squidmaps handles presentation, interaction, and publishing. There does not need to be a dedicated button in the product for every operation that already exists in mature spatial libraries. This is where squidmaps finally breaks free of the endless feature requirements problem with geo projects (and the ensuring over-technical-ness of them that ultimately alienates the very users who it might have set out to help).&lt;/p&gt;

&lt;h2 id=&quot;constraints-are-part-of-the-value&quot;&gt;Constraints are part of the value&lt;/h2&gt;

&lt;p&gt;AI systems are increasingly capable of writing valid GeoJSON and spatial-processing code. They are still inconsistent at the graphical part of mapping. They choose too many colors, create noisy labels, obscure important features, or produce legends that do not quite explain the map. Humans struggle with these things too, to be fair.&lt;/p&gt;

&lt;p&gt;Squidmaps provides a strong set of visual constraints: sensible defaults, a cohesive symbol language, a predictable information panel, legends, folders, tooltips, and a basemap that stays out of the way. Those constraints guide the agent’s intent toward something legible.&lt;/p&gt;

&lt;p&gt;That is the part that reminds me most of early Felt. The interesting thing is not merely that a nontechnical user can make a map quickly. It is that they can make one by describing what they mean, while the platform keeps the graphical result within a reasonably good cartographic system.&lt;/p&gt;

&lt;h2 id=&quot;one-possible-next-step-extrusion&quot;&gt;One possible next step: extrusion&lt;/h2&gt;

&lt;p&gt;Out of curiosity, I also tried adding elevation to the route so the line could rise and fall with the terrain. The current API does not render altitude-bearing coordinates or line-extrusion properties, and its saved view does not yet accept pitch or bearing. Extra elevation data can travel with a feature, but it remains a flat line.&lt;/p&gt;

&lt;p&gt;Extrusion is often overused and can make maps less legible, but this was a case where it would have been useful: the height of the route could have made the long downhill portion of the walk immediately visible. Since the viewer already permits interactive tilting, feature extrusion feels like a natural future addition to the map specification and API.&lt;/p&gt;

&lt;p&gt;The experiment left me excited about the underlying pattern. The chatbot translates informal language into structured spatial data and can perform established geo operations in code. Squidmaps supplies the constrained visual system and produces a clean, interactive, shareable map. That seems like a very promising way to make simple mapping genuinely accessible without asking the mapping platform itself to do everything.&lt;/p&gt;
</description>
        <pubDate>Fri, 30 Oct 2026 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2026/10/30/talking-a-map-into-existence-with-squidmaps/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2026/10/30/talking-a-map-into-existence-with-squidmaps/</guid>
      </item>
    
      <item>
        <title>Integration Tradeoffs Between MCPs and Plugins</title>
        <description>&lt;h1 id=&quot;the-integration-layer-why-mcps-blow-up-context&quot;&gt;The Integration Layer: Why MCPs “Blow Up” Context&lt;/h1&gt;

&lt;p&gt;I wrote this post primarily to dig into why the Model Context Protocol (MCP) is often blamed for consuming massive context windows and driving out-of-control token costs in online discussions.&lt;/p&gt;

&lt;p&gt;The main complaint I see of MCP centers on its tendency to create massive context windows, leading to higher costs and increased latency. This isn’t necessarily a bug, but a side effect of a fundamental difference in how data moves into the model. Traditional Plugins and Skills treat tools as functions with strict schemas: the model calls a defined tool and receives a targeted, concise response that keeps the context window small.&lt;/p&gt;

&lt;p&gt;MCPs, in contrast, treat tools as data providers that stream &lt;em&gt;any information&lt;/em&gt; (be it files, logs, or database rows) directly into the prompt. In this philosophy, the model acts as the primary interpreter: So it gets a huge blob of raw data and reasons about it in an entirely flexible manner, treating it purely as unstructed text at the onset. This means that even if only 5% of a document is relevant, often 100% of it is loaded into the context, turning the context window itself into the integration layer.&lt;/p&gt;

&lt;p&gt;But this is also a product of how MCPs are designed - if you have an MCP that provides large unsorted blobs of data like this, you end up getting that flexibility. If you didn’t and you previously had more scoped MCPs, there are other considerations vs. a plugin for example, that need to be considered. Those will be discussed later.&lt;/p&gt;

&lt;h1 id=&quot;local-execution-and-the-permission-model&quot;&gt;Local Execution and the Permission Model&lt;/h1&gt;

&lt;p&gt;The architectural shift in MCP is most apparent when looking at local execution. Thus, one of the most important distinctions in MCP architectures is &lt;strong&gt;where execution happens and under whose identity&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Consider a scenario where an AI agent needs to perform an AWS Athena query.&lt;/p&gt;

&lt;h2 id=&quot;the-mcp-model-run-as-you&quot;&gt;The MCP Model: “Run as You”&lt;/h2&gt;

&lt;p&gt;In an MCP setup, the “server” is frequently just a local script (Python or Node) running on your machine. When the LLM invokes an MCP tool to run a query, the script executes as a local process.&lt;/p&gt;

&lt;h3 id=&quot;flow-diagram&quot;&gt;Flow Diagram&lt;/h3&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
  subgraph LocalEnv[&quot;Local Environment&quot;]
    direction LR
    A[Claude/Client]
    B[MCP Script]
    C[&quot;~/.aws/credentials&quot;]
  end
  D[(&quot;AWS Athena&quot;)]
  
  A --&amp;gt; B
  B --&amp;gt; C
  C --&amp;gt; D
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&quot;what-this-means&quot;&gt;What this means&lt;/h3&gt;

&lt;p&gt;Because this script lives in your environment, it implicitly inherits your identity, utilizing your local credentials and active SSO sessions. This provides immense flexibility but introduces a significant permissions risk. That is, the model effectively gains a “remote control” for your environment. It will execute any query you are personally authorized to run unless your code explicitly blocks it. That is, event if your prompt says not to do something, there is a risk that it may be done regardless - there is no guarantee against those hazards.&lt;/p&gt;

&lt;h3 id=&quot;the-tradeoff&quot;&gt;The tradeoff&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Pros&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;Extremely flexible&lt;/li&gt;
  &lt;li&gt;Easy to iterate&lt;/li&gt;
  &lt;li&gt;Powerful local integrations&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Cons&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;High permission risk&lt;/li&gt;
  &lt;li&gt;The model can indirectly trigger any action you are authorized to perform&lt;/li&gt;
  &lt;li&gt;Safety depends entirely on your code (not the prompt)&lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;the-plugin-model-call-a-service&quot;&gt;The Plugin Model: “Call a Service”&lt;/h2&gt;

&lt;p&gt;Conversely, a plugin calls a remote hosted service via an API. The execution happens on an external server using service-side credentials. This creates a very explicity and hard control boundary; the model is confined to defined endpoints and schemas, and the backend enforces security rules that the model cannot bypass through prompt manipulation alone.&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart LR
  A[Claude / Client]
  B[Plugin API Endpoint]
  C[Backend Service]
  D[(AWS Athena)]

  A --&amp;gt; B
  B --&amp;gt; C
  C --&amp;gt; D
&lt;/code&gt;&lt;/pre&gt;

&lt;h1 id=&quot;memory-the-harness-and-identity&quot;&gt;Memory, the Harness, and Identity&lt;/h1&gt;

&lt;p&gt;There is additional consideration to be had regarding reliance on memory when evaluating data from an MCP response and holding it in raw, blob text form for evaluation and downstream flow reference. Specifically, you are relying on the behavior of the agent/harness and how it manages memory to ensure the important elements from your MCP response are preserved. This is subject to the agent’s interpration during runtime and not explicitly handled like in a plugin.&lt;/p&gt;

&lt;p&gt;A helpful insight that further expands on this comes from this blog post &lt;a href=&quot;https://blog.langchain.com/your-harness-your-memory/&quot;&gt;“Your harness, your memory”&lt;/a&gt; is that memory is not a plugin: it lives in the harness. The “harness” is the system managing the context lifecycle, such as Cursor or a managed chat interface (Opus, Codex, etc.). It is the harness that makes “invisible decisions” about what to summarize, truncate, or delete as the conversation progresses.&lt;/p&gt;

&lt;p&gt;While MCP assumes memory is external data we can supply, the reality is that memory is whatever survives the context management of the harness. This creates a form of “state dependency”. If the harness owns the memory, you cannot easily move your agent’s learned patterns or history between different platforms.&lt;/p&gt;

&lt;h1 id=&quot;skills-the-behavioral-layer&quot;&gt;Skills: The Behavioral Layer&lt;/h1&gt;

&lt;p&gt;To complete the hierarchy, skills act as a third layer that sits above execution. While MCPs and plugins provide the capabilities (e.g. “What code or services can I run?”), skills provide the policies (e.g. “How should I behave?”).&lt;/p&gt;

&lt;p&gt;So we can see how the two aforementioned concepts can exist in parallel and interact with the same remote resources, but with plugins and MCPs existing as different intermediaries with different potential permissions scopes and degrees of flexibility. Then, skills provide guidance on how to use either of these (or any other available tooling).&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
  Skill[&quot;Skills (Behavioral Policy Layer)&quot;]
  LLM[&quot;LLM Reasoning Layer&quot;]
  MCP[&quot;MCP (Local Execution Tools)&quot;]
  Plugin[&quot;Plugins (Remote APIs)&quot;]
  System[&quot;External Systems (AWS, DBs, etc.)&quot;]

  Skill --&amp;gt; LLM
  LLM --&amp;gt; MCP
  LLM --&amp;gt; Plugin
  MCP --&amp;gt; System
  Plugin --&amp;gt; System
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;A skill does not directly access AWS or run queries. Instead, it biases the model’s decision-making process—for instance, instructing it to always inspect a schema or, for example, apply a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;LIMIT 1000&lt;/code&gt; before invoking the Athena DWH query tool. The tool then, can exist in entities such as the more deterministic MCP and plugin layer described prior.&lt;/p&gt;

&lt;h1 id=&quot;conclusion&quot;&gt;Conclusion&lt;/h1&gt;

&lt;p&gt;Ultimately, the choice between these architectures is a trade off. MCPs provide the most flexibility for reasoning by operating directly within your local environment, yet they inherit the risk of lower explicit control, especially as they are running with your full identity rather than as a sandboxed agent. Plugins are on the other end of the spectrum in this sense: they are strictly scoped by design, both in their permission sets and in how the agent harness prioritizes their structured responses within its memory. Above both these execution layers sit skills, acting as the behavioral guide. They don’t handle the mechanics of the query, but instead set preferences for agents on when to lean into the flexible stream of an MCP and when to rely on the predictable boundaries of a plugin.&lt;/p&gt;
</description>
        <pubDate>Sun, 12 Apr 2026 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2026/04/12/understanding-difference-between-plugin-mcp-skills/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2026/04/12/understanding-difference-between-plugin-mcp-skills/</guid>
      </item>
    
      <item>
        <title>Streaming When Your Cache Becomes the Bottleneck</title>
        <description>&lt;h1 id=&quot;introduction&quot;&gt;Introduction&lt;/h1&gt;

&lt;p&gt;With many real-time systems, there’s a pretty standard shape:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;ingest from a high-volume event stream&lt;/li&gt;
  &lt;li&gt;assign those events to some entity&lt;/li&gt;
  &lt;li&gt;periodically recompute derived state from recent observations&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;At small to medium scale, a shared cache (Redis/Valkey) works great as the boundary between ingestion and aggregation. However, at a large enough scale, this same cache configuration can become this biggest bottleneck to both a performant data pipieline and developer velocity in terms of attaching to it or spinning up parallel pipelines.&lt;/p&gt;

&lt;p&gt;This post walks through a tradeoff I ran into:
&lt;strong&gt;using a distributed cache vs a streaming system (Kinesis)&lt;/strong&gt; as the interface between live data ingestion and downstream computation.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/cache_to_stream/diagram.png&quot; alt=&quot;diagram_of_system&quot; /&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Above: Last attempt at a Gemini AI-generated diagram for this just on a whim, attempting to show how Kinesis enables multi-tenant consumption of a high-read resource that, as a cache, would be overwhelmed or trigger excessive queuing, as represented by the well.&lt;/em&gt;&lt;/p&gt;

&lt;h2 id=&quot;system-overview&quot;&gt;System Overview&lt;/h2&gt;

&lt;p&gt;Stripping away from my domain specifics (live probe data from real-world telemetry map matched onto a road network and then generating real-time speeds), the system looks like this:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;~100M events per minute (~1.6M/sec)&lt;/li&gt;
  &lt;li&gt;each event is assigned to one of hundreds of millions of possible entities&lt;/li&gt;
  &lt;li&gt;at any moment, ~250–500M entities are “active”&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;There are two main stages:&lt;/p&gt;

&lt;h3 id=&quot;1-ingestion--assignment&quot;&gt;1. Ingestion + Assignment&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;clean raw events&lt;/li&gt;
  &lt;li&gt;run compute-heavy assignment (classification / matching)&lt;/li&gt;
  &lt;li&gt;emit output data with pairing metadata &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;(entity_id, event)&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;2-aggregation--estimation&quot;&gt;2. Aggregation / Estimation&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;group entities into partitions&lt;/li&gt;
  &lt;li&gt;periodically recompute derived state using &lt;em&gt;all qualifying recent events&lt;/em&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TD
    A[Event Stream] --&amp;gt; B[Ingestion + Assignment]
    B --&amp;gt; C[&quot;(entity_id, event)&quot;]
    C --&amp;gt; D[Cache]
    D --&amp;gt; E[Aggregation Workers]
&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;the-initial-design-cache-centric&quot;&gt;The Initial Design: Cache-Centric&lt;/h2&gt;

&lt;p&gt;After assignment, all events are written into a distributed cache (Redis/Valkey). Aggregation workers then:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;scan all relevant keys for a partition&lt;/li&gt;
  &lt;li&gt;load everything into memory&lt;/li&gt;
  &lt;li&gt;compute derived state&lt;/li&gt;
  &lt;li&gt;repeat frequently (potentially sub-minutely - so high rate of revolution)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This had worked well enough for a while. But a problem in the design was present that kept rising up: &lt;strong&gt;aggregation is stateless&lt;/strong&gt;. That means every run starts from scratch - reading all of the cache for its respective partition.&lt;/p&gt;

&lt;h2 id=&quot;the-problem-read-amplification&quot;&gt;The Problem: Read Amplification&lt;/h2&gt;

&lt;p&gt;At this scale, the system isn’t just write-heavy; it is also &lt;em&gt;extremely read-heavy&lt;/em&gt;. So, in practice, the cache layer was handling:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;&lt;strong&gt;~660K operations/sec (reads + writes)&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;~510 MB/sec sustained network throughput&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;~1.6 KB average payload size&lt;/strong&gt;&lt;/li&gt;
  &lt;li&gt;across &lt;strong&gt;24 shards&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each aggregation cycle:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;re-reads large portions of recent data&lt;/li&gt;
  &lt;li&gt;across many partitions&lt;/li&gt;
  &lt;li&gt;often in parallel&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The consquence of this was a few major issues:&lt;/p&gt;

&lt;h3 id=&quot;1-read-amplification&quot;&gt;1. Read amplification&lt;/h3&gt;

&lt;p&gt;The same data is read repeatedly, even when only a small fraction has changed.&lt;/p&gt;

&lt;h3 id=&quot;2-synchronized-load-spikes&quot;&gt;2. Synchronized load spikes&lt;/h3&gt;

&lt;p&gt;Many workers scanning the same partitions at the same time:&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TB
  subgraph workers[&quot;Aggregation workers&quot;]
    direction LR
    W1[scan]
    W2[scan]
    W3[scan]
    W4[scan]
    W5[scan]
  end
  Cache[(&quot;Cache&quot;)]
  W1 --&amp;gt; Cache
  W2 --&amp;gt; Cache
  W3 --&amp;gt; Cache
  W4 --&amp;gt; Cache
  W5 --&amp;gt; Cache
&lt;/code&gt;&lt;/pre&gt;

&lt;h3 id=&quot;3-contention&quot;&gt;3. Contention&lt;/h3&gt;

&lt;ul&gt;
  &lt;li&gt;ingestion writes&lt;/li&gt;
  &lt;li&gt;aggregation reads&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;…all competing for the same resource.&lt;/p&gt;

&lt;p&gt;Interestingly, the system settled into roughly a &lt;strong&gt;1:1 read-to-write ratio&lt;/strong&gt;—but that hides the real issue that the reads are large, repeated scans, not incremental updates.&lt;/p&gt;

&lt;h2 id=&quot;naive-solution-scale-the-cache&quot;&gt;Naive Solution: Scale the Cache&lt;/h2&gt;

&lt;p&gt;The first fix is the obvious one which was taken first:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;add more nodes&lt;/li&gt;
  &lt;li&gt;increase memory&lt;/li&gt;
  &lt;li&gt;scale throughput&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This works and bought us lots of time, but it’s expensive and doesn’t address the underlying inefficiency.&lt;/p&gt;

&lt;p&gt;In our case:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;~24 shards&lt;/li&gt;
  &lt;li&gt;node type: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;cache.r7g.4xlarge&lt;/code&gt;&lt;/li&gt;
  &lt;li&gt;&lt;strong&gt;~$13,500/month&lt;/strong&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;And more importantly the system must be provisioned for peak load at all times. Furthermore, every time a developer wants to work with the same data, we can’t just add a new consumer to the cache - that would cause the cache to fall over. So we need to create a new pipeline to feed a new cache. This is a lot of pipeline duplicate and very expensive. The developer time involved in doing this is often prohibitively high, not to mention the operational complexity of accomplishing it.&lt;/p&gt;

&lt;h3 id=&quot;a-subtle-scaling-problem&quot;&gt;A subtle scaling problem&lt;/h3&gt;

&lt;p&gt;Unlike compute systems (Lambda, ECS, etc.), cache scaling is not elastic:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;scaling out (adding shards) is manual and slow&lt;/li&gt;
  &lt;li&gt;scaling in (removing shards) is risky and disruptive&lt;/li&gt;
  &lt;li&gt;no true autoscaling based on load&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The result, in reality, is that you provision for peak and pay for it even at trough. In a production system, where you want to buy a lot of headroom (literally), this can get pricey on serious workload caches very fast.&lt;/p&gt;

&lt;h2 id=&quot;next-solution-make-consumers-stateful&quot;&gt;Next solution: Make Consumers Stateful&lt;/h2&gt;

&lt;p&gt;One idea was to flip the model; so, instead of repeatedly scanning the cache:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;make aggregation workers stateful&lt;/li&gt;
  &lt;li&gt;assign each worker a stable partition&lt;/li&gt;
  &lt;li&gt;maintain local in-memory state&lt;/li&gt;
  &lt;li&gt;update incrementally via pub/sub&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Redis (and Valkey) support &lt;strong&gt;keyspace notifications&lt;/strong&gt;, which can be used as a lightweight pub/sub mechanism.&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TD
  Cache[(&quot;Cache&quot;)]
  Cache --&amp;gt;|&quot;pub/sub updates&quot;| Workers[&quot;Stateful Aggregation Workers&quot;]
  Workers --&amp;gt; Outputs[&quot;Derived State Outputs&quot;]
&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;The main advantages of this approach are that it avoids repeated full scans of the data and significantly reduces read pressure on the cache. However, this approach comes with its own set of tradeoffs:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;requires stable partition ownership&lt;/li&gt;
  &lt;li&gt;introduces stateful workers&lt;/li&gt;
  &lt;li&gt;harder failure recovery (e.g. handling cold starts)&lt;/li&gt;
  &lt;li&gt;still tied to shared cache&lt;/li&gt;
  &lt;li&gt;does &lt;em&gt;not&lt;/em&gt; solve multi-consumer needs (lots of cold starts, deploys are all stampeding herd situations, can destabilize prod stack)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So, while this solution has merit and does incrememntally help, it doesn’t solve the bigger problem.&lt;/p&gt;

&lt;h2 id=&quot;the-bigger-problem-coupling&quot;&gt;The Bigger Problem: Coupling&lt;/h2&gt;

&lt;p&gt;The cache bottleneck exposes a deeper problem that the ingestion pipeline and aggregation logic are tightly coupled. If someone wants to try a new model or experiment they had to re-run ingestion and including the expensive assignment step; as noted prior. In practice this means:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;duplicate pipelines&lt;/li&gt;
  &lt;li&gt;high compute cost&lt;/li&gt;
  &lt;li&gt;backpressure on shared services&lt;/li&gt;
  &lt;li&gt;slow iteration&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;At this scale, recomputing upstream work is often more expensive than storing and distributing it.&lt;/p&gt;

&lt;h2 id=&quot;the-constraint-unsafe-multi-tenancy&quot;&gt;The Constraint: Unsafe Multi-Tenancy&lt;/h2&gt;

&lt;p&gt;So, fundamentally, this architecture of a shared cache cannot safely support multiple consumers. Adding experimental workloads meant:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;increased read pressure&lt;/li&gt;
  &lt;li&gt;unpredictable latency&lt;/li&gt;
  &lt;li&gt;risk to production systems&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So experimentation required isolated infrastructure for the entire data pipeline - very expensive and hard to set up and manage.&lt;/p&gt;

&lt;h2 id=&quot;the-shift-introduce-a-stream&quot;&gt;The Shift: Introduce a Stream&lt;/h2&gt;

&lt;p&gt;The solution was to decouple ingestion from consumption using a stream. After assignment, events are written to a Kinesis stream:&lt;/p&gt;

&lt;pre&gt;&lt;code class=&quot;language-mermaid&quot;&gt;flowchart TD
  ES[Event Stream]
  IA[Ingestion + Assignment]
  KS[(&quot;Kinesis Stream&quot;)]
  Prod[Prod]
  ExpA[Experiment A]
  ExpB[Experiment B]
  ES --&amp;gt; IA
  IA --&amp;gt; KS
  KS --&amp;gt; Prod
  KS --&amp;gt; ExpA
  KS --&amp;gt; ExpB
&lt;/code&gt;&lt;/pre&gt;

&lt;h2 id=&quot;why-kinesis-works-better-here&quot;&gt;Why Kinesis Works Better Here&lt;/h2&gt;

&lt;p&gt;With on the order of ~100 shards, throughput scales roughly linearly and parallelism stays predictable: No guessing how much headroom a single shared reader needs.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Enhanced Fan-Out (EFO)&lt;/strong&gt; gives each consumer its own dedicated throughput, so consumers do not contend with each other and production workloads stay isolated from experiments. The bigger structural win is decoupling: ingestion runs once, downstream consumers can evolve independently, and the architecture drops the shared read bottleneck that hamstrung the previous cache-centric design.&lt;/p&gt;

&lt;h3 id=&quot;cost-comparison&quot;&gt;Cost Comparison&lt;/h3&gt;

&lt;h4 id=&quot;cache-redis--valkey&quot;&gt;Cache (Redis / Valkey)&lt;/h4&gt;

&lt;ul&gt;
  &lt;li&gt;~$13,500/month&lt;/li&gt;
  &lt;li&gt;scales with memory + read load&lt;/li&gt;
  &lt;li&gt;provisioned for peak&lt;/li&gt;
&lt;/ul&gt;

&lt;h4 id=&quot;kinesis&quot;&gt;Kinesis&lt;/h4&gt;

&lt;ul&gt;
  &lt;li&gt;~$1,500/month base (100 shards)&lt;/li&gt;
  &lt;li&gt;~$500–1,000 per consumer&lt;/li&gt;
  &lt;li&gt;~$3k per EFO consumer&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Even with multiple consumers, total costs remain significantly lower than scaling the cache or duplicating ingestion pipelines.&lt;/p&gt;

&lt;h4 id=&quot;tradeoffs&quot;&gt;Tradeoffs&lt;/h4&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Dimension&lt;/th&gt;
      &lt;th&gt;Cache (Redis)&lt;/th&gt;
      &lt;th&gt;Stream (Kinesis)&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;Read efficiency&lt;/td&gt;
      &lt;td&gt;Poor (scan-heavy)&lt;/td&gt;
      &lt;td&gt;High (push-based)&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Multi-consumer&lt;/td&gt;
      &lt;td&gt;No bueno&lt;/td&gt;
      &lt;td&gt;Excellent&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Cost scaling&lt;/td&gt;
      &lt;td&gt;High&lt;/td&gt;
      &lt;td&gt;Moderate&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;Latency&lt;/td&gt;
      &lt;td&gt;Very low&lt;/td&gt;
      &lt;td&gt;Slightly higher&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;The stream is not a strict upgrade on every axis: you give up a little of the sub-millisecond read profile you get from a hot cache, and you take on streaming operations (shards, consumers, EFO) as a first-class part of the bill. Here that was an explicit trade I can make. That is, aggregation is periodic and bounded by read amplification and multi-consumer safety well before raw cache latency would be an issue.&lt;/p&gt;

&lt;h2 id=&quot;conclusion&quot;&gt;Conclusion&lt;/h2&gt;

&lt;p&gt;The shared cache served its purpose and even handled the high volume scale of a single consumer well enough for long enough to get us here. But, with the following contraints:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;high read amplification&lt;/li&gt;
  &lt;li&gt;stateless consumers&lt;/li&gt;
  &lt;li&gt;multiple downstream use cases&lt;/li&gt;
  &lt;li&gt;need for experimental stacks to have safe read access&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That design had run its course and become a bottleneck not just in performance, but in our ability to develop and evolve our overall system into the future. Moving to a streaming model shifts the system from being pull-based, tightly coupled, and read-heavy to more push-based and decoupled enabling the multi-consumer paradigm we want. So we don’t solve for just performance, but also gain key aspects of flexibility:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;new consumers without recomputation&lt;/li&gt;
  &lt;li&gt;isolation between production and experiments&lt;/li&gt;
  &lt;li&gt;(more) predictable scaling costs&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;When multiple consumers need the same high-volume data, a stream is often a better abstraction than a shared cache; especially when recomputing that data is expensive.&lt;/p&gt;
</description>
        <pubDate>Tue, 07 Apr 2026 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2026/04/07/scaling-cache-to-kinesis-stream-multi-tenant/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2026/04/07/scaling-cache-to-kinesis-stream-multi-tenant/</guid>
      </item>
    
      <item>
        <title>Dynamically Rebalancing Geo-Constrained Stream Processing</title>
        <description>&lt;h1 id=&quot;context&quot;&gt;Context&lt;/h1&gt;

&lt;p&gt;One of the more common failure modes in real-time geospatial systems has nothing to do with algorithms being &lt;em&gt;wrong&lt;/em&gt;. It’s that the real world refuses to stay still.&lt;/p&gt;

&lt;p&gt;This post walks through a practical pattern for handling high-volume, real-time location data where part of your pipeline is &lt;em&gt;explicitly geo-constrained&lt;/em&gt; (map matching, spatial joins, routing lookups, etc.), while the rest of the system is not. We’ll look at why static geographic partitioning breaks down, and how to use real-time monitoring plus fast redeploys to continuously rebalance work instead of over-allocating forever.&lt;/p&gt;

&lt;p&gt;The canonical pipeline shape&lt;/p&gt;

&lt;p&gt;Most real-time geo pipelines look roughly like this:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;┌─────────────────┐         ┌──────────────────────┐         ┌─────────────────┐
│   Aspatial      │         │  Geo-Constrained     │         │   Downstream    │
│  Data Stream    │────────&amp;gt;│    Transformer       │────────&amp;gt;│    Consumers    │
│ (ex: Kinesis)   │         │                      │         │                 │
└─────────────────┘         └──────────────────────┘         └─────────────────┘
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;You ingest a jumbled, global stream of location events.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;You pass it through a geo-constrained transformer (map matching is a common example).&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;After enrichment, the data fans out to downstream consumers that generally don’t care about geography anymore.&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The critical detail is that &lt;em&gt;only one section of the pipeline&lt;/em&gt; has strict geographic constraints. That section is where everything gets interesting — and unstable.&lt;/p&gt;

&lt;h2 id=&quot;why-geo-partitioning-is-inherently-unstable&quot;&gt;Why geo-partitioning is inherently unstable&lt;/h2&gt;

&lt;p&gt;The issue isn’t poor engineering; it’s that real-world spatial data is non-stationary.&lt;/p&gt;

&lt;p&gt;Volume changes come from:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Day/night cycles&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Commute peaks&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Weather&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Local events&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Virality and feedback loops&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/realtime-geo-partition/utilization_many_partitions_avg.png&quot; alt=&quot;utilization_many_partitions_avg&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Above image is a generic example showing how even with the best partitioning strategy, various partitions are subject to time-of-day resource demand fluctuations.&lt;/p&gt;

&lt;p&gt;Even if &lt;em&gt;global&lt;/em&gt; throughput is stable, regional load never is. One city lights up while another goes quiet. Then they swap.&lt;/p&gt;

&lt;p&gt;A common mitigation is “smart” partitioning:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Pair cities on opposite sides of the globe&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Mix antipodal time zones (Johannesburg + Honolulu, etc.)&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Try to smooth diurnal cycles statistically&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This helps — but it never solves the problem. You still end up with:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Hot partitions you must size for worst-case load&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Cold partitions wasting compute most of the day&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;A few megacities that remain pathological outliers no matter how clever your scheme is&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;At scale, this means systematic over-allocation.&lt;/p&gt;

&lt;h2 id=&quot;real-goal-rebalance-dont-predict&quot;&gt;Real goal: rebalance, don’t predict&lt;/h2&gt;

&lt;p&gt;Instead of trying to design the perfect static partitioning algorithm, the goal shifts: Continuously rebalance the geo-constrained service based on observed load.&lt;/p&gt;

&lt;p&gt;That means:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Monitoring real-time spatial volume&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Recomputing partitions from &lt;em&gt;current&lt;/em&gt; conditions&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Redeploying the geo-service frequently enough to track reality&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This post assumes a few important properties:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Fast startup: New partition workers can come online in seconds to minutes.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Blue-green deploys: You can stand up a new geo-partitioned service in parallel and flip traffic.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;No instantaneous spikes: Because this is real-world geo data, even “viral” events ramp over minutes (at least, if not longer), and definitely not less (not milliseconds).&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Under those assumptions, dynamic rebalancing becomes not only possible, but practical.&lt;/p&gt;

&lt;h2 id=&quot;a-miniaturized-example&quot;&gt;A miniaturized example&lt;/h2&gt;

&lt;p&gt;To make this concrete, we’ll shrink the problem down to a single metro area instead of the globe. We define:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Two system states: before and after&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;The “after” state has:&lt;/p&gt;

    &lt;ul&gt;
      &lt;li&gt;~2× the total points - and thus higher overall activity&lt;/li&gt;
      &lt;li&gt;More hotspots of dense activity vs. the prior state&lt;/li&gt;
    &lt;/ul&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each partition is capped at 2,500 points. The goal is to build &lt;em&gt;contiguous&lt;/em&gt; geographic partitions that get as close to that limit as possible.&lt;/p&gt;

&lt;h2 id=&quot;state-1-before&quot;&gt;State 1: before&lt;/h2&gt;

&lt;p&gt;Here’s a representative partitioning outcome:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Total partitions: 12
Max points per partition: 2500

Partition   0:   2272 points (90.9%)
Partition   1:   2265 points (90.6%)
Partition   2:   2257 points (90.3%)
Partition   3:   2254 points (90.2%)
Partition   4:    396 points (15.8%)
Partition   5:    371 points (14.8%)
Partition   6–11: &amp;lt; 200 points each
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;A few things jump out: First; hot areas pack efficiently. Secondly, cold regions fragment into many tiny partitions that are not contiguous. These tail partitions can safely be merged later. So far, so good.&lt;/p&gt;

&lt;h2 id=&quot;state-2-naive-preservation-breaks-down&quot;&gt;State 2: naive preservation breaks down&lt;/h2&gt;

&lt;p&gt;Now activity doubles and new hotspots appear. If we &lt;em&gt;try to preserve existing partitions&lt;/em&gt; and only split the ones that overflow, we get something like this:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Partition   0: 3243 points (129.7%)
Partition   2: 3689 points (147.6%)
...
Total partitions: 21
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/realtime-geo-partition/partition_transition_first.png&quot; alt=&quot;partition_transition_first&quot; /&gt;&lt;/p&gt;

&lt;p&gt;We’ve avoided redoing everything, but introduced a new problem:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Weird “edge” partitions appear&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Shapes shrink inward awkwardly&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Utilization becomes noisy and uneven&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;These liminal partitions are artifacts of trying to respect history that no longer matters.&lt;/p&gt;

&lt;h2 id=&quot;resolution-rebuild-from-scratch&quot;&gt;Resolution: rebuild from scratch&lt;/h2&gt;

&lt;p&gt;If your deploys are fast, there’s no reason to preserve old partitions at all. Instead:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Ignore the previous state&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Repack all quadkeys based on current load&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Blue-green swap the new configuration in&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/realtime-geo-partition/partition_transition_second.png&quot; alt=&quot;partition_transition_second&quot; /&gt;&lt;/p&gt;

&lt;p&gt;The result is cleaner, fewer partitions, and higher average utilization:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Total partitions: 13
Mean utilization: 61.5%
Median utilization: 90.1%
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Cold tail partitions still exist, but they’re smaller in number, they’re easy to group together, they don’t pollute the hot path. This turns partitioning into a stateless optimization problem, not a migration problem.&lt;/p&gt;

&lt;h2 id=&quot;why-this-matters-allocation-mismatch&quot;&gt;Why this matters: allocation mismatch&lt;/h2&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/realtime-geo-partition/allocation_bar_charts.png&quot; alt=&quot;allocation_bar_charts&quot; /&gt;&lt;/p&gt;

&lt;p&gt;To see the cost of &lt;em&gt;not&lt;/em&gt; rebalancing, apply State-2 data to State-1 partitions:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Partition 2: 2257 → 6602 points (264% utilized)
Partition 0: 2272 → 4510 points (180% utilized)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/realtime-geo-partition/allocation_mismatch.png&quot; alt=&quot;allocation_mismatch&quot; /&gt;&lt;/p&gt;

&lt;p&gt;You’d need to provision 2–3x the resources just to survive peak load in a single partition — and every other partition would sit idle most of the time. Dynamic rebalancing converts that worst-case sizing problem into a steady-state one.&lt;/p&gt;

&lt;h2 id=&quot;system-architecture&quot;&gt;System architecture&lt;/h2&gt;

&lt;p&gt;At a high level, the control plane for this looks like:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Kinesis Stream

   → Managed Flink (Kinesis Data Analytics / EKS)
       - Job Manager
       - Task Managers
       - State backend (S3)
       - Checkpoints (S3)

   → DynamoDB / S3
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Managed Flink on AWS makes this pattern pretty easy to implement. You get a continuously running, stateful streaming job without having to own the cluster lifecycle, and can still retain enough control to make dynamic reconfiguration viable.&lt;/p&gt;

&lt;p&gt;Flink’s execution model lines up well with what is needed:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;It has native keyed aggregation: Counting by quadkey is a first-class operation (&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;keyBy → window / process&lt;/code&gt;)&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Continuous output: do not need to wait for batch windows to close. Emit rolling aggregates on a cadence (e.g. every 30–60 seconds) that’s fast enough to drive rebalancing.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Operational slack: The system tolerates a few minutes of lag between “things changed” and “partitions updated,” which matches real-world geo dynamics well.&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;On AWS specifically, this is easiest to run as Kinesis Data Analytics for Apache Flink (fully managed).&lt;/p&gt;

&lt;p&gt;This leads to a modified pipeline architecture from the canonical one shown originally:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;                   ┌────────────────────────┐
                   │   Managed Flink Job    │
                   │ (Kinesis → Flink)      │
                   │                        │
                   │  • lat/lon → quadkey   │
                   │  • counts by quadkey   │
                   │  • checkpointed state  │
                   └───────────┬────────────┘
                               │
                               │ periodic snapshot
                               ▼
              ┌──────────────────────────────────┐
              │   Spatial Control / Partitioner  │
              │                                  │
              │  • reads quadkey counts          │
              │  • builds contiguous partitions  │
              │  • enforces max load per shard   │
              └────────────┬─────────────────────┘
                           │
            new partition  │ spec
                           ▼
              ┌──────────────────────────────────┐
              │   Geo Processing Service (NEW)   │
              │   Blue / Green Deployment        │
              │                                  │
              │  • one worker per partition      │
              │  • warmed up off to the side     │
              └───────────┬──────────────────────┘
                          │
                   traffic swap
                          ▼
              ┌──────────────────────────────────┐
              │        Downstream Consumers      │
              │  (post-geo, no spatial aspect)   │
              └──────────────────────────────────┘

&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h4 id=&quot;triggering-new-geo-service-versions&quot;&gt;Triggering new geo-service versions&lt;/h4&gt;

&lt;p&gt;Can achieve this in multiple ways:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;CI/CD pipelines (GitHub Actions / CodePipeline) that kick off deployment once new partition specs land in S3/DynamoDB&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Kubernetes operators that watch a config map or annotation and perform a blue-green swap&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;AWS ECS / EKS webhook triggers from your partitioner process&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;example-quadkey-aggregation-job&quot;&gt;Example: quadkey aggregation job&lt;/h3&gt;

&lt;p&gt;At a conceptual level, the Flink job does something very simple:&lt;/p&gt;

&lt;ol&gt;
  &lt;li&gt;
    &lt;p&gt;Read events from Kinesis&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Derive a quadkey for each point&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Maintain a running count per quadkey&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Periodically flush those counts to an external store&lt;/p&gt;
  &lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Pseudocode-wise, this looks like:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;stream&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;map&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;event&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&amp;gt;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;quadkey&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;lat&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;event&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;lon&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;),&lt;/span&gt; &lt;span class=&quot;il&quot;&gt;1L&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;keyBy&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;_1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;process&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;QuadkeyCountProcessFn&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;addSink&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;countSink&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Where &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;QuadkeyCountProcessFn&lt;/code&gt;:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Keeps per-quadkey counters in keyed state&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Emits updated counts on a timer (e.g. every 60s)&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h2 id=&quot;partition-construction&quot;&gt;Partition construction&lt;/h2&gt;

&lt;h3 id=&quot;1-start-from-the-hottest-locations&quot;&gt;1. Start from the hottest locations&lt;/h3&gt;

&lt;p&gt;We always seed new partitions from peak quadkeys first:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;sorted_qks = sorted(qk_counts.items(), key=lambda x: -x[1])
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;This ensures:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Dense areas get first claim on capacity&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Hotspots don’t get fragmented across partitions&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;h3 id=&quot;2-grow-partitions-by-adjacency&quot;&gt;2. Grow partitions by adjacency&lt;/h3&gt;

&lt;p&gt;Contiguity matters. We explicitly grow partitions using neighboring quadkeys:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;def&lt;/span&gt; &lt;span class=&quot;nf&quot;&gt;get_quadkey_neighbors&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;bp&quot;&gt;self&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;qk&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;-&amp;gt;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;Set&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;str&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;  
    &lt;span class=&quot;n&quot;&gt;tile&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;mercantile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;quadkey_to_tile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;qk&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;  
    &lt;span class=&quot;n&quot;&gt;neighbors&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;set&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;()&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dx&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;  
        &lt;span class=&quot;k&quot;&gt;for&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dy&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;in&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;1&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]:&lt;/span&gt;  
            &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dx&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt; &lt;span class=&quot;ow&quot;&gt;and&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dy&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;==&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;0&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;  
                &lt;span class=&quot;k&quot;&gt;continue&lt;/span&gt;  
            &lt;span class=&quot;n&quot;&gt;neighbor_tile&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;mercantile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Tile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;tile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;x&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dx&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;y&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;+&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;dy&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;tile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;z&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;  
            &lt;span class=&quot;n&quot;&gt;neighbors&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;add&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;mercantile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;quadkey&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;neighbor_tile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;))&lt;/span&gt;

    &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;neighbors&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;This guarantees partitions are spatially contiguous, necessary for map matching (you would use this area plus a buffer to end up with a contiguous region to safely ensure all edges needed to match to the points are present).&lt;/p&gt;

&lt;h3 id=&quot;3-prefer-square-ish-growth&quot;&gt;3. Prefer “square-ish” growth&lt;/h3&gt;

&lt;p&gt;When expanding a partition, neighbors are ranked by how many edges they share with the current component:&lt;/p&gt;

&lt;div class=&quot;language-python highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;adjacency_score&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nb&quot;&gt;len&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;neighbor_neighbors&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;&amp;amp;&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;component&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;We then sort by adjacency (favor compact shapes) and point count (fill efficiently). This produces partitions that are both well-packed and geometrically sane.&lt;/p&gt;

&lt;h2 id=&quot;why-this-works-in-practice&quot;&gt;Why this works in practice&lt;/h2&gt;

&lt;p&gt;This works because it matches how the system behaves in reality. Instead of predicting a stable future, it responds to current conditions, sizes capacity to what’s actually happening, and keeps geographic complexity confined to a single stage. The cost is a bit of redeploy churn, but the payoff is far less wasted compute.&lt;/p&gt;

&lt;p&gt;Most importantly, it accepts that geo load balancing is not a one-time design problem. It’s a continuous control problem.&lt;/p&gt;

</description>
        <pubDate>Thu, 01 Jan 2026 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2026/01/01/geo-partition-realtime/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2026/01/01/geo-partition-realtime/</guid>
      </item>
    
      <item>
        <title>Triaging Heuristics for Erronous Matches</title>
        <description>&lt;h2 id=&quot;handling-noisy-probes-and-unrealistic-paths&quot;&gt;&lt;strong&gt;Handling Noisy Probes and Unrealistic Paths&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;This is a follow up to my last post; discussing issues I saw when map matching and some notes on improving against those problems. One issue that became increasingly obvious after running the matcher against real probe data is how &lt;em&gt;noisy probes&lt;/em&gt; interact with dense road networks.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/map-match-spur-improvements/diagram-of-errors.png&quot; alt=&quot;diagram_of_errors&quot; /&gt;&lt;/p&gt;

&lt;p&gt;In urban environments especially (as shown in above example), a single probe can be spatially close to multiple candidate ways: a main road, a frontage road, a service alley, or even a perpendicular side street. When the scoring model is too permissive, the matcher will occasionally “snap” to one of these intersecting roads even though the vehicle never really traveled down it.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/map-match-spur-improvements/example-raw-trace-data.png&quot; alt=&quot;raw_trace_data&quot; /&gt;&lt;/p&gt;

&lt;h2 id=&quot;context-from-naive-viterbi-to-practical-heuristics&quot;&gt;&lt;strong&gt;Context: From Naive Viterbi to Practical Heuristics&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;None of the strategies described below are novel. In fact, they’re fairly standard ideas in map matching and routing systems more broadly.&lt;/p&gt;

&lt;p&gt;In my previous post, &lt;a href=&quot;https://kuanbutts.com/2025/12/25/lightweight-go-router/&quot;&gt;Lightweight HMM Map Matching in Go&lt;/a&gt;, I intentionally started from a very naive place: a straightforward Viterbi implementation over candidate road segments, with minimal transition logic and few guardrails. That was useful as a baseline, but it also made the failure modes extremely obvious once real probe data entered the picture.&lt;/p&gt;

&lt;p&gt;This follow-up is really about identifying the &lt;em&gt;minimum set of logical checks&lt;/em&gt; needed to make the matcher behave plausibly, without turning it into a heavy, compute-intensive routing engine. The goal isn’t to perfectly model driver behavior or handle every edge case — it’s to avoid the most common and most egregious matching errors while preserving simplicity, performance, and operational clarity.&lt;/p&gt;

&lt;p&gt;Everything that follows can be thought of as adding just enough structure around the HMM to constrain it to realistic paths, rather than letting it “mathematically” solve the problem in ways that no real vehicle ever would.&lt;/p&gt;

&lt;h3 id=&quot;the-problem-intersections--noise--bad-matches&quot;&gt;&lt;strong&gt;The Problem: Intersections + Noise = Bad Matches&lt;/strong&gt;&lt;/h3&gt;

&lt;p&gt;When this happens, the downstream effect is worse than just a single bad segment. The HMM will often try to recover by immediately transitioning back to the original road. The resulting matched path looks something like:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;main road&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;sudden turn onto a side street, go down to next intersection&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;immediate u-turn (no matter how unrealistic)&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;back onto the main road (could have just proceeded straight)&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;From a routing perspective, this is clearly unrealistic. From a scoring perspective, however, the original model didn’t strongly discourage this behavior. Short segments, small distances, and weak penalties made these transitions look acceptable.&lt;/p&gt;

&lt;p&gt;Over longer traces, these errors compound into paths that zig-zag through intersections in ways no real vehicle would.&lt;/p&gt;

&lt;h2 id=&quot;first-fix-penalize-u-turns&quot;&gt;&lt;strong&gt;First Fix: Penalize U-Turns&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;The most obvious initial fix was to explicitly penalize u-turns.&lt;/p&gt;

&lt;p&gt;If a transition implies a near-180° change in heading between consecutive matched ways, that transition should be costly. In real driving, u-turns are rare, deliberate, and usually constrained to specific locations. They should not be the default recovery mechanism for noisy probes.&lt;/p&gt;

&lt;p&gt;Adding a u-turn penalty immediately reduced the most egregious back-and-forth behavior.&lt;/p&gt;

&lt;p&gt;But once that was in place, a broader issue became clear.&lt;/p&gt;

&lt;h2 id=&quot;generalizing-the-idea-penalize-turns-not-just-u-turns&quot;&gt;&lt;strong&gt;Generalizing the Idea: Penalize Turns, Not Just U-Turns&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;U-turns are just the extreme case. In practice, many bad matches involve sharp turns that aren’t full reversals but are still implausible given the trace.&lt;/p&gt;

&lt;p&gt;This led to a more general approach: &lt;strong&gt;add a turn cost based on heading change&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Instead of a binary “u-turn or not” check, transitions are penalized proportionally to how sharp the turn is. Small heading changes are cheap. Large heading changes get increasingly expensive.&lt;/p&gt;

&lt;p&gt;This makes the matcher prefer smooth, continuous motion unless the probes strongly indicate otherwise.&lt;/p&gt;

&lt;h2 id=&quot;road-class-matters&quot;&gt;&lt;strong&gt;Road Class Matters&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;Even with turn penalties, another pattern showed up repeatedly: many of the accidental detours were happening on &lt;em&gt;low-class roads&lt;/em&gt;.&lt;/p&gt;

&lt;p&gt;Alleys, service roads, and tiny access lanes are often geometrically close to major roads. A single noisy probe can easily fall closer to an alley than to the primary road the vehicle is actually on.&lt;/p&gt;

&lt;p&gt;What made these cases especially bad was the sequence:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;primary road → alley&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;short travel&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;u-turn&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;back to primary road&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;From a modeling standpoint, this should be extremely unlikely.&lt;/p&gt;

&lt;p&gt;To address this, transition costs now also consider &lt;strong&gt;road class&lt;/strong&gt;. Transitions from higher-class roads (e.g. primary or secondary roads) to much lower-class roads (e.g. alleys or service roads) are penalized heavily, especially when followed by sharp turns or u-turns.&lt;/p&gt;

&lt;p&gt;This reflects real behavior: drivers don’t casually dip into alleys and immediately reverse course unless they are intentionally accessing something there.&lt;/p&gt;

&lt;h2 id=&quot;distance-and-probe-coverage&quot;&gt;&lt;strong&gt;Distance and Probe Coverage&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;Another important signal is &lt;em&gt;how much evidence&lt;/em&gt; there is that a candidate way was actually traveled.&lt;/p&gt;

&lt;p&gt;If a candidate road is only supported by a single probe, especially when neighboring probes align well with another road, the matcher should be skeptical. A single noisy observation should not be enough to justify a detour.&lt;/p&gt;

&lt;p&gt;To capture this, transition scoring now incorporates:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;&lt;strong&gt;Distance traveled on the candidate way&lt;/strong&gt;&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;&lt;strong&gt;Probe coverage&lt;/strong&gt;: how well the trace aligns with the geometry over multiple points&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Short, weakly supported segments get penalized relative to longer, well covered ones. This makes it much harder for the matcher to justify hopping onto a side road for just one probe.&lt;/p&gt;

&lt;h2 id=&quot;cleanup-pass-fixing-what-still-slips-through&quot;&gt;&lt;strong&gt;Cleanup Pass: Fixing What Still Slips Through&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;Even with improved scoring, some unrealistic paths can still sneak through—especially in dense downtown grids or highly noisy traces.&lt;/p&gt;

&lt;p&gt;To address this, I added a lightweight cleanup step that runs after the main matching pass. This step walks back through the matched result and looks for obvious anomalies:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;extremely short detours&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;rapid back-and-forth transitions&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;isolated low-class road segments sandwiched between higher class roads&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;When detected, these segments can be collapsed or replaced with more plausible alternatives from the surrounding context.&lt;/p&gt;

&lt;p&gt;This cleanup isn’t meant to “fix everything,” but it acts as a final sanity check to smooth out pathological cases that the probabilistic model occasionally produces.&lt;/p&gt;

&lt;h2 id=&quot;performance-impact-of-the-added-heuristics&quot;&gt;&lt;strong&gt;Performance Impact of the Added Heuristics&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;After adding these heuristics, I re-ran the exact same benchmark harness used in the previous post to sanity-check whether match quality improvements came with a performance cost.&lt;/p&gt;

&lt;h3 id=&quot;updated-results&quot;&gt;Updated Results&lt;/h3&gt;

&lt;div class=&quot;language-yaml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;na&quot;&gt;Total routes&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;   &lt;span class=&quot;m&quot;&gt;10000&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Successful&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;10000 (100%)&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Total time&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;19.82s&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Throughput&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;~504.6 routes/sec&lt;/span&gt;

&lt;span class=&quot;na&quot;&gt;Median latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;~136ms&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;P95 latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;s&quot;&gt;~321ms&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;P99 latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;s&quot;&gt;~392ms&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Compare this to the old results from the last blog post:&lt;/p&gt;

&lt;div class=&quot;language-yaml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;na&quot;&gt;Total routes&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;   &lt;span class=&quot;m&quot;&gt;10000&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Successful&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;10000 (100%)&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Total time&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;34.29s&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Throughput&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;~291.6 routes/sec&lt;/span&gt;

&lt;span class=&quot;na&quot;&gt;Median latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;~294ms&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;P95 latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;s&quot;&gt;~913ms&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;P99 latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;s&quot;&gt;~980ms&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h3 id=&quot;observations&quot;&gt;Observations&lt;/h3&gt;

&lt;p&gt;At face value, the updated matcher is noticeably faster and has significantly better tail latencies. That said, I want to be careful not to over-interpret this result.&lt;/p&gt;

&lt;p&gt;These changes were primarily about constraining the state space — discouraging implausible transitions early rather than allowing them and “fixing” them later. It’s entirely possible that the improved performance is partially due to the Viterbi pass having fewer viable transitions to consider, rather than any intentional optimization.&lt;/p&gt;

&lt;p&gt;It’s also possible some of this improvement is simply noise or an artifact of how the benchmark exercises the matcher. Either way, the important takeaway is not that the matcher got faster, but that it did not get meaningfully slower.&lt;/p&gt;

&lt;p&gt;Given that these heuristics are lightweight (simple arithmetic, heading comparisons, and metadata checks), they appear to improve match quality without introducing noticeable computational overhead. For the intended use case — high-volume, short traces — that’s exactly the tradeoff I was hoping for.&lt;/p&gt;

&lt;h2 id=&quot;final-thoughts&quot;&gt;&lt;strong&gt;Final thoughts&lt;/strong&gt;&lt;/h2&gt;

&lt;p&gt;None of these changes are particularly complex on their own. The improvement comes from stacking multiple weak signals:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;turn cost&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;u-turn penalties&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;road class awareness&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;distance and coverage weighting&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;post-processing cleanup&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;All these need to work together to produce reliable results. These are all heuristics in the end - need to also understand the quality of the input data. Helps to know what the input data looks like - if it fits a common pattern, then we are better suited to optimize for that versus a more general purpose use case.&lt;/p&gt;

</description>
        <pubDate>Fri, 26 Dec 2025 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2025/12/26/lightweight-go-router-match-error-heuristics/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2025/12/26/lightweight-go-router-match-error-heuristics/</guid>
      </item>
    
      <item>
        <title>Lightweight HMM Map Matching in Go</title>
        <description>&lt;h1 id=&quot;introduction&quot;&gt;Introduction&lt;/h1&gt;

&lt;p&gt;Over the past few weeks I’ve been digging into a small, self-contained map matcher written in Go. The goal was simple: explore whether it’s possible to build a lightweight Hidden Markov Model (HMM) map matching service that doesn’t rely on external routing engines, yet still handles high concurrency and good throughput for short GPS traces.&lt;/p&gt;

&lt;p&gt;The use case I had in mind is one where a service might need to process many &lt;strong&gt;short GPS traces&lt;/strong&gt; (think under 5 minutes and only a few miles), at &lt;strong&gt;high volume&lt;/strong&gt; (think on the order of hundreds of thousands per hour) and do so with minimal infrastructure fuss.&lt;/p&gt;

&lt;p&gt;The prototype lives here: https://github.com/kuanb/gorouter&lt;/p&gt;

&lt;h2 id=&quot;what-the-router-does&quot;&gt;What the Router Does&lt;/h2&gt;

&lt;p&gt;You start the router like this:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;go run ./cmd/router &lt;span class=&quot;nt&quot;&gt;-pbf&lt;/span&gt; district-of-columbia-251222.osm.pbf
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;On launch it parses the specified OSM PBF, builds an in-memory road graph, indexes road segments with an R-tree, and exposes a simple HTTP endpoint for map matching.&lt;/p&gt;

&lt;p&gt;Each incoming trace is matched using a straightforward HMM approach:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;It finds nearby segment candidates using the spatial index.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;It scores emission likelihoods based on distance.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;It scores transitions using graph connectivity and simple heuristics.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;It runs a Viterbi pass over the sequence to find the most likely path.&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This isn’t a full routing engine (it doesn’t do traffic modeling or turn penalties, for example) but for short traces it gets the job done.&lt;/p&gt;

&lt;h1 id=&quot;go-and-concurrency-reasoning-for-language-selection&quot;&gt;Go and Concurrency: Reasoning for Language Selection&lt;/h1&gt;

&lt;p&gt;One of the reasons this project feels “Go-ish” is that concurrency comes almost for free with the standard library. The router uses Go’s built-in HTTP server, and each request is already handled in its own goroutine by default.&lt;/p&gt;

&lt;p&gt;Here’s the core HTTP handler:&lt;/p&gt;

&lt;div class=&quot;language-go highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;n&quot;&gt;http&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;HandleFunc&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;s&quot;&gt;&quot;/match&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;func&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;w&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;http&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;ResponseWriter&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;r&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;*&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;http&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Request&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;:=&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;matcher&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Match&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;r&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Context&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;trace&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
    &lt;span class=&quot;k&quot;&gt;if&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;!=&lt;/span&gt; &lt;span class=&quot;no&quot;&gt;nil&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
        &lt;span class=&quot;n&quot;&gt;http&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Error&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;w&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;err&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Error&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(),&lt;/span&gt; &lt;span class=&quot;n&quot;&gt;http&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;StatusBadRequest&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
        &lt;span class=&quot;k&quot;&gt;return&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;n&quot;&gt;json&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;NewEncoder&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;w&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;Encode&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;n&quot;&gt;result&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;})&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;There’s no worker pool or thread scheduler in user code: Go’s &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;net/http&lt;/code&gt; does the heavy lifting. The shared graph and spatial index are read-only after initialization, and per-request state is short-lived. That pattern maps well to workloads where requests are independent and bursts are expected.&lt;/p&gt;

&lt;h2 id=&quot;libraries-for-spatial-indexing-and-geospatial-work&quot;&gt;Libraries for Spatial Indexing and Geospatial Work&lt;/h2&gt;

&lt;p&gt;One area where I had more hesitation than usual was around geospatial libraries. My familiarity with Go’s geospatial ecosystem is at this time limited, going into this project.&lt;/p&gt;

&lt;p&gt;For spatial indexing, I used &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;github.com/tidwall/rtree&lt;/code&gt;&lt;/strong&gt;, which provides a simple in-memory R-tree implementation. That underpins the nearest-neighbor lookups used to find candidate road segments for each GPS point. I also used &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;github.com/tidwall/geoindex&lt;/code&gt;&lt;/strong&gt;, which wraps common spatial indexing patterns in a slightly higher-level API. Together, these handled the core spatial lookup needs without introducing much complexity.&lt;/p&gt;

&lt;p&gt;For geometry primitives and distance calculations, I relied on &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;github.com/paulmach/orb&lt;/code&gt;&lt;/strong&gt;. Orb provides clean representations for points and line strings and enough geometric operations to avoid reinventing basic math, while still being easy to reason about.&lt;/p&gt;

&lt;p&gt;For OpenStreetMap ingestion, I used &lt;strong&gt;&lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;github.com/qedus/osmpbf&lt;/code&gt;&lt;/strong&gt; to parse PBF files and stream OSM primitives into my own graph structures.&lt;/p&gt;

&lt;p&gt;Just thinking out loud: I was initially uneasy building this on top of libraries with only a few hundred stars. In ecosystems like Python, geospatial tooling tends to be backed by much larger and more established communities. Go’s geo ecosystem feels smaller and more fragmented, and there isn’t an obvious “standard” stack. It could also just be me being naive, though.&lt;/p&gt;

&lt;p&gt;That said, once I read through the source of the libraries I was considering, I felt comfortable moving forward. The code is small, readable, and fairly direct. There’s very little abstraction or magic, which made it easier to reason about correctness and performance.&lt;/p&gt;

&lt;p&gt;Tradeoffs I also wonder about: The ecosystem is clearly smaller, but it’s also a pragmatic and composable language. For this project, assembling a solution from a handful of focused building blocks ended up being a reasonable tradeoff.&lt;/p&gt;

&lt;h2 id=&quot;load-testing&quot;&gt;Load Testing&lt;/h2&gt;

&lt;p&gt;To get a sense of performance, I wrote a small Python harness that sends concurrent requests against a locally running router and measures throughput and latency.&lt;/p&gt;

&lt;p&gt;I ran it locally on a MacBook Pro (M2, 32 GB RAM) with a Washington, DC PBF. The test sent 10,000 total requests with about ~250 concurrent in-flight requests.&lt;/p&gt;

&lt;p&gt;Here are the results:&lt;/p&gt;

&lt;div class=&quot;language-yaml highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;na&quot;&gt;Total routes&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;   &lt;span class=&quot;m&quot;&gt;10000&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Successful&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;10000 (100%)&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Total time&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;34.29s&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;Throughput&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;     &lt;span class=&quot;s&quot;&gt;~291.6 routes/sec&lt;/span&gt;

&lt;span class=&quot;na&quot;&gt;Median latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s&quot;&gt;~294ms&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;P95 latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;s&quot;&gt;~913ms&lt;/span&gt;
&lt;span class=&quot;na&quot;&gt;P99 latency&lt;/span&gt;&lt;span class=&quot;pi&quot;&gt;:&lt;/span&gt;    &lt;span class=&quot;s&quot;&gt;~980ms&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;A few things jump out. Throughput stays close to ~300 requests per second, the median latency is under 300 ms even under load, and tail latencies sit below a second without any tuning. For a small, single-process prototype, that’s a solid baseline.&lt;/p&gt;

&lt;h2 id=&quot;batch-size-and-concurrency-observations&quot;&gt;Batch Size and Concurrency Observations&lt;/h2&gt;

&lt;p&gt;I also experimented with the effect of batch size on throughput and latency. Using the same 10,000-route test set, I compared three scenarios: high concurrency with 250 in-flight requests, moderate concurrency with batch size 100, and effectively no concurrency with batch size 1.&lt;/p&gt;

&lt;p&gt;Two interesting results stood out:&lt;/p&gt;

&lt;h3 id=&quot;batch-size-100&quot;&gt;Batch Size 100&lt;/h3&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Total routes: 10000
Successful: 10000 (100%)
Total time: 32.62s
Throughput: 306.6 routes/sec

Median latency: 102.8ms
P95 latency: 494.0ms
P99 latency: 537.1ms
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;With a moderate batch size, throughput improved slightly over the earlier 250-concurrency test. Median latency dropped to ~103ms, although tail latency (P95/P99) remained near half a second.&lt;/p&gt;

&lt;h3 id=&quot;batch-size-1-no-concurrency&quot;&gt;Batch Size 1 (No Concurrency)&lt;/h3&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Total routes: 10000
Successful: 10000 (100%)
Total time: 47.38s
Throughput: 211.05 routes/sec

Median latency: 3.0ms
P95 latency: 4.8ms
P99 latency: 6.0ms
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Processing requests sequentially drastically reduces per-request latency. Each individual match is extremely fast - single-digit milliseconds - but overall throughput suffers: the total run time increases because requests are not processed in parallel.&lt;/p&gt;

&lt;h3 id=&quot;implications&quot;&gt;Implications&lt;/h3&gt;

&lt;p&gt;For a high-volume service like the one this router is targeting, moderate concurrency (e.g., batch sizes of 100–250) hits a sweet spot: high aggregate throughput while keeping most latencies under 0.5s. The results also suggest that for very small traces, the core matching algorithm itself is extremely fast; the limiting factor for throughput is mostly concurrency management and resource contention rather than the algorithm. I would need to look into how to manage concurrency in Go – potentially limiting additional requests from being processed (so some queueing mechanism).&lt;/p&gt;

&lt;p&gt;I added a metrics health-checker to the benchmarking logic to hit a background metrics endpoint to track the following stats:&lt;/p&gt;

&lt;table&gt;
  &lt;thead&gt;
    &lt;tr&gt;
      &lt;th&gt;Metric&lt;/th&gt;
      &lt;th&gt;Description&lt;/th&gt;
    &lt;/tr&gt;
  &lt;/thead&gt;
  &lt;tbody&gt;
    &lt;tr&gt;
      &lt;td&gt;goroutines&lt;/td&gt;
      &lt;td&gt;Current number of goroutines&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;alloc_mb&lt;/td&gt;
      &lt;td&gt;Currently allocated heap memory&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;sys_mb&lt;/td&gt;
      &lt;td&gt;Total memory obtained from OS&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;heap_objects&lt;/td&gt;
      &lt;td&gt;Number of allocated heap objects&lt;/td&gt;
    &lt;/tr&gt;
    &lt;tr&gt;
      &lt;td&gt;num_gc&lt;/td&gt;
      &lt;td&gt;Number of completed GC cycles&lt;/td&gt;
    &lt;/tr&gt;
  &lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;Re-running our benchmarker with this new metrics health-checker and a “sweet-spot” concurrency of 200:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;python benchmark_mapmatch.py synthetic_routes.geojsonl  &lt;span class=&quot;nt&quot;&gt;--batch-size&lt;/span&gt; 200 &lt;span class=&quot;nt&quot;&gt;--metrics-output&lt;/span&gt; benchmark
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;With this, I was able to track a few internal metrics while running the benchmarks to get a sense of memory usage, goroutine count, and garbage collection behavior. Summary results were as follows:&lt;/p&gt;

&lt;div class=&quot;language-plaintext highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;Server Metrics Summary
Collection duration: 31.7s
Samples collected: 26

Memory (Allocated MB):
Min: 19.48 MB
Max: 299.10 MB
Mean: 41.99 MB

Goroutines:
Min: 103
Max: 115
Mean: 105.2
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/lightweight-go-router/goroutine-stats.png&quot; alt=&quot;resulting_system_stats&quot; /&gt;&lt;/p&gt;

&lt;p&gt;General observations from the results:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;Memory usage is modest. Even at peak, the router allocated ~300MB (upon the initial request, it immediately dropped down to the about the median). The average was around 42MB. This confirms that the in-memory graph and R-tree are lightweight.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Goroutine count stays predictable. Between 103–115 goroutines, the server handles concurrency without spawning excessive threads. Most of these goroutines might also be the HTTP server, worker routines, and GC activity.&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;Garbage collection is frequent but cheap. 204 GC cycles occurred during the ~32s benchmark, reflecting the allocation and deallocation of per-request state. The low impact on throughput and latency suggests that Go’s GC handles this workload efficiently.&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Overall, these internal metrics reinforce the earlier observations: the router is lightweight, scales with concurrency, and does not impose significant memory or GC overhead under realistic load.&lt;/p&gt;

&lt;h2 id=&quot;back-of-the-envelope-capacity&quot;&gt;Back-of-the-Envelope Capacity&lt;/h2&gt;

&lt;p&gt;At roughly 292 requests per second, a single instance translates to:&lt;/p&gt;

&lt;ul&gt;
  &lt;li&gt;
    &lt;p&gt;~17,500 requests per minute&lt;/p&gt;
  &lt;/li&gt;
  &lt;li&gt;
    &lt;p&gt;~1 million requests per hour&lt;/p&gt;
  &lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In practice, it’s safer to discount this a bit. Larger graphs, cloud overhead, and garbage collection will all eat into headroom. Even with a conservative estimate of ~10k requests per minute per instance, we can start to think about what it takes to reach very high throughput.&lt;/p&gt;

&lt;p&gt;If the target is 250k requests per minute, then:&lt;/p&gt;

&lt;div class=&quot;language-bash highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;250,000 / 10,000 ≈ 25 instances
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Add headroom for regional load variability, burstiness, and failure domains, and you’re likely in the ballpark of 30–40 routers. Note based on the above metrics these don’t need to be particularly beefy instance types.&lt;/p&gt;

&lt;p&gt;Importantly, you wouldn’t load the entire continental U.S. graph into a single process. You’d partition regionally, allocating more capacity to dense metros and fewer resources to sparser areas.&lt;/p&gt;

&lt;h2 id=&quot;why-this-matters&quot;&gt;Why This Matters&lt;/h2&gt;

&lt;p&gt;Just to recap why I am doing this versus using something like Valhalla or OSRM. Those tools are very mature and stable, but they’re also large, complex, and optimized for general routing tasks/very flexible.&lt;/p&gt;

&lt;p&gt;If your workload mostly consists of short, independent traces as my use case does, then you do not need full route planning, and you want minimal dependencies and simple scaling. So in this case, a small Go service can be a very practical alternative.&lt;/p&gt;

&lt;p&gt;Go’s standard library gives you concurrency, a production-ready HTTP server, and predictable performance characteristics out of the box. Combined with a focused HMM implementation and spatial indexing, that’s enough to solve this class of problems.&lt;/p&gt;

&lt;h2 id=&quot;whats-next&quot;&gt;What’s Next&lt;/h2&gt;

&lt;p&gt;There’s more work to do here to flesh this out: real regional sharding, smarter batching, memory profiling, benchmarking on larger PBFs, and exploring batch matching APIs. It’s also quickly apparently the matching model needs tweaks to more strongly penalize u-turns to prevent erroneous in/out patterns for side roads when performing a map match on a road network.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/lightweight-go-router/labelled-match-issues.png&quot; alt=&quot;two_lines&quot; /&gt;&lt;/p&gt;

&lt;p&gt;But even in its current form, this prototype suggests that a lightweight, Go-based map matcher can handle serious volume when scoped appropriately. Not the Github repo may be updated after this blog post is published if I find more time to tinker on this.&lt;/p&gt;
</description>
        <pubDate>Thu, 25 Dec 2025 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2025/12/25/lightweight-go-router/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2025/12/25/lightweight-go-router/</guid>
      </item>
    
      <item>
        <title>Full stack map control</title>
        <description>&lt;h1 id=&quot;introduction&quot;&gt;Introduction&lt;/h1&gt;

&lt;p&gt;I went to State of the Map US this past weekend in Richmond, VA and learned more about &lt;a href=&quot;https://protomaps.com/&quot;&gt;Protomaps&lt;/a&gt; which makes self-serving your own static map tiles dead simple. This is the area of the web mapping ecosystem I am furthest away from, so I often rely on 3rd party vendors (as do most), such as Mapbox or Maptiler. Protomaps makes it possible to control this component and generate tiles from a PBF I own/manipulated and serve it all from, for example, the same Github page that I might be hosting my simple site under.&lt;/p&gt;

&lt;p&gt;The Protomaps website contains sufficient document, I will just make some notes about gotchas that I hit when working on this to get up and running under my personal website &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;kuanbutts.com&lt;/code&gt;. The reference repository for this work is on Github &lt;a href=&quot;https://github.com/kuanb/pm-maps-oak&quot;&gt;here&lt;/a&gt;.&lt;/p&gt;

&lt;iframe src=&quot;https://kuanbutts.com/pm-maps-oak/&quot; height=&quot;500px&quot; width=&quot;100%&quot; title=&quot;Example Protomaps on a Github Page&quot;&gt;&lt;/iframe&gt;

&lt;h2 id=&quot;generate-pmtiles&quot;&gt;Generate PMTiles&lt;/h2&gt;

&lt;p&gt;Protomaps uses a vector tile format called &lt;a href=&quot;https://protomaps.com/docs/pmtiles&quot;&gt;PMTiles&lt;/a&gt;. It has nifty features that allows the API to use &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests&quot;&gt;HTTP range requests&lt;/a&gt; to query a single file containg the compressed basemap information.&lt;/p&gt;

&lt;p&gt;Simple PMTiles for a custom area can be generated with &lt;a href=&quot;https://app.protomaps.com/downloads/small_map&quot;&gt;this offered PMTiles service&lt;/a&gt; from Protomaps. Working with a Shapefile or some other custom data source? PM allows for export from Tippecanoe to PMTiles.&lt;/p&gt;

&lt;p&gt;For me, I downloaded a bounding box around Oakland from the simple PM service and the resulting file was about 15mb. PM will extend the map rendering functionality to support HTTP range requests thereby enabling a direct query from the map rendering engine to the single hosted PMTile.&lt;/p&gt;

&lt;p&gt;&lt;img src=&quot;https://raw.githubusercontent.com/kuanb/kuanb.github.io/master/images/_posts/protomaps-gh-pages/pmtilesviewer.png&quot; alt=&quot;pmtileviewer&quot; /&gt;&lt;/p&gt;

&lt;p&gt;Protomaps also provides a &lt;a href=&quot;https://protomaps.github.io/PMTiles/?url=https%3A%2F%2Fkuanbutts.com%2Fpm-maps-oak%2Foakland.pmtiles#map=11.48/37.798/-122.2457&quot;&gt;tile inspector&lt;/a&gt; that will load the exported PMTiles into a viewport that will help to expose the various layer and contents that have been packaged up. If further file size efficiency is desired; this is a great tool with which to additionally trim down the pacakged OSM data to just what is needed for a specific use case.&lt;/p&gt;

&lt;h2 id=&quot;hosting-locally-for-development&quot;&gt;Hosting locally for development&lt;/h2&gt;

&lt;p&gt;Once you have your PMTile file, you can start a simple SPA React app with the &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;create-react-app&lt;/code&gt; command. I then chose to place the file within the &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;public/&lt;/code&gt; directory so that published builds would roll up and deliver the file to Github published static sites. You can see the file there &lt;a href=&quot;https://github.com/kuanb/pm-maps-oak/blob/main/public&quot;&gt;here&lt;/a&gt;. This also prevents gotchas where the file is requested from the &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;main/&lt;/code&gt; branch but your personal site has a custom domain, which will cause a CORS cross-domain request headache.&lt;/p&gt;

&lt;p&gt;Once held in a steady location, use your desired method to serve the file over local host (for ex: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;python -m http.server&lt;/code&gt; or with JS: &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;http-server . -p 8020 --cors&lt;/code&gt;).&lt;/p&gt;

&lt;h2 id=&quot;rendering-the-map&quot;&gt;Rendering the map&lt;/h2&gt;

&lt;p&gt;Once a simple app has been created, a &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Map&lt;/code&gt; component can be introduced to the main &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;App.js&lt;/code&gt; &lt;a href=&quot;https://github.com/kuanb/pm-maps-oak/blob/main/src/App.js&quot;&gt;script&lt;/a&gt;. The entirety of the map-from-local-Github-pages-files concept will be encapsulated in that new &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;Map&lt;/code&gt; &lt;a href=&quot;https://github.com/kuanb/pm-maps-oak/blob/main/src/components/map.js&quot;&gt;component&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;First, a conditional for development vs. deploy needs to be set so that when published, we can read from appropriate endpoint:&lt;/p&gt;

&lt;div class=&quot;language-js highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;kd&quot;&gt;const&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;basePmUrl&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;process&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;env&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;NODE_ENV&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;===&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;development&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;?&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;http://127.0.0.1:8080/public&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;https://kuanbutts.com/pm-maps-oak&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;Next, we will create a new instance of a MapLibre map instance. However, before we do that, there is a configuration setting that needs to be set:&lt;/p&gt;

&lt;div class=&quot;language-js highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;Protocol&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;pmtiles&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;
&lt;span class=&quot;k&quot;&gt;import&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;layers&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;from&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;protomaps-themes-base&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;;&lt;/span&gt;

&lt;span class=&quot;kd&quot;&gt;let&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;protocol&lt;/span&gt; &lt;span class=&quot;o&quot;&gt;=&lt;/span&gt; &lt;span class=&quot;k&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;Protocol&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;();&lt;/span&gt;
&lt;span class=&quot;nx&quot;&gt;maplibregl&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;addProtocol&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;pmtiles&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&quot;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;protocol&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;tile&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;p&gt;This added protocol will allow Protomaps to query with the aforementioned range requests. Once set, all that is left to do is to create a new MapLibre map instance with the requisite style settings for Protomaps + MapLibre to use to query from the static file (instead of a traditional tiling service):&lt;/p&gt;

&lt;div class=&quot;language-js highlighter-rouge&quot;&gt;&lt;div class=&quot;highlight&quot;&gt;&lt;pre class=&quot;highlight&quot;&gt;&lt;code&gt;&lt;span class=&quot;k&quot;&gt;new&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;maplibregl&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nb&quot;&gt;Map&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;({&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;container&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;mapContainer&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;.&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;current&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;style&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;version&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;mi&quot;&gt;8&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;glyphs&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;sources&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
      &lt;span class=&quot;na&quot;&gt;protomaps&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;{&lt;/span&gt;
            &lt;span class=&quot;na&quot;&gt;type&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;vector&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;na&quot;&gt;url&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;s2&quot;&gt;`pmtiles://&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;${&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;basePmUrl&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;&lt;span class=&quot;s2&quot;&gt;/oakland.pmtiles`&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
            &lt;span class=&quot;na&quot;&gt;attribution&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;&amp;lt;a href=&quot;https://protomaps.com&quot;&amp;gt;Protomaps&amp;lt;/a&amp;gt; © &amp;lt;a href=&quot;https://openstreetmap.org&quot;&amp;gt;OpenStreetMap&amp;lt;/a&amp;gt;&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;
        &lt;span class=&quot;p&quot;&gt;}&lt;/span&gt;
    &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
    &lt;span class=&quot;na&quot;&gt;layers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;layers&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;(&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;protomaps&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;s1&quot;&gt;light&lt;/span&gt;&lt;span class=&quot;dl&quot;&gt;&apos;&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;)&lt;/span&gt;
  &lt;span class=&quot;p&quot;&gt;},&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;center&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;nx&quot;&gt;lng&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;lat&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;zoom&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;nx&quot;&gt;zoom&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt;
  &lt;span class=&quot;na&quot;&gt;maxBounds&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;:&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[[&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;122.36159&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;37.71505&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;],&lt;/span&gt; &lt;span class=&quot;p&quot;&gt;[&lt;/span&gt;&lt;span class=&quot;o&quot;&gt;-&lt;/span&gt;&lt;span class=&quot;mf&quot;&gt;122.12976&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;,&lt;/span&gt; &lt;span class=&quot;mf&quot;&gt;37.88092&lt;/span&gt;&lt;span class=&quot;p&quot;&gt;]]&lt;/span&gt;
&lt;span class=&quot;p&quot;&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/div&gt;

&lt;h2 id=&quot;conclusion&quot;&gt;Conclusion&lt;/h2&gt;

&lt;p&gt;That’s about it. The simple web site is up on Github &lt;a href=&quot;https://github.com/kuanb/pm-maps-oak/tree/main&quot;&gt;here&lt;/a&gt;. The webapp queries the PMTiles raw file, which is exposed via the &lt;code class=&quot;language-plaintext highlighter-rouge&quot;&gt;public/&lt;/code&gt; bucket in the final custom domain/path endpoint the same as the rest of the site JS, static files. With this pattern, I am able to publish a simple website without any external resource requirements outside what is delivered and available from the single site.&lt;/p&gt;
</description>
        <pubDate>Tue, 13 Jun 2023 00:00:00 +0000</pubDate>
        <link>http://kuanbutts.com/2023/06/13/protomaps-simple-gh-page-service/</link>
        <guid isPermaLink="true">http://kuanbutts.com/2023/06/13/protomaps-simple-gh-page-service/</guid>
      </item>
    
  </channel>
</rss>
