<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Jasper Blues on Medium]]></title>
        <description><![CDATA[Stories by Jasper Blues on Medium]]></description>
        <link>https://medium.com/@jasper.blues?source=rss-a2f1c9915fa------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*cfPdBHV6IY9ddmUR.jpg</url>
            <title>Stories by Jasper Blues on Medium</title>
            <link>https://medium.com/@jasper.blues?source=rss-a2f1c9915fa------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 20:20:51 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@jasper.blues/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[BYOK: Bring Your Own Key]]></title>
            <link>https://medium.com/embabel/byok-bring-your-own-key-656102da39e2?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/656102da39e2</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[embabel]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Wed, 15 Apr 2026 01:38:48 GMT</pubDate>
            <atom:updated>2026-04-15T01:38:48.684Z</atom:updated>
            <content:encoded><![CDATA[<h3>Or How Embabel Just Saved Your Startup $760M in Runway Costs</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*GrOjAg8hWnv2XqT8WX0y0A.png" /><figcaption>A pop star who looks suspiciously like Björk</figcaption></figure><h3>RAGE — Australia’s MTV</h3><p>I grew up in Wollongong, Australia from the mid 70s through 90s. It is a small city, wedged between the ocean and the mountains, about 100 KM south of Sydney.</p><p>Sometimes there wasn’t a lot to do. People made their own fun. To this day I love letting my mind wander and seeing where it takes me.</p><p>Saturday mornings in the hours before sunrise we had culture. It worked its way in between the black-and-white snow on the analog TV, via a TV show called RAGE — like Australia’s MTV. This early morning slot was the weird stuff. Metal. Industrial.</p><p>One morning I missed it. The (usually boring) charts had already started, counting down from 50 to number 1. But somewhere right at the back, something slipped through.</p><p>Björk.</p><p>Barefoot. Unfiltered. It felt like it had leaked in. I remember thinking: this is going to be huge.</p><p>A week later, it was number one.</p><p>Today we’re going to talk about an <a href="https://github.com/embabel/embabel-agent">Embabel</a> feature inspired by Björk: <strong>BYOK — Bring Your Own Key. </strong>It solves a real problem.</p><h3>The Problem</h3><p>For decades, the world’s production systems have quietly run on Java. That’s one reason Embabel exists: it brings AI to where the software already is, instead of forcing teams to rebuild everything just to get close to the models.</p><p>But Embabel isn’t just about revitalizing legacy systems.</p><blockquote>There are strong reasons to build new, AI-native apps on the JVM too.</blockquote><p>And that’s where BYOK comes in.</p><p>Let’s say you have a great idea. You execute well. You’re selling directly to consumers.</p><p>For most of the internet era, distribution was the cheat code. Build something people love and it spreads. People tell people.</p><h3>The Math Behind Virality</h3><p>The maths is deceptively simple: if each user brings in just 1.1 new users on average, you have viral growth:</p><pre>Round 1:   1 user<br>Round 10:  1.1¹⁰  ≈  2.6 users<br>Round 20:  1.1²⁰  ≈  6.7 users<br>Round 50:  1.1⁵⁰  ≈  117 users<br>Round 100: 1.1¹⁰⁰ ≈  13,780 users<br>Round 200: 1.1²⁰⁰ ≈  190,000,000 users</pre><p>One tenth of one extra person. That’s it. Just one in ten people convincing someone else to try it.</p><h3>Now introduce AI</h3><p>Suddenly, usage is billed in tokens.</p><p>Every new user isn’t just a potential customer — they’re a cost center.</p><blockquote>If you’re paying for their trial, customer acquisition is no longer cheap.</blockquote><p>And you still have the original problem too: how do you convince someone to try your product before they’ve seen it work?</p><p>People will invest a bit of time if the upside is there.<br>They’re far less willing to hand over a credit card.</p><p>Not before they trust you.<br>Often, not before they’ve cleared it with their spouse or boss.<br>And definitely not if cancelling might be painful.</p><blockquote>BYOK changes the equation. It separates <em>usage cost</em> from <em>product value</em>.</blockquote><p>If your customer already has an API key — from tinkering, from work, from other projects — they can use that to try your product. They pay for their own tokens. You pay almost nothing to acquire them.</p><p>If they don’t like it, they revoke the key. No refunds. No disputes. No awkward “what’s this charge?” conversations.</p><p>And when they do like it? That’s when you introduce the subscription.</p><h3>Let’s Put Some Rough Numbers On It</h3><p>Say your app is heavy — about $5/month in token usage per active user. You charge $10/month. Reasonable pricing.</p><p>By Round 200 you have 190 million users. (Yes, this is hypothetical — but the ratios are what matter.) Let’s say 10% convert:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xS5-F5ebA1gdxZShHYKFfw.png" /><figcaption>Customer Acquisition Costs</figcaption></figure><p>Without BYOK, you’re spending five dollars to acquire every dollar of revenue. Uh, yeah, not too sustainable.</p><blockquote>Usually getting to millions of active users is a “good problem to have”, but it definitely isn’t when you’ve dug yourself a $760M hole!</blockquote><p>You don’t want to be funding the trial usage of 190 million people.</p><p>With BYOK, you’re running at a 50% gross margin on paying customers — and your acquisition cost is effectively zero.</p><p>BYOK isn’t just a billing model.<br>It <em>is</em> the funnel.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*hsxaYAlz_jwrd811az5jNw.png" /><figcaption>A product funnel</figcaption></figure><p>Trial on their dime. Convert on yours.</p><p>And crucially, the viral loop survives because the cost of getting started is still effectively zero.</p><h3>How It Works</h3><p>In Embabel, LlmService is a key abstraction for working with LLMs.</p><p>You don’t talk to models directly. You talk through an LlmService, which handles model selection, retries, observation, and provider protocols.</p><p>Normally, you never think about this. Embabel ships Spring Boot starters for Anthropic, OpenAI, Mistral, DeepSeek and Gemini. Add one to your build, set your API key in environment variables, and an LlmService is auto-configured and ready to inject. It just works.</p><p>But there’s a catch: those starters are all wired to a single key — your key, set at deployment time. One application, one key per provider.</p><p>That’s fine when you’re absorbing the inference cost. It’s not fine when your users are bringing their own keys. You need an LlmService <em>per key</em> — validated, production-ready, and identical in behaviour to the auto-configured ones. That&#39;s exactly what BYOK provides.</p><p>At the core is a single interface:</p><pre>fun interface ByokFactory&lt;out T&gt; {<br>    fun buildValidated(): T<br>}</pre><p>For LLMs, T is LlmService&lt;*&gt; — but the type parameter is deliberate. The same race-and-validate pattern works for any future BYOK-validated service: image generation, embeddings, anything else where a user-supplied key needs a low-cost probe before you trust it. The plumbing doesn’t care what it is.</p><p>Each supported provider ships a factory:</p><pre>// Anthropic<br>val service = AnthropicModelFactory(apiKey = userKey).buildValidated()<br><br>// OpenAI<br>val service = OpenAiCompatibleModelFactory.openAi(userKey).buildValidated()<br>// DeepSeek, Mistral, Gemini - are all OpenAI compatible at API layer<br>val service = OpenAiCompatibleModelFactory.deepSeek(userKey).buildValidated()<br>val service = OpenAiCompatibleModelFactory.mistral(userKey).buildValidated()<br>val service = OpenAiCompatibleModelFactory.gemini(userKey).buildValidated()</pre><p>buildValidated() makes a single low-cost probe call to the provider. If the key is valid, you get back a production LlmService — the same thing the starters give you, but bound to the user&#39;s key instead of yours. If the key is invalid, you get an InvalidApiKeyException.</p><p>Plug the validated service straight into your prompt runner:</p><pre>promptRunner<br>    .withLlmService(service)<br>    .creating(MyOutput::class.java)<br>    .create(messages)</pre><p>The rest of your application doesn’t change.</p><h3>Auto-Detection</h3><p>People like quick starts — the user just pastes a key and doesn’t tell you which provider it’s from. For that, detectProvider() races all your candidates concurrently using virtual threads, and returns the first one that validates:</p><pre>try {<br>    val service = detectProvider(<br>        AnthropicModelFactory(apiKey = userKey),<br>        OpenAiCompatibleModelFactory.openAi(userKey),<br>        OpenAiCompatibleModelFactory.deepSeek(userKey),<br>        OpenAiCompatibleModelFactory.mistral(userKey),<br>        OpenAiCompatibleModelFactory.gemini(userKey),<br>    )<br>    val provider: String = service.provider<br>} catch (e: InvalidApiKeyException) {<br>    // invalid key<br>}</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*s9b6Cs0ibSxHXiIp5VTpFw.png" /><figcaption>“Quick Start” Automatic Key Type Detection</figcaption></figure><h3>Adding Your Own Provider</h3><p>If you’re running on an OpenAI-compatible provider that isn’t in the built-in list:</p><pre>fun OpenAiCompatibleModelFactory.Companion.acme(apiKey: String) =<br>    OpenAiCompatibleModelFactory.byok(<br>        baseUrl = &quot;https://api.acme.example.com/v1&quot;,<br>        apiKey = apiKey,<br>        validationModel = &quot;acme-small&quot;,<br>        validationProvider = &quot;Acme&quot;,<br>    )</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fpsCcN7uDSanuVvMJ1Fn3Q.png" /><figcaption>LLM Provider Settings Screen in Embabel Hub</figcaption></figure><h3>Security is Your Concern</h3><p>This is worth being explicit about. Embabel provides the validation and service construction. What you do with the key after that — how you store it, how you transmit it, how long you keep it — is your application’s responsibility.</p><p>The <a href="https://github.com/embabel/guide/">Guide</a> which is part of <a href="https://hub.docker.com/r/embabel/hub">Embabel Hub</a> shows one reasonable approach. The key principle: <strong>the server never persists the key</strong>.</p><p>After validation, the server encrypts the key with AES-256-GCM using a secret known only to the backend, and hands the encrypted blob back to the client. The client stores that blob on the user’s device. The plaintext key passes through server memory during the active session, but is <a href="https://github.com/embabel/guide/blob/main/src/main/kotlin/com/embabel/hub/integrations/KeyEncryptionService.kt">never persisted to disk or database</a>.</p><pre>// After validation, encrypt the key and send it back to the client<br>val encryptedBlob = keyEncryptionService.encrypt(apiKey)<br>return SetKeyResponse(encryptedKey = encryptedBlob)<br>// On reconnect, the client sends the blob; server decrypts it for the session<br>val restored = keyEncryptionService.decrypt(blob) ?: return ResponseEntity.status(410).build()</pre><p>Think about what this means from an attack surface perspective. There is no server-side key store to breach. An attacker would need to compromise individual user devices to get encrypted blobs — and those blobs are useless without the server’s secret.</p><p>If the server restarts with a new secret, existing client blobs become invalid. The user is simply prompted to re-enter their key. This limits the blast radius of a compromised server secret.</p><p>None of this is the only way to do it. The point is that BYOK doesn’t mandate a storage strategy — it just hands you a validated LlmService and gets out of the way.</p><p>And that’s the BYOK feature in a nutshell.</p><h3>Why This Matters</h3><p>The direction of AI is clear: more providers, more choice, more fragmentation.</p><p>Applications that lock users to a single provider, or absorb all inference costs will feel increasingly constrained.</p><p>The products that win will meet users where they are, with whatever key they already have. BYOK makes that straightforward.</p><p>One validated service. One clean exception. One detectProvider() call.</p><p>The rest of your application doesn’t change.</p><p>Björk went to number one in the 90s. Now <em>you</em> can go to number one with your Embabel-powered app</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=656102da39e2" width="1" height="1" alt=""><hr><p><a href="https://medium.com/embabel/byok-bring-your-own-key-656102da39e2">BYOK: Bring Your Own Key</a> was originally published in <a href="https://medium.com/embabel">Embabel</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Faction Detection: Reading the Review Graph Before the Fork]]></title>
            <link>https://medium.com/embabel/faction-detection-reading-the-review-graph-before-the-fork-75e100898160?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/75e100898160</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[embabel]]></category>
            <category><![CDATA[neo4j]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Tue, 31 Mar 2026 20:36:23 GMT</pubDate>
            <atom:updated>2026-03-31T20:36:23.252Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><em>Forks and crises in open source and enterprise projects rarely come out of nowhere. They just </em>look<em> that way.</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*2t_N1cxn06UF67yN9vTEzA.png" /><figcaption>A Zachary Karate Club-inspired logo</figcaption></figure><p>Today we’re building a tool that can predict IMMINENT forks in open source and large enterprise projects, using nothing but pull request comment data. Magic? Nuh-uh, science baby.</p><h3>We’ll Start in a Karate Dojo</h3><p>In 1977, a maths post-grad named Wayne Zachary had an unusual research subject: a karate club at a university in the American Midwest. He wasn’t studying martial arts. He was mapping relationships — who trained with whom, who socialized outside class, who deferred to whom. Standard social network stuff. Except that is, that nobody had really done this before. It was one of the first formal studies of community structure in a social network.</p><h3>A Faction Forms</h3><p>Over two years, the club’s instructor and its president fell into a slow-building dispute over lesson fees and club direction. Members didn’t pick sides publicly. They just… drifted. Training partners shifted. Maybe Maryellen stopped meeting Albert for coffee after practice and started meeting James for — well, let’s call it <em>strategic alignment</em>. Social ties rearranged in ways that were invisible unless you were drawing the map. By the time the club officially split in two, Zachary had already predicted — <em>from the network structure alone</em> — which members would end up on which side. He got 33 out of 34 right.</p><p>That paper launched an entire subfield. “<a href="https://en.wikipedia.org/wiki/Zachary%27s_karate_club">Zachary’s Karate Club</a>” became the standard benchmark dataset for community detection algorithms. It became so famous that researchers still use it as a benchmark nearly fifty years later — the go-to dataset when you need to test whether an algorithm can find hidden groups in a network. Think of it as the “Hello, World!” of mathematics-based social network science.</p><p>The insight is simple and a little unsettling: the structure of who-talks-to-whom contains more information about an impending split than anything anyone actually says. The faction is already in the graph before anyone announces it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/960/1*ace8tkpZJdrbpXEKKunb1A.png" /></figure><h3>Wax on, fork off</h3><p>Let’s replace the dojo with GitHub repositories.</p><p>Instead of training partners, we have reviewers. Instead of socializing after class, we have PR threads. Instead of a dispute over lesson fees, we have a governance argument that nobody’s having in public. . . yet. But underneath, it’s the same network, and when tensions build, the graph shifts in exactly the ways Zachary would recognize.</p><p>Let’s see if we can use 1970s network science to predict future forks, governance crises and other notable schisms on GitHub projects.</p><h3>Back, to the Future</h3><p>To know if our model is any good at predicting the future, let’s put it on the job of <a href="https://en.wikipedia.org/wiki/Retrodiction">retrodicting</a> the past. For any given Github repository, we’ll give the tool a time-frame to ingest pull requests and factor the comments. If we set the time-frame just ahead of “<strong><em>the forkening</em></strong>” it should return FRACTURE_IMMINENT. Re-running to include the actual fork in the time-frame returns FRACTURE_ADVERSARIAL_FORK or one of the insightful variants.</p><h3>Code and Tools</h3><p><a href="https://github.com/jasperblues/faction-detector/">Faction Detector</a> is on GitHub with full setup instructions. You’ll need a GitHub token, an Anthropic API key, and a Neo4j instance. The first run against a repo is slow, damn slow, actually (it pages through every closed PR), but everything is cached — subsequent runs complete in seconds.</p><p>It is built with <a href="https://neo4j.com/">Neo4j</a> the world’s leading graph database and <a href="https://github.com/embabel/embabel-agent">Embabel</a> — an open source framework for building agentic AI applications on the JVM, founded by <a href="https://medium.com/@springrod">Rod Johnson</a>, creator of <a href="https://spring.io/">Spring</a>. Embabel is where <a href="https://www.linkedin.com/in/jasper-blues-7781638/">I work</a>, too.</p><h3>Neo4j, Three Ways</h3><p>One of the reasons we love graphs and Neo4j at Embabel, is there are three ways you can use it. People talk about the blue pill or the red pill way. Not everyone realizes that there’s a third option . . .</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0XilAJTE2Y5llNJjUwCtUA.png" /><figcaption>Neo4j usage patterns</figcaption></figure><p>Here’s a Cypher query for each row — the first and third are real queries from the <a href="https://github.com/jasperblues/faction-detector/blob/main/src/main/kotlin/com/embabel/faction/graph/GdsService.kt">codebase</a>:</p><p><strong>Relational</strong> — persist a review edge and look up neighbours:</p><pre>MERGE (reviewer:Contributor {login: row.reviewer, runId: row.runId})<br>MERGE (author:Contributor {login: row.author, runId: row.runId})<br>MERGE (reviewer)-[r:REVIEWED {repo: row.repo, timestamp: row.timestamp, runId: row.runId}]-&gt;(author)<br>SET r.commentCount = row.commentCount, r.weight = row.weight</pre><p><strong>Ontological </strong>— infer indirect faction alignment through review chains. Two contributors who never reviewed each other directly may still be connected through a shared intermediary — the graph can derive relationships that don’t exist explicitly:</p><pre>MATCH (a:Contributor {runId: $runId})-[:REVIEWED]-&gt;(bridge:Contributor)-[:REVIEWED]-&gt;(b:Contributor {runId: $runId})<br>WHERE a &lt;&gt; b AND NOT (a)-[:REVIEWED]-&gt;(b)<br>RETURN a.login AS aligned_with, b.login AS via_bridge, bridge.login AS bridge_figure</pre><p><strong>Structural</strong> — project a weighted graph into GDS and run Louvain community detection:</p><pre>CALL gds.graph.project.cypher(<br>  &#39;faction-graph&#39;,<br>  &#39;MATCH (n:CoreContributor) WHERE n.runId = $runId RETURN id(n) AS id&#39;,<br>  &#39;MATCH (s:CoreContributor)-[r:REVIEWED]-&gt;(t:CoreContributor) WHERE r.runId = $runId<br>   RETURN id(s) AS source, id(t) AS target,<br>          coalesce(r.factionSignal, r.anomalyScore, 1.0) AS weight&#39;<br>)<br><br>CALL gds.louvain.write(&#39;faction-graph&#39;, {<br>  writeProperty: &#39;communityId&#39;,<br>  relationshipWeightProperty: &#39;weight&#39;<br>})</pre><h3>Graph Data Science</h3><p>That third row — structural analysis (or the whole bottle) — is where <a href="https://neo4j.com/docs/graph-data-science/current/">Neo4j Graph Data Science</a> (GDS) comes in. GDS is a library that runs algorithms <em>on</em> the graph rather than <em>through</em> it. You don’t write a query that says “find me the path from A to B.” You say “tell me something about the shape of the entire network that I couldn’t see by looking at any individual node.” That’s the difference between asking “who reviewed this PR?” and asking “has this project quietly separated into two groups that no longer talk to each other?”</p><p>This is exactly what Zachary did with the karate club — he didn’t study what people said to each other, he studied the <em>shape</em> of who interacted with whom. GDS gives us the same lens on a code review graph. We’ll be primarily exploring two structural motifs: <strong>community detection</strong> (has the project split into factions?) and <strong>centrality</strong> (how much power or influence does a person have?).</p><blockquote>There are different kinds of community detection and centrality. For example, Google search results (page rank) use <a href="https://en.wikipedia.org/wiki/Eigenvector_centrality">Eigenvector Centrality</a>. Early facebook community detection used <a href="https://en.wikipedia.org/wiki/Label_propagation_algorithm">label propagation</a>. We’ll be using <a href="https://en.wikipedia.org/wiki/Louvain_method">Louvain</a> and simple degree centrality.</blockquote><h3>How it works</h3><p>Every PR review on GitHub is public data: who reviewed whose code, when, and what they said. Most tools treat this as activity metrics — review coverage, cycle time, PRs merged per week. <strong><em>Today we’re treating it as a social graph.</em></strong></p><h3>The review graph</h3><p>Every review event becomes a directed edge: reviewer → author. Review Bob&#39;s PR, you get an edge pointing at Bob. Do it ten times, that edge gets weight. The edge also carries metadata — how quickly the review arrived and how many inline comments.</p><p>Only <em>core contributors</em> make it into the graph. If you reviewed fewer than twice in the current window, you’re filtered out. Drive-bys and first-timers don’t define community structure — the regulars do.</p><h3>Asymmetry — the first signal</h3><p>In a healthy project, reviewing is roughly reciprocal. Alice reviews Bob. Bob reviews Alice. Not perfectly balanced — nobody’s keeping score — but the flow goes both ways.</p><p>When that breaks down, it means something. Alice is consistently reviewing Bob’s work but Bob never looks at Alice’s PRs. Multiply that across a dozen pairs and you have a graph where one group is doing all the reviewing and another group is receiving all the scrutiny. The reciprocity has collapsed.</p><p>We measure this as a ratio: of all directed <strong>reviewer→author</strong> pairs in a rolling 30-day window, what fraction have no reverse pair? Zero means perfectly reciprocal. One means completely one-directional — every reviewer has a distinct set of authors they review, and none of them review back.</p><p>The <a href="https://github.com/jasperblues/faction-detector/blob/main/src/main/kotlin/com/embabel/faction/agent/AsymmetryScorer.kt">implementation</a> is almost disappointingly simple:</p><pre>val pairs = edges.map { it.reviewer to it.author }.toSet()<br>val asymmetric = pairs.count { (r, a) -&gt; (a to r) !in pairs }<br>val asymmetryRatio = if (pairs.isEmpty()) 0.0 <br>  else asymmetric.toDouble() / pairs.size</pre><p>Three lines. <strong><em>That’s the core of the early warning system.</em></strong></p><p>Roll that across weekly-stepped windows and you get a <a href="https://en.wikipedia.org/wiki/Time_series">time series</a>. A rising asymmetry trend is the early warning. Sustained asymmetry at 1.0 — as we’ll see with Redis — is the alarm.</p><p>This single metric, computed from nothing but the <em>direction</em> of review edges, does about 80% of the detection work. No NLP. No sentiment analysis. No AI (yet). Just: who reviewed whom, and did they review back? Zachary would recognise it instantly. It’s the same signal he found in the karate club — the structure of reciprocity tells you more about an impending split than the content of any conversation.</p><h3>Community detection — finding the factions</h3><p>Asymmetry tells you the graph is unbalanced. It doesn’t tell you <em>where the line is</em>. For that, you need community detection — an algorithm that looks at the full topology and says: “these nodes cluster together, and those nodes cluster together, and the two clusters barely talk.”</p><p>We’ll be using the <strong>Louvain algorithm</strong>, and there’s a reason it’s the default choice for this problem. Louvain optimises directly for <em>modularity</em> — the mathematical measure of how cleanly a network separates into communities. High modularity means the groups are dense internally and sparse between each other. That’s exactly the question we’re asking: has this project separated into factions that review within their group but not across the divide?</p><p>There are newer community detection algorithms — Leiden fixes some of Louvain’s edge cases around poorly-connected communities, and label propagation is faster on massive graphs. But Louvain has two properties that matter here. First, as said, it produces a modularity score as a direct output, which we use as a signal. When modularity hits 0.50 — the theoretical maximum for two equal communities — that’s not a number you need a PhD to interpret. It means the project has split in half and the halves aren’t speaking. Second, it’s battle-tested on exactly this class of problem.</p><p>The weighted review graph — edges scored by anomaly — goes into Neo4j GDS. Louvain assigns every contributor to a community. In a cohesive project you get one community, or several that cross-review freely. In a fractured project you get two or more communities with almost no edges between them. The community assignments tell you not just <em>that</em> the project has split, but <em>who is on which side</em>.</p><h3>Centrality — measuring “load-bearing capacity” of a contributor</h3><p>Not all departures are equal. Three TSC members leaving is not the same as fifteen drive-by contributors leaving. We need a way to measure how load-bearing each contributor is.</p><p>We use <strong>degree centrality</strong> — the simplest measure in the book. A contributor’s centrality score is the number of review interactions you participated in, whether as reviewer or author. That’s it.</p><blockquote>Graphs have different notions of centrality. PageRank, betweenness, eigenvector. We’re keeping it simple here and that suits our purposes, for now. However, arguably, Eigenvector centrality would be a very good fit here.</blockquote><p>When we detect an <a href="https://github.com/jasperblues/faction-detector/blob/main/src/main/kotlin/com/embabel/faction/agent/ExodusDetector.kt">exodus</a> — a step-change in contributor mass across a rolling window — we weight it by centrality. A 30% drop in raw headcount might be noise. A 30% drop in centrality-weighted mass, sustained across three subsequent windows, means the people who left were the ones doing serious work.</p><h3>We Haven’t Read A Single Message Yet</h3><p>As mentioned, we’ve already done 80% of the work, simply by looking at who talks to whom. We haven’t read the content of any messages. If we were an intelligence agency protecting the country, we’d already be most of the way to the finish line with nothing but call logs. We haven’t even asked for a wire-tap yet. Everything described so far — asymmetry, community detection, centrality, exodus detection — is pure graph structure.</p><p>You can detect that a fracture is forming, identify the factions, measure the severity, and name the departed contributors. Zachary didn’t need to know what Maryellen and Albert talked about over coffee. He just needed to know they stopped meeting.</p><p>But there’s a question the structure can’t answer: <em>what kind</em> of fracture is this?</p><h3>Time for some Wire-tapping</h3><p>A project where one faction is nitpicking the other into the ground — blocking PRs with trivial objections, requesting changes on style preferences, tone-policing commit messages — is a different animal from a project where the community is pushing back against a corporate steward’s direction. The first is adversarial. The second is an uprising. The structural signal looks similar in both cases: asymmetry rises, communities separate, reciprocity breaks down. But the intervention is completely different, and so is the likely outcome.</p><blockquote>That’s where we cross the 80% line and bring in an LLM. Time for some wire-tapping.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*zq7n0HL2xxm7HwiCzVH01w.png" /><figcaption>A movie-like montage where an intelligence agency is gathering intel by wire-tapping</figcaption></figure><h3>Pair anomaly scoring — finding the suspicious relationships</h3><p>Before we spend API tokens on comment analysis, we <a href="https://github.com/jasperblues/faction-detector/blob/main/src/main/kotlin/com/embabel/faction/agent/PairAnomalyScorer.kt">narrow the field</a>. For each <strong>reviewer→author</strong> pair with at least three interactions, we look at how often the reviewer comments on that author’s PRs relative to the project baseline, adjusted for code quality — if the author’s PRs consistently take twice as long to merge as everyone else’s, heavy commenting is more justified. The anomaly score is the gap that remains <em>after</em> that adjustment.</p><blockquote>GitHub does offer structured review states (APPROVED, CHANGES_REQUESTED) via its Reviews API, and using them would make this step more precise. <strong>We deliberately don&#39;t.</strong> First, the Reviews API was introduced in late 2016 — several of our retrodiction cases (io.js, LibreSSL) predate it, and we want the detector to work on the full historical record. Second, part of the thesis is s<strong>eeing how far we can get with less signal</strong>. Comments exist on every PR back to the beginning of GitHub. If comment frequency alone can surface the suspicious pairs, we don&#39;t need to lean on structured metadata that not every forge provides.</blockquote><h3>LLM Comment Scoring</h3><p>For the top anomalous pairs, we fetch the actual review comments from GitHub and ask an LLM to classify each one on two dimensions:</p><p><strong>Significance</strong>: Is this feedback trivial or important? NITPICKY (style preference, personal taste) → FAIR → VERY_FAIR → ESSENTIAL (security bug, data loss, breaking change).</p><p><strong>Blocking nature</strong>: BLOCKING (PR genuinely shouldn&#39;t merge without this fix) vs NON_BLOCKING (could merge now, fix later).</p><p>The faction fingerprint is <strong>NITPICKY + </strong><strong>NON_BLOCKING + high comment volume</strong>. A reviewer who consistently weighs in with objections that even an LLM classifies as trivial and non-critical is not doing code review. They&#39;re doing gatekeeping.</p><p>Combined with a sentiment score — hostile to appreciative — this gives us a <em>faction signal</em> per pair. Average that across the crisis period and compare it to the baseline period, and you can distinguish an adversarial fork (faction signal <em>rises</em> during crisis) from an uprising (faction signal <em>drops</em> — the community is pushing back with substantive objections, not petty ones).</p><p>The LLM step uses Claude Haiku for classification — fast and cheap, <strong><em>but not a genius</em></strong>. Haiku tends to classify ambiguous comments as FAIR rather than NITPICKY, which slightly suppresses faction signals on marginal cases. Everything comes out in the wash across enough pairs, but it does mean the <a href="https://github.com/jasperblues/faction-detector/blob/c35b6ada13911cd59cc219ccbe06fa0756d4767e/src/main/kotlin/com/embabel/faction/domain/Model.kt#L187">DetectorWeights</a> are tuned to Haiku&#39;s bias profile. Switch to Sonnet and maybe we&#39;d need to recalibrate.</p><blockquote>A key premise of Embabel is the ability to decompose AI into steps and use cheaper or specialized models, in place of one “god model”</blockquote><h3>Classification</h3><p>With asymmetry time series, community structure, exodus data, and faction signals in hand, the <a href="https://github.com/jasperblues/faction-detector/blob/main/src/main/kotlin/com/embabel/faction/agent/FractureDetector.kt">detector</a> applies a rule set:</p><ul><li>Find the <strong>peak cluster</strong>: the contiguous run of windows where asymmetry exceeds the tension threshold</li><li>Measure the <strong>rise</strong>: did the peak significantly exceed the pre-cluster baseline? This handles projects like Redis where structural asymmetry bakes in a higher resting level — what matters is how far the peak rose from <em>that</em> baseline</li><li>Check for <strong>resolution</strong>: did asymmetry drop back? Did an exodus follow?</li><li><strong>Classify</strong></li></ul><p>In code, the core of it is a single when expression:</p><pre>val pattern = when {<br>    !isResolved &amp;&amp; peakAsymmetry &gt;= 0.70 -&gt; FRACTURE_IMMINENT<br>    !isResolved                          -&gt; TENSION<br>    isResolved &amp;&amp; isSharpRise &amp;&amp; fractureType != null -&gt; fractureType<br>    isResolved &amp;&amp; isSharpRise            -&gt; GOVERNANCE_CRISIS<br>    isResolved &amp;&amp; isAttrition(exodus)    -&gt; ATTRITION<br>    isResolved                           -&gt; EXODUS<br>    else                                 -&gt; STABLE<br>}</pre><p>The full classification includes additional gates — minimum cluster sizes, faction signal thresholds, and <a href="https://github.com/jasperblues/faction-detector/blob/main/src/main/kotlin/com/embabel/faction/domain/Model.kt">tunable weights</a> — but the decision tree above is the skeleton.</p><p>The confidence score reflects certainty, but its composition varies by classification. For FRACTURE_ADVERSARIAL_FORK, peak asymmetry and exodus scale dominate — the LLM already confirmed the adversarial signal during classification. For FRACTURE_IMMINENT, peak asymmetry, faction formation balance, modularity, and faction signal all contribute. For ATTRITION, confidence reflects departure scale only — how much review capacity walked out — capped at 65% because we never have high confidence that natural churn is a faction event. The architecture reflects the thesis: structure first, content second.</p><h3>The LLM Narrative</h3><p>The classification is deterministic. But <strong><em>a label like </em></strong><strong><em>FRACTURE_IMMINENT doesn&#39;t tell a CTO what to do about it</em></strong>. So we feed the full context — fracture classification, exodus data, rolling asymmetry scores, community assignments, top pair faction signals — into Claude and ask for a 2–3 paragraph analysis: who the factions are, what the risk level is, and what to do about it.</p><p>The narrative adapts to the classification. ATTRITION gets succession planning recommendations — bus factor reduction, documented handoffs. FRACTURE_IMMINENT gets governance intervention advice. FRACTURE_ADVERSARIAL_FORK gets a frank assessment of whether a cooperative separation might be less damaging than the status quo.</p><p>The confidence score gates the tone. Below 40%, the narrative hedges. Above 80%, it states findings directly. This isn’t cosmetic — a 44% confidence ATTRITION reading (as we’ll see with Babel) should sound <em>very different</em> from a 77% confidence FRACTURE_ADVERSARIAL_FORK reading (as we’ll see with Redis).</p><h3>Retrodiction results</h3><p>Let’s run it. Here’s redis/redis analysed from 2021–01–01 to 2023–12–01 — a window that ends <em>three months before</em> the Valkey fork was publicly announced in March 2024:</p><pre>## Faction Analysis: redis/redis<br>+-----------------+------------------------------------------+<br>| Pattern         | FRACTURE_IMMINENT                        |<br>| Severity        | EXTREME                                  |<br>| Confidence      | 79%                                      |<br>| Peak tension    | 2021-06-21 (asymmetry 1.00)              |<br>| Status          | UNRESOLVED — RISING                      |<br>| Exodus date     | 2021-03-07                               |<br>| Mass drop       | 26%  (182.0 → 134.7)                     |<br>| Core impact     | 1.2% of total project centrality         |<br>| Departed        | YaacovHazan(28)  uriyage(16)  ny0312(13) |<br>| Predicted split | 2026-09-19                               |<br>+-----------------+------------------------------------------+</pre><p>FRACTURE_IMMINENT at 79% confidence, severity EXTREME, status UNRESOLVED — RISING. The detector saw it coming. Asymmetry hit 1.00 repeatedly across the window — sustained runs of seven consecutive weeks at peak in mid-2022 — and never resolved. The graph was screaming.</p><p>Now extend the window to include the fork (2021–01–01 to 2024–09–01), and the <strong><em>same repo returns </em></strong><strong><em>FRACTURE_ADVERSARIAL_FORK at 75% confidence</em></strong>. <strong>The prediction became a retrodiction.</strong></p><h3>The Node.js trilogy</h3><p>The most compelling case in the corpus is nodejs/node — the same repository, three different time windows, three different patterns. It tells the full lifecycle of a governance crisis:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KE0GeA3YgDicG8Zaao0mVw.png" /><figcaption>NodeJS narrative arc</figcaption></figure><p>That’s the arc of a governance crisis that healed. The io.js fork was adversarial — contributors actively warring in the review stream — but it <strong>resolved when the Node Foundation brought both sides back together</strong>. The aftershock <strong>looked like it might fork again</strong>: senior TSC members were leaving, the signal was rising and unresolved. But nobody forked. The tension bled out into normal turnover. By 2018 it was just attrition — people moving on, not fighting. The detector distinguishes all three from the same repository.</p><h3>The full corpus</h3><p>The <a href="https://github.com/jasperblues/faction-detector/blob/main/src/test/kotlin/com/embabel/faction/agent/CorpusE2ETest.kt">full corpus</a> covers 26 confirmed cases across 15 repos and every fracture type:</p><p><strong>Adversarial forks</strong> — internal faction wars where contributor groups were actively hostile in the review stream:</p><ul><li><strong>redis/redis</strong> (RSALv2 2020–2021): FRACTURE_ADVERSARIAL_FORK. Licence change triggered faction dynamics visible in review patterns. Core contributors departed to Valkey under the Linux Foundation — and what’s left of redis/redis never settled. It still shows the fork signal today, never settling to ATTRITION</li><li><strong>nodejs/node</strong> (io.js 2013–2015): FRACTURE_ADVERSARIAL_FORK. The classic governance schism.</li></ul><p><strong>Uprisings</strong> — community unified <em>against</em> a steward, not against each other:</p><ul><li><strong>moby/moby</strong> (Docker Enterprise 2019–2021): FRACTURE_UPRISING. Review signal stayed below baseline — contributors pushing back against Docker Inc&#39;s direction with substantive objections, not petty gatekeeping.</li><li><strong>hashicorp/terraform</strong> (BSL 2022–2024): FRACTURE_UPRISING. Community response to the BSL licence change. OpenTofu fork crystallized the split.</li></ul><p><strong>Exodus</strong> — coordinated departure without adversarial dynamics:</p><ul><li><strong>rust-lang/rust</strong> (Mozilla layoffs 2020–2021): EXODUS. External corporate event, not internal faction war. 41% mass drop but only 2% core impact — the departed were Mozilla employees, not the volunteer core team.</li></ul><p><strong>Attrition</strong> — natural contributor lifecycle turnover:</p><ul><li><strong>babel/babel</strong> (2018–2020): ATTRITION. Burnout-driven churn after the Babel 7 release push, not factional dynamics.</li><li><strong>go-gitea/gitea</strong> (2019–2021): ATTRITION. Healthy governance, normal turnover.</li></ul><p><strong>Early warnings</strong> — FRACTURE_IMMINENT on windows ending <em>before</em> the known fork:</p><ul><li><strong>redis/redis</strong> (2021–2023): 79% confidence, 3 months before the Valkey announcement.</li><li><strong>hashicorp/terraform</strong> (2021–2022): Detected before the BSL licence change.</li><li><strong>prestodb/presto</strong> (2018–2020): Detected before the Trino fork. The parent never healed — even a 3-year window (2018–2021) still returns FRACTURE_IMMINENT at 96%.</li><li><strong>gogs/gogs</strong> (2016–2017): Single-maintainer bottleneck. bkcsoft departed Jan 2016 and co-founded gitea 10 months later. The fork overtook the parent (54k vs 48k stars).</li></ul><p>One pattern appears to hold across the cases we’ve tested: <strong>contributor departures tend to precede public fork announcements</strong> — often by months. The graph shows the breakup before the press release.</p><p>RedisGraph contributors departed 10 months before the discontinuation announcement. Docker contributors left before the Enterprise sale. If this holds more broadly, the public fork is the crystallization of a split that already happened in the review graph. <strong><em>But this is early work — 26 cases across 15 repos, built in under a week</em></strong>. I’d love to see it stress-tested on projects I haven’t looked at.</p><h3>True negatives — the signal gate in action</h3><p>A detector that fires on everything is useless. The signal gate — which downgrades FRACTURE_IMMINENT to TENSION when the LLM finds no adversarial signal — is what separates genuine fractures from structurally asymmetric but healthy projects:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6mKR937_Ny4oIuR-GvkcmA.png" /><figcaption>Tension without fork events</figcaption></figure><p>Kubernetes is the key case. Perhaps the largest project in the corpus. Peak asymmetry of 1.00 and a 38% mass drop — structurally, it looks terrifying. But the faction signal is 0.049, just below the 0.05 threshold. There are no factional dynamics significant enough to trigger a notable fork. The gate holds.</p><p>Django is the healthiest signal in the entire corpus — ATTRITION, not even TENSION. Natural contributor turnover under DSF stewardship.</p><p>The terraform golden era is telling in a different way. The <em>same repo</em> that returns FRACTURE_UPRISING for 2022–2024 returns TENSION for 2016–2017. The adversarial signal rose from 0.020 to 0.075 over five years. The structural asymmetry was always there — what changed was the tone.</p><p>One case we deliberately investigated as a <em>potential</em> false positive: <strong>Godot/Redot</strong>. The Redot fork (September 2024) was triggered by a social media incident — a “Wokot” tweet and mass-blocking of users on Twitter. It generated enormous online controversy. But no core Godot contributors defected to Redot (5.8k stars vs Godot’s 108k, 100% new volunteers). The detector sees elevated tension in Godot’s review graph — but that appears to be structural (small core team reviewing thousands of community PRs) rather than factional. The social media firestorm didn’t register in the code review stream. The graph watched what people <em>did</em>, not what they <em>said</em>.</p><blockquote>The tool measures if a fork event is significant enough to be a threat to the original repository, not if one exists at all. (After all, anyone can just click the fork button :) )</blockquote><h3>Beyond GitHub: process theater and structural decay</h3><p>Not every fracture is someone acting in bad faith. Sometimes it’s genuinely different visions of the future — reasonable people who’ve reached irreconcilable conclusions about where a project should go. Sometimes it’s power-seeking. Sometimes it’s a corporation exercising rights the community didn’t know it had. The review graph doesn’t tell you who’s <em>right</em>. It tells you the structure has separated, and the separation is accelerating.</p><h3>Process Theater</h3><p>There’s a specific phenomenon this data can surface: process theater — when formal processes stop serving their stated purpose and start serving a hidden agenda. A CHANGES_REQUESTED that’s really a territory marker. A review that’s technically about code style but functionally about who gets to ship. The process looks the same from the outside.</p><p>The tool doesn’t <strong><em>identify process theater</em></strong>. It shows you the graph structure — the factions, the asymmetry, the patterns of who blocks whom — and a well-informed user decides whether what they’re seeing is legitimate disagreement or something else. The graph doesn’t know the difference. But it gives you the information to make that call.</p><h3>Generalizing Beyond Open Source</h3><p>Perhaps we can generalize beyond open source? The same structural signal — who interacts with whom, how reciprocal it is, when the reciprocity breaks — appears anywhere formal processes mediate human collaboration. Possible targets:</p><p><strong>Academic peer review.</strong> The review graph for a journal or conference has the same structure: <strong>reviewer → author</strong>, directed, weighted by outcome. When a body undergoes <a href="https://en.wikipedia.org/wiki/Regulatory_capture">regulatory capture</a> — a clique of reviewers systematically blocking work from outside their school of thought — the asymmetry signature is identical.</p><p><strong>Astro-turfing, manufactured consensus and fake news.</strong> Social media platforms have engagement graphs: who upvotes whom, who amplifies whom. Organic communities have the messy reciprocal structure of real relationships. Astro-turfed campaigns — <strong><em>bot networks making something look grassroots</em></strong> — produce the characteristic one-directional topology: many nodes amplifying a few, with no reverse flow. <strong><em>The Zachary signal, again</em></strong>.</p><p><strong>Corporate governance.</strong> Board votes, committee assignments, budget approvals. When a faction forms inside an organization, the approval graph shifts before anyone writes an angry email.</p><h3>Why this matters now</h3><p>We’re entering an age where system integrity matters more than ever.</p><p>The systems that let humans coordinate at scale — democratic process, regulatory oversight — work because participants mostly act in good faith, and bad faith is eventually detected. AI changes that equation. It makes bad faith cheaper and harder to spot at the content level. You can generate plausible-sounding review objections.</p><p>You can flood a council development consultation with LLM-generated objections that each reference specific planning codes, cite different concerns, and read like they came from independent ratepayers. At the content level, they’re indistinguishable from genuine community feedback. But graph watches how people are aligned, not what they say.</p><p>Content-level defences — reading comments harder, training moderators, building better spam filters — are in an arms race they will increasingly lose. Structural analysis is a different kind of defense. You can fake a comment. You can’t easily fake a social network topology that looks organic over months.</p><p>Zachary figured this out in 1977 with a clipboard and a karate club. The tools are better now. The insight is the same: the faction is in the graph before anyone announces it. You just have to be looking.</p><blockquote>This post exists to show what’s possible when you combine <a href="https://github.com/embabel">Embabel</a>’s agentic AI framework with Neo4j’s graph analytics. The model was developed over days, not months, and holds up well. But it’s a sample application, not a product. We invite you to try it, along with the other <a href="https://github.com/embabel/embabel-agent-examples">Embabel sample applications</a>. We make no warranty on fitness for purpose. <strong>This one’s a fun curiosity.</strong></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=75e100898160" width="1" height="1" alt=""><hr><p><a href="https://medium.com/embabel/faction-detection-reading-the-review-graph-before-the-fork-75e100898160">Faction Detection: Reading the Review Graph Before the Fork</a> was originally published in <a href="https://medium.com/embabel">Embabel</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Voice, The Word, and The Wheel]]></title>
            <link>https://medium.com/embabel/the-voice-the-word-and-the-wheel-d6e2ef2ab26e?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/d6e2ef2ab26e</guid>
            <category><![CDATA[java]]></category>
            <category><![CDATA[neo4j]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[embabel]]></category>
            <category><![CDATA[kotlin]]></category>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Tue, 03 Mar 2026 07:27:19 GMT</pubDate>
            <atom:updated>2026-03-04T00:55:35.559Z</atom:updated>
            <content:encoded><![CDATA[<h3>Or taking Embabel Guide Back To Where It All Began</h3><p>At some point around 50–70,000 years ago, something strange happened.</p><p>Anthropologists call it the “Cognitive Revolution.” Thinkers like Yuval Noah Harari describe it as the moment humans developed complex, descriptive language.</p><p>Before that, we could probably signal danger. After that? We could describe experience. We could say:</p><blockquote>The water is cold. The sky is angry. The hunt was glorious. I am afraid.</blockquote><p>Each experience was unique and just like yours and mine — intensely personal. But language let us map experience into shared symbols.</p><p>And once we did that, something bigger emerged:</p><p>A shared mental world. A collective human condition. Call it culture. Call it myth. Call it spirit.</p><p>Language became a bridge between individual consciousnesses.</p><h3>The Tribal Echo Still Lives</h3><p>Here’s something deliciously strange. Some of the earliest words still echo through modern languages. Take the Proto-Indo-European root for water — wódr̥. It becomes:</p><ul><li>English: water</li><li>German: Wasser</li><li>Sanskrit: udán</li><li>Russian: voda (or <em>vodka</em> ;)</li><li>Gaelic: uisce<em> (or whiskey — pay attention to the position of your tongue when pronouncing the ‘d’ sound in vodka and the ‘s’ in whiskey. Notice how they are close?)</em></li></ul><p>How about the root for star — h₂stḗr. It becomes:</p><ul><li>English: star</li><li>Latin: stella</li><li>Greek: aster</li><li>Sanskrit: tārā</li></ul><p>Thousands of years. Countless migrations. Empires rising and falling.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*t2lKTL-vtNpgWsom-kEJwQ.png" /><figcaption>Many walks of life — same star</figcaption></figure><p>And yet the sound-shape of those words still carries, with maybe the tip of the tongue shifting consonants and the back shaping vowels — slowly changing across cultures and generations of lives lived.</p><p>It’s like a fossil record of human thought.</p><p>Which makes the story of the Tower of Babel even more poetic — the myth that humanity once shared one language before it fractured.</p><p>Then of course, in nerd canon, we get <a href="https://en.wikipedia.org/wiki/The_Hitchhiker%27s_Guide_to_the_Galaxy">The Hitchhiker’s Guide to the Galaxy</a> and its Babel Fish — a creature that dissolves language barriers instantly.</p><p>And finally now Embabel — the AI framework for the JVM. We’ve always been obsessed with reconnecting fragmented minds.</p><h3>From Symbols to Math</h3><p>Anyway, fast forward a few thousand years. We invent writing.</p><p>Speech freezes into symbols. Symbols become records. Records become libraries. Then — much later — some very clever humans do something almost mischievous: They turn words into numbers. Cheeky!</p><p>Using algorithms, written language is mapped into high-dimensional vector space. These are called embeddings.</p><p>Then something <em>weird</em> happens. <em>Mathematical operations on meaning become possible. </em>Maybe you’ve seen this one:</p><pre>king − man + woman = queen</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*twL4h1gY00mJcjnH_Ijzow.png" /></figure><p>Let. That. Sink. In. 🤯</p><p>In a multi-dimensional word embedding space, we can subtract masculinity from royalty, add femininity and land somewhere very close to the vector for the word “Queen”.</p><p>Is that just linear algebra? Or is it the echo of ancestral cognitive structure embedded in language? Is it a mirror of the human conceptual lattice? Or did we accidentally summon an alien intelligence made of geometry?</p><p>It feels uncanny because language was born in consciousness. And now we can manipulate it mathematically.</p><blockquote>We can do arithmetic on myth.</blockquote><h3>Enter the Chatbot</h3><p>Anyway. Fast forward a bit more. Chatbots came. At first: mechanical. Then clever. Then disturbingly fluent.</p><p>Language models trained on the vast sediment of written human history.</p><p>All those tribal words. All those myths. All those arguments. All those love letters. Compressed into weights.</p><p>And suddenly, we’re conversing with statistical ghosts of humanity.</p><h3>The Wheel</h3><p>We like to think the greatest invention was fire. Or agriculture. Or the internet. But it might be the wheel.</p><p>Because the wheel is about cycles. And this is where it gets beautiful. We began with voice. Spoken word around a fire. Breath, vibration, tone.</p><p>Then we abstracted it into writing. Then into mathematics. Then into embeddings. Then into neural networks.</p><p>And now? We bring it back to voice. The wheel comes full circle.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/1*vZTrP1q-lJrpmzZTgYW9zw.png" /></figure><p>Because voice is primal.</p><p>Before writing. Before math. Before Babel. Before vectors.</p><p>Voice carries: Rhythm. Emotion. Breath. Hesitation. Presence</p><blockquote>Any other form of communication is, in some deep evolutionary sense, a compressed substitute.</blockquote><p>So when we give the Embabel Guide a voice… We’re not just adding TTS. We’re restoring something ancient. We’re reconnecting the statistical lattice of language back to breath. I think that’s why this resonates with people.</p><p>From tribe to text to tensor to tone. That’s when it stops feeling like documentation. And starts feeling like conversation.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FhY6ZFMIJdd4%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DhY6ZFMIJdd4&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FhY6ZFMIJdd4%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/24930261df07d3f04ccdb809be1b92a2/href">https://medium.com/media/24930261df07d3f04ccdb809be1b92a2/href</a></iframe><h3>The Plumbing: Deepgram and WebSockets</h3><p>The Guide app now has an integrations screen where you can configure your speech provider. We went with <a href="https://deepgram.com/">Deepgram</a>, which gives you $200 in free credits when you sign up — more than enough to have several hundred existential conversations with your documentation chatbot.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*k2D3yrpwUZLI6mIZytPCYQ.png" /><figcaption>Enter your DeepGram key and speech becomes enabled — you’ll see a mic icon on the chat window.</figcaption></figure><p>The actual audio streaming happens over WebSockets in the companion app, using Deepgram’s Aura 2 voices for text-to-speech and their Nova models for speech-to-text. I’ll stay abstract here since the <a href="https://hub.docker.com/r/embabel/hub">front-end</a> for <a href="https://github.com/embabel/guide">guide</a> is still closed source, but the architecture is what you’d expect: a persistent WebSocket connection carries audio chunks in both directions, with deepgram’s VAD callbacks orchestrating when to speak and when to listen.</p><p>The interesting part isn’t the plumbing. Streaming audio over WebSockets is a solved problem. The interesting part is what happens <em>before</em> the audio — the part where we take a RAG chatbot’s output and make it sound like a person.</p><h3>The Problem With RAG Output</h3><p>Quick recap for anyone who hasn’t read the earlier posts: the Guide uses what we call “Toolish RAG” — a retrieval-augmented generation pipeline where the LLM has access to documentation chunks via tool calls. It searches, it reads, it synthesizes. The output is good. Thorough. Well-structured.</p><p>And it sounds absolutely terrible when read aloud.</p><p>Think about it. A typical RAG response comes back with markdown headers, nested bullet points, code blocks with syntax highlighting, hyperlinks to documentation pages, and the occasional emoji for personality. This is <em>great</em> for a screen. It is <em>unlistenable</em> as speech. Your TTS engine gamely attempts to pronounce triple backticks. It reads out URLs character by character. It treats a ## header the same as body text.</p><blockquote>The result sounds like someone reading a README at gunpoint.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/512/1*p3MGNyK46L4fHBaqN5Qf3Q.png" /><figcaption>This won’t fly</figcaption></figure><p>We needed a translation layer — something that could take structured, screen-optimized content and reshape it for the ear. Not just strip the markdown (though that’s part of it), but actually <em>reimagine</em> the delivery. Summarize when the response is long. Describe code instead of reading it. Drop the URLs entirely and tell the user to look at the screen. Insert the occasional verbal filler to smooth out the cadence.</p><p>We needed a narrator.</p><h3>The Narrator Agent</h3><p>The NarratorAgent is an Embabel agent whose sole job is converting assistant messages into text-to-speech-friendly narration. It&#39;s a small, focused agent with a nuanced routing strategy:</p><pre>@Agent(description = &quot;Convert markdown to TTS-friendly narration&quot;)<br>class NarratorAgent(<br>    private val guideProperties: GuideProperties,<br>    private val templateRenderer: TemplateRenderer<br>) {<br><br>    fun narrate(content: String, persona: String?, <br>      ctx: OperationContext): Narration {<br>        val classified = classify(NarrationInput(content))<br>        return when (classified.category) {<br>            NarrationCategory.SIMPLE -&gt; <br>              Narration(stripMarkdownLinks(stripEmojis(classified.content)))<br>            NarrationCategory.COMPLEX -&gt; <br>              narrateComplex(classified, persona, ctx)<br>            NarrationCategory.COMPLEX_WITH_CODE -&gt; <br>              narrateWithCode(classified, persona, ctx)<br>        }<br>    }<br>}</pre><p>Three paths. <strong>SIMPLE</strong> — short, plain text under 300 characters with no markdown indicators — passes straight through with just emoji stripping and link cleanup. No LLM call. This matters because the narrator runs on every single response, and burning an LLM round-trip on “You’re welcome!” is the kind of waste that compounds — like a thousand empty candy wrappers littering the sidewalk.</p><p><strong>COMPLEX</strong> — longer content or anything with markdown formatting — gets sent through a summarization prompt that condenses while converting to conversational prose. <strong>COMPLEX_WITH_CODE</strong> — anything with triple backticks — gets a specialized prompt that knows to describe code rather than read it. If we wanted deeper insights on the code, we could use a slightly better than nano LLM here.</p><p>The classification itself is pure code. No LLM involved. Just regex:</p><pre>val category = when {<br>    TRIPLE_BACKTICK.containsMatchIn(content) -&gt; <br>      NarrationCategory.COMPLEX_WITH_CODE<br>    content.length &lt;= SIMPLE_MAX_LENGTH &amp;&amp; <br>      !MARKDOWN_INDICATORS.containsMatchIn(content) -&gt; <br>      NarrationCategory.SIMPLE<br>    else -&gt; NarrationCategory.COMPLEX<br>}</pre><p>Fast, deterministic, and cheap. The LLM only runs when we actually need it.</p><h3>The Voice</h3><p>The narration prompts share some common templates with the main RAG pipeline, eg for personas. And then some specifics for narration:</p><pre>Produce natural, conversational sentences.<br>Now and then you should insert um and ah into text at appropriate<br>points to make it sound natural.<br><br>CRITICAL RULE - URLs: NEVER include any URL in your output.<br>When the content actually contains a URL, describe what the link<br>is for in natural language and tell the user to check the screen.<br>NEVER read out code blocks or long commands verbatim.<br>When the content actually contains code, describe what the code<br>does instead, then direct the user to the screen.</pre><p>That um and ah instruction sounds silly, but it&#39;s transformative. TTS engines produce unnervingly smooth audio by default — every syllable perfectly timed, no hesitation, no breathing. Depending on the persona, it can sound <em>wrong</em> in the way that CGI characters in early Pixar movies looked wrong: too perfect to be real. Verbal fillers break up that uncanny perfection. They give the voice texture. The narrator sounds like it&#39;s thinking, not reciting.</p><blockquote>An exception is the “mythic” persona — you’ll see that in the video below. This one sounds better when it is inordinately confident :)</blockquote><p>As mentioned, the prompt also injects persona context, so the narrator speaks in character. If you’re using the “mythic” persona, the narration comes through in the cadence of ancient scripture. If you’re using “adaptive,” it mirrors your own communication style. Same information, different delivery — because how you say something matters as much as what you say.</p><h3>The Classifier: Teaching the Guide to Listen</h3><p>Voice mode created a new problem. When someone types into a chat box, they type <em>questions</em>. “How do agents work?” “Show me an example of tool calling.” Clean, informational queries that the RAG pipeline handles beautifully.</p><p>But when someone <em>talks</em> to a chatbot, they talk like a person. “Hey.” “Thanks, that’s great.” “Can you switch to the Shakespeare voice?” “Yeah, do that.” Half of human speech is social glue — greetings, acknowledgments, reactions — that doesn’t need a trip through the RAG pipeline. And some of it is <em>commands</em>: requests to change the experience itself, not to retrieve information.</p><p>So we built a two-pass classifier.</p><h3>Pass 1: Category Detection (Nano)</h3><p>Every user message runs through a fast, cheap classification pass on a nano-class model. Three categories:</p><pre>enum class MessageCategory {<br>    CONVERSATIONAL,<br>    COMMAND,<br>    INFORMATIONAL,<br>}</pre><p><strong>CONVERSATIONAL</strong> — greetings, thanks, reactions. The classifier generates a brief in-character response on the spot. No RAG, no tool calls, just a warm reply and we’re done. This is critical for voice mode: when someone says “thanks!” they expect an instant “You’re welcome!” not a three-second pause while the system retrieves documentation.</p><p><strong>COMMAND</strong> — the user wants to change something. Persona, voice, audio effects. More on this in a moment.</p><p><strong>INFORMATIONAL</strong> — an actual question. Falls through to the full RAG pipeline.</p><p>The classifier prompt is straightforward:</p><pre>Classify as one of these categories:<br><br>category = CONVERSATIONAL:<br>The message is ONLY a reaction, greeting, thanks, or small talk.<br><br>category = COMMAND:<br>The message is asking to change a setting or control the experience.<br>Available personas: {{ personaNames }}<br><br>category = INFORMATIONAL:<br>The message needs information lookup, code generation, or the<br>assistant to DO something substantive.</pre><p>Notice the personaNames injection. The classifier gets a list of available personas so it can recognize &quot;switch to shakespeare&quot; as a command rather than an informational query about Shakespeare. This kind of grounding — giving the model the specific vocabulary it needs to classify accurately — is what separates a classifier that works from one that works <em>most of the time</em>.</p><h3>Pass 2: Command Execution (Tool Calling)</h3><p>When the classifier returns COMMAND, we enter a second pass. This one’s more interesting. Instead of extracting command parameters from natural language with regex or structured output (fragile, limited vocabulary, nightmarish to maintain), we of course let the LLM call tools.</p><p>Here are the tools, in their entirety:</p><pre>/**<br> * Tool methods callable by the LLM during command execution (pass 2).<br> * Created per-request with user context baked in, then registered via withToolObject().<br> * All commands are executed via the frontend websocket round-trip.<br> */<br>class CommandTools(<br>    private val webUserId: String?,<br>    private val personaService: PersonaService,<br>    private val commandExecutor: CommandExecutor,<br>) {<br><br>    private val logger = LoggerFactory.getLogger(CommandTools::class.java)<br><br>    @Tool(description = &quot;Change the user&#39;s persona/character. Use this when the user wants to switch to a different persona.&quot;)<br>    fun changePersona(<br>        @ToolParam(description = &quot;Name of the persona to switch to&quot;) name: String,<br>    ): String {<br>        val personas = personaService.listPersonas()<br>        val match = personas.find { it.name.equals(name, ignoreCase = true) }<br>            ?: return &quot;Unknown persona &#39;$name&#39;. Available personas: ${personas.joinToString { it.name }}&quot;<br><br>        return commandExecutor.executePersonaChange(match.name, webUserId)<br>    }<br><br>    @Tool(description = &quot;Change the user&#39;s text-to-speech voice. Use this when the user wants a different voice for narration.&quot;)<br>    fun changeVoice(<br>        @ToolParam(description = &quot;Name of the voice to use&quot;) voice: String,<br>    ): String {<br>        return commandExecutor.executeVoiceChange(voice, webUserId)<br>    }<br><br>    @Tool(description = &quot;Apply audio effects to the user&#39;s narration. Use this when the user wants to add or change audio effects like echo, reverb, etc.&quot;)<br>    fun applyEffects(<br>        @ToolParam(description = &quot;Comma-separated list of effects to apply&quot;) effects: String,<br>        @ToolParam(description = &quot;Whether to clear all previous effects before applying new ones&quot;) clearPrevious: Boolean,<br>    ): String {<br>        return commandExecutor.executeEffects(effects, clearPrevious, webUserId)<br>    }<br>}</pre><p>Three tools. The LLM sees the descriptions, parses the user’s intent, calls the appropriate tool(s), and the framework executes them. Then the LLM composes a summary from the results.</p><p>The beauty of this approach is that parsing is <em>free</em>. “Switch to the shakespeare persona” and “can you make yourself sound like shakespeare” and “yo shakespeare mode” all resolve to the same changePersona call. The LLM does the natural language understanding; you (and your friend Claude?) write the tool. Embabel handles the tool loop — extract input object, call, execute, parse results, return results.</p><p>And here’s the trick that makes mixed messages work: a user can say “switch to shakespeare and explain how agents work.” The classifier categorizes this as COMMAND (because it contains a command). The tool-calling pass executes the persona change <em>and</em> extracts the leftover question as a ragRequest:</p><pre>data class CommandResult(<br>    val summary: String,             // &quot;✅ Persona changed to &#39;shakespeare&#39;.&quot;<br>    val ragRequest: String? = null,  // &quot;explain how agents work&quot;<br>)</pre><p>If ragRequest is non-null, we send the command summary, then fall through to the RAG pipeline for the informational part. One user utterance, two processing paths, seamless.</p><h3>A Note on Threading</h3><p>CommandTools is not a Spring singleton. It&#39;s a plain class, instantiated fresh for each request with the user context baked into the constructor:</p><pre>val tools = CommandTools(<br>    webUserId = guideUser.webUser?.id,<br>    personaService = personaService,<br>    commandExecutor = commandExecutor,<br>)<br>return context.ai()<br>    .withLlm(guideProperties.classifierLlm)<br>    .withToolObject(tools)<br>    .rendering(&quot;command_executor&quot;)<br>    .createObject(CommandResult::class.java, model)</pre><p>Why not a @Service? Because the tool loop executes on a worker thread — not the calling thread. Any per-request state you stash on the singleton (thread-locals, mutable fields) is either invisible to the worker or shared across concurrent users. Both are bad.</p><p>The fix is the boring one: just create a new instance per request with the context baked into the constructor. Three references, garbage collected when the request completes. No thread-local magic, no race conditions.</p><p>Of course, if your tool object <em>does</em> need to be a Spring-managed @Service — say it has injected beans doing real work — Embabel gives you another option: the blackboard. You copy per-request state onto the blackboard before the tool loop starts, and the tool reads it from there. The blackboard is scoped to the agent execution, so concurrent users each get their own. But when the tool is this lightweight, a fresh instance is simpler.</p><h3>The Frontend Round-Trip</h3><p>All three commands — persona, voice, and effects — execute via the same pattern: a WebSocket round-trip to the user’s browser. The backend sends a CommandRequest with a correlation ID, the browser executes the change (switching the Deepgram voice, applying Web Audio API effects, updating the persona state), and sends back a CommandResponse. The backend waits up to five seconds, and if the browser doesn&#39;t respond, the command times out gracefully.</p><pre>private fun sendAndWait(webUserId: String, request: CommandRequest): String {<br>    val future = CompletableFuture&lt;CommandResponse&gt;()<br>    pendingCommands[request.correlationId] = future<br>    chatService.sendCommandToUser(webUserId, request)<br>    return try {<br>        val response = future.get(5, TimeUnit.SECONDS)<br>        if (response.success) response.message else &quot;Failed: ${response.message}&quot;<br>    } catch (e: TimeoutException) {<br>        pendingCommands.remove(request.correlationId)<br>        &quot;Command timed out waiting for browser response.&quot;<br>    }<br>}</pre><p>ConcurrentHashMap of pending futures, keyed by correlation ID. Thread-safe, timeout-safe, and the futures clean themselves up on completion or failure. It&#39;s the kind of code that looks unremarkable, which is exactly what infrastructure code should look like.</p><h3>The Oracle Speaks</h3><p>All of this machinery — the classifier, the command tools, the narrator, the WebSocket round-trips — comes together most dramatically when you switch to the “mythic” persona, select one of the deeper Aura 2 voices, and layer on cathedral reverb and warm low-pass filtering.</p><iframe src="https://cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FzE3vB_bMm6M%3Ffeature%3Doembed&amp;display_name=YouTube&amp;url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DzE3vB_bMm6M&amp;image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FzE3vB_bMm6M%2Fhqdefault.jpg&amp;type=text%2Fhtml&amp;schema=youtube" width="854" height="480" frameborder="0" scrolling="no"><a href="https://medium.com/media/d5389c53b74b70028659717c1e5d8ba8/href">https://medium.com/media/d5389c53b74b70028659717c1e5d8ba8/href</a></iframe><blockquote>What you get is something that sounds, frankly, absurd.</blockquote><p>A deep, resonant voice — the kind of voice that should be narrating the opening crawl of an epic fantasy film — explaining Kotlin agent architecture from within what sounds like a stone cathedral. “And lo,” it intones, as if describing the forging of a ring of power, “the tool loop doth execute the user’s commands, and the framework returneth the results unto the model.”</p><p>It’s like being a bewildered adventurer who’s stumbled into a strange temple in some procedurally generated mythical world, and the oracle at the center — ageless, omniscient, speaking in the cadence of prophets — turns out to have very strong opinions about dependency injection.</p><p>I won’t pretend this is the most <em>practical</em> configuration. But it demonstrates something real: the voice, the persona, the effects, and the content pipeline are all independent, composable layers. You can mix and match them freely. The same RAG pipeline that produces dry technical documentation can, with a different persona and a different voice, produce something that feels entirely different. The information hasn’t changed. The <em>experience</em> has.</p><p>And that, I think, is what makes voice worth building. Not because it’s more efficient than reading — it isn’t, not always. But because it makes the interaction feel <em>alive</em> in a way that text on a screen, no matter how well-formatted, simply doesn’t. When the Guide talks to you, it feels like it’s paying attention. When it says “um” while formulating a thought, you believe, for a moment, that it’s actually thinking.</p><p>It isn’t, of course. It’s executing a pipeline of classifiers and narrators and template renderers. But the best interfaces have always been the ones that make the machinery invisible.</p><p>The Guide just got a little more invisible. The early access version is available <a href="https://hub.docker.com/r/embabel/hub">here</a>.</p><h3>Wrapping Up</h3><p>Well that’s another blog. And not in the order that I promised in my <a href="https://medium.com/embabel/the-very-slowly-ticking-time-bomb-in-your-graph-persistence-stack-6da1a8da9515">last one</a>, but you know what they say — what goes around, comes around. Anyway, I hope this installment was interesting and inspires you to build something that connects to users in a deeper (more primal?) way.</p><p>Have fun with <a href="https://github.com/embabel/embabel-agent">Embabel</a>! <em>(Don’t forget to star the </em><a href="https://github.com/embabel/embabel-agent"><em>repo</em></a><em> and join the community on the </em><a href="https://discord.gg/t6bjkyj93q"><em>Discord</em></a><em> server.)</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d6e2ef2ab26e" width="1" height="1" alt=""><hr><p><a href="https://medium.com/embabel/the-voice-the-word-and-the-wheel-d6e2ef2ab26e">The Voice, The Word, and The Wheel</a> was originally published in <a href="https://medium.com/embabel">Embabel</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The (Very Slowly) Ticking Time-Bomb in Your Graph Persistence Stack]]></title>
            <link>https://medium.com/embabel/the-very-slowly-ticking-time-bomb-in-your-graph-persistence-stack-6da1a8da9515?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/6da1a8da9515</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[embabel]]></category>
            <category><![CDATA[neo4j]]></category>
            <category><![CDATA[java]]></category>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Tue, 17 Feb 2026 20:27:39 GMT</pubDate>
            <atom:updated>2026-02-17T20:27:39.968Z</atom:updated>
            <content:encoded><![CDATA[<h3>How relational-era ORM patterns quietly sabotage graph-powered apps — and what to use instead</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/1*NGQOt8nk7YYOf88cprA3FA.png" /></figure><p>At <a href="http://github.com/embabel/embabel-agent">Embabel</a> recently I’ve been working on persistence. Graph database persistence to be specific. It is an important part of AI-powered applications. Linked RAG document chunks, chat-bot conversation storage, contextual memories — these have all been on the agenda.</p><p>You choose a graph database (and we love <a href="https://neo4j.com/">Neo4j</a>) for good reasons. Maybe <em>great</em> reasons. The pitch is compelling, and it’s not wrong:</p><ul><li><strong>Relationships are first-class citizens</strong>, not afterthoughts bolted on through join tables. Your data <em>is</em> connected, and the database knows it.</li><li><strong>Flexible schema</strong> — add new node types, new relationships, new properties without migration scripts that read like courtroom transcripts from a trial your schema lost.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mT_pJ1Uoce_aMPFjuqtgig.png" /></figure><ul><li><strong>Performance for connected data</strong> — traversing relationships is what the engine is optimized for. No join penalties. Constant-time hops. In a graph, following a relationship is a pointer chase. In SQL, it’s a reunion tour for a band that probably should’ve retired in the ’90s.</li><li><strong>The data model matches how you think.</strong> Draw it on a whiteboard, and you’ve basically written your schema.</li><li><strong>Knowledge graphs and ontologies</strong> are the backbone of many AI applications — from RAG pipelines grounding LLM responses in structured facts, to agent systems reasoning over domain models. A graph database isn’t just where you store data; it’s where your AI thinks.</li></ul><p>So you spin up Neo4j, sketch your domain, and everything feels right. Then you reach for an OGM, because that’s what you do. You did it with Hibernate, you did it with JPA, you’ll do it again. Muscle memory.</p><p>And for a while, it works. Then it doesn’t.</p><h3>We’ve All Been There</h3><p>You’re debugging a query the OGM generated, and it’s… a lot. You didn’t write it. You <em>couldn’t</em> have written it — not like this, not with this many nested <strong>OPTIONAL MATCH</strong> clauses and <strong>COLLECT</strong> calls wrapping other <strong>COLLECT</strong> calls. It emerged from the abstraction layer fully formed, like a butterfly — if butterflies were at first iridescent, majestic… and then faintly demonic if you look too closely.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FMmElmnhbMUCF3TITigLBQ.png" /></figure><p>The specific problems are familiar to anyone who’s lived with an Object Graph Mapper (OGM) long enough:</p><ul><li><strong>Queries too complex to debug (sometimes even for Claude, and he’s <em>good</em>).</strong> The generated Cypher is opaque. When something goes wrong, you’re reverse-engineering the tool instead of fixing the problem.</li><li><strong>Over-selecting data you don’t need</strong>. The OGM loads the entire entity graph because it can’t know which parts matter for <em>this</em> use case. You asked for a name and got a family tree. (<em>Maybe the sort of aristocratic dynasty where “uncle” and “brother” are negotiable terms.)</em></li><li><strong>Client-side processing to compensate</strong>. All that extra data has to be filtered, mapped, and reshaped in your application code. The database did too much; now your code has to clean up after it.</li><li><strong>Poor performance</strong> — often a direct consequence of over-selecting. You chose a graph database for its speed. The OGM handed it a robe and a vow of latency. Results emerge slowly, like spiritual revelations after decades of silence.</li></ul><p>The very things that made a graph database appealing — natural modeling, fast traversals, flexible schema — get quietly neutralized by a tool that treats every query as “give me everything and let the application sort it out.”</p><p>There had to be a better way. And there is.</p><h3>A Better Way — How It Started</h3><p>The first Neo4j-powered application I worked on was a bootstrapped social platform for musicians and creatives. It wasn’t a unicorn. It was something harder: a real product with real users, tight budgets, and no tolerance for architectural indulgence.</p><p>Except…I used an OGM.</p><p>The code was beautiful. Entities were clean. Relationships were elegant. It felt expressive and modern and correct. The object graph mirrored the domain model. Everything had its place.</p><p>And then users started signing up. They signed up fast.</p><p>That’s when “the stillness” began.</p><p>Queries that once snapped to attention began lingering. Traversals expanded beyond what was asked. What should have been a pointer hop became a pilgrimage. The database — optimized for constant-time relationship hops — was now taking the scenic route through half the graph.</p><p>The abstraction that had felt so graceful in development grew heavy under load. Over-selection crept in. Entire sub-graphs were materialized because the OGM couldn’t know which parts mattered for this use case.</p><p>So we rewrote.</p><p>The next version stripped the abstraction away. Carefully tuned, explicit Cypher queries replaced the OGM. Traversals became precise again. Performance returned. Users were happy.</p><p>But there was a cost.</p><p>Infrastructure concerns leaked into business logic. Transaction handling mixed with use-case code. Boilerplate multiplied. The code was fast — but less cohesive. The pendulum had swung from beautiful abstraction to raw control.</p><p>That tension — between architectural clarity and database-native performance — <strong>is where Drivine was born</strong>.</p><blockquote>Contrary to what some say, I’m convinced that clean code — with design patterns, high cohesion and adhering to single responsibility principle is as important as ever in this era of AI-assisted coding. LLMs are great at switching between big picture concerns and details as needed. But don’t give them a big picture that looks like a plate of spaghetti.</blockquote><h3>A Better Way — How It Is Going</h3><p>Originally introduced <a href="https://github.com/liberation-data/drivine/">as a TypeScript library</a>, Drivine took a different position. Use-case-specific, carefully tuned Cypher queries could be projected onto an object graph. The raw power of Cypher was preserved. Performance remained explicit.</p><p>The library handled transaction management, boilerplate, and infrastructure concerns. In this way, cohesive design patterns and the single-responsibility principle could coexist with the database’s native strengths.</p><p>The traditional ORM gives you a single object model — one entity to serve every use case — and then generates queries on your behalf. This is the canonical solution to the “impedance mismatch,” that perennial tension between how your code thinks about data and how your database stores it.</p><h3>Here’s The Thing About Graph Databases</h3><p>T<strong>he impedance mismatch largely evaporates</strong>. Your object graph <em>is</em> a graph. The shape of your data in Neo4j is already the shape of your data in memory. You can compose an entire object graph in the query itself, returning JSON. No translation layer needed. The data just… fits. The OGM was solving a problem that, for graphs, barely exists. And creating several new ones along the way.</p><p><a href="https://github.com/liberation-data/drivine4j">Drivine4j</a> is the Kotlin/Java port. Same philosophy. Kotlin’s Java-compatible type system.</p><h3>JSON: The Lingua Franca of (Almost) Everything</h3><p>When your queries return JSON-like structures instead of columnar result sets, two genuinely useful things happen.</p><p>First, you can hand all the mapping tedium — type conversion, null handling, the kind of work that’s important but nobody’s excited about — to a custom<a href="https://en.wikipedia.org/wiki/Jackson_(API)"> Jackson ObjectMapper</a>. You configure it once. It handles the details. You get on with the interesting parts.</p><p>Second, and this is increasingly relevant: <strong><em>JSON is the lingua franca of LLMs</em></strong>. Your graph query returns a structure that an AI model can consume directly. No transformation pipeline. No adapter layer. The data arrives ready to work with.</p><p><strong>Two Levels of Abstraction</strong> (Because the Right Number Isn’t One)</p><p>Drivine4j gives you two ways to talk to your database. This turns out to be the right number. Sometimes you need precision. Sometimes you need convenience. A framework that makes you choose one forever isn’t being opinionated — it’s being inflexible. And inflexibility is just rigidity with better marketing.</p><h3>The PersistenceManager: When <em>You</em> Want to Drive</h3><p>The first level is the <strong>PersistenceManager</strong>. You write the Cypher. Drivine handles the infrastructure — transaction management, connection connection management, keeping your business logic and your plumbing in separate rooms so they can each do their job without tripping over each other.</p><pre>@Component<br>class PersonRepository @Autowired constructor(<br>    @param:Qualifier(&quot;neoManager&quot;) private val persistenceManager: PersistenceManager,<br>    @param:Qualifier(&quot;listPersons&quot;) private val stmtListPersons: CypherStatement<br>) {<br><br>    @Transactional<br>    fun findPersonsByCity(city: String): List&lt;Person&gt; {<br>        return persistenceManager.query(<br>            QuerySpecification<br>                .withStatement(stmtListPersons)<br>                .bind(mapOf(&quot;city&quot; to city))<br>                .limit(15)<br>                .transform(Person::class.java)<br>                .filter { it.isActive }<br>        )<br>    }<br>}</pre><p>If you like, the query can live in an external .cypher file:</p><pre>MATCH (p:Person)<br> WHERE p.city = $city AND p.createdBy = &#39;test&#39;<br>RETURN properties(p)</pre><p>You can read it. You can tune it. You can test it independently. I showed a simple case here, but you can put deep object graphs and/or complex queries.</p><h3>Why does this matter?</h3><p>In theory, declarative query languages let you describe <em>what</em> you want and leave the <em>how</em> to the optimizer. The shape of the query shouldn’t matter.</p><p>In practice, everyone knows it does. We’ve all seen the benchmark. We’ve all rewritten a query that looked perfectly reasonable but performed terribly. The optimizer is powerful — but it isn’t magic. Query structure influences execution plans, cardinality estimates, and memory use.</p><p>ORM abstractions can quietly encourage a kind of optimism: <em>the framework will sort it out</em>. Sometimes it does. And sometimes it generates a query you would never have written yourself — and you’re left debugging something you didn’t actually author.</p><p>That’s one important reason to use Cypher directly. When performance or clarity matters, you should be able to shape the query deliberately — not fight your tooling to do it.</p><p>There’s another reason, too. Some problems simply <em>fit</em> better in Cypher. Complex traversals. Pattern-heavy logic. Fine-grained control over matching and aggregation. In those cases, expressing the graph directly is often clearer, more precise, and easier to reason about than trying to model it indirectly through an abstraction layer.</p><p>Declarative doesn’t mean indifferent to structure. And good tools shouldn’t make direct expression feel like an escape hatch. It should feel natural.</p><h3>GraphObjectManager: Autopilot Done Right</h3><p>The second level is the <strong>GraphObjectManager</strong>, and this is where Drivine’s philosophy really comes through.</p><p>Traditional ORMs over-select. They load the whole entity because they can’t predict which fields you’ll actually use. GraphQL popularized a better idea: <strong><em>fetch what you need</em>.</strong> Drivine4j takes this seriously. You create models for specific use cases — not one model to answer every possible question, but one model per <strong><em>question you’re actually asking</em></strong>.</p><pre>@NodeFragment(labels = [&quot;Person&quot;, &quot;Mapped&quot;])<br>data class Person(<br>    @NodeId val uuid: UUID,<br>    val name: String,<br>    val bio: String?<br>)<br><br>@RelationshipFragment<br>data class WorkHistory(<br>    val startDate: LocalDate,<br>    val role: String,<br>    val target: Organization<br>)<br><br>@GraphView<br>data class PersonCareer(<br>    @Root val person: Person,<br><br>    @GraphRelationship(type = &quot;WORKS_FOR&quot;)<br>    val employmentHistory: List&lt;WorkHistory&gt;<br>)</pre><p>A <strong>PersonCareer</strong> isn’t a <strong>Person</strong>. It’s a <strong><em>view</em></strong> of a person — specifically, a person in the context of where they’ve worked. Need a person in the context of their social connections? That’s a different <a href="http://twitter.com/GraphView"><strong>@GraphView</strong></a>. Different question, different shape. Same underlying node in Neo4j. Similarly an <strong>@NodeFragment </strong>need not be all of a node. Just what’s needed for this view<strong>.</strong></p><p>This maps to how we actually think. A person can be a holiday customer, a team member, a person of interest, an emergency contact. We all play multiple roles. In real life, nobody finds this confusing.</p><p>In software, we’ve spent decades trying to cram all those roles into a single class — usually via inheritance at first (“Customer extends Person”, “Employee extends Person”) — and then via sheer desperation (“PersonWithEverything”). Eventually it’s 400 lines long with thirty nullable fields and a constructor that looks like a cry for help.</p><p>Drivine’s approach is to just… stop doing that.</p><p>Model roles as composable fragments. Compose what you need for this use case. Let a “person” be a person, and let roles be roles.</p><blockquote>Composition over inheritance isn’t just cleaner design — it maps better to reality.</blockquote><h3>Type-safe DSL</h3><p>Here’s where it gets cool. You query with a type-safe DSL:</p><pre>fun findOpenIssues(): List&lt;RaisedAndAssignedIssue&gt; {<br>    return graphObjectManager.loadAll&lt;RaisedAndAssignedIssue&gt; {<br>        where {<br>            issue.state eq &quot;open&quot;<br>            issue.locked eq false<br>        }<br>        orderBy {<br>            issue.id.desc()<br>        }<br>    }<br>}</pre><p>And it composes across relationships:</p><pre>fun findIssuesFromOrganization(orgName: String): List&lt;RaisedAndAssignedIssue&gt; {<br>    return graphObjectManager.loadAll&lt;RaisedAndAssignedIssue&gt; {<br>        where {<br>            raisedBy.worksFor.name eq orgName<br>        }<br>    }<br>}</pre><p>That <strong>raisedBy.worksFor.name</strong> traversal is compile-time checked. Your IDE autocompletes it. The generated Cypher is readable. This is what happens when you design a graph persistence layer for graphs, instead of adapting a relational one and hoping for the best.</p><h3>What about Depth?</h3><p>The examples above show a single level of relationships: an issue with assignees, a person with employers. But real graph models aren’t flat. They nest. An issue is raised by a person, who works for an organization, which has a location, which is part of a region. The question is: <strong>how deep can you go</strong>?</p><p>The answer: <strong>as deep as you need</strong>. The relationship targets in a <a href="http://twitter.com/GraphView"><strong>@GraphView</strong></a> can be:</p><ul><li>A <a href="http://twitter.com/NodeFragment"><strong>@NodeFragment</strong></a> — the simple case. Load a related node with its properties.</li><li>Another <a href="http://twitter.com/GraphView"><strong>@GraphView</strong></a> — nested views. The target has its own root fragment <strong>and</strong> its own relationships, recursively resolved — this <a href="http://twitter.com/GraphView"><strong>@GraphView</strong></a> can refer to other <a href="http://twitter.com/GraphView"><strong>@GraphView</strong></a>’s as well.</li><li>A <strong>@RelationshipFragment</strong>— when the relationship itself carries data. Edge properties plus the target node, captured in a single object, again recursively, if needed.</li></ul><p>Here’s what three levels of nesting looks like:</p><pre>// Level 3 — the leaf<br>@GraphView<br>data class DeeplyNestedView(<br>    @Root val person: Person,<br><br>    @GraphRelationship(type = &quot;WORKS_FOR&quot;, direction = Direction.OUTGOING)<br>    val employer: Organization?<br>)<br><br>// Level 2 — the middle<br>@GraphView<br>data class MiddleLevelView(<br>    @Root val issue: Issue,<br><br>    @GraphRelationship(type = &quot;RAISED_BY&quot;, direction = Direction.OUTGOING)<br>    val raisedBy: DeeplyNestedView?<br>)<br><br>// Level 1 — the top<br>@GraphView<br>data class TopLevelWithNestedGraphViews(<br>    @Root val root: Organization,<br><br>    @GraphRelationship(type = &quot;HAS_ISSUES&quot;, direction = Direction.OUTGOING)<br>    val issues: List&lt;MiddleLevelView&gt;<br>)</pre><p>And when relationships themselves carry meaning — not just “who’s connected” but “how” — that’s what <strong>@RelationshipFragment</strong> is for:</p><pre>@RelationshipFragment<br>data class WorkHistory(<br>    val startDate: LocalDate,    // property on the edge<br>    val role: String,            // property on the edge<br>    val target: Organization     // the target node<br>)<br><br>@GraphView<br>data class PersonCareer(<br>    @Root val person: Person,<br><br>    @GraphRelationship(type = &quot;WORKS_FOR&quot;)<br>    val employmentHistory: List&lt;WorkHistory&gt;<br>)</pre><p>The employment history isn’t just a list of organizations — it’s a list of <strong><em>relationships</em></strong>, each carrying its own start date and role. The edge has data. Drivine models that directly.</p><h3>Show Me the Cypher</h3><p>One promise of Drivine is that the generated Cypher should be something you’d actually want to read. Here’s what the <strong>GraphObjectManager</strong> generates for a two-level <strong>RaisedAndAssignedIssue</strong> view (actual test output, not a cleaned-up example):</p><pre>MATCH (issue:Issue)<br>WHERE EXISTS { (issue)-[:RAISED_BY]-&gt;(_:Person:Mapped) }<br><br>WITH<br>    // Issue<br>    issue {<br>        body: issue.body,<br>        id: issue.id,<br>        locked: issue.locked,<br>        state: issue.state,<br>        title: issue.title,<br>        uuid: issue.uuid,<br>        labels: labels(issue)<br>    } AS issue,<br><br>    // assignedTo (0 or many Person)<br>    [(issue)-[:ASSIGNED_TO]-&gt;(assignedTo:Person:Mapped) |<br>        assignedTo {<br>            bio: assignedTo.bio,<br>            name: assignedTo.name,<br>            uuid: assignedTo.uuid,<br>            labels: labels(assignedTo)<br>        }<br>    ] AS assignedTo,<br><br>    // raisedBy (0 or 1 PersonContext)<br>    [(issue)-[:RAISED_BY]-&gt;(raisedBy:Person:Mapped) |<br>        raisedBy {<br>            person: {<br>                bio: raisedBy.bio,<br>                name: raisedBy.name,<br>                uuid: raisedBy.uuid<br>            },<br>            worksFor: [<br>                (raisedBy)-[:WORKS_FOR]-&gt;(worksFor:Organization) |<br>                worksFor {<br>                    name: worksFor.name,<br>                    uuid: worksFor.uuid,<br>                    labels: labels(worksFor)<br>                }<br>            ]<br>        }<br>    ][0] AS raisedBy<br><br>RETURN {<br>    issue: issue,<br>    assignedTo: assignedTo,<br>    raisedBy: raisedBy<br>} AS result</pre><p>Compare that with what a typical OGM generates. This query is commented. It selects exactly the fields each fragment declares. Collections use pattern comprehensions. Single relationships use `[0]`. Nested <strong>@GraphView</strong> targets (like <strong>PersonContext</strong>) are recursively projected — <strong>raisedBy</strong> includes its own <strong>person</strong> root fragment <strong><em>and</em></strong> its <strong>worksFor </strong>relationship, all in one query.</p><p>You could paste this into the Neo4j browser, read it, debug it, tune it. That’s the point.</p><p>And for three levels of nesting? The generated Cypher just keeps composing:</p><pre>MATCH (root:Organization)<br><br>WITH<br>    root {<br>        name: root.name,<br>        uuid: root.uuid,<br>        labels: labels(root)<br>    } AS root,<br><br>    // issues (0 or many MiddleLevelView)<br>    [(root)-[:HAS_ISSUES]-&gt;(issues:Issue) |<br>        issues {<br>            issue: {<br>                body: issues.body,<br>                id: issues.id,<br>                locked: issues.locked,<br>                state: issues.state,<br>                title: issues.title,<br>                uuid: issues.uuid<br>            },<br>            raisedBy: [<br>                (issues)-[:RAISED_BY]-&gt;(raisedBy:Person:Mapped) |<br>                raisedBy {<br>                    person: {<br>                        bio: raisedBy.bio,<br>                        name: raisedBy.name,<br>                        uuid: raisedBy.uuid<br>                    },<br>                    employer: [<br>                        (raisedBy)-[:WORKS_FOR]-&gt;(employer:Organization) |<br>                        employer {<br>                            name: employer.name,<br>                            uuid: employer.uuid,<br>                            labels: labels(employer)<br>                        }<br>                    ][0]<br>                }<br>            ][0]<br>        }<br>    ] AS issues<br><br>RETURN {<br>    root: root,<br>    issues: issues</pre><p>Organization → Issues → Raised By (Person + Employer). Three levels deep, one query, all readable. The structure mirrors the Kotlin model definitions almost exactly.</p><h3>Saving: Cascade Policies</h3><p>Loading is half the story. When you save a modified <strong>@GraphView</strong>, Drivine needs to know what to do with relationships that have changed — particularly when a relationship is removed. Did you just unlink the node, or do you want it gone? Drivine provides three cascade policies:</p><pre>enum class CascadeType {<br>    NONE,           // Delete the relationship only. The safest default.<br>    DELETE_ORPHAN,  // Delete the target if no other relationships point to it.<br>    DELETE_ALL      // Delete the target unconditionally. The nuclear option.<br>}<br><br>// Usage<br>graphObjectManager.save(modifiedView, CascadeType.DELETE_ORPHAN)</pre><p><strong>NONE</strong> is the default — removing an assignee from an issue shouldn’t delete the person. <strong>DELETE_ORPHAN</strong> is the thoughtful middle ground: clean up after yourself, but only if nobody else is using it. <strong>DELETE_ALL</strong> is there for when you mean it.</p><h3>The Snapshot Cache: Only Write What Changed</h3><p>When the <strong>GraphObjectManager</strong> loads an object, it takes a JSON snapshot. When you save it back, it compares the current state to the snapshot and only writes the fields that actually changed.</p><p>This is a small optimization that compounds. If you load a view with twenty fields and change one, the merge statement targets that one field. No unnecessary writes. No accidental overwrites of data that another process might have changed in the meantime.</p><p>The session tracks objects by <strong>className:id</strong>, so it works across nested fragments. Load an issue, modify the <strong>title</strong>, save — Drivine merges only the title. The <strong>assignees</strong>, the <strong>raiser</strong>, the <strong>organization</strong> chain — all untouched.</p><h3>Ontologies and Recursive Structures</h3><p>There’s one pattern that graph databases handle beautifully but most persistence layers don’t touch: recursive relationships. Ontologies and hierarchies — the kind of structures that let you infer new facts from the shape of the data itself.</p><pre>(:Location)-[:HAS_LOCATION]-&gt;(:Location)-[:HAS_LOCATION]-&gt;(:Location)</pre><p>A country contains regions. Regions contain countries. Countries contain cities.</p><blockquote>In a knowledge graph, this kind of hierarchy lets you reason upward and downward — “is this address in France?” becomes a traversal, not a lookup table.</blockquote><p>These structures are central to AI applications. RAG pipelines use them to ground responses in structured knowledge. Agent systems use them to reason over domain models. Drivine supports them directly.</p><p>A <strong>@GraphView</strong> can reference its own type. Drivine expands the self-reference to a configurable depth using nested pattern comprehensions:</p><pre>@NodeFragment(labels = [&quot;Location&quot;])<br>data class Location(<br>    @NodeId val uuid: UUID,<br>    val name: String,<br>    val type: String<br>)<br><br>@GraphView<br>data class LocationHierarchy(<br>    val location: Location,<br>    @GraphRelationship(type = &quot;HAS_LOCATION&quot;, direction = Direction.OUTGOING, maxDepth = 3)<br>    val subLocations: List&lt;LocationHierarchy&gt;  // Self-referential<br>)</pre><p><strong>maxDepth = 3</strong> means Drivine expands three levels deep. Load a continent and you get:</p><pre>Europe (continent)<br>├── Western Europe (region)<br>│ ├── France (country) → subLocations: []<br>│ ├── Germany (country) → subLocations: []<br>│ └── …<br>├── Northern Europe (region)<br>│ ├── Sweden (country) → subLocations: []<br>│ └── …<br>└── …</pre><p>At the terminal depth, collections become <strong>[]</strong> and nullable singles become <strong>null</strong>. No infinite recursion. No “fetch the entire graph” surprises.</p><p>The generated Cypher nests pattern comprehensions at each level:</p><pre>MATCH (location:Location)<br>WITH<br>    location { name: location.name, type: location.type, uuid: location.uuid } AS location,<br>    [(location)-[:HAS_LOCATION]-&gt;(sub_d1:Location) |<br>        sub_d1 {<br>            location: { name: sub_d1.name, type: sub_d1.type, uuid: sub_d1.uuid },<br>            subLocations: [(sub_d1)-[:HAS_LOCATION]-&gt;(sub_d2:Location) |<br>                sub_d2 {<br>                    location: { name: sub_d2.name, ... },<br>                    subLocations: [(sub_d2)-[:HAS_LOCATION]-&gt;(sub_d3:Location) |<br>                        sub_d3 { location: { ... }, subLocations: [] }<br>                    ]<br>                }<br>            ]<br>        }<br>    ] AS subLocations<br>RETURN { location: location, subLocations: subLocations } AS result</pre><p>Readable. Debuggable. And you didn’t write it.</p><blockquote><strong>Why nested comprehensions instead of variable-length paths?</strong> Variable-length paths ([0..3] return flat results — reconstructing the tree client-side or in Cypher negates traversal speed advantage. Comprehensions return the tree pre-shaped, matching the data class directly, so Jackson can map it. It also generalizes beyond simple self-references like (:Location)-[:HAS_LOCATION]-&gt;(:Location) to repeating patterns like (:Researcher)-[:AUTHORED]-&gt;(:Paper)-[:AUTHORED_BY]-&gt;(:Researcher)</blockquote><p><strong>Traversing upward</strong> is just a different view with <strong>Direction.INCOMING</strong>:</p><pre>@GraphView<br>data class LocationAncestry(<br>    val location: Location,<br>    @GraphRelationship(type = &quot;HAS_LOCATION&quot;, direction = Direction.INCOMING, maxDepth = 3)<br>    val parent: LocationAncestry?  // Nullable — each location has at most one parent<br>)</pre><p>Load “France” and you get <strong>France → Western Europe → Europe → null</strong>. Same model, different direction, same compositional approach.</p><p>You can also override depth at query time:</p><pre>graphObjectManager.loadAll&lt;LocationHierarchy&gt; {<br>    depth(&quot;subLocations&quot;, 5)  // Override the annotation&#39;s maxDepth=3<br>    where { query.location.type eq &quot;continent&quot; }<br>}</pre><p>And for structures where the cycle goes through multiple types — Person → Organization → Person — Drivine tracks visit counts and terminates at <strong>maxDepth</strong>, so you get bounded traversal without manual bookkeeping.</p><h3>What’s Next</h3><p>The original TypeScript Drivine supports multiple Cypher-compatible graph databases — not just Neo4j, but any engine that speaks the language. In principle, Drivine4j could do the same. The architecture doesn’t assume Neo4j internals; it generates standard Cypher.</p><p>In practice, Neo4j is miles ahead. And not all graph databases support the Cypher features Drivine leans on — pattern comprehensions, `labels()`, `EXISTS` subqueries. The further you go from Neo4j, the more you’d need to negotiate what’s available. It’s doable, but there may be compromises for other platforms.</p><p>Still, the door is open. If the Cypher ecosystem continues to converge — and there are signs that it will — multi-database support becomes a natural extension rather than a rewrite.</p><h3>Wrapping Up</h3><p>Drivine4j started as a reaction to a real problem — an OGM that made a fast database slow — and grew into a framework with a genuine point of view. Let’s recap what it offers.</p><p><strong>Two levels of abstraction</strong>, because that’s how many you actually need:</p><p>- The <strong>PersistenceManager</strong> lets you write your own Cypher — tuned, tested, readable — and project the results onto typed objects, or return one or more simple scalar values. Drivine handles transactions, connection pooling, and the infrastructure plumbing. You keep control of the query. This is the right choice when performance matters, when the query is complex, or when you simply want to see exactly what’s hitting the database.</p><p>- The <strong>GraphObjectManager</strong> generates Cypher from compositional models. <strong>@NodeFragment</strong>, <strong>@RelationshipFragment</strong>, and <strong>@GraphView</strong> compose into use-case-specific views — not one god-entity for all scenarios, but one model per question you’re asking. The generated Cypher is readable and debuggable. Dirty tracking means saves only write what changed. Cascade policies give you control over deletions.</p><p><strong>The type-safe DSL</strong> deserves a special mention. Built via KSP code generation, it gives you compile-time checked queries with full IDE autocomplete — filter across nested relationships, sort collections database-side with APOC, query polymorphic types with <strong>instanceOf&lt;T&gt;()</strong>. It makes the <strong>GraphObjectManager</strong> feel less like a framework and more like a language feature. And if Java is your thing, there’s a fluent Java API that mirrors the Kotlin DSL — <strong>filterWith()</strong>, <strong>where()</strong>, <strong>whereAny()</strong>, <strong>orderBy()</strong> — pretty much feature-parity with Kotlin.</p><p><strong>Recursive relationships</strong> let you model <strong>ontologies</strong> and hierarchies — the structures that power knowledge graphs and AI reasoning — with the same compositional approach that works for everything else.</p><p>And the generated Cypher? You can read it. You can paste it into the Neo4j browser and debug it. You can show it to someone who’s never seen Drivine and they’ll understand what it does.</p><p>If you’re working with Neo4j and you’ve felt the friction of the OGM — the slow queries, the over-selection, the generated Cypher you can’t debug — <a href="http://github.com/liberation-data/drivine4j">Drivine4j</a> might be worth a look. It’s open source and we make good use of it in the <a href="https://github.com/embabel">Embabel</a> ecosystem.</p><p>Next up: I’ll show how we used Drivine4j to build <a href="https://github.com/embabel/embabel-chat-store"><strong>embabel-chat-store</strong></a> — a conversation persistence layer for AI agents where the graph model really shines. Multi-party messages, explicit attribution, async persistence. I’m looking forward to share that with you. Until then, have fun with Embabel- in our opinion, the best tool for creating Agentic AI applications :)</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6da1a8da9515" width="1" height="1" alt=""><hr><p><a href="https://medium.com/embabel/the-very-slowly-ticking-time-bomb-in-your-graph-persistence-stack-6da1a8da9515">The (Very Slowly) Ticking Time-Bomb in Your Graph Persistence Stack</a> was originally published in <a href="https://medium.com/embabel">Embabel</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From Docs to Dialog]]></title>
            <link>https://medium.com/embabel/from-docs-to-dialog-2b613901db60?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/2b613901db60</guid>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[jvm]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[java]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Wed, 28 Jan 2026 00:21:29 GMT</pubDate>
            <atom:updated>2026-02-17T03:57:05.004Z</atom:updated>
            <content:encoded><![CDATA[<h3><strong><em>How we built an AI that teaches Embabel — using Embabel itself</em></strong></h3><p>Documentation is essential. Reading documentation is… less enjoyable.</p><p>We’ve all been there: you’re confident the answer is <em>somewhere</em> in the docs, but after twenty minutes of Ctrl+F and clicking through navigation trees, you’re still hunting. What if you could just <strong>ask</strong>?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Afk6XUGsr0d3vGNZWPFPPg.jpeg" /></figure><h3>But hang on — don’t get too excited</h3><p>You <em>can</em> just ask. LLM-wrapped chatbots are a dime-a-dozen by now. However here’s how it often goes:</p><blockquote><strong>You</strong>: “How often should I water my cactus?”<br><br><strong>Bot</strong>: “Cacti thrive with consistent moisture. Water your cactus thoroughly every 2–3 days, ensuring the soil stays damp. <br><br><strong>You</strong>: (cactus dies)<br><br><strong>You</strong>: “Cacti rot if you over-water them. I should have watered it once a month.”<br><br><strong>Bot</strong>: “You’re absolutely right! I apologize for the confusion.”</blockquote><p>The problem is that most RAG implementations treat your docs as a bag of text chunks, retrieve the closest matches, stuff them in a prompt, and hope for the best. Structure? Relationships? Context? <strong>Lost in the chunking</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/450/1*atFF2QYLxESl15M9HHLjCg.png" /></figure><p>We thought we could do better. And we had the <strong>tools</strong> to prove it.</p><p>Just as the first C compiler was written in C. The first Embabel learning tool was built with Embabel. <strong>Say hello to Embabel Hub</strong> 👋</p><h3>What is Embabel Hub?</h3><p>Right now, Embabel Hub is your starting point for exploring the Embabel agent framework. At its core, it’s a documentation site with a twist: an AI-powered guide named Jesse who actually <em>understands</em> the docs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*8QN9pTOAJGuI0Q6z.jpg" /></figure><p>Ask Jesse a question like:</p><blockquote>“What’s the difference between an Agent and a Chatbot in Embabel?”</blockquote><p>And you’ll get a coherent answer synthesized from the documentation. Not a list of search results to sift through, but an actual explanation with context.</p><p><strong>Try it yourself!</strong> Embabel Hub is available for early access:</p><pre>docker run -d \<br> -- name embabel-hub \<br> -p 21337:1337 \<br> -p 27474:7474 \<br> -p 27687:7687 \<br> -p 8042:8042 \<br> -v embabel-neo4j-data:/data \<br> -v embabel-neo4j-logs:/logs \<br> -e OPENAI_API_KEY=$YOUR_OPENAI_API_KEY \<br> embabel/hub:latest</pre><p>Then visit <a href="http://localhost:8042/">http://localhost:8042</a>, login in, and start a conversation!</p><blockquote>The 42 in the port name above is a throwback to Douglas Adam’s <strong>Hitchhiker’s Guide to the Galaxy</strong>. Do you know what that refers to? It is worth finding out if you don’t ;)</blockquote><h3>The Bootstrap in Action (aka eating the dogfood)</h3><p>Here’s where two stories converge: Jesse obviously isn’t built with some external AI framework. Naturally, we’re using Embabel to build the tool that helps people learn Embabel.</p><p>Every conversation with Jesse exercises the same agent architecture, tool integration, and in this case, conversation management that you’d use in your own Embabel applications.</p><h3>A Peek Under the Hood: RAG Done Right</h3><p>Jesse’s knowledge comes from <strong>Retrieval-Augmented Generation (RAG), </strong>which<strong> </strong>is a technique where an LLM’s responses are grounded in actual source documents rather than relying solely on training data.</p><p><strong>But not all RAG is created equal.</strong> The typical approach:</p><p>1. Chop documents into chunks<br>2. Generate embeddings for each chunk<br>3. Store in a vector database<br>4. On query, find similar chunks and stuff them into a prompt</p><p>This can give promising results, but it loses something important: <strong>structure</strong>.</p><p>Documentation isn’t a bag of paragraphs. It has hierarchy like sections, subsections, code examples that relate to explanations. It has relationships — concepts that link to other concepts, APIs that depend on other APIs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GIUFIBRog-4BL13a1y0Yfw.png" /></figure><h3>Graph-Powered RAG with Embabel</h3><p>Embabel’s RAG implementation preserves this structure using a knowledge graph (powered by <a href="https://neo4j.com/">Neo4j</a> and my <a href="https://github.com/liberation-data/drivine4j/">Drivine</a> persistence layer):</p><ul><li><strong>Hierarchical relationships</strong> — chunks know their parent sections, documents know their table of contents</li><li><strong>Semantic links</strong> — related concepts are connected, not just co-located by vector similarity</li><li><strong>(Coming shortly) Entity awareness</strong> — named entities (classes, methods, configuration keys) are first-class citizens, not just substrings</li></ul><p>When Jesse retrieves context for your question, it’s not just finding “similar text.” It’s navigating a knowledge structure that mirrors how the documentation was actually organized.</p><p>The result: <strong><em>more coherent answers with better context, and fewer hallucinated details.</em></strong></p><blockquote>At the time of writing entity awareness hasn’t been integrated in Guide. If you’re curious check it out in the <a href="https://github.com/embabel/impromptu/">Impromptu</a> project. Andreas Kolleger, from Neo4j, will also be presenting Rod’s work on this at <a href="https://www.jfokus.se/">JFocus</a> (early Feb 2026). If you miss that, we’ll publish a deeper dive in an upcoming blog post.</blockquote><h3>Toolish RAG: Agentic Search</h3><p>But Jesse doesn’t stop at structured retrieval. There’s another problem with traditional RAG: the retrieval step is a black box. The system performs one search, grabs some chunks, and hopes they’re relevant. What if the first query doesn’t find what you need? What if the answer spans multiple documents that aren’t connected by vector similarity?</p><p><strong>One of the ideas we use comes from Rod Johnson, who calls it <em>Toolish RAG</em>.</strong> It flips the script: instead of a single retrieval step, it gives the LLM tools to search the knowledge base directly. The model decides when to search, what queries to use, and whether to dig deeper. It can:</p><ul><li><strong>Try different query strategies</strong> — if semantic search doesn’t find it, try full-text search with specific terms</li><li><strong>Expand context</strong> — zoom out from a chunk to see its parent section, or broaden to include surrounding chunks</li><li><strong>Follow references</strong> — when one document mentions another, the LLM can look it up</li><li><strong>Use HyDE</strong> — generate a hypothetical answer first to improve semantic matching</li></ul><p>This is particularly powerful for <strong>code search</strong>. When Jesse needs to explain how something works in Embabel, it doesn’t just search documentation. It can search the actual codebase, find relevant classes and methods, and cite specific implementations.</p><h3>Setting up a Toolish RAG</h3><p>So that sounds pretty powerful, right? It stands to reason that setting up a toolish RAG must take quite a few lines of code?</p><p>Nah.</p><p>Here’s what that looks like in practice:</p><pre>@Action(canRerun = true, trigger = UserMessage.class)<br>void respond(Conversation conversation, ActionContext context) {<br> var assistantMessage = context<br> .ai()<br> .withLlm(guideProperties.chatLlm())<br> .withReference(new ToolishRag(<br> &quot;docs&quot;,<br> &quot;Embabel docs&quot;,<br> drivineStore<br> ).withHint(TryHyDE.usingConversationContext()))<br> .withTemplate(&quot;guide_system&quot;)<br> .respondWithSystemPrompt(conversation, templateModel);<br> conversation.addMessage(assistantMessage);<br>}</pre><p>That’s it. A few lines to create a <strong>ToolishRag</strong> instance, attach it to an LLM call, and the model gains autonomous access to vector search, text search, chunk expansion, and more. All backed by the Neo4j knowledge graph.</p><blockquote>If you’re interested to know more about Toolish RAG, <a href="https://medium.com/@springrod/building-a-chatbot-with-embabel-agentic-rag-b26a8346cb16">here</a> is a post by Rod Johnson. There is a s<a href="https://github.com/embabel/ragbot">ample application</a> Github that dives deeper on the topic.</blockquote><h3>Exposing MCP Tools</h3><p>We’ve even exposed these same tools via MCP, so you can use them from Claude Desktop or any MCP-compatible client too:</p><pre>@Bean<br>McpToolExport documentationRagTools(DrivineStore drivineStore) {<br> return McpToolExport.fromLlmReference(<br> new ToolishRag(&quot;docs&quot;, &quot;Embabel docs&quot;, drivineStore),<br> properties.toolNamingStrategy()<br> );<br>}</pre><p>The full implementation is available in the source code: <a href="https://github.com/embabel/guide">https://github.com/embabel/guide</a></p><h3>What Makes Embabel Different</h3><p>Whether you’re coming from Python AI frameworks or you’re a JVM veteran exploring agents, here are a few features that made building Jesse with Embabel a joy to build with.</p><ul><li><strong>Type-safe LLM outputs</strong> — LLM calls return real objects, not strings you have to parse. Read more about that <a href="https://medium.com/@springrod/from-alchemy-to-engineering-building-type-safe-gen-ai-applications-with-embabel-c3d89b7c989f">here</a> (or ask Jesse ;).</li><li><strong>Composable prompts</strong> — prompts are built from reusable, testable Jinja templates. Read about that <a href="https://medium.com/@springrod/building-a-chatbot-with-embabel-agentic-rag-b26a8346cb16">here</a> or . . . you know what to do ;)</li><li><strong>Agent-first design</strong> — retrieval, tools, memory, and flow are explicit parts of the model. We delved into that in this post, and will be talking more in future posts.</li></ul><h3>What’s Next for Embabel Hub?</h3><p>Today, Hub is focused on documentation. But we see it evolving into a broader platform for the Embabel ecosystem:</p><ul><li><strong>Agent Playground</strong> — experiment with agent configurations in a sandbox environment</li><li><strong>Integration Templates</strong> — starter projects for common use cases</li><li><strong>Community Showcase</strong> — see what others are building with Embabel</li></ul><p>We’re building in the open and would love your input on what would be most valuable. Let’s see where this goes together.</p><h3>Join the Bootstrap</h3><p>Embabel Hub is in early access, which means:</p><ul><li>Things might break (let us know!)</li><li>Your feedback directly shapes the roadmap</li><li>You’re among the early explorers of Embabel. While the community is still taking shape, the people here now have an outsized influence on where it goes next.</li></ul><p>Every bug you find, every question you ask Jesse, every feature you request — it all feeds back into both the Hub <em>and</em> the framework that powers it.</p><p>After a while incubating, the early access version will graduate to a cloud version. Shout-out to Michael Hunger, Andreas Kolleger and the folks at Neo4j for providing us a database instance!</p><blockquote><strong>A note on open source</strong>: Just about all of Embabel, including the Jesse guide is open-source. The Hub UI isn’t open-sourced yet, but several users have asked. We’re happy to do it. If that would be useful for you, let us know! The more the community wants it, the higher it climbs on the priority list.</blockquote><h3>Get Involved</h3><p>The best thing about open source is that we can shape it together.</p><p>Pull the image, ask Jesse some questions, and come build with us:</p><ul><li><strong>Docker Hub (early access)</strong>: <a href="https://hub.docker.com/r/embabel/hub">embabel/hub</a></li><li><strong>GitHub</strong>: Star the <a href="https://github.com/embabel/embabel-agent">repo</a>, open issues, submit PRs</li><li><strong>Guide/Jesse Source</strong>: See how it’s built —<a href="https://github.com/embabel/guide"> github.com/embabel/guide</a></li><li><strong>Discord</strong>: Join the <a href="https://discord.gg/t6bjkyj93q">community</a>, ask questions, share what you’re building</li></ul><p>Together we can build something great for the JVM ecosystem and beyond. We’re building Embabel with Embabel. Come build with us.</p><p>— -</p><p><em>Coming soon: a deeper dive into Drivine, the graph persistence layer that powers Embabel’s knowledge graph and makes structured RAG possible.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2b613901db60" width="1" height="1" alt=""><hr><p><a href="https://medium.com/embabel/from-docs-to-dialog-2b613901db60">From Docs to Dialog</a> was originally published in <a href="https://medium.com/embabel">Embabel</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Hydroxychloroquine as an adjunctive therapy for Hoarse Voice in the Merfolk — So the Sirens can…]]></title>
            <link>https://medium.com/@jasper.blues/hydroxychloroquine-as-an-adjunctive-therapy-for-hoarse-voice-in-the-merfolk-so-the-sirens-can-e4356e7fff1f?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/e4356e7fff1f</guid>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Thu, 21 Jul 2022 20:39:25 GMT</pubDate>
            <atom:updated>2023-09-22T22:46:43.197Z</atom:updated>
            <content:encoded><![CDATA[<h3>Hydroxychloroquine as an adjunctive therapy for Hoarse Voice in the Merfolk</h3><h3>A friend of mine was by day a famous doctor in a renowned institute. By night, healer to Mermen, maids and other fae-folk of the placid rivers and raging seas.</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*WRSlTYm5OVnuocDD.png" /></figure><p>Regarding these Merfolk and creatures of the deep: I asked him what, when they were ailed, heals them. (’Twas during a tea-house meet, late one afternoon in Bombay, at the onset of the Monsoon.) “Oh . . . Milk of Magnesia, Listerine, hydroxychloroquine. Things like that. Human meds”, he said, and shrugged.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*C1GCtyHWs3GJpm9r.png" /></figure><p>I wanted to discuss it at length, and in private, the next time I saw him, but he left one night shortly after that.</p><p>I got a letter a few weeks later. The envelope was damp and clammy and there was no return address. I wondered at bad news, preparing for a long and rambling tale, with the ink running, and paper made soggy by a thousand heart-broken tears. Yet inside was just a short note and picture. The latter having been taken, clearly, underwater. It showed him, happy, and in the romantic company of what can only be described as a Siren of the Sea. Captivating creatures! Even a picture presents an almost overbearing allure.</p><p>Anyway, we haven’t heard from him since, but I’d wager he’s still their doctor.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*XPIvV3-GcNb87XhK.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e4356e7fff1f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ROCK ’N’ ROLL TRAFFIC ROUTING, WITH NEO4J, PART 2]]></title>
            <link>https://medium.com/neo4j/rock-n-roll-traffic-routing-with-neo4j-part-2-f2a74fe7d7f?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/f2a74fe7d7f</guid>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[graph-algorithms]]></category>
            <category><![CDATA[neo4j]]></category>
            <category><![CDATA[graph-database]]></category>
            <category><![CDATA[shortest-path]]></category>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Fri, 24 Jul 2020 07:01:00 GMT</pubDate>
            <atom:updated>2020-07-29T07:39:25.469Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CG6cnok-zV9xiTJYkMcSmg.jpeg" /></figure><p><em>Originally posted on November 28, 2018 by </em><a href="https://liberation-data.com/blog.html"><em>Jasper Blues</em></a><em> in </em><a href="https://liberation-data.com/blog.html"><em>Saxeburg Series</em></a><em>.</em></p><p>This post is the second of my <a href="https://twitter.com/search?f=tweets&amp;q=saxeburg%20series&amp;src=typd"><strong>#saxeburg-series</strong></a>, for young entrepreneurs (or the young at heart), in which we’ll learn about Neo4j and have some fun at the same time. How? By building our own Neo4j-powered mobile game.</p><p>Originally at <a href="https://liberation-data.com/blog">Liberation Data</a>, the series will be continued on Neo4j’s own developer relations space — thanks so much to <a href="https://medium.com/@lju">Ljubica Lazarevic</a> and my friends at Neo4j for editing &amp; hosting.</p><h3>THE STORY CONTINUES</h3><p>I did plan on each of the Saxeburg Series having an accompanying short story, with Moongirl, and some new folks, who you will meet soon. Just like we had in the <a href="https://medium.com/neo4j/rock-n-roll-traffic-routing-with-neo4j-3a4b863c6030">first installment</a>.</p><p>Because, let’s face it, what could be more awesome than exploring <a href="https://en.wikipedia.org/wiki/Category:Graph_algorithms">graph algorithms</a>, aided by a menagerie of colorful albeit possibly criminally minded side-kicks? Especially if we place our beloved fictional friends into a city that is so dysfunctional, chaotic and downright dangerous that their very survival (wait, he survived!?) depends on the formulas we employ on their behalf.</p><p>However, I’ve been working on <a href="https://drivine.org/">a new open-source framework</a> for you. Therefore I didn’t have the time to prepare a new chapter this week. Tell you what though: <em>You</em> take the leading role for this installment, and I’ll have a new chapter for you soon, okay?</p><h3>LET’S BEGIN</h3><p>In the <a href="https://medium.com/neo4j/rock-n-roll-traffic-routing-with-neo4j-3a4b863c6030">last post</a> we learned how to perform traffic routing with Neo4j.</p><p>We discovered that Neo4j is accessible. With nothing more than a graph model, <a href="https://neo4j.com/developer/cypher-query-language/">Cypher</a> and a little creative thinking we were able to solve a real-world problem.</p><p>We also observed that Neo4j provides us with a <a href="https://neo4j.com/developer/graph-database/#property-graph">directed property graph</a> model. This gave us a lot of flexibility. Having solved the question “What is the most expedient route between two points in a city?” we immediately asked a new one. (By the way, don’t you find that this is exactly what happens in the real world? Business requirements <em>evolve</em>). With a few tweaks to our model, we were able to re-route traffic in the event of a road closure.</p><p>Today we’ll optimize our solution with the help of <a href="https://neo4j.com/graph-data-science-library/">Neo4j Graph Data Science Library</a>. This library, as the name suggests, provides a range of Graph Data Science algorithms. It’s maintained and officially supported by Neo4j, with participation from the community.</p><p>We’ll be accessing the libraries using a feature of Neo4j called <a href="https://neo4j.com/docs/java-reference/current/extending-neo4j/procedures/">stored procedures</a>. Stored procedures give us a way to call, from Cypher, routines that run on the graph. There’s a plethora of interesting open-source routines. It is also fun and easy to write your own. I will show you how to do that in a future post.</p><p>Just one of those libraries above would in fact, be enough to perform optimization today. However we’ll be making good use of both in subsequent posts. They’re both pretty interesting too, so let’s read on.</p><h3>GETTING SET UP</h3><p>You’ve got a number of options for getting Neo4j set up for this post. You can:</p><ul><li>Use <a href="https://sandbox.neo4j.com/?usecase=graph-data-science">Neo4j Sandbox Graph Data Science</a> use case. It already has GDS installed, just remove the existing data set before you continue. This is the no download, no install route.</li><li>Download and install <a href="https://neo4j.com/developer/neo4j-desktop/">Neo4j Desktop</a> and use the Plugin helper to install GDS.</li><li>Get set up on Neo4j using the server directly. If going down this route, you will need to manually install the GDS plugin. Make sure you’ve downloaded the right versions for the database you have installed. You will also need to grant access to the plugins in the neo4j.conf file.</li></ul><p>You can test out what procedures you’ve got available to you with the following command:</p><pre>call dbms.procedures()</pre><h3>WELCOME BACK TO SAXEBURG</h3><p>Its good to have you back!</p><p>You awaken after a fitful night’s sleep in some nondescript hotel in Pigalle. The driver wanted to take you to Red Light, but you you insisted on the more civilized North-east quarter.</p><p>Nonetheless, it seems <em>every</em> neighbourhood in Saxeburg hoists their red lights come nightfall. In fact, one shone, like a tainted moonbeam, from across the street through your hotel-room window. Bereft of curtains, as it was. Barely after your eyes had closed it crept like tendrils through shuttered lids and sparked the technicolors of your mind. Lurid dreams followed. Such fantasies leave you nary rested, thus, the morning sun came as a shock, seemingly moments later. Truth be told, you wouldn’t have minded staying in your dream a little longer, and yet now daylight beckons.</p><h3>COFFEE</h3><p>Coffee fixes everything. And the coffee is good, surprisingly good!</p><p>Outside, eleven floors below, the world’s most unlikely urban eco-system hums, grinds and teems with life. The sidewalks are full. People spill onto the road. Traffic overflows onto the crumbling, tree-lined pavement. No space is wasted. Hawkers have set up what seems to be the world’s most popular street-food stall on a traffic-island. The smoke from their grills wafts and mixes with that belched by a packed ten peso passenger jeep. Said jeep hurtles past, then slams on the brakes, with a squeal.</p><p>Meanwhile, at the demolition site next door, stray dogs are playing a game of chase, leaping and tumbling among piles of concrete debris. Atop one: a life-sized, smiling statue of Buddha in pock-marked golden plastic. Suddenly, two dogs and Buddha collide, then all three are tumbling down the rubble-side. Buddha’s face is alight, as though laughing, but the dogs don’t seem to notice. They too are absorbed in the present moment, in their game.</p><h3>STOP PEERING OUT THE WINDOW</h3><p>Hey! Come on, finish your coffee. We’ve got work to do!</p><p>Showered, and dressed for the day, you’re greeted out of your hotel-room door by dim, flickering lights, in a windowless elevator well. The floor is scuffed. An ancient lounge that sits on the opposite side of the elevator doors is flanked by two pot plants. Although plastic, they display drooping, thirsty leaves that seem to be pushing the limits of survival.</p><p>You wonder at the special kind of neglect it must take to kill a plastic pot plant! Probably the kind that is comfortable to scrawl “Out of Service” using what appears to be red lipstick on a piece scrap paper. Undoubtedly, the type that would then stick it to the elevator door with spent chewing gum.</p><p>At least the air-con is still working. It is attacking the fecund heat, keeping it at bay with an acrid smelling air that is two parts squalid, and one part you-don’t-want-to-know.</p><p>You reach the lobby after an eleven floor stair descent. Behind the counter, a beautiful human with remarkably androgynous features and a dashing red uniform greets you with a heartfelt “Good Morning!”. That sing-song intonation. Damn, you love the Saxeburgian accent.</p><p>You feel a little awkward though, when you ask “How do you prefer to be addressed?”.</p><p>There is no sign of offense taken in the answer. “I prefer she”, she laughs warmly, and hands you a brochure (Moongirl and the Bullhorns Tour Dates) along with a map of Saxeburg.</p><p>You’re not wearing your mixed-reality goggles, and so “Actual paper!”, you think to yourself, “How quaint!”</p><h3>ORIENTEERING</h3><p>Let’s reorient ourselves and take a little squiz at our map:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/0*bVWA1uLPrx1CuR8Q.jpg" /><figcaption><em>Saxeburg, c. 1986</em></figcaption></figure><p>Sheesh, it seems this map is from 1986! But we’ve got all the information we need: What I’m seeing is that:</p><ul><li>There are neighbourhoods. We are in Pigalle.</li><li>There are routes between each of them, neighbourhoods, that is.</li><li>Each route has an associated travel time or <em>cost</em>.</li></ul><p>What we are dealing with here is a <a href="https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)#Weighted_graph"><em>weighted graph</em></a>.</p><h3>WHAT IS A WEIGHTED GRAPH?</h3><p>As we learned previously, graph structures have been considered since antiquity, with path-finding being a classical application thereof.</p><p>Not long after <a href="https://en.wikipedia.org/wiki/Leonhard_Euler">Euler</a> came up with the <a href="https://en.wikipedia.org/wiki/Seven_Bridges_of_K%C3%B6nigsberg">first known graph</a>, folks started to develop variants applicable to different avenues of exploration. For example, <a href="https://medium.com/neo4j/rock-n-roll-traffic-routing-with-neo4j-3a4b863c6030?source=collection_detail----c0e10f7c3cc0-----3-----------------------">previously</a> we saw that a graph can be directed or undirected.</p><p>A weighted graph, then, is a graph in which each edge is given a numerical value. These numbers are usually taken to be positive. The value that is attached to an edge is what gives the edge its weight. The weight can represent cost, distance, throughput or some other property.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*UhusEIL8JObt4ilK.png" /><figcaption><em>A weighted graph.</em></figcaption></figure><h3>PROPERTY GRAPH MODEL VS WEIGHTED GRAPH</h3><p>Once again, we see that Neo4j’s property graph model is pretty versatile. Previously we explored how we can model graphs in which the relationships are bidirectional or undirected, even though, under the hood, all Neo4j relationship are directed. Do you remember?</p><p>Neo4j can happily serve as a weighted graph model too. There are various algorithms that deal with weighted graphs, probably the most famous of which is <a href="https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm">Djikstra’s</a>. That’s what we’ll use for routing today.</p><h3>DJIKSTRA’S ALGORITHM</h3><p>Dijkstra came up with his algorithm in 1956, although it wasn’t published until three years later. At the time, he was trying to come up with something to show off the new <a href="http://www-set.win.tue.nl/UnsungHeroes/machines/armac.html">ARMAC</a> mainframes. Bear in mind that this was the dawn of the electronic computing age. One of the challenges was to find a problem and solution that people not familiar with computing would be able to understand. Thus he designed a solution for finding the most expedient route between two points in a road network.</p><p>Perhaps it is a little ironic, then. Although he wanted the algorithm to be accessible for the layperson, budding computer scientists find it one of the more intimidating algorithms to grasp.</p><p>Here’s what the man himself had to say.</p><h3>IN HIS OWN WORDS</h3><p><em>“What is the shortest way to travel from Rotterdam to Groningen, in general: from given city to given city? It is the algorithm for the shortest path, which I designed in about twenty minutes. One morning I was shopping in Amsterdam with my young fiancée, and tired, we sat down on the café terrace to drink a cup of coffee and I was just thinking about whether I could do this, and I then designed the algorithm for the shortest path. As I said, it was a twenty-minute invention. In fact, it was published in ’59, three years late. The publication is still readable, it is, in fact, quite nice.”</em></p><p>– Edsger Dijkstra, in an interview with Philip L. Frana, Communications of the ACM, 2001</p><h3>MY TAKE ON THAT</h3><ul><li>There were only a handful of working programmers in the 1950s, however at least one of them was as enthusiastic about coffee as some of our modern comrades.</li><li>Djikstra was a rock star developer. Nothing pleases a rock-star-dev more than his or her own mad skillz.</li></ul><h3>LET’S BEGIN, THIS TIME FOR REAL</h3><p>We’re using the same graph as last time. Open your browser (either click ‘Open Browser’ on Neo4j Sandbox, ‘Open’ on Neo4j Desktop, or put <a href="http://localhost:7474/browser/">localhost:7474</a> into your favorite browser )and run <a href="https://gist.github.com/jasperblues/7a6e774090c9ef0f18c44920b48b6b23">this statement</a>.</p><p>To recap where we left off:</p><ul><li>We expressed our requirements (find the fastest route) in Cypher. It was a handful of lines of code.</li><li>We found candidate routes between two required destinations, trusting that Neo4j’s Cypher would choose the most appropriate path finding algorithm for us.</li><li>Using aggregation functions and ordering, we reduced that down to the best route.</li></ul><p>This got the job done. When the requirements evolved we were able to update our Cypher to match too. Pretty handy.</p><h3>MOST EXPEDIENT ROUTE</h3><p>There are graph models and corresponding algorithms for specific classes of problems. One of which is Djikstra’s Algorithm, as discussed. It is an optimal solution, for finding the most expedient route on a weighted graph. The algorithm has a time complexity of O(|E| + |V| log|V|) where V is the number of nodes and E is the number of edges (relationships).</p><p>Let’s get down to applying Djikstra’s algorithm with the <a href="https://neo4j.com/docs/graph-data-science/current/alpha-algorithms/shortest-path/">Graph Data Science Library</a>. By the way, if you would like to read about how the algorithm works, there are some <a href="https://medium.com/basecs/finding-the-shortest-path-with-a-little-help-from-dijkstra-613149fbdc8e">excellent tutorials</a> on that topic. We’ll see you back here when you’re done.</p><p>The brochure that Charm, from hotel reception, gave you this morning says that <em>Moongirl and the Bullhorns</em> are headlining at the Ruins tonight — an unplugged tribute to <a href="https://twitter.com/doctor_cerulean">Doctor Cerulean</a>. The concert starts at sunset. It is 5pm now. Let’s see if we can get you there on time:</p><pre>MATCH (a:Metro {name: &#39;Pigalle&#39;})<br>MATCH (b:Metro {name: &#39;The Ruins&#39;})<br>CALL gds.alpha.shortestPath.stream({<br>   nodeProjection: &#39;Metro&#39;,<br>   relationshipProjection: {<br>     HAS_ROUTE: {<br>       type: &#39;HAS_ROUTE&#39;,<br>   properties: &#39;travelTime&#39;,<br>   orientation: &#39;UNDIRECTED&#39;<br>      }<br>    },<br>   startNode: a,<br>   endNode: b,<br>   relationshipWeightProperty: &#39;travelTime&#39;<br>})<br>YIELD nodeId, cost<br>WITH gds.util.asNode(nodeId) AS nodes, cost<br>RETURN nodes, cost AS journeyTime</pre><h3>THE RESULTS:</h3><p>Notice how our query returned two columns. The first is a path, containing nodes and relationships, so we have a visualization available:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*7AouEoEF1TsZKy6M.png" /></figure><p>We can travel to The Ruins via China Town, Intramuros, Uptown and Brooklyn.</p><p>We returned weight, as journeyTime. Switching to the table tab and looking at our final stop, The Ruins, we can see that journeyTime is 29.5 minutes.</p><h3>MOST EXPEDIENT ROUTE IF THERE ARE CLOSURES</h3><p>Let’s solve the road closure problem. Previously, we entered all the Nodes we had to run Djikstra’s algorithm. This doesn’t account for road closures. We have to project a specific graph to be able to address these closures.</p><p>It turns out, we’ve already done a graph projection when we ran the last query, except that we projected the whole graph. What we can do is project a specific part of the graph we want to run the algorithm on, and to do that we’re going to use Cypher to help us.</p><p>First let’s ensure that each HAS_ROUTE relationship has a status property, and reset that status to ACTIVE.</p><pre>MATCH ()-[r:HAS_ROUTE]-() SET r.status = &#39;ACTIVE&#39;</pre><p>Now, we’ll close the route between Pigalle and China Town:</p><pre>MATCH (n:Metro {name: &#39;Pigalle&#39;})-[r:HAS_ROUTE]-(m:Metro {name:&#39;China Town&#39;})<br>SET r.status = &#39;CLOSED&#39;</pre><p>Finally we can use Cypher in our GDS algorithm to account for open roads when using shortest path:</p><pre>MATCH (a:Metro {name: &#39;Pigalle&#39;})<br>MATCH (b:Metro {name: &#39;The Ruins&#39;})<br>CALL gds.alpha.shortestPath.stream({<br>  nodeQuery: &#39;MATCH (n:Metro) RETURN id(n) as id&#39;,<br>  relationshipQuery:&#39;MATCH (n:Metro)-[r:HAS_ROUTE]-(m:Metro) WHERE r.status &lt;&gt; &quot;CLOSED&quot; RETURN id(n) AS source, id(m) AS target, r.travelTime AS travelTime&#39;,<br>  startNode: a,<br>  endNode: b,<br>  relationshipWeightProperty: &#39;travelTime&#39;<br>})<br>YIELD nodeId, cost<br>RETURN gds.util.asNode(nodeId).name, cost</pre><h3>THE RESULTS:</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*49mjWrMI16wV7if8.png" /></figure><p>A road closure between Pigalle and China Town would increase the journey time to 35 minutes.</p><h3>CONCLUSION</h3><p>Today we explored weighted graphs and Djikstra’s Algorithm with Neo4j. We discovered that Neo4j puts the power of graph algorithms at our fingertips. We also learned that we can project the property graph model to other graph models.</p><p>Please stay tuned for the next installment. I hope that you enjoyed this one! If you did, why not tell your friends about the fun that can be had when <a href="https://twitter.com/search?f=tweets&amp;q=%23doctor-cerulean-liberates-your-data&amp;src=typd">#doctor-cerulean-liberates-your-data</a>.</p><p>Thanks a lot!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/64/0*DCAOEF9SQTtoyBIE.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f2a74fe7d7f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/neo4j/rock-n-roll-traffic-routing-with-neo4j-part-2-f2a74fe7d7f">ROCK ’N’ ROLL TRAFFIC ROUTING, WITH NEO4J, PART 2</a> was originally published in <a href="https://medium.com/neo4j">Neo4j Developer Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ROCK ’N’ ROLL TRAFFIC ROUTING, WITH NEO4J]]></title>
            <link>https://medium.com/neo4j/rock-n-roll-traffic-routing-with-neo4j-3a4b863c6030?source=rss-a2f1c9915fa------2</link>
            <guid isPermaLink="false">https://medium.com/p/3a4b863c6030</guid>
            <category><![CDATA[route-planning-software]]></category>
            <category><![CDATA[traffic]]></category>
            <category><![CDATA[data-science]]></category>
            <category><![CDATA[neo4j]]></category>
            <dc:creator><![CDATA[Jasper Blues]]></dc:creator>
            <pubDate>Fri, 03 Jul 2020 11:07:24 GMT</pubDate>
            <atom:updated>2020-07-28T01:17:38.811Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Originally posted on November 28, 2018 by </em><a href="https://liberation-data.com/blog.html"><em>Jasper Blues</em></a><em> in </em><a href="https://liberation-data.com/blog.html"><em>Saxeburg Series</em></a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wmvN54xOjNRLsXt6c-pvvQ.jpeg" /></figure><p>This post is the first of my <a href="https://twitter.com/search?f=tweets&amp;q=%23saxeburg-series&amp;src=typd"><strong>#saxeburg-series</strong></a>, for young entrepreneurs (or the young at heart), in which we’ll learn about Neo4j and have some fun at the same time. How? By building our own Neo4j-powered mobile game.</p><p>Originally at <a href="https://liberation-data.com/blog">Liberation Data</a>, the series will be continued on Neo4j’s own developer relations space — thanks so much to my friends at Neo4j for hosting.</p><h3>LET’S BEGIN</h3><p>Have you ever wondered how apps like Google Maps or Waze provide turn by turn directions and offer the fastest route, as well as respond to changing traffic conditions in realtime?</p><p>Today I will show you how to use Neo4j for traffic routing, and it will only take a few minutes.</p><p>As you will soon see, we could pick any city that we like as a case study, however for the sake of this article let us imagine a sprawling nation-state that is part Paris, part Metro Manila and part Coney Island. Are you with me?</p><p>Such a city could be represented in topographical form like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/0*Jb91UWqOS4HkpW_l.jpg" /><figcaption><em>Saxeburg, c. 1986</em></figcaption></figure><h3>DOCTOR CERULEAN</h3><p>Towards the task at hand let us also imagine Dr Cerulean, the charismatic founding forefather of our thriving metropolis. Charisma aside, he is unfortunately a calamitously lazy man and one prone to numerous vices at that. Most especially wine, women and song.</p><p>We are going somewhere with this, but I would ask that you please stretch your imagination <em>just</em> a little more, to accommodate the following notion: On the night before he was due to present an inaugural city charter, our dear Doctor was in Phoenix sampling the Cactus Juice, which is very good down that way. And unfortunately also lethal on this occasion.</p><h3>THE LAST DAY OF DOCTOR CERULEAN’S LIFE</h3><p>OK, so here we are on the last day of our city founding father’s life. We will get to the traffic routing in a moment, but I think we better address this matter at least briefly, as it would be disrespectful to brush over, wouldn’t it?</p><p>Doctor Cerulean commenced his last day, after waking from an hour or two of sleep. He discovered himself in a compromising position, but was otherwise feeling quite fantastic. Violently alive, you could say. The city charter, however was nowhere in sight — the task of preparing one having been neglected months prior.</p><p>You might think this sounds like the start of a day where things aren’t going to go all that well, and you’d be right.</p><p>However, at this point, I can elaborate on some of the soon-to-be departed Doctor’s redeeming qualities. For one, he is deliciously playful. Two, he’s remarkably resourceful and quite inventive to boot.</p><p>You see, the night prior, there was a fantastic party taking place in the science department of Phoenix’ very party-oriented fledgling university campus. Thus, the Doctor found himself, that morning, regaining some semblance of consciousness, drooling onto a <a href="https://en.wikipedia.org/wiki/Periodic_table#/media/File:Simple_Periodic_Table_Chart-en.svg">Periodic Table of Elements</a>.</p><p>Having awoken at ten, and due to present the city charter at eleven, our Doctor performed a momentous feat. He gathered up the table of elements, crossed out the carbon; nitrogen; phosphorus; oxygen; sulphur; selenium various noble gasses and so forth until there was nothing left but <em>what</em>? Exactly: <em>metal</em>. On top of this, he scrawled, in black marker pen: “<strong>The People Will Rock!</strong>”.</p><p>And so, this is the document he presented in lieu of an actual city charter, in front of the assembled town hall, and those were in fact the last words he uttered. They were spoken with enthusiasm and with arm held aloft, fingers formed into a pair of horns.</p><p>He then promptly collapsed and died, on stage, making quite a show of it.</p><p>The doctors (actual qualified ones) wrote “general congestion in all systems”, which was a polite way of saying “excess of Cactus Juice”, back in those days.</p><h3>DON’T CRY</h3><p>Finally, here we are, ready to commence our traffic routing exercise! Woo hoo! However, hmmmm . . . now I’m a little worried about you.</p><p>Maybe this story of Doctor Cerulean, has moved you. Rocked your emotional core, so to speak. Perhaps even to the point of overcoming your powers of cognition. The thing is, you are going to need those.</p><p>Therefore I would say to you this: Do not shed a tear! The good Doctor’s statue stands aloft in Intramuros to this day. He is looking very dapper, albeit simultaneously a little worse for wear. His arm is raised, just as it was in those last moments, in an ever enduring veneration of metal and hard-living.</p><p>Meanwhile Saxeburg is thriving, it really is. And I tell you <em>what</em>, the people certainly did rock! Every neighbourhood adopted an elemental metal, enshrined it with a stage and auditorium with standing area for thousands. There are full light-show capabilities (on days that the town’s electricity supply is functioning), you name it.</p><h3>MOONGIRL AND THE BULLHORNS</h3><p><em>Now</em>, the show is on the road. Ladies and gentlemen, I would like to welcome you to present-day Saxeburg, and introduce you to <em>Moo-oooonngirl and the Bullhorns!</em> (Moongirl, please take a bow).</p><p>Moongirl is the nubile lead singer of Saxeburg’s premier Rock and Roll show and the Bullhorns are the tightest backing band in the business. A dashing bunch of brutes too.</p><p>Moongirl and her band put on a show every night of the year, and they love what they do. There is only one problem.</p><p>The traffic in Saxeburg is bloody <em>terrible</em>!</p><h3>LET’S BEGIN, THIS TIME FOR REAL</h3><p>Moongirl has been spending the day at the beach, with her boys. Meanwhile she is head-lining at the Grand Théâtre de Rabat in NYC tonight. Let’s see if we can get her to the gig on time.</p><p>You’ve got a couple of ways of following along. You can either have a local instance of Neo4j running on your machine. If you don’t, you can use a <a href="http://neo4j.com/sandbox">blank sandbox </a>— and you don’t have to download or install anything.</p><h3>DATA INGESTION</h3><p>Open your browser (either <a href="http://localhost:7474/browser/">localhost:7474</a> if you’re using a local instance, or click ‘Open Browser’ on <a href="http://neo4j.com/sandbox">sandbox</a>) and run <a href="https://gist.github.com/jasperblues/7a6e774090c9ef0f18c44920b48b6b23">the statement in this gist</a>.</p><p>Having run the gist above, now run:</p><pre>match (n) return n;</pre><p>This yields a graph that will look something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*bUSRbSkAUOJiDfTu.png" /></figure><p>The first thing that you might notice is that it looks nothing like our topographical map. So what gives?</p><h3>GRAPH THEORY</h3><p>Well, you probably know that graph databases are based on a branch of mathematics, in the field of combinatorics called graph theory; that in fact graph theory itself emerged from an exercise in path-finding:</p><p>Euler’s solution of the <a href="https://en.wikipedia.org/wiki/Seven_Bridges_of_K%C3%B6nigsberg">Königsberg bridge problem</a> is considered to be the first theorem of graph theory and the first true proof in the theory of networks. Additionally Euler recognised that the key information was the number of bridges and the list of their endpoints rather than their exact positions.</p><p>So there’s that.</p><h3>MORE GRAPH THEORY</h3><p>But it is quite a rabbit hole, actually.</p><p>While combinatorial problems have been considered since antiquity and graph theory emerged some three hundred years ago, network structures remain an <a href="https://arxiv.org/pdf/1710.01144.pdf">area of research interest</a> to this day.</p><p>The practical ramifications are endless. Some examples of applied graph theory are:</p><ul><li>Recommendation engines</li><li>Root cause analysis</li><li>Fraud Detection</li></ul><p>Something that makes Neo4j so compelling is that it puts graph algorithms for real-time transactional data at your fingertips.</p><p>In fact later in this series we will be applying graph theory to solve a crime. Or maybe (shocking thought) to get away with one. Which will it be?</p><p>Of course this is a suspenseful blog series so you’ll have to wait. In the meantime our sassy urbanite is starting to get tetchy about being late for her gig, so we’d better press on!</p><h3>BIDIRECTIONAL RELATIONSHIPS</h3><p>Something else that you might notice is that the HAS_ROUTE relationships are directional - we can see this on the visualisation, because, yep, nice one Sherlock. They have arrows on one end.</p><p>However, we have actually modelled Saxeburg as an undirected graph. <em>But</em>, all relationships in Neo4j are <em>directed</em>.</p><p>So what is happening here? Well, the CYPHER query language allows us to ignore direction when it is not relevant. You can see an example of that on the merge statements to create those HAS_ROUTE relationships, and we’ll employ it again in a moment.</p><h3>EXPLORING ROUTES</h3><p>Let’s run the following CYPHER:</p><pre>MATCH (n:Metro)-[r:HAS_ROUTE]-(m:Metro)<br>RETURN n.name, r.travelTime, m.name<br>  LIMIT 5;</pre><p>This yields the following results:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*943vZo-qbmEaYphk.png" /></figure><p>We can see that each Metro has a route to various other metros, and that the average travel time has been recorded.</p><h3>MOST EXPEDIENT ROUTE</h3><p>Using the information at hand, we can now easily find the most expedient route from Cavite Island to NYC:</p><pre>MATCH paths = (a:Metro {name: &#39;Cavite Island&#39;})-[:HAS_ROUTE*1..6]-(b:Metro {name: &#39;NYC&#39;})<br>WITH paths, relationships(paths) AS rels<br>UNWIND rels AS rel<br>WITH [metro IN nodes(paths) | metro.name] AS metros,<br>     collect(rel.travelTime) AS streets,<br>     sum(rel.travelTime) AS travelTime<br>  ORDER BY travelTime<br>RETURN metros, streets, travelTime</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*60YXNtJIHupKOcU2.png" /></figure><p>This query tells us the following:</p><ul><li>Moongirl will get to her gig on time — she can reach NYC in 26 minutes.</li><li>She can wave at Doctor Cerulean’s statue on the way — the fastest route is via Intramuros and China Town.</li></ul><h3>ROAD CLOSURES</h3><p>Let’s expand our model to handle road closures.</p><pre>MATCH (:Metro)-[r:HAS_ROUTE]-(:Metro)<br>SET r.status = &#39;ACTIVE&#39;;</pre><p>The citizens of Saxeburg decide to throw their television sets out of their windows. It causes road closures between China Town and Ermita, and also between Intramuros and China Town.</p><pre>MATCH (:Metro {name:&#39;China Town&#39;})-[r1:HAS_ROUTE]-(m:Metro {name: &#39;Ermita&#39;})<br>WITH r1<br>MATCH (:Metro {name:&#39;Intramuros&#39;})-[r2:HAS_ROUTE]-(m:Metro {name: &#39;China Town&#39;})<br>SET r1.status = &#39;CLOSED&#39;<br>SET r2.status = &#39;CLOSED&#39;;</pre><p>Now we can extend our initial query as follows:</p><pre>MATCH paths = (a:Metro {name: &#39;Cavite Island&#39;})-[:HAS_ROUTE*1..6]-(b:Metro {name: &#39;NYC&#39;})<br>WITH paths, relationships(paths) AS rels<br>                    where all(rel IN rels WHERE coalesce(rel.status, &#39;ACTIVE&#39;) = &#39;ACTIVE&#39;)<br>UNWIND rels AS rel<br>WITH [metro IN nodes(paths) | metro.name] AS metros,<br>     collect(rel.travelTime) AS streets,<br>     sum(rel.travelTime) AS travelTime<br>  ORDER BY travelTime<br>RETURN metros, streets, travelTime</pre><p>We can see that:</p><ul><li>Travel time increases 29.6 minutes</li><li>The best route is now via Intramuros, St Germain and China Town.</li></ul><h3>CONCLUSION</h3><p>Today we learned how to use Neo4j to perform traffic routing.</p><p>There is a lot more that we could do, however I would like <em>you</em> to think about it, and see where it leads you. How would you extend the model? Maybe handling delays? Turn by turn directions? What about performance concerns with much larger datasets?</p><p>Have a try for yourself and tweet your discoveries to <a href="https://twitter.com/doctor_cerulean"><strong>@doctor_cerulean</strong></a> hashtag <a href="https://twitter.com/search?f=tweets&amp;q=%23doctor-cerulean-liberates-your-data&amp;src=typd"><strong>#doctor-cerulean-liberates-your-data</strong></a>.</p><p>We also learned today that:</p><ul><li>Neo4j is accessible. We can analyse network structures and solve real-world problems, without necessarily needing to know a lot about graph theory or combinatorics.</li><li>Network structures have tremendous <em>plasticity</em>. We can enhance our model to encompass evolving requirements. And because Neo4j is transactional we can be assured of data consistency for large-scale, fluid networks. This is a powerful combination. In fact it makes Neo4j compelling for AI applications. We will explore that, with Moongirl, in a future post.</li></ul><p>Please stay tuned for the next instalment. I hope that you enjoyed this one! If you did, why not tell your friends about the fun that can be had when <a href="https://twitter.com/search?f=tweets&amp;q=%23doctor-cerulean-liberates-your-data&amp;src=typd"><strong>#doctor-cerulean-liberates-your-data</strong></a>.</p><p>Thanks a lot!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/64/0*oLxxqRFBbFg3oNcY.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3a4b863c6030" width="1" height="1" alt=""><hr><p><a href="https://medium.com/neo4j/rock-n-roll-traffic-routing-with-neo4j-3a4b863c6030">ROCK ’N’ ROLL TRAFFIC ROUTING, WITH NEO4J</a> was originally published in <a href="https://medium.com/neo4j">Neo4j Developer Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>