<?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 manav ghosh on Medium]]></title>
        <description><![CDATA[Stories by manav ghosh on Medium]]></description>
        <link>https://medium.com/@manavghosh?source=rss-37f405263f94------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*P3-A1x_WkNMAONyA.jpg</url>
            <title>Stories by manav ghosh on Medium</title>
            <link>https://medium.com/@manavghosh?source=rss-37f405263f94------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 12:58:12 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@manavghosh/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[Your Broker Now Speaks English, Part 1: Research and Portfolio Reviews with Claude and Dhan]]></title>
            <link>https://medium.com/@manavghosh/your-broker-now-speaks-english-part-1-research-and-portfolio-reviews-with-claude-and-dhan-d544c87629b5?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/d544c87629b5</guid>
            <category><![CDATA[claude]]></category>
            <category><![CDATA[trading]]></category>
            <category><![CDATA[fintech]]></category>
            <category><![CDATA[dhan]]></category>
            <category><![CDATA[claude-code]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Wed, 07 Oct 2026 03:40:14 GMT</pubDate>
            <atom:updated>2026-10-07T03:40:14.795Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Bie6qJP84YiJ-7ad6y8bCg.png" /></figure><p><em>How an amateur F&amp;O trader connected a live Dhan account and Exa research to Claude, and turned four browser tabs into one conversation.</em></p><blockquote><strong>Disclosure:</strong> I’m not a professional trader, and I’m not a SEBI-registered investment adviser or research analyst. I’m an enterprise architect and an AI and agentic systems architect who’s learning the financial markets as an amateur trader, and my focus is on building a trading system with AI, not on telling anyone what to trade. Nothing here is investment advice. You’ll find the full disclosure, and some guardrails for practising this setup, near the end.</blockquote><p>Let me start with a morning you might recognise.</p><p>It’s 9:14 AM on a weekly expiry Tuesday. Nifty has opened gap-down, and India VIX is climbing. (India VIX is the NSE’s volatility index. People often call it the market’s fear gauge, because it rises when traders expect big swings.) You have four tabs open: your broker terminal, an option chain, a news site, and a spreadsheet where you’re working out your margin by hand. You flick between them, piece the story together, and by the time it all makes sense, the first fifteen minutes of trading have already gone.</p><p>Now imagine the same morning with a single window. You type one request, in ordinary English:</p><blockquote>“Show my open positions, the margin I’m using, and the three news items most likely to move Nifty today. Then tell me which of my short strikes is closest to being breached.”</blockquote><p>A few seconds later, you have your answer. It’s built from your live broker account and from fresh research on the web, side by side.</p><blockquote><strong>A quick note before we go on: this is a two-part series.</strong> In <strong>Part 1</strong>, the one you’re reading now, you’ll learn to talk to your trading account: connecting Dhan to Claude, researching the market, and reviewing your portfolio in plain English. You won’t need to write any code. In <strong>Part 2, coming soon</strong>, you’ll learn to build: turning a trading idea into a working algorithm with Claude Code, safely, one gate at a time. Each part stands on its own, and together they take you from your first question to your first live algorithm.</blockquote><p>This isn’t a futuristic demo. You can set it up today. Dhan, one of India’s fastest-growing discount brokers, now offers two ways for software to talk to your account:</p><ul><li><strong>An official MCP server.</strong> MCP stands for Model Context Protocol. It’s an open standard that lets an AI assistant discover tools and use them, a bit like a common plug that any appliance built to the standard can use.</li><li><strong>A mature REST API, called DhanHQ v2.</strong> A REST API is the plain web interface that your own programs talk to.</li></ul><p>Connect these to Claude Desktop or Claude Code, add a research tool such as Exa (a search engine built for AI assistants), and something lovely happens. Your broker starts to understand plain English.</p><p>If there’s one idea I’d like you to carry through this whole tutorial, it’s this one. <strong>The terminal was never the real advantage. The quality of the question was.</strong> These tools make it much easier to ask good questions, and this guide is about learning to ask them.</p><p>Here’s what we’ll build together in this first part. By the end of it, you’ll have:</p><ol><li>Dhan connected to Claude Desktop (and claude.ai), so you can research and review your portfolio in conversation.</li><li>Five ready-made research workflows for Indian equities.</li><li>Five portfolio workflows that act like a patient risk officer.</li><li>A few simple safety habits to keep you in control.</li></ol><p>Don’t worry if some of these terms are new. We’ll take them one step at a time.</p><h3>The Core Insight: Three Layers, One Conversation</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1H6AA-GqzzcDF9bIZN-Qdg.png" /></figure><p>Before we change a single setting, it helps to see the whole picture. Once you understand the shape of the system, every step that follows will feel like it has a reason.</p><p>Here’s a simple way to picture it. Think of a small trading desk with three people on it:</p><ul><li>a <strong>terminal operator</strong>, who watches your account and the live market;</li><li>a <strong>quant</strong>, who writes and runs code;</li><li>a <strong>research analyst</strong>, who reads the news so the other two don’t have to.</li></ul><p>Claude sits in the middle of the desk and talks to all three. Each of them maps to one layer of our setup.</p><p><strong>Layer 1 is the Dhan MCP server, our terminal operator.</strong> It’s Dhan’s own hosted connection point, and it links your live account to any MCP-compatible app. Through it, Claude can look at your portfolio, market data and margin, set alerts, and (only with your permission) place orders. Every session asks for your explicit consent (<a href="https://docs.dhanhq.co/mcp/">DhanHQ docs</a>). This is the layer you’ll use for conversation.</p><p><strong>Layer 2 is the DhanHQ Agent Skill and the Python SDK, our quant.</strong> The skill is a package of instructions that teaches a coding assistant how the DhanHQ v2 APIs work. The SDK (software development kit) is Dhan’s official Python library, which runs your code without you needing to sit and watch it (<a href="https://github.com/dhan-oss/dhanhq-skills">dhanhq-skills</a>). This is the layer you’ll use for building, from inside Claude Code, and it’s the star of Part 2.</p><p><strong>Layer 3 is a research MCP such as Exa, our analyst.</strong> Your broker knows prices and positions, but it doesn’t read the news. Exa fills that gap with news, company filings, policy updates and analyst commentary. Claude Code can use Exa too, but you’ll find yourself using it most in Claude Desktop.</p><p>Why does this picture matter? Because every workflow later in this guide is a different way of combining these three layers. If you ever feel lost, come back to this diagram and ask, “Which layer is doing the work here?”</p><p>And here’s the lesson hiding inside it. <strong>The AI model isn’t where the advantage comes from. The advantage comes from the question you ask, and the data you connect it to.</strong></p><h3>Before You Start: What You’ll Need</h3><p>Let’s gather everything in one place before we begin. For this first part, you only need four things, and once they’re ready, the rest is mostly copy and paste.</p><ul><li><strong>A Dhan trading account.</strong> If you plan to trade derivatives, you’ll also need F&amp;O activated. (F&amp;O stands for futures and options, India’s derivatives segment.) Opening the account is free, and this is the account Claude will read from and, with your approval, act on.</li><li><strong>DhanHQ Trading API access.</strong> This covers orders, your portfolio, funds and margin. It’s free, with no monthly charge (<a href="https://docs.dhanhq.co/mcp/">DhanHQ docs</a>).</li><li><strong>A DhanHQ Data API plan.</strong> This is the part that unlocks market data: live quotes, market depth, the option chain with Greeks, and historical OHLC candles. (OHLC means open, high, low and close, the four prices that make up each candle on a chart.) The plan costs ₹499 plus taxes a month and renews every 30 days (<a href="https://dhan.co/support/platforms/dhanhq-api/how-does-the-dhanhq-data-api-subscription-work/">Dhan support</a>).</li><li><strong>Claude Desktop or claude.ai.</strong> You’ll need a Claude plan that supports custom connectors.</li></ul><p>An Exa API key is optional, but I’d strongly recommend one for the research workflows. (Part 2 adds a few more items for coding, such as Claude Code, Python and a static IP address. You don’t need any of them yet.)</p><p>Let me share a small lesson I learned the hard way, because it might save you an evening. When I first connected Dhan to Claude, my portfolio questions worked perfectly, yet every request for a quote or an option chain came back with Unauthorized. I assumed something was broken. It wasn&#39;t. The Trading API is free, but the Data API is a separate subscription, and I hadn&#39;t switched it on. So if you see that error, check your Data API plan before you suspect the MCP server.</p><h3>Connect Dhan to Claude Desktop in Five Minutes</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mxn3LU6V8v7A_EeKfIKNbQ.png" /></figure><p>We’ll start with the easiest win: talking to your account from Claude Desktop. The nice thing about Dhan’s official MCP server is that it’s hosted for you, so there’s nothing to install. The same connection works in Claude Desktop, in claude.ai on the web, and in the Claude mobile app.</p><h3>Step 1: Add Dhan as a custom connector</h3><p>A “connector” is how Claude learns about an outside service. Here’s how to add one for Dhan:</p><ol><li>Open Claude Desktop (or claude.ai) and go to <strong>Settings → Connectors</strong>. On newer versions, this takes you to <strong>Customize → Connectors</strong>.</li><li>Click <strong>+</strong> and choose <strong>Add custom connector</strong>.</li><li>Give it the name Dhan, and paste in this address: https://mcp.dhan.co/mcp. You&#39;ll see optional fields for an OAuth client ID and secret under the advanced settings; you can leave those empty.</li><li>Click <strong>Add</strong>, then <strong>Connect</strong>. Claude sends you to Dhan’s own login page, where you sign in with your usual credentials and 2FA (two-factor authentication, the second code you enter after your password).</li></ol><p>A question people often ask at this point: “Does Claude see my password?” It doesn’t. You log in on Dhan’s page, and Dhan gives Claude permission for that session. Your password never passes through the chat.</p><h3>Step 2: Decide what Claude may do without asking</h3><p>This step is about trust, so let’s slow down for a moment.</p><p>Think of a joint bank account. Anyone on the account can check the balance whenever they like, but a withdrawal needs a second signature. We want exactly that arrangement with Claude.</p><p>Open the Dhan connector’s settings, and you’ll see a list of tools. For each tool you can choose whether Claude may use it freely or must ask you first.</p><ul><li><strong>Reading tools</strong> (holdings, positions, quotes, option chain) are safe to set to <strong>Always allow</strong>. Looking can’t hurt you.</li><li><strong>Order tools</strong> (anything that places, modifies or cancels an order) should be set to <strong>Ask first</strong>.</li></ul><p>You might wonder whether this is necessary, since Dhan already has its own safety checks. It’s true that Dhan asks for confirmation before orders and defaults to LIMIT orders (<a href="https://docs.dhanhq.co/mcp/">DhanHQ docs</a>). But a second gate on your side costs you one click, and it protects you from the day a vaguely worded request gets misunderstood. Two signatures are better than one.</p><h3>Step 3: Check that it’s working</h3><p>Start a new chat, switch on the Dhan connector from the tools menu, and type:</p><pre>Check my holdings, open positions and available funds on Dhan.</pre><p>If your session has expired, Claude will give you a Dhan login link instead. That’s normal. Complete the login, come back, and ask again.</p><p>When it works, you’ll see Claude call the portfolio tool and reply with a summary. Here’s a satisfying little test: compare the numbers with your Dhan terminal. They should match to the paisa. That’s how you know Claude is reading your real account, not guessing. And if quotes or option chains fail with Unauthorized, you already know the fix: activate the Data API plan.</p><h3>What can Claude actually reach?</h3><p>Now that you’re connected, it’s worth knowing what Claude can see. The connector offers around a dozen tools. The exact names may vary slightly in your version, but they fall into these families, and I’ve added an example question for each so you can try them straight away:</p><ul><li><strong>Portfolio:</strong> your holdings, positions, funds and today’s trades. Try: <em>“What’s my unrealised P&amp;L (profit and loss) by position?”</em></li><li><strong>Order book and tradebook:</strong> pending orders, executed trades, and trades by order ID. Try: <em>“Show today’s fills and average prices.”</em></li><li><strong>Market data:</strong> the LTP (last traded price), OHLC, a full quote with market depth, the option chain with Greeks, and the list of expiries. Try: <em>“Nifty option chain for the nearest expiry, and highlight the strikes with the most open interest.”</em></li><li><strong>Historical data:</strong> daily and intraday candles. Try: <em>“Six months of daily candles for HDFCBANK.”</em></li><li><strong>Margin:</strong> the margin needed for one order or a basket of orders. Try: <em>“Margin to sell a Nifty 24000/24200 call spread.”</em></li><li><strong>Orders and alerts:</strong> placing, modifying and cancelling orders (including super orders), plus price and indicator alerts. Try: <em>“Alert me if TCS closes below its 50-day average.”</em></li></ul><h3>Step 4: Add a research tool alongside Dhan</h3><p>Here’s an important limitation to understand. Your broker knows your account and the live market, but it has no idea <em>why</em> the market moved. For that, we add a second connector.</p><p>Add Exa as another custom connector, with the address https://mcp.exa.ai/mcp. Exa brings in news, company filings and analyst commentary.</p><p>If you’d like market-wide fundamentals and stock screeners across NSE and BSE (India’s two main stock exchanges), research-focused Indian MCP servers pair well with a broker. Tapetide is one example. It’s a data service covering roughly 8,200 listed stocks, with a ratio screener and FII/DII flows, and you don’t need a brokerage account to use it (<a href="https://dev.to/govind_sisara/indian-stock-market-mcp-the-best-mcp-servers-for-nse-bse-data-2026-p28">DEV Community comparison</a>).</p><h3>Prefer to keep everything on your own machine?</h3><p>Some people prefer not to use a hosted service, and that’s a perfectly reasonable choice. Community-built servers such as dhan-mcp-server run locally over stdio. (Stdio means standard input and output; in practice, Claude starts the server as a small program on your own computer.)</p><p>To set one up, add the following to claude_desktop_config.json, which lives in %APPDATA%\Claude\ on Windows and ~/Library/Application Support/Claude/ on macOS, then restart Claude Desktop:</p><pre>{<br>  &quot;mcpServers&quot;: {<br>    &quot;dhan-local&quot;: {<br>      &quot;command&quot;: &quot;dhan-mcp-server&quot;,<br>      &quot;env&quot;: {<br>        &quot;DHAN_CLIENT_ID&quot;: &quot;your_client_id&quot;,<br>        &quot;DHAN_ACCESS_TOKEN&quot;: &quot;your_access_token&quot;<br>      }<br>    }<br>  }<br>}</pre><p>Every choice has a trade-off, so here’s this one. A local server works only on that one computer, community servers usually offer fewer tools, and you’ll need to renew the access token yourself. For most people, the hosted connector is the better place to start.</p><h3>Market Research Workflows for Indian Equities</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ukGD1qXgpIUsVauyak0T4w.png" /></figure><p>With the setup done, we arrive at the part I enjoy most: actually using it.</p><p>Every workflow in this section follows one simple pattern, and once you see it, you’ll be able to design your own. <strong>Exa tells you why the market moved. Dhan tells you what moved, and at what price. Claude connects the two.</strong></p><p>Why do we need both? Because each one alone is incomplete. Research without live prices is like reading yesterday’s newspaper. Prices without research is like playing a slot machine. Put together, they give you understanding.</p><p>Let’s ground this in a real month. September 2026 was a tough one. The Nifty 50 fell 6.1% to close at 22,620.45 on 30 September, its worst September since 2018. Crude oil climbed above $100 a barrel, the US Federal Reserve raised rates, and foreign investors sold heavily (<a href="https://www.brecorder.com/news/40441987/india-benchmark-shares-log-worst-month-since-march-as-oil-global-rate-hikes-spark-outflows">Reuters</a>, <a href="https://www.thehindubusinessline.com/markets/september-rout-makes-history-nifty-posts-worst-monthly-fall-in-8-years-worst-series-drop-since-2001/article71528719.ece">BusinessLine</a>). FIIs (foreign institutional investors) sold a net ₹44,013 crore of Indian shares that month, while DIIs (domestic institutional investors, such as Indian mutual funds) bought ₹76,030 crore (<a href="https://www.moneycontrol.com/news/business/markets/nifty-down-nearly-13-in-2026-as-september-delivers-11-of-fiis-year-to-date-selling-14042636.html/amp">Moneycontrol</a>).</p><p>Months like that are exactly when a calm, structured morning routine earns its keep. So let’s build one.</p><h3>Workflow 1: The 9:00 AM pre-market brief</h3><p>This first workflow gives you a clear picture of the day before the market opens. Run it in Claude Desktop with both Dhan and Exa switched on:</p><pre>Build my pre-market brief for Indian equities today.<br>1. From Dhan: Nifty 50 and Bank Nifty previous close, and daily candles for the last 20 sessions.<br>2. From Exa: GIFT Nifty indication, overnight US and Asian markets, crude and USD/INR,<br>   provisional FII/DII cash flows, and any India-specific news since yesterday&#39;s close.<br>3. Flag scheduled events this week: RBI policy, major results, F&amp;O expiry.<br>End with three bullets: likely opening tone, key levels to watch, and one risk I may be underestimating.</pre><p>Two terms in that prompt deserve a short explanation. <strong>GIFT Nifty</strong> is the Nifty futures contract traded at GIFT City, India’s international financial centre in Gujarat. Because it trades before the Indian market opens, it’s the best early hint of how the day might begin. The <strong>RBI</strong> is the Reserve Bank of India, and its policy meetings move interest rates, and with them, bank stocks.</p><p>Look closely at how the prompt is built, too. Each line says where a fact should come from. That small habit makes a big difference, and we’ll come back to it at the end of this section.</p><h3>Workflow 2: Read the option chain like a desk analyst</h3><p>The option chain can feel overwhelming at first, so let’s ask Claude to do the heavy lifting:</p><pre>Pull the Nifty option chain for the nearest weekly expiry from Dhan.<br>Compute PCR on OI, the max-pain strike, the three strikes with the highest call and put OI,<br>and the change in OI versus the previous session.<br>Describe the IV skew between 5% OTM puts and calls.<br>What range is the market pricing for expiry? Present one table and three sentences.</pre><p>If some of these terms are unfamiliar, here’s a gentle glossary:</p><ul><li><strong>OI (open interest)</strong> is the number of contracts still open at a strike. Think of it as how many people are holding a position there.</li><li><strong>PCR (put-call ratio)</strong> divides put OI by call OI. It’s a rough reading of sentiment: a higher number suggests more traders are buying protection.</li><li><strong>Max pain</strong> is the strike where option buyers, as a group, would lose the most money at expiry.</li><li><strong>IV (implied volatility)</strong> is the size of move the market is pricing in. When IV is high, options are expensive, because traders expect big swings.</li><li><strong>OTM (out of the money)</strong> describes strikes away from the current price, which only pay off if the market moves towards them.</li></ul><p>The good news is that Dhan’s option chain already returns OI, the previous day’s OI, the Greeks and IV for every strike, so “change in OI” works straight out of the box (<a href="https://dhanhq.co/docs/v2/option-chain/">DhanHQ option chain docs</a>). The DhanHQ skill also includes ready patterns for PCR, max pain, payoff diagrams and IV skew. So once you like this analysis, you can ask Claude Code to turn it into a script you can reuse every morning. We’ll set Claude Code up in Part 2.</p><h3>Workflow 3: A single-stock deep dive</h3><p>When you’re considering a stock, this workflow gathers the story and the numbers together:</p><pre>Deep dive on HDFC Bank for a 3-6 month view.<br>- Exa: last two quarterly results, management commentary on margins and deposit growth,<br>  recent analyst rating changes, any regulatory news.<br>- Dhan: 1 year of daily candles. Compute 50/200-day moving averages, 52-week high/low,<br>  distance from each, and average daily traded value.<br>- Compare valuation and recent performance with ICICI Bank and Kotak Mahindra Bank.<br>Give a bull case, a bear case, and what would change your mind. Cite every news source.</pre><p>I’d like to point out my favourite line in this prompt: <em>“what would change your mind.”</em> Asking for that keeps the analysis honest. It’s easy to find reasons to agree with yourself; it’s much more useful to know what would prove you wrong.</p><h3>Workflow 4: A sector rotation scan</h3><p>Money moves between sectors over time, and this workflow helps you notice where it’s going:</p><pre>Using Dhan historical data, compare 1-week, 1-month and 3-month returns of Nifty IT,<br>Nifty Bank, Nifty Pharma, Nifty Auto, Nifty FMCG and Nifty Metal.<br>Use Exa to explain the top and bottom performer in two sentences each.<br>Which sector shows improving momentum while still below its 3-month average?</pre><h3>Workflow 5: An event-driven watchlist</h3><p>Company results can move a stock sharply, and options often price that move in advance. This workflow helps you compare what’s expected with what usually happens:</p><pre>Use Exa to list Nifty 50 companies reporting results in the next 10 trading days.<br>For each, pull the current price and ATM implied volatility from the Dhan option chain<br>where stock options exist. Rank them by implied move versus their average post-results move.</pre><p>Here, <strong>ATM (at the money)</strong> means the strike closest to the current price. Its IV is the cleanest reading of how big a move the market expects.</p><p>Before we move on, let’s gather the lesson running through all five workflows. <strong>Write prompts like specifications, not wishes.</strong> For each fact, name where it should come from, what calculation you want, and how the answer should be laid out. The more your prompt reads like a careful brief, the more the answer reads like real research.</p><h3>Portfolio Management Workflows</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mB-sfpxLVK-8U5isMUst_w.png" /></figure><p>Let’s turn from the market to your own portfolio.</p><p>Here’s something I’ve come to believe, both from my own trading and from watching friends trade. Most retail portfolios don’t struggle because of poor stock picks. They struggle because too much money sits in one place, because margin quietly creeps up, or because a trade was never reviewed. The workflows in this section turn Claude into the gentle, patient risk officer most of us never had.</p><h3>Workflow 6: A daily portfolio health check</h3><p>Think of this as a quick morning check-up for your portfolio:</p><pre>From Dhan, pull my holdings, positions and funds.<br>Show: total value, unrealised P&amp;L by holding, top 5 positions by weight,<br>sector exposure (map each stock to its Nifty sector index), and cash as % of portfolio.<br>Flag any single stock above 15% weight or any sector above 30%.</pre><p>The 15% and 30% limits are only a starting point. Choose numbers that fit your own comfort, and write them down so the check stays consistent.</p><h3>Workflow 7: An F&amp;O risk dashboard</h3><p>If you sell options, I’d encourage you to run this one every evening. It’s the most valuable prompt in the tutorial:</p><pre>From Dhan, list my open F&amp;O positions and margin utilised.<br>For each short option, pull the option chain and report delta, theta, vega and IV,<br>and the distance of the strike from spot in points and in % of spot.<br>Aggregate net delta, theta and vega for the book.<br>Then estimate P&amp;L if Nifty moves -2%, -1%, +1% and +2% by expiry, holding IV constant.<br>Which position should I adjust first, and why?</pre><p>Let me explain the three Greeks in that prompt, because they’re the key to reading your risk:</p><ul><li><strong>Delta</strong> tells you how much an option’s price moves for each point the index moves.</li><li><strong>Theta</strong> tells you how much value the option loses each day as time passes. For an option seller, this is the money you earn by waiting.</li><li><strong>Vega</strong> tells you how much the option’s price changes for each point of IV.</li></ul><p>When you add these up across your whole book, you see your true exposure, which is often quite different from the exposure you <em>feel</em> you have. That gap is precisely where surprises come from.</p><h3>Workflow 8: A margin check before you commit</h3><p>It’s always better to know the cost before you trade. This prompt calculates it without placing anything:</p><pre>Using Dhan&#39;s margin calculator (basket mode), how much margin do I need to:<br>sell 1 lot Nifty 24000 CE, buy 1 lot Nifty 24200 CE, same weekly expiry?<br>Compare with the margin for selling the 24000 CE naked. Do not place any order.</pre><p>A quick note on the labels: <strong>CE</strong> is a call option and <strong>PE</strong> is a put option. When you compare the two answers, you’ll usually find that the spread needs far less margin than the naked call, because the bought option limits your risk. Seeing that number before you trade has a wonderful way of changing your behaviour for the better.</p><h3>Workflow 9: The weekly trade journal</h3><p>Reviewing your trades is how you improve, yet it’s the first thing we all skip when we’re busy. This prompt makes it painless:</p><pre>From Dhan&#39;s tradebook, list my trades for this week. Group by underlying and strategy.<br>Compute realised P&amp;L, win rate, average win, average loss and the largest single loss.<br>Which trades broke my own rules (no stop-loss, oversized, entered in the first 5 minutes)?<br>Write a five-line review I can paste into my journal.</pre><p>In Part 2, once you’re working in Claude Code, the skill’s trade_logger.py keeps a permanent journal for you, so this review can look back over months instead of days.</p><h3>Workflow 10: A tax-aware rebalancing plan</h3><p>Rebalancing means trimming what has grown too large and topping up what has shrunk, so your portfolio stays close to your plan. Taxes make it a little trickier, so let’s ask Claude to help:</p><pre>My target weights are in config/targets.yaml. Compare them with current Dhan holdings.<br>Propose the minimum set of trades to get within 2% of each target.<br>For every sell, flag whether the lot would be short-term or long-term based on purchase date,<br>and prefer selling lots that are already long-term.<br>Output the order list for my review. Do not place any order.</pre><p>Why prefer long-term lots? Under the current rules, gains on listed shares held for more than 12 months are taxed as long-term gains at 12.5%, above an annual exemption of ₹1.25 lakh. Gains on shares held for less are taxed as short-term gains at 20%. So selling older lots usually costs you less tax. Do confirm with your tax adviser before acting, though, as your situation may differ.</p><p>Here’s the quiet benefit of all these workflows. <strong>An AI that reads your portfolio every morning will notice the things you’ve trained yourself not to see.</strong></p><h3>Three Safety Habits Before You Go Further</h3><p>You now have a broker that answers questions in plain English. Before we finish, let’s put three small habits in place. They take minutes, and they’ll protect you long after you’ve forgotten this article.</p><ul><li><strong>Keep order tools on “Ask first”.</strong> We set this up in the connector settings, and it’s worth checking again now. Reading is free; acting should always need your yes.</li><li><strong>Ask for numbers, then check one.</strong> Before you act on a level, a margin figure or a Greek from Claude, compare at least one value with the Dhan app. It takes seconds, and it builds well-earned trust.</li><li><strong>Let research inform you, never instruct you.</strong> Anything Exa brings back from the web is information. A news page or a forum post should never be able to cause an order, so keep research and trading as separate steps, with your own decision in between.</li></ul><p>In Part 2, we’ll build on these habits with the regulator’s rules and the platform’s own safety checks, the full set of three locks on the door.</p><h3>Common Mistakes (Most of Which I’ve Made)</h3><p>I’d like to save you some of the bumps I hit along the way. Here are the mistakes I see most often, starting with my own:</p><ul><li><strong>Blaming the MCP server for a data-plan problem.</strong> If quotes or option chains say Unauthorized, the Data API plan almost always needs switching on.</li><li><strong>Leaving order tools on “Always allow”.</strong> It feels convenient, right up until a loosely worded request turns into a real order. Asking first costs you one click.</li><li><strong>Letting research and trading share a single step.</strong> If one prompt can read a news site <em>and</em> place an order, a cleverly written web page could steer your account.</li></ul><h3>Cheat Sheet: 10 Prompts Worth Bookmarking</h3><p>Here’s a summary of the prompts from this tutorial, gathered in one place. You might keep them in a text expander or a Claude Project. Each one names where the facts come from, what to calculate, and how to present the answer:</p><ol><li><strong>Account snapshot</strong> (Dhan): <em>“Holdings, positions and available funds on Dhan in one table.”</em></li><li><strong>Pre-market brief</strong> (Dhan + Exa): <em>“Nifty and Bank Nifty last close from Dhan; GIFT Nifty, global cues and FII/DII flows from Exa; three bullets on opening tone.”</em></li><li><strong>Option chain read</strong> (Dhan): <em>“Nearest-expiry Nifty chain: PCR, max pain, top 3 call and put OI strikes, implied range.”</em></li><li><strong>Short-strike watch</strong> (Dhan): <em>“For each short option, distance from spot in points and %, delta and IV. Which is closest to breach?”</em></li><li><strong>Book Greeks</strong> (Dhan): <em>“Net delta, theta and vega of my F&amp;O book, and P&amp;L at Nifty ±1% and ±2%.”</em></li><li><strong>Margin what-if</strong> (Dhan): <em>“Basket margin for this spread versus the naked leg. Do not place orders.”</em></li><li><strong>Concentration check</strong> (Dhan): <em>“Flag any stock above 15% or sector above 30% of my portfolio.”</em></li><li><strong>Stock deep dive</strong> (Exa + Dhan): <em>“Last two quarters, management commentary and rating changes for X; 50/200-day moving averages and 52-week range.”</em></li><li><strong>Sector momentum</strong> (Dhan + Exa): <em>“1-week, 1-month and 3-month returns for six sector indices; explain the top and bottom.”</em></li><li><strong>Weekly journal</strong> (Dhan): <em>“This week’s trades: realised P&amp;L, win rate, rule breaks, five-line review.”</em></li></ol><h3>The Bottom Line</h3><p>Let’s look back at what we’ve covered in this first part.</p><p>We started with four tabs and a ticking clock, and we ended with one conversation that can see your account, read the market and explain the news. Along the way, we met the three layers of our trading desk, connected Dhan to Claude Desktop, and built ten workflows for research and portfolio reviews.</p><p>If I could leave you with three ideas from Part 1, they’d be these:</p><ul><li><strong>Connect first, trade later.</strong> These read-only workflows give you most of the value with almost none of the risk.</li><li><strong>Let Exa explain why, and let Dhan show you what.</strong> A good prompt names its source for every fact.</li><li><strong>Write prompts like specifications, not wishes.</strong> Say where each fact comes from, what to calculate, and how to lay out the answer.</li></ul><h3>Your homework for this week</h3><p>Every good lesson ends with a little practice, so here’s yours:</p><ol><li>Add the Dhan connector in Claude Desktop, and set every order tool to ask first (<a href="https://docs.dhanhq.co/mcp/">DhanHQ MCP docs</a>).</li><li>Run the pre-market brief for five mornings in a row.</li><li>Run the F&amp;O risk dashboard every evening, and notice what surprises you.</li><li>Try the daily portfolio health check once, and write down one thing it showed you that you hadn’t noticed.</li></ol><h3>Disclosure, and How to Use This Guide Safely</h3><p>Before we close this part, I’d like to be clear about who’s been teaching you, and how I hope you’ll use what you’ve learned.</p><p><strong>Who I am.</strong> I’m not a professional trader, and I’m not registered with SEBI as an investment adviser, research analyst or broker. By profession, I’m an enterprise architect and an AI and agentic systems architect. In the markets, I’m a learner and an amateur trader, and what interests me most is building a trading <em>system</em> with AI: the connections, the safety checks and the discipline around it, more than any individual trade.</p><p><strong>What this guide is, and what it isn’t.</strong> It’s an educational walkthrough of tools and workflows. It isn’t investment advice, a recommendation to buy or sell any security, or a strategy you should trade. The stocks, indices and strikes in this part (HDFC Bank, ICICI Bank, Kotak Mahindra Bank, TCS, Nifty, Bank Nifty and the Nifty sector indices) are teaching examples. I chose them because they’re familiar, not because I think they’re good investments.</p><p><strong>My interests.</strong> I have no paid relationship with Dhan, Anthropic (the company that makes Claude) or Exa. There’s no sponsorship, no payment and no referral link here; I’m a paying user of these tools like you. I may hold or trade positions in some of the stocks or indices used as examples.</p><p><strong>The views here are my own</strong> and don’t represent my employer.</p><p><strong>Guardrails if you practise this setup.</strong> These are the conditions under which I share this guide, and they’re there to protect you:</p><ul><li><strong>Start read-only.</strong> Spend your first weeks using only the reading workflows from this part. Don’t give any AI tool permission to place orders until you’ve used the setup long enough to trust what it reads.</li><li><strong>Practise before you risk real money.</strong> Use paper trading or the smallest possible size first, and only ever trade with money you can afford to lose.</li><li><strong>You own every decision.</strong> Claude, Dhan and Exa are tools. Data can be delayed, and an AI can misread a question or state something confidently that isn’t true. Check important numbers against your broker and primary sources before you act on them.</li><li><strong>Check the rules for yourself.</strong> Regulations, prices, tax rates and APIs change. Everything here was accurate as of October 2026, but please confirm it with SEBI, the exchanges, Dhan and a qualified tax adviser before relying on it.</li><li><strong>Ask a professional when it matters.</strong> If you’re unsure whether a trade or strategy suits your situation, speak to a SEBI-registered investment adviser.</li><li><strong>Respect F&amp;O risk.</strong> Derivatives can lose money quickly, sometimes more than you expect. SEBI’s own studies have found that most individual F&amp;O traders lose money.</li><li><strong>Protect your account.</strong> Never share passwords, access tokens or 2FA codes with anyone, and keep them out of AI chats, notebooks and screenshots.</li></ul><p><strong>Use this at your own risk.</strong> I share this in good faith, to help you learn. I can’t accept responsibility for any loss that comes from using these tools, workflows or code, so please treat everything here as a starting point for your own learning, not as instructions to follow blindly.</p><h3>Coming Soon in Part 2: What Happens When the AI Writes the Strategy?</h3><p>Before you go, I’d like to leave you with a question, because it’s the one Part 2 is built around.</p><p>Everything we’ve done today has been safe. Claude reads, calculates and explains, and you make every decision. But the moment you open Claude Code, something changes. Claude can write a complete trading strategy in about two minutes, with entry rules, exits and position sizing, and the code will look perfectly reasonable.</p><p>So how do you know whether it’s any good?</p><p>I don’t mean whether the code runs. I mean whether the <em>strategy</em> is real, or a pattern that only existed in the past data it was tested on. That gap, between a strategy that looks good and one that is good, is where a lot of trading strategies quietly fall apart. It’s what Part 2 is about.</p><p>In Part 2, I’ll walk you through:</p><ul><li><strong>The five gates</strong> every strategy should pass before it touches real money, and why skipping even one is the most expensive shortcut in trading.</li><li><strong>The one sentence worth adding to every backtest prompt.</strong> It asks Claude to tell you, honestly, when a strategy’s edge disappears.</li><li><strong>A small piece of code that stands between your algorithm and your money,</strong> with a kill switch built in.</li><li><strong>The SEBI rule that bans the most common order type in retail algos.</strong> It’s easy to miss, and it changes how you write every order.</li></ul><p><strong>Part 2 is coming soon.</strong> If you’d like it to reach you the day it’s out, follow me on Medium or LinkedIn, wherever you’re reading this.</p><p>In the meantime, try your homework. Then tell me in the comments which workflow surprised you most, or where Claude got something wrong. I read every response, and your questions will help shape Part 2.</p><h3>Sources</h3><ul><li>DhanHQ, <a href="https://docs.dhanhq.co/mcp/">“DhanHQ Documentation: MCP, Agent Skills and Dhan Cloud”</a>, 2026.</li><li>Dhan, <a href="https://github.com/dhan-oss/dhanhq-skills">“dhan-oss/dhanhq-skills”</a>, GitHub, 2026.</li><li>DhanHQ, <a href="https://dhanhq.co/docs/v2/option-chain/">“Option Chain, DhanHQ v2 API”</a>.</li><li>Dhan Support, <a href="https://dhan.co/support/platforms/dhanhq-api/how-does-the-dhanhq-data-api-subscription-work/">“How does the DhanHQ Data API subscription work?”</a>.</li><li>Govind Sisara, <a href="https://dev.to/govind_sisara/indian-stock-market-mcp-the-best-mcp-servers-for-nse-bse-data-2026-p28">“Indian Stock Market MCP: The Best MCP Servers for NSE &amp; BSE Data (2026)”</a>, DEV Community, July 2026.</li><li>Reuters via Business Recorder, <a href="https://www.brecorder.com/news/40441987/india-benchmark-shares-log-worst-month-since-march-as-oil-global-rate-hikes-spark-outflows">“India benchmark shares log worst month since March as oil, global rate hikes spark outflows”</a>, 30 September 2026.</li><li>Anupama Ghosh, <a href="https://www.thehindubusinessline.com/markets/september-rout-makes-history-nifty-posts-worst-monthly-fall-in-8-years-worst-series-drop-since-2001/article71528719.ece">“September rout makes history: Nifty posts worst monthly fall in 8 years”</a>, The Hindu BusinessLine, 30 September 2026.</li><li>Khushi Keswani, <a href="https://www.moneycontrol.com/news/business/markets/nifty-down-nearly-13-in-2026-as-september-delivers-11-of-fiis-year-to-date-selling-14042636.html/amp">“Nifty down nearly 13% in 2026 as September delivers 11% of FIIs’ year-to-date selling”</a>, Moneycontrol, 1 October 2026.</li></ul><p><em>If you found this helpful, follow me on </em><a href="https://medium.com/@manavghosh"><em>Medium</em></a><em> or LinkedIn so Part 2 reaches you as soon as it’s out, along with more hands-on pieces on agentic AI and Claude Code.</em></p><p><em>Have a setup, a story of something that went wrong, or a different point of view? Leave a comment below. I read every response and would love to continue the conversation.</em></p><p><em>If this was useful, please share it with a trader or developer who’s thinking about connecting AI to their broker. Let’s keep learning together.</em></p><p>#AgenticAI #ClaudeAI #MCP #IndianStockMarket #Nifty50 #OptionsTrading #PortfolioManagement #Dhan #FinTech #AIinFinance</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d544c87629b5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Similarity Is Not a Decision]]></title>
            <link>https://medium.com/@manavghosh/similarity-is-not-a-decision-7010e753c3cf?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/7010e753c3cf</guid>
            <category><![CDATA[jevs]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[system-1-and-system-2]]></category>
            <category><![CDATA[rags]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Mon, 28 Sep 2026 15:57:39 GMT</pubDate>
            <atom:updated>2026-09-28T15:57:39.130Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3xF0SwOP57_BG8qmnSyvJw.png" /></figure><p><em>Embedding models tell you what looks alike. They cannot tell you what is allowed. Why that gap is quietly breaking enterprise workflows, and what decision models such as TypeSafe’s Jev change.</em></p><p>A shopper writes to an online store: <em>“Do not cancel my order. I only want to change the delivery address.”</em></p><p>The store’s support system routes the message with an embedding model, the same kind of model behind most product search and RAG today. It turns the message into a vector, compares it with a vector for each queue, and picks the closest. The closest queue is <em>Cancellations</em>. “Cancel” and “order” dominate the vector; “do not” barely moves it. Within minutes, an automated workflow has cancelled an order the customer wanted to keep.</p><p>Nothing is broken here. The model did exactly what it was trained to do: find what is <em>similar</em>. The system asked it a different question: what is <em>allowed</em>, what is <em>required</em>, what should <em>happen next</em>.</p><p><strong>Similarity is not a decision.</strong></p><p>I think this is one of the quietest design mistakes in enterprise AI right now. We took models built to measure closeness and promoted them to make decisions. Routing, filtering, eligibility checks, guardrails: many of these run on a similarity score and a threshold someone tuned on a Friday afternoon.</p><p>I noticed it in my own work. I am building an agent that has to filter a large, noisy feed and keep only the few items worth acting on. My first instinct was the usual one: embed everything, compare it with what I want, keep whatever scores above a threshold. When TypeSafe released Jev this month, I had to ask a question I had skipped. Was I asking my model to <em>find</em> things, or to <em>decide</em> things?</p><p>Those are different jobs, and most enterprise stacks I have seen use one model for both. This piece is what I found when I compared the two, and the test I now plan to run before trusting either one with a real decision.</p><h3>A quick primer: System 1 and System 2</h3><p>In <em>Thinking, Fast and Slow</em> (2011), psychologist Daniel Kahneman described two modes of human thinking.</p><ul><li><strong>System 1</strong> is fast, automatic and effortless. It recognises a friend’s face, hears anger in a voice, and knows that 2 + 2 is 4 without trying. It runs most of our day.</li><li><strong>System 2</strong> is slow, deliberate and effortful. It works out 17 × 24, fills in a tax form, or checks a contract clause line by line. It steps in when System 1 is unsure or the stakes are high.</li></ul><p>The split maps neatly onto AI. Reasoning models, which think step by step before answering, are System 2: powerful, but they take seconds to minutes and cost more with every step. Yet most decisions inside business software are System 1 in shape. Is this message urgent? Which queue does it go to? Does this order break a rule? TypeSafe’s argument is that companies have been paying System 2 prices for System 1 jobs.</p><h3>Two models, two different questions</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fRfG5odnmLcNyv9Gd_sxIQ.png" /></figure><p><strong>Contrastive embedding models</strong> learn by pulling matching pairs together and pushing mismatched pairs apart. A question and its answer, an image and its caption, a query and the right document end up close in the same vector space. CLIP made this famous for images and text. The same idea now powers BGE, Qwen3-Embedding, and Tencent’s new WeMM-Embedding family, which puts text, images, video and documents into one space. Ask one of these models a question and the answer is always a distance.</p><p><strong>System One models</strong> are a new category. TypeSafe AI came out of stealth this month with Jev, which takes program state in and returns typed decisions with probabilities out. You give it a customer message and a set of questions. It answers each one in a fixed shape: yes or no (noul), one of up to 255 named options (choice), or a position on a described scale (score). It never writes a sentence. TypeSafe trains it with a method it calls Reinforcement Learning for Calibrated Decisions, aimed at making its stated confidence match how often it is right.</p><p>The simplest way to hold the difference:</p><ul><li>An embedding model answers <strong>“how close is this to that?”</strong></li><li>A decision model answers <strong>“does this meet these conditions, and how sure are you?”</strong></li></ul><p>Both are useful. The trouble starts when the first one is asked the second question.</p><h3>Why this matters now</h3><p>In my <a href="https://medium.com/@manavghosh/token-economics-in-agentic-ai-a-comprehensive-analysis-b19631e4386b">Token Economics piece</a> in June, I argued that the Jevons paradox governs AI spend: as tokens get cheaper, we do not spend less, we automate more. Menlo Ventures’ December 2025 enterprise survey puts 2025 enterprise generative-AI spend at $37 billion, more than three times 2024, with $12.5 billion of it on foundation-model APIs. Its prediction for 2026 was exactly that paradox: falling inference prices, rising total spend.</p><p>It is hard not to read the name Jev as a nod to Jevons, and the pitch is Jevons applied to decisions. TypeSafe lists input at $0.042 per million tokens, output unbilled, and 70 to 500 milliseconds per call. At that price, the thousands of small yes/no calls buried in enterprise workflows no longer need a frontier chat model. They no longer need to be faked with a similarity threshold either.</p><p>One caution before going further. TypeSafe’s speed and quality claims are its own, published at launch. Its workflow evaluation uses the average answers of two frontier models as the reference, which TypeSafe itself notes may bias the result. Treat the numbers as a hypothesis to test in your own workflows, which is where this article ends up.</p><h3>Both are System 1, but not the same kind</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-j7zkJyc4dVxBwcwwkKgmA.png" /></figure><p>By Kahneman’s definition, a contrastive embedding model is also System 1. It produces its answer in a single pass, with no reasoning steps, in milliseconds. Nobody markets it that way, and “System One model” is TypeSafe’s name for its own category, but the behaviour fits.</p><p>The difference is which part of System 1 each one copies.</p><ul><li><strong>A contrastive model is System 1 recognition.</strong> It is the instant sense that <em>this looks like that</em>: a face you know, a song you have heard before, a document that resembles the one you need. It associates. It does not judge.</li><li><strong>Jev is System 1 judgment.</strong> It is the snap call an experienced person makes: <em>this ticket is urgent</em>, <em>this request is out of policy</em>, <em>this one goes to billing</em>, together with a gut sense of how sure they are.</li><li><strong>A reasoning LLM is System 2.</strong> It works through a problem step by step. Slow, expensive, and the right tool when the case is new or the stakes are high.</li></ul><p>People use all three every day, usually in that order: recognise, judge, and deliberate only when the judgment feels shaky. A well-designed AI workflow can follow the same order.</p><h3>Which model for which job</h3><p><strong>Reach for a contrastive model</strong> when the job is about closeness:</p><ul><li>Semantic search and RAG retrieval</li><li>Recommendations (“more like this”)</li><li>Deduplication, clustering and topic discovery</li><li>Search across images, video and documents</li><li>Semantic caching of repeated questions</li></ul><p><strong>Reach for a decision model</strong> when the job is about conditions:</p><ul><li>Routing orders, returns and customer messages to a queue</li><li>Policy and eligibility gates: approve, reject, escalate</li><li>Guardrails such as jailbreak, PII or off-topic checks</li><li>Scoring on a defined scale such as urgency, risk or sentiment</li><li>Choosing which model or agent handles a task</li></ul><p><strong>Hand it to a reasoning model or a person</strong> when the job needs thought:</p><ul><li>Novel cases no rule anticipated</li><li>Writing replies, summaries and reports</li><li>Multi-step analysis and arithmetic</li><li>Low-confidence calls from the layer before</li><li>Anything with legal or financial liability, or that must be explained in prose</li></ul><h3>Five questions that pick the model</h3><ol><li><strong>Is the output a ranking or a decision?</strong> Ranking points to embeddings; a decision points to a decision model.</li><li><strong>Does the business rule contain <em>not</em>, <em>except</em> or <em>at least</em>?</strong> If yes, keep embeddings away from the final call.</li><li><strong>Do you need a probability you can put in an audit trail?</strong> Jev returns one; a cosine score does not.</li><li><strong>Must the data stay inside your network?</strong> Open-weight embeddings can; Jev is a hosted API today.</li><li><strong>Would a careful person need to think it through?</strong> Then it is a System 2 job, and neither model should decide alone.</li></ol><h3>Where each one breaks</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VUdOdgH536-AfjEzBJoRvA.png" /></figure><h3>What the research says about embeddings as gatekeepers</h3><p>The cancelled order is not a made-up edge case. It is a measured weakness.</p><ul><li><strong>Negation.</strong> The <a href="https://aclanthology.org/2024.eacl-long.139.pdf">NevIR benchmark</a> (EACL 2024) asked retrieval models to rank two documents that differ only by a negation. Most models, including state-of-the-art ones, did no better than random. Bi-encoders, the architecture behind standard embedding search, came last; only slower cross-encoders did meaningfully better.</li><li><strong>Exclusion.</strong> <a href="https://arxiv.org/html/2404.17288">ExcluIR</a> tested queries like “tell me about X, but not Y.” Nearly every retriever scored less than 10% above random at ranking the right document first. More training data helped, but a large gap to human performance remained.</li><li><strong>Combinations.</strong> A 2025 paper from Google DeepMind, <a href="https://arxiv.org/html/2508.21038v1">“On the Theoretical Limitations of Embedding-Based Retrieval”</a>, proved that a single vector of fixed size cannot represent every combination of relevant results. Their simple LIMIT dataset defeated state-of-the-art models. The more your query looks like a rule with <em>and</em>, <em>or</em> and <em>not</em>, the closer you get to that ceiling.</li><li><strong>Scores that are not probabilities.</strong> <a href="https://arxiv.org/html/2403.05440v1">Netflix researchers</a> showed that cosine similarity between learned embeddings can be arbitrary, depending on how the model was regularised. A score of 0.82 does not mean 82% likely. Any threshold you set on it is a guess you have to recalibrate by hand, and recalibrate again when the model changes.</li></ul><p>None of this makes embeddings bad. It makes them the wrong tool for a gate.</p><h3>Side by side</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0hcRuznEgUtkDIcCceN7JQ.png" /></figure><p>The comparison comes down to a handful of differences:</p><ul><li><strong>Output.</strong> Embeddings give you a vector per item and a similarity score per pair. Jev gives typed answers, each with a probability.</li><li><strong>Several checks on one item.</strong> Embeddings need a set of labels or a trained head for every new check. Jev answers many questions in one pass over the same input.</li><li><strong>Negation and exclusion.</strong> Measurably weak for embeddings. For Jev, you state them directly in the question.</li><li><strong>Confidence.</strong> Raw scores that you calibrate yourself, versus calibration as the training goal, per TypeSafe.</li><li><strong>Scale.</strong> Embeddings are built to rank millions of items. Jev judges one input at a time.</li><li><strong>Data control and maturity.</strong> Open-weight embeddings run inside your network and have years of independent benchmarks. Jev is a hosted API that launched this month, and its claims are mostly self-reported.</li></ul><h3>Where the decision model breaks</h3><p>Jev is not a free upgrade, and an honest architecture review should say so.</p><ul><li><strong>It knows only what you send.</strong> Jev has no knowledge beyond the state in the request. Whoever assembles that state decides what the model is allowed to know, which makes the context pipeline a governance question, not a plumbing one.</li><li><strong>It does not write, summarise or read images.</strong> The output is a decision, never text, and today the input is text or structured data.</li><li><strong>Versions move.</strong> The jev-latest alias points to whatever TypeSafe shipped last. If you tune thresholds on probabilities, pin the version and log the one that answered.</li><li><strong>It is a new vendor.</strong> Early access, a waitlist, and a hosted-only API. For a regulated workload, that is a procurement conversation before it is a technical one.</li></ul><blockquote>Use an embedding model when the question is about closeness. Use a decision model when the question is about conditions. When in doubt, ask whether the business rule contains the word not.</blockquote><h3>Putting it into practice</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MXvNmL2ZWbRdU80VBrEo8g.png" /></figure><h3>The cascade: find, decide, sign off</h3><p>For most workflows the answer is not either/or. It is a sequence, where each model does the one job it is good at.</p><ol><li><strong>Find with embeddings.</strong> Narrow a large set to a small one. Pull the 20 help-centre articles closest to the customer’s message, the 200 products closest to a shopper’s search, or the 50 past returns that look like today’s. This is cheap, fast, and runs inside your network.</li><li><strong>Decide with a decision model.</strong> Ask typed questions about each shortlisted item or about the incoming request, with the rule written out in plain words.</li><li><strong>Act on confidence.</strong> Act automatically above a high threshold, ask for confirmation in the middle band, and send the rest to a person or a full reasoning model. Set that threshold per action, according to what a wrong answer costs.</li></ol><p>For the order message, step two looks like this (the request shape follows TypeSafe’s published API):</p><pre>{<br>  &quot;model&quot;: &quot;jev-1.13.0&quot;,<br>  &quot;state&quot;: &quot;Do not cancel my order. I only want to change the delivery address.&quot;,<br>  &quot;questions&quot;: {<br>    &quot;wants_cancellation&quot;: {<br>      &quot;type&quot;: &quot;noul&quot;,<br>      &quot;instructions&quot;: &quot;Is the customer asking to cancel the order?&quot;<br>    },<br>    &quot;queue&quot;: {<br>      &quot;type&quot;: &quot;choice&quot;,<br>      &quot;instructions&quot;: &quot;Which team should handle this?&quot;,<br>      &quot;criteria&quot;: {<br>        &quot;order_changes&quot;: &quot;address, delivery date or item changes to an open order&quot;,<br>        &quot;cancellations&quot;: &quot;customer wants the order stopped&quot;,<br>        &quot;returns&quot;: &quot;customer wants to send back a delivered item&quot;<br>      }<br>    }<br>  }<br>}</pre><p>The code that consumes the answer is an ordinary if-statement: route to <em>Cancellations</em> only if wants_cancellation is above, say, 0.9. That threshold is something a risk owner can read, argue about and sign off. A cosine cut-off never was.</p><h3>The test that settles it for your workflow</h3><p>Do not take my word, or TypeSafe’s, for any of this. The comparison takes a week to run.</p><ol><li><strong>Label 200 real items</strong> from one workflow: orders, returns, refund requests, product reviews. For each, record the right decision and the business rule behind it. Deliberately include the awkward ones with negation and exclusion.</li><li><strong>Run three setups</strong> on the same 200: embedding zero-shot (closest label description wins), embeddings plus a small classifier trained on part of your labels, and a decision model with the rules written as typed questions.</li><li><strong>Score four things.</strong> Accuracy on the full set. Calibration: when a setup says 90%, is it right about nine times in ten? False yeses on the hard rules, the errors that cost money or compliance. And cost per 1,000 items at your real volume.</li><li><strong>Keep the 200 items</strong> as a regression set. Run it again whenever a model version, a threshold or a rule changes.</li></ol><p>My expectation is that embeddings win on cost and on finding things, and the decision model wins on the hard-rule gates and on how far you can trust its confidence. But the point of the test is that you will not need my expectation.</p><h3>What to ask your team on Monday</h3><ul><li>Which decisions in our workflows are currently made by a similarity score and a threshold?</li><li>Which of those contain the word <em>not</em>, <em>except</em> or <em>at least</em>?</li><li>Who owns each threshold, and when was it last checked against real outcomes?</li><li>If we adopt a hosted decision model, what data leaves our network, and which version are we pinned to?</li></ul><h3>The closing argument</h3><p>For three years, enterprise AI architecture has had two main parts: a big model that talks, and an embedding model that finds. Everything in between, the routing, the gating, the escalation, got built out of whichever of the two was nearer to hand.</p><p>Decision models add a third part with a narrow job: answer a typed question, say how sure you are, and nothing more. Jev may end up defining that part, or it may only be the first to name it. Either way, the architecture holds. Similarity finds the candidates. Conditions decide what happens to them. A person signs off on what the machine is unsure about.</p><p><strong>Find with vectors. Decide with rules the model can read. Keep a human where the confidence runs out.</strong></p><p><em>If you found this article helpful, follow me on </em><a href="https://medium.com/@manavghosh"><em>Medium</em></a><em> and connect with me on LinkedIn for more in-depth pieces on enterprise AI architecture, agentic systems, and the engineering behind them.</em></p><p><em>Have questions, a different take, or production numbers of your own? Leave a comment below. I read every response and would love to discuss further.</em></p><p><em>If this was useful to you, share it with your team or anyone building retrieval and routing into their AI stack. You can also reach out to me directly. Let’s keep the conversation going.</em></p><p>#AI #EnterpriseAI #Embeddings #VectorSearch #RAG #AIArchitecture #AgenticAI #LLM #MachineLearning #SoftwareEngineering</p><p><strong>Sources and further reading</strong></p><ul><li>TypeSafe AI, <a href="https://typesafe.ai/blog/introducing-system-one-models-and-jev">“Introducing System One Models and Jev”</a>, September 2026.</li><li>TypeSafe AI, <a href="https://docs.typesafe.ai/models">Models and versioning documentation</a>.</li><li>Menlo Ventures, <a href="https://menlovc.com/perspective/2025-the-state-of-generative-ai-in-the-enterprise/">“2025: The State of Generative AI in the Enterprise”</a>, December 2025.</li><li>Weller, O. et al., <a href="https://aclanthology.org/2024.eacl-long.139.pdf">“NevIR: Negation in Neural Information Retrieval”</a>, EACL 2024.</li><li><a href="https://arxiv.org/html/2404.17288">“ExcluIR: Exclusionary Neural Information Retrieval”</a>, 2024.</li><li>Weller, O. et al., <a href="https://arxiv.org/html/2508.21038v1">“On the Theoretical Limitations of Embedding-Based Retrieval”</a>, Google DeepMind, 2025.</li><li>Steck, H., Ekanadham, C. and Kallus, N., <a href="https://arxiv.org/html/2403.05440v1">“Is Cosine-Similarity of Embeddings Really About Similarity?”</a>, Netflix, 2024.</li><li>Kahneman, D., <em>Thinking, Fast and Slow</em>, Farrar, Straus and Giroux, 2011.</li><li>Ghosh, M., <a href="https://medium.com/@manavghosh/token-economics-in-agentic-ai-a-comprehensive-analysis-b19631e4386b">“Token Economics in Agentic AI: A Comprehensive Analysis”</a>, June 2026.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7010e753c3cf" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Graph Is the Plumbing. The Ontology Is the Language.]]></title>
            <link>https://medium.com/@manavghosh/the-graph-is-the-plumbing-the-ontology-is-the-language-b63c1b67a85a?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/b63c1b67a85a</guid>
            <category><![CDATA[ontology]]></category>
            <category><![CDATA[rags]]></category>
            <category><![CDATA[graphrag]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Sun, 06 Sep 2026 15:47:26 GMT</pubDate>
            <atom:updated>2026-09-06T15:47:26.597Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uv9DbKMcheJGzi2ttVH5xA.png" /></figure><p><em>Why every “enterprise knowledge graph” that failed was really an ontology that was never written.</em></p><p><em>Part 1 of a four-part series on ontology in the enterprise.</em></p><p>Picture an architecture review at a large enterprise. A team is demoing their new knowledge graph. Eighteen months of work. Forty million nodes. A visualisation that looks like a galaxy. The room is impressed.</p><p>Then someone from Finance asks one question: “How many active customers do we have in EMEA?”</p><p>The graph returns three different numbers.</p><p>Not because the data is wrong. Because the graph has three different ideas of what a <em>customer</em> is — one inherited from the CRM, one from Billing, one from Support — and in eighteen months nobody has forced those three ideas to agree. Chances are the discrepancy has been quietly propagating into a forecast, or a board deck, or a compliance filing for the better part of a year. The team has built the plumbing. They have never written the language.</p><p>If that scenario feels uncomfortably familiar, it is because some version of it is playing out in most enterprises that have a “knowledge graph” on the roadmap.</p><p>That language is the ontology. And it is the single most under-invested layer in enterprise AI today.</p><h3>What an ontology actually is (without the philosophy lecture)</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Zs9Tp6boLqF0C4pwh6FXRg.png" /></figure><p>Strip away the academic baggage and an ontology is three things, written down and enforced:</p><ol><li><strong>The concepts your organisation cares about.</strong> Customer. Product. Contract. Asset. Incident. Not tables — <em>concepts</em>.</li><li><strong>The relationships that are allowed between them.</strong> A Contract <em>is signed by</em> a Customer. An Asset <em>is installed at</em> a Site. A Site <em>belongs to</em> a Region.</li><li><strong>The rules that make those relationships mean something.</strong> A Contract must have exactly one Customer. An Asset cannot be installed at two Sites at once. A Subsidiary <em>is a</em> Customer, so anything true of Customers is true of Subsidiaries.</li></ol><p>A schema tells a database how to store data. An ontology tells a business — and now, a machine — what the data <em>means</em>.</p><p>That distinction sounds subtle until you try to reason across silos. A schema can tell you that cust_id in the CRM and account_ref in Billing are both strings. Only an ontology can tell you they refer to the same real-world thing, that one is the legal entity and the other is the billing relationship, and that the two are linked by a <em>has billing account</em> relationship with a start date and an end date.</p><blockquote>A knowledge graph without an ontology is a very expensive way of storing the same confusion you already had in your spreadsheets.</blockquote><h3>Why it matters more now than it did five years ago</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CwzPxLRjdhh-R-6hTsHLGw.png" /></figure><p>For two decades ontologies were the domain of a small tribe — semantic web researchers, a few pharma informatics teams, the odd bank with a regulatory scare. Most enterprises could ignore them. Humans were the consumers of data, and humans are remarkably good at resolving ambiguity on the fly. Ask an analyst “what’s a customer?” and they will give you the answer that fits the question.</p><p>That era is over, for one reason: <strong>the consumers of your enterprise data are increasingly not human.</strong></p><p>An agent that is asked to reconcile a revenue figure, approve a vendor, or triage an incident cannot pause and ask a colleague which definition of <em>customer</em> applies. It will pick one. Confidently. And the confidence is the dangerous part — a wrong answer delivered fluently is worse than no answer at all.</p><p>Three forces are converging:</p><p><strong>Agents need a shared vocabulary to hand off work.</strong> When one agent extracts entities from a contract and another checks them against a compliance policy, they must agree on what an <em>Entity</em> is, what <em>Jurisdiction</em> means, and how <em>Obligation</em> relates to <em>Party</em>. Without an ontology, every agent-to-agent handoff is a translation problem — and translation problems compound.</p><p><strong>Governance now has to be machine-readable.</strong> Regulators, auditors and your own risk function are asking questions that cannot be answered from a data catalogue alone: <em>Which decisions used personal data? Which models consumed which sources? What does “material” mean in this policy?</em> Those are ontological questions. If the answers live in a Confluence page, they are not governance — they are folklore.</p><p><strong>Reasoning is finally cheap.</strong> The historic objection to ontologies was that they were expensive to build and nobody used the inference. Large language models have flipped both sides of that equation: they can draft a first-cut ontology from your documents in an afternoon, and they are the first mass-market consumer of the constraints an ontology encodes. The cost went down and the demand went up simultaneously.</p><h3>Where an ontology earns its keep</h3><p>Not every graph needs a formal ontology. If you are building a recommendation engine over clickstream data, a lightweight property graph and a good engineer will get you most of the way. The ontology becomes non-negotiable in a specific set of conditions:</p><ul><li><strong>Multiple systems claim ownership of the same concept.</strong> Customer, Product, Employee, Asset — anything that has been “mastered” three different ways.</li><li><strong>The cost of a wrong answer is regulatory, financial or physical.</strong> Compliance reporting, clinical decisions, safety-critical operations.</li><li><strong>You need inference, not lookup.</strong> “Show me every asset affected by this supplier’s recall” requires the machine to <em>know</em> that a Component is part of an Assembly which is part of a Product which is installed at a Customer Site.</li><li><strong>Non-human consumers are downstream.</strong> Agents, automated decisioning, anything that acts without a human reading the result first.</li><li><strong>Blast radius has to be computable.</strong> When an incident fires, the interesting question is not “what broke” but “what depends on what broke”. If your CMDB does not enforce <em>depends-on</em>, your incident commanders are guessing.</li><li><strong>The vocabulary has to survive people leaving.</strong> If the only person who knows why two fields are the same is retiring next year, you have an ontology — it is stored in a human.</li></ul><p>If two or more of those apply, the question is no longer <em>whether</em> to write an ontology. It is whether you write it deliberately, or discover it painfully.</p><h3>Five signs your knowledge graph has no ontology</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*U_49QvwU9OMkz_JxewTPzQ.png" /></figure><p>You may already have a graph — or a data platform that calls itself one. Here is a test you can run in an afternoon. Score one point for each that is true.</p><ol><li><strong>The same business term returns different numbers depending on who runs the query.</strong> Customer, revenue, active user, open incident. If the answer depends on the analyst, the definition lives in people, not in the system.</li><li><strong>Two nodes with the same label mean different things.</strong> A Product from the catalogue and a Product from the ERP share a name and nothing else. Nobody can say, without opening a ticket, whether they are the same thing.</li><li><strong>Nothing can be rejected.</strong> You can create a Contract with no Customer, an Asset with two Sites, an Employee reporting to a cost centre. The graph accepts anything. Acceptance without constraint is storage, not knowledge.</li><li><strong>Multi-hop questions require a person.</strong> “Which customer sites contain a part from this supplier?” is answerable — but only by someone who knows which relationships to chain and in what order. The chain is not written down anywhere the machine can read.</li><li><strong>The definitions live in a document, not in the platform.</strong> A Confluence page, a data dictionary, a slide from 2021. If the graph can be changed without that document changing — or vice versa — the two have already diverged.</li></ol><p><strong>0–1:</strong> you probably have an ontology, even if nobody calls it that. <strong>2–3:</strong> you are running on tribal knowledge, and it works until the tribe changes. <strong>4–5:</strong> every agent you point at this graph will inherit the confusion — and answer confidently anyway.</p><h3>Three places the industry has already done the work</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*369Xj2s0X05QkTICLTQbtA.png" /></figure><p>The strongest argument for ontologies is that the sectors with the most to lose have already adopted them. None of these are experiments.</p><h3>1. Financial services — the regulatory vocabulary</h3><p>After 2008, regulators discovered that the world’s largest banks could not answer a simple question: <em>what is your total exposure to this counterparty?</em> Not because they lacked data, but because “counterparty” meant something different on every desk.</p><p>The response was the <a href="https://spec.edmcouncil.org/fibo/">Financial Industry Business Ontology (FIBO)</a>, an open standard maintained by the EDM Council that formally defines concepts like legal entity, financial instrument, contract and ownership — and, critically, the relationships between them. A bank that maps its internal data to FIBO can answer exposure, beneficial-ownership and risk-aggregation questions across business lines without a six-month reconciliation project.</p><p>The evidence is not hypothetical. <a href="https://www.stardog.com/pdf/resources-research/Distributed_Data_and_Ontologies_An_Integrated_Semantic_Web_Architecture_Enabling_Mo.pdf">A peer-reviewed study with State Street</a>, published in the <em>Journal of the Association for Information Science and Technology</em>, built a FIBO-based reporting layer over the bank’s legacy fund systems and ran it against live data. Preparing one regulatory money-market fund report had been consuming roughly 200 person-hours a quarter; individual aggregations that took three to four hours were reduced to three to four seconds. More telling, the ontology’s reasoner surfaced data-quality anomalies — bonds carrying contradictory accrual bases across funds — that the relational warehouse had never flagged, because no one had written down that both could not be true. And the bank did not have to migrate a single legacy system to get there; the ontology sat on top.</p><p>The lesson for everyone else: <strong>the ontology was the regulatory response, not the technology.</strong> The graph databases came later.</p><h3>2. Healthcare and life sciences — the machine-readable clinic</h3><p>Medicine is the most mature ontology user on the planet. SNOMED CT encodes hundreds of thousands of clinical concepts with formal <em>is-a</em> and <em>finding-site</em> relationships, so a system knows that a fractured femur <em>is a</em> fracture <em>of a</em> long bone <em>of the</em> lower limb — without a human writing that rule per record. The Gene Ontology does the same for molecular biology, and drug-discovery pipelines run on top of it.</p><p>The payoff is not search. It is <strong>safe automation</strong>: a clinical decision-support system can flag a drug interaction because the ontology knows that two differently-named medicines share an active ingredient class. Nobody had to hand-code that pair.</p><p>The same discipline is now paying off in pharma R&amp;D. <a href="https://graphwise.ai/blog/astrazeneca-enabling-new-medicines-through-semantic-knowledge-graphs/">AstraZeneca’s semantic infrastructure team</a> has built a knowledge graph over roughly 350 clinical studies and 750,000 trial subjects, linking studies to subjects to samples to observations. When a data-science team feared they lacked enough patients in a subpopulation to train a model, the graph surfaced five additional studies they had not known about; the search that used to take weeks of manual digging took minutes. But their most interesting lesson was a pivot: rather than only loading data <em>into</em> the graph, they now push the ontology’s controlled vocabularies <em>out</em> into the ordinary SQL data pipelines, so every new data product arrives already speaking the shared language.</p><p>For an enterprise reader, the transferable idea is this: the ontology is what lets you automate a decision <em>without</em> enumerating every case in advance — and the fastest route to adoption is to make the vocabulary the path of least resistance for the teams producing data, not only the teams consuming it.</p><h3>3. Manufacturing and asset-heavy industries — the digital twin’s skeleton</h3><p>Every industrial company now talks about digital twins. Very few will admit that a digital twin is, at its core, an ontology with sensor data attached. Standards like ISO 15926 (process plants) and the Industry 4.0 Asset Administration Shell exist because a twin of a refinery, a wind farm or a factory line is useless if the twin from Vendor A cannot understand the pump from Vendor B.</p><p><a href="https://info216.wiki.uib.no/images/5/5e/Bosch-LIS.pdf">Bosch’s Line Information System</a> is the cleanest example I know of. Production planning, process engineering, quality and purchasing each had their own view of the same “production line”, spread across MES, ERP and master-data systems that disagreed with each other. Bosch wrote a single ontology — reusing the Industrial Digital Twin Association’s core manufacturing model where it could — mapped all three sources onto it, and rolled it out across 12 plants covering more than 1,100 production lines, 16,000 physical machines and 400 manufacturing processes. The point was never the graph. It was that, for the first time, a planner in one plant and a quality engineer in another could ask the same question and mean the same thing.</p><p><a href="https://metaphacts.com/smart-turbine-spare-parts-management-at-siemens-energy">Siemens Energy</a> did the equivalent for gas-turbine spare parts: a knowledge graph that unified fleet configurations documented differently across systems, so service engineers could identify identical parts across turbines and size outage packages properly — replacing bespoke SAP report requests and saving around 1,500 engineering hours in the first year alone. <a href="https://www.mm-software.com/en/cases/detail/sew-eurodrive-from-data-silos-to-data-clarity/">SEW-EURODRIVE</a>, the drive-technology manufacturer, went one step further and standardised its product vocabulary on ECLASS so that, in their words, “Colour” and “Farbe” finally meant the same thing across systems — the prerequisite for shipping a standards-compliant digital twin to customers at all.</p><p>Where I have seen this land hardest is in service and warranty operations. When a supplier issues a recall on one component, the question <em>“which installed products at which customer sites contain this part, and who is the contracted service partner for each?”</em> is a five-hop traversal. It is answerable in seconds only if someone defined, in advance, what <em>contains</em>, <em>installed at</em> and <em>serviced by</em> actually mean and how they chain together.</p><h3>What building one actually looks like</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ugVH7JYz2_F5eXbVOUEk-A.png" /></figure><p>I will spare you the tooling debate — that is a different article. What matters at the leadership level is sequencing, and the sequencing is counter-intuitive:</p><p><strong>Start with the questions, not the data.</strong> Write down the twenty questions the business cannot currently answer without a reconciliation project. Each one names the concepts and relationships you need. That list <em>is</em> the scope of your first ontology.</p><p><strong>Borrow before you build.</strong> FIBO, SNOMED, Schema.org, ISO 15926, STIX — someone with more domain depth than your team has already argued about the definitions. Adopt, extend, and only invent where your business is genuinely different.</p><p><strong>Treat it as a product, not a project.</strong> An ontology that is not versioned, owned and governed decays into a data dictionary within a year. It needs an owner the way an API needs an owner.</p><p><strong>Let the model draft, let the domain expert decide.</strong> The fastest teams I have seen use an LLM to propose concepts and relationships from existing documentation, then put a human steward in the loop for every definition that ships. The model accelerates; it does not authorise.</p><p><strong>Enforce it at the boundary.</strong> The ontology is only real if something rejects data that violates it. If a Contract can be created without a Customer, you do not have an ontology — you have a suggestion.</p><h3>The closing argument</h3><p>For twenty years we built enterprise architecture on the assumption that a human would be the last mile — the person who reads the report, resolves the ambiguity, and makes the call. Ontologies felt like over-engineering because humans absorbed the cost of missing ones.</p><p>That last mile is being automated. The ambiguity does not disappear; it gets inherited by whatever system is downstream. And the only way to hand a machine an unambiguous world is to have written that world down.</p><p>The graph is where the knowledge lives. The ontology is what makes it knowledge.</p><p><strong>Build the language before you build the plumbing.</strong></p><p><em>If you scored 3 or more on the test above, I’d like to hear how it showed up in your organisation — which term, which three numbers. Drop a comment, or reach out directly.</em></p><p><em>Next in the series — Part 2: Nobody Agrees What a Customer Is. Here’s How to Fix That. The practical build: which twenty questions to start from, what to borrow from FIBO and SNOMED, and a worked example of the first ten concepts.</em></p><p><strong>Sources and further reading</strong></p><ul><li>Browne, O. et al., <a href="https://www.stardog.com/pdf/resources-research/Distributed_Data_and_Ontologies_An_Integrated_Semantic_Web_Architecture_Enabling_Mo.pdf">“Distributed Data and Ontologies: An Integrated Semantic Web Architecture Enabling More Efficient Data Management”</a>, <em>Journal of the Association for Information Science and Technology</em>, 70(6), 2019 — the State Street / FIBO study.</li><li>Grangel-González, I. et al., <a href="https://info216.wiki.uib.no/images/5/5e/Bosch-LIS.pdf">“LIS: A Knowledge Graph-Based Line Information System”</a> (Bosch).</li><li>Gardner, B., <a href="https://graphwise.ai/blog/astrazeneca-enabling-new-medicines-through-semantic-knowledge-graphs/">“AstraZeneca: Enabling New Medicines Through Semantic Knowledge Graphs”</a>, Graphwise, Jan 2026.</li><li><a href="https://metaphacts.com/smart-turbine-spare-parts-management-at-siemens-energy">“Smart turbine spare parts management at Siemens Energy”</a>, metaphacts case study.</li><li><a href="https://www.mm-software.com/en/cases/detail/sew-eurodrive-from-data-silos-to-data-clarity/">“SEW-EURODRIVE: Turning data silos into data clarity”</a>, M&amp;M Software, Dec 2025.</li><li>EDM Council, <a href="https://spec.edmcouncil.org/fibo/">Financial Industry Business Ontology (FIBO)</a>.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b63c1b67a85a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Enterprise Knowledge Graph: A CTO’s Playbook for AI That Understands Your Business]]></title>
            <link>https://medium.com/@manavghosh/enterprise-knowledge-graph-a-ctos-playbook-for-ai-that-understands-your-business-fc0f87c7a7df?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/fc0f87c7a7df</guid>
            <category><![CDATA[rags]]></category>
            <category><![CDATA[enterprise-knowledge]]></category>
            <category><![CDATA[ekg]]></category>
            <category><![CDATA[graphrag]]></category>
            <category><![CDATA[ontology]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Sun, 05 Jul 2026 03:32:41 GMT</pubDate>
            <atom:updated>2026-07-05T03:32:41.339Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NHgrrwRnM277gtzeuMaOfw.png" /></figure><h3>Core Concepts: Understanding the Enterprise Knowledge Graph</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EYeyqETFjo_hH4lTR2ngjw.png" /></figure><h3>What is an Enterprise Knowledge Graph?</h3><p>Here’s the plain version: an Enterprise Knowledge Graph stores the relationships, not just the records. It models your organization as a network of typed entities and relationships, governed by an ontology — a shared, machine-readable definition of what your business terms actually mean. Your relational databases tell you <em>that</em> a customer and an order exist. A knowledge graph tells you how they connect, and lets both your people and your AI reason across data that used to sit in separate silos. The market is betting on it: according to Improvado (a marketing-data platform), the EKG market will reach USD (United States dollars) 6.94 billion by 2030, driven by demand for AI explainability and decision intelligence.</p><h3>Why Are EKGs Essential?</h3><p>Picture a retailer where inventory, sales, logistics, and customer service each run on their own system, none of them talking to the others. A customer complains about a delayed shipment. On a graph, the AI connects that one ticket to inventory levels, the shipping schedule, and the customer’s history in a single hop — and resolves it. Without the graph, that’s four systems and a phone tree. The value was never the data. It’s the connections.</p><h3>The Competitive Advantage of EKGs</h3><p>Connect those silos and your AI stops guessing. That’s the moat. And it’s a rare one: as Gartner highlights, fewer than 15% of enterprises have scaled a knowledge-graph project past the pilot stage, usually tripping on ontology design and entity resolution. Read that as opportunity — if you get this right while your competitors stall in pilot, the edge is yours to take.</p><h3>Best Practices: Building and Scaling Your EKG</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MjAQbpLoR-KP3MBQ8x7LpQ.png" /></figure><h3>Designing the Ontology: The Backbone of Your EKG</h3><p>Ontology design is where you start, and where most teams overthink it. It means understanding your business domain and how its entities genuinely relate. Jim Webber, Chief Scientist at Neo4j (the graph-database company), makes the core call simple: pick the right model for the job. RDF (Resource Description Framework — a World Wide Web Consortium standard that models data as simple subject–predicate–object statements) wins for data integration and formal reasoning; property graphs win when operational performance is what matters most.</p><h4>Steps in Ontology Design</h4><ol><li><strong>Domain Analysis</strong>: Map your domain with the people who live in it. Sit with domain experts and pin down the entities and relationships that actually matter.</li><li><strong>Model Selection</strong>: Choose RDF or a property graph on the facts — data complexity, integration needs, and performance — not on vendor marketing.</li><li><strong>Iterative Development</strong>: Build it incrementally. Start small and expand as real requirements surface. A twelve-month ontology is one nobody ends up using.</li><li><strong>Validation and Testing</strong>: Test the ontology against real questions. If it can’t answer the ones that matter to the business, it isn’t done.</li></ol><h3>Leveraging LLMs for Entity Extraction</h3><p>Here’s what changed the economics. Large language models (LLMs — the kind of AI that powers assistants like ChatGPT) now do the grunt work of extraction. They pull entities and relationships out of your unstructured data and help draft the schema — work that used to take a team of specialists months. TigerGraph (a graph-database vendor) points out that folding LLMs into the EKG stack both speeds up construction and sharpens entity recognition.</p><h4>Implementation of LLMs</h4><ol><li><strong>Integration with Data Pipelines</strong>: Wire LLMs into your existing data workflows so extraction and tagging happen inline, not as a separate project.</li><li><strong>Training and Fine-tuning</strong>: Tune them on your industry’s vocabulary so they catch the nuances a generic model misses.</li><li><strong>Continuous Learning</strong>: Let them learn from new data so the graph stays current instead of quietly going stale.</li></ol><h3>Integration with GraphRAG</h3><p>GraphRAG (Graph-based Retrieval-Augmented Generation — a retrieval method that grounds an LLM’s answers in a knowledge graph rather than in loose text passages) is where the graph pays off for AI. It pairs the graph with vector embeddings so the system can do multi-hop reasoning (chaining several facts together to answer one question) instead of matching keywords. The result: answers synthesized across many documents, fewer hallucinations, and a decision you can actually defend. Gurutech (an enterprise-AI publication) calls this integration critical for enterprises pushing their AI past simple lookups.</p><h4>Implementation Steps for GraphRAG</h4><ol><li><strong>Data Preparation</strong>: Get the knowledge graph and its vector embeddings aligned so they describe the same reality.</li><li><strong>Algorithm Selection</strong>: Pick retrieval and multi-hop methods that fit your complexity and your compute budget.</li><li><strong>System Integration</strong>: Wire GraphRAG into your existing AI systems and data sources.</li><li><strong>Performance Monitoring</strong>: Watch it in production and tune the models and data as you learn what breaks.</li></ol><h3>Real-World Examples: EKGs in Action</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*A7DepDzBJ1avgDey5rMCmg.png" /></figure><h3>Cisco’s Knowledge Findability Challenge</h3><p>Cisco’s salespeople were each losing up to an hour a day hunting for the right document. A Neo4j metadata knowledge graph made the content findable and saved over 4 million employee hours. Not a moonshot — a boring, expensive problem, solved by connecting the data.</p><h4>Implementation Details</h4><ul><li><strong>Data Integration</strong>: Cisco pulled its scattered sources into one graph — a single place to find anything.</li><li><strong>User Interface Design</strong>: They built a clean front end so anyone could query the graph without writing graph queries.</li></ul><h3>Siemens Energy’s Turbine Management</h3><p>Siemens Energy was buried under mismatched turbine configurations and customer-specific spare-parts catalogs. A knowledge-graph application on metaphactory over Amazon Neptune gave them fleet-wide analysis and saved up to 1,500 hours a year. When your data is this tangled, the graph is what makes it legible.</p><h4>Key Features</h4><ul><li><strong>Fleet-Wide Analysis</strong>: One view across every turbine, surfacing the patterns that drive proactive maintenance.</li><li><strong>Integration with Existing Systems</strong>: It slotted into Siemens’ existing IT (information technology) infrastructure, so adoption didn’t mean a rip-and-replace.</li></ul><h3>Pharmaceutical Research Acceleration</h3><p>A Fortune 500 pharmaceutical company put a knowledge graph on its research process and cut insight turnaround by 60%, with a 2X ROI (return on investment) in year one. A multi-agent extraction framework let it track drug interactions across datasets no analyst could hold in their head. In research, cross-document reasoning is the whole game.</p><h4>Benefits and Outcomes</h4><ul><li><strong>Improved Data Accessibility</strong>: Researchers got fast access to the full picture, so hypotheses got tested sooner.</li><li><strong>Enhanced Collaboration</strong>: Teams worked off one shared map of the data instead of their own conflicting copies.</li></ul><h3>Statistics: The Business Case for EKGs</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tMFKaAMrODjY3DXhmqsgbg.png" /></figure><h3>Market Growth and Investment Trends</h3><p>The numbers back the urgency. The EKG market was worth USD 3.47 billion in 2026 and is compounding at a CAGR (Compound Annual Growth Rate — the average yearly growth rate over a period) of 21.3% through 2033. And nearly 59% of enterprises above $100M in revenue now treat semantic layers as mission-critical AI-trust infrastructure. This stopped being a research project.</p><h4>Deeper Analysis</h4><ul><li><strong>Sector-Specific Growth</strong>: Healthcare, finance, and manufacturing lead adoption — the industries with the messiest data and the highest cost of being wrong.</li><li><strong>Investment in AI Explainability</strong>: Companies are buying EKGs to make AI auditable, which is fast becoming a regulatory requirement rather than a nice-to-have.</li></ul><h3>ROI and Efficiency Gains</h3><p>A study by Forrester (a technology research and advisory firm) on the EKG platform from Stardog (an enterprise knowledge-graph vendor) put the ROI at 320%, most of it from saved infrastructure and data-scientist time. Cisco’s 4 million reclaimed hours tell the same story from the operations side. Priced against numbers like these, the build usually isn’t a close call — as long as you scope it to a real use case.</p><h4>Detailed Insights</h4><ul><li><strong>Cost Savings</strong>: Less manual integration and analysis means lower operating cost and people freed for work that matters.</li><li><strong>Productivity Improvements</strong>: When the right information is one query away, the search tax disappears.</li></ul><h3>Risk and Exposure</h3><p>None of this is free of risk, and you’re the one who’ll answer for it. EKGs pull sensitive data from many systems, so privacy rules matter — compliance with frameworks like GDPR (the General Data Protection Regulation, the European Union’s data-privacy law) isn’t optional. And a large ontology is a maintenance burden: let it drift and your graph starts returning confident, outdated answers. The mitigation is unglamorous — regular audits, a named owner, and a habit of updating the model as the business changes.</p><h3>Common Pitfalls: Navigating the Challenges</h3><h3>Ontology Design and Maintenance</h3><p>The most common way an EKG project dies is quietly: the ontology stops keeping up. As Thoughtworks (a global software consultancy) notes, semantic divergence — where the model no longer matches how the business actually works — is the slow leak. The queries still run. They’re just increasingly wrong.</p><h4>Troubleshooting Tips</h4><ol><li><strong>Regular Reviews</strong>: Revisit the ontology on a schedule so it tracks the business instead of freezing in time.</li><li><strong>Stakeholder Engagement</strong>: Pull in people from across departments so the model reflects how the whole company works, not one team’s view.</li></ol><h3>Data Integration and Scalability</h3><p>Wiring diverse sources into one coherent graph is hard, and it’s where momentum goes to die. As The Data Praxis (a data-strategy publication) observed, plenty of EKG initiatives die in year two — the graph technically works, but nobody planned for the integration and scale it would actually need.</p><h4>Solutions for Success</h4><ol><li><strong>Incremental Integration</strong>: Start with a few sources that matter and grow from there. Manageable beats comprehensive.</li><li><strong>Scalability Planning</strong>: Design for the data volumes and users you’ll have later, not just the ones in the pilot.</li></ol><h3>Expert Perspectives: Insights from Industry Leaders</h3><h3>The Role of Governance in EKG Success</h3><p>Frédéric Verhelst, author of the industry newsletter <em>The Ontology Imperative</em> and an enterprise-AI governance advisor, puts it bluntly: governance can’t be retrofitted. Close your capability gaps <em>before</em> you launch agentic AI (AI systems that act autonomously on your behalf) pilots — because when they fail, it gets blamed on leadership, not the technology.</p><h4>Governance Strategies</h4><ul><li><strong>Clear Policies</strong>: Set the rules for who can access and use what in the graph, up front.</li><li><strong>Risk Management</strong>: Build in the controls that catch data-security and privacy problems before they ship.</li></ul><h3>The Future of GraphRAG</h3><p>Kaleb Schultz, a consultant at the knowledge-management firm Enterprise Knowledge, points out that GraphRAG extends traditional RAG (Retrieval-Augmented Generation — the standard technique of feeding an LLM retrieved documents to ground its answers) by grounding retrieval and reasoning in a graph built on semantic standards — a real step up from vector-only systems in both reliability and explainability. And as Microsoft Research (the research division of Microsoft) notes, its knack for synthesizing answers across many documents is what makes it a building block for the next wave of AI architectures.</p><h4>Future Directions</h4><ul><li><strong>Enhanced Reasoning Capabilities</strong>: Expect more reasoning built on the semantic context the graph provides.</li><li><strong>Broader Adoption</strong>: Expect GraphRAG to spread as more industries watch it work.</li></ul><h3>Key Takeaways</h3><ol><li><strong>Get the ontology right.</strong> It’s the backbone. Model your domain honestly and let it evolve — a frozen model is a dead one.</li><li><strong>Let LLMs do the heavy lifting.</strong> They cut the time and cost of entity extraction and ontology work dramatically. Use them.</li><li><strong>Ground your AI with GraphRAG.</strong> Pairing the graph with vector embeddings is what sharpens the answers and kills hallucinations.</li><li><strong>Plan the integration.</strong> Most projects don’t die on technology. They die on data integration and scale, so design for both early.</li><li><strong>Own the governance early.</strong> You can’t bolt it on after the fact — build it in before the first agent goes live.</li><li><strong>Watch the market.</strong> The category is moving fast. Keep your strategy pointed at where it’s going, not where it was.</li></ol><h3>Conclusion</h3><p>An Enterprise Knowledge Graph isn’t another tool to bolt onto the stack. It’s the context layer that decides whether your AI investment compounds or stalls in year two. Get the design, integration, and governance right and you hand your AI a map of the business it never had. So don’t boil the ocean. Pick the decision that hurts most, model just enough to answer it, and ship something on top within a quarter.</p><p>What’s your experience building an EKG in your organization — early pilot, year-two wall, or real payoff? Share it in the comments, or follow me for more on building enterprise AI you can actually trust.</p><p><em>Sources: Improvado, Neo4j, TigerGraph, Gartner, Cisco, Siemens Energy, Forrester, Thoughtworks, Microsoft Research</em></p><p><em>If you found this article helpful, consider following me for more in-depth articles on AI, developer tools, and software engineering trends.</em></p><p><em>Have questions or a different perspective? Leave a comment below — I read every response and would love to discuss further.</em></p><p><em>You can also reach out to me directly or connect on LinkedIn. Let’s keep the conversation going.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fc0f87c7a7df" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From RAG to Agentic Search: How Retrieval Learned to Think]]></title>
            <link>https://medium.com/@manavghosh/from-rag-to-agentic-search-how-retrieval-learned-to-think-6321d23bc639?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/6321d23bc639</guid>
            <category><![CDATA[agentic-rag]]></category>
            <category><![CDATA[rags]]></category>
            <category><![CDATA[rag-vs-agentic-rag]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Sun, 28 Jun 2026 09:08:04 GMT</pubDate>
            <atom:updated>2026-06-28T09:08:04.433Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1J6xTS6JgyKl64Yy4gg-UQ.png" /></figure><blockquote>“It’s not just retrieving; it’s refining its queries using reasoning, turning RAG into a sophisticated tool, and managing information over time.” — Nicola Sessions, NVIDIA Technical Blog</blockquote><h3>Introduction</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*alk0qXeIBchrsdTwuozgjg.png" /></figure><p>The journey from traditional Retrieval-Augmented Generation (RAG) to Agentic Search represents a profound shift in the methodology of information retrieval in artificial intelligence (AI). Historically, RAG has served as a core component of AI applications, primarily functioning through a static process: retrieving data from a pre-indexed source and generating responses based on that data. This approach, while effective for simple questions, struggles with complex queries. These require nuanced understanding and dynamic interaction.</p><p>Agentic Search, the new frontier in retrieval, introduces intelligence through reasoning-capable agents that refine and adapt the retrieval process. This transformation turns retrieval from a passive information-fetching operation into a dynamic, problem-solving entity. As Ivan Belcic and Cole Stryker, technology writers on IBM’s Think editorial team, put it, “Agentic RAG is a transition from static rule-based querying to adaptive, intelligent problem-solving.” This evolution is critical for enterprise architects and solution designers tasked with developing systems that not only endure but thrive in complex and changing environments. The key question now is how to integrate retrieval with generation intelligently to maximize adaptability and accuracy.</p><p>In this comprehensive exploration, we delve into the core concepts, best practices, real-world examples, statistical insights, common pitfalls, and expert perspectives shaping the transition from traditional RAG to Agentic Search. By the end, you will have a nuanced understanding of why this evolution matters and how it can be strategically implemented in your own systems.</p><h3>Core Concepts</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xeYoBiT4fEY6GQj9ea_Zvw.png" /></figure><h3>Traditional RAG vs. Agentic RAG</h3><p><strong>Traditional RAG</strong> operates on a linear pipeline: it retrieves relevant data using an embedding model and a vector database, then generates responses with a language model. This method is efficient for simple, fact-based queries but falls short when tasked with complex problem-solving. According to Nicola Sessions, who writes about AI infrastructure on NVIDIA’s developer blog, traditional RAG functions as a “quick lookup” system — efficient for speed and cost but limited in scope and adaptability.</p><p><strong>Agentic RAG</strong>, however, embeds AI agents into the retrieval pipeline, introducing a layer of intelligence. These agents engage in tasks such as query planning, decomposition, and iterative refinement, thereby transforming retrieval into an active participant in problem-solving. The taxonomy of architectures within agentic RAG, as outlined in the systematization-of-knowledge paper, includes single-agent routers, multi-agent systems, and hierarchical models. Each architecture enhances capabilities, ranging from simple decision-making to complex and reflective reasoning.</p><h4>Detailed Explanation</h4><p>Traditional RAG’s reliance on vector embeddings limits its ability to understand context and nuance. For example, when retrieving information about “Jaguar,” traditional RAG might struggle to distinguish between the animal and the car brand without additional context. Agentic RAG, conversely, uses agents that can infer context from surrounding data, dynamically adjusting the query approach to retrieve the most relevant information.</p><h3>The Role of AI Agents</h3><p>AI agents in the RAG pipeline increase system adaptability and accuracy by enabling large language models (LLMs) to retrieve information from multiple sources while managing complex workflows. IBM’s definition highlights the transition from static to dynamic interactions, emphasizing systems that manage information over time rather than executing predefined queries. This shift is crucial for systems demanding high accuracy and flexibility, such as enterprise search applications and customer support systems.</p><h4>Practical Implementation Details</h4><p>Implementing AI agents involves integrating machine learning techniques that allow systems to understand context and intent. These agents use reinforcement learning to refine their decision-making over time, improving retrieval accuracy and relevance.</p><h3>Best Practices</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gkUIZ76AcDybeUQcxsuNpw.png" /></figure><h3>Implementing Agentic Retrieval</h3><p>Implementing agentic retrieval involves several best practices to optimize AI systems’ performance and efficiency. Microsoft’s Azure AI Search, for instance, productizes agentic retrieval through an API enabling parallel query processing. Here, an LLM performs query planning, breaking down complex questions into multiple sub-queries processed in parallel. This enhances retrieval accuracy and system capability to synthesize information from diverse sources.</p><h4>Practical Steps</h4><ol><li><strong>Query Decomposition</strong>: Break complex queries into manageable sub-queries.</li><li><strong>Parallel Processing</strong>: Use parallelism to handle multiple sub-queries simultaneously, increasing efficiency.</li><li><strong>Contextual Understanding</strong>: Employ context-aware agents to refine queries based on user intent.</li></ol><h3>Decision Boundaries in Retrieval</h3><p>Understanding and interpreting user intent is a critical challenge in agentic retrieval. As outlined by the Chanl engineering team, which writes about production retrieval systems, a retrieval agent must decide how to retrieve information — not just perform retrieval. This process involves interpreting user intent, rewriting or decomposing the query, selecting appropriate sources, and executing retrieval in a manner aligning with user needs. Misinterpreting intent leads to costly retrieval errors, both in computational resources and user satisfaction.</p><h4>Troubleshooting Tips</h4><ul><li><strong>Intent Analysis</strong>: Implement natural language processing (NLP) models to analyze and understand user intent.</li><li><strong>User Feedback</strong>: Incorporate user feedback loops to refine intent interpretation and retrieval accuracy.</li></ul><h3>The OPERA Architecture</h3><p>The OPERA architecture represents a reinforcement learning-enhanced approach to multi-hop retrieval. It uses an orchestrated planner-executor design to decompose and sequence complex questions. This architecture demonstrates measurable gains in retrieval accuracy and efficiency, highlighting the potential of combining planning and execution with reinforcement learning to enhance retrieval processes.</p><h4>Use Cases</h4><ul><li><strong>Complex Research Queries</strong>: Ideal for academic research where queries require nuanced understanding and multi-step retrieval.</li><li><strong>Customer Support Systems</strong>: Enhances the ability to resolve customer inquiries that involve multiple related queries.</li></ul><h3>Real-World Examples</h3><h3>Claude Code’s Shift to Agentic Search</h3><p>Anthropic’s Claude Code offers a compelling case study of the shift from traditional RAG to agentic search. Initially, the system relied on vector-indexing to retrieve information from a codebase. However, vector similarity alone couldn’t effectively model complex call chains or causal relationships. Consequently, Claude Code transitioned to an agentic approach, dynamically managing retrieval processes and improving accuracy in complex coding tasks.</p><h4>Example Scenario</h4><p>In a software development environment, Claude Code’s agentic retrieval can intelligently navigate a codebase to find relevant snippets, dependencies, and documentation, significantly enhancing a developer’s efficiency.</p><h3>The Router-Then-Agent Architecture</h3><p>Another practical implementation is the router-then-agent architecture, as described by Sapota (SapotaCorp), a software-engineering firm that published a detailed teardown of what agentic RAG actually costs in production. This approach begins with a naive RAG system utilizing hybrid search and reranking for straightforward queries. A small, fast LLM router classifies each query as single-hop, multi-hop, or structured, directing complex queries to an agentic retrieval process. This architecture balances cost and accuracy, using agentic retrieval only when it provides significant benefits.</p><h4>Implementation Details</h4><ul><li><strong>Router Classification</strong>: Use machine learning models to classify query types efficiently.</li><li><strong>Dynamic Routing</strong>: Implement dynamic routing to ensure complex queries are handled by agentic processes, optimizing resource use.</li></ul><h3>Azure AI Search’s Agentic Retrieval</h3><p>Microsoft’s Azure AI Search exemplifies the commercialization of agentic retrieval. By leveraging an LLM for query planning and decomposition, Azure AI Search processes complex questions in parallel, synthesizing accurate and cited responses. This approach not only enhances retrieval accuracy but also improves the system’s ability to handle diverse information sources, making it ideal for enterprise applications requiring high levels of accuracy and flexibility.</p><h4>Example in Practice</h4><p>In an enterprise setting, Azure AI Search can seamlessly integrate with existing data infrastructures, providing employees with precise information retrieval capabilities across multiple departments and data silos.</p><h3>Statistics and Their Implications</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iZLL1E3WsJzs57e9WY_Icw.png" /></figure><p>Quantitative analysis of agentic RAG highlights both strengths and limitations. For example, agentic RAG can outperform naive RAG by 20 to 40 percentage points on genuinely multi-step queries, as reported by Sapota. However, this accuracy comes at a cost: agentic RAG can be 5x to 15x more expensive in terms of LLM spend per query and can add 3x to 10x the latency of naive RAG due to the multi-call retrieve-and-reason loop.</p><h4>Deeper Analysis</h4><p>The increased cost and latency highlight the need for strategic deployment. Organizations must balance the benefits of improved accuracy with the financial and operational implications of higher computational demands. The deployment of agentic RAG should be reserved for scenarios where its capabilities deliver significant value, such as complex decision-making or critical data retrieval tasks.</p><p>Furthermore, Sapota’s analysis indicates that approximately 65–75% of production queries are single-hop lookups, which naive RAG answers correctly at a fraction of the agentic cost. Only 15–25% of queries are genuinely multi-step and benefit from agentic retrieval. This underscores the importance of evaluating the specific use case before implementing an agentic solution.</p><h4>Strategic Deployment</h4><ul><li><strong>Cost-Benefit Analysis</strong>: Perform a thorough cost-benefit analysis to determine when agentic retrieval’s accuracy justifies its cost.</li><li><strong>Query Categorization</strong>: Develop systems to categorize queries efficiently, ensuring agentic processes are employed only for complex, multi-step queries.</li></ul><h3>Common Pitfalls</h3><h3>Retrieval Failures</h3><p>A significant portion of RAG failures, estimated at 73%, occurs before the LLM even sees the query. These failures primarily involve retrieval issues, such as poor chunking, weak embeddings, vocabulary mismatches, and the absence of reranking. Gabriel Anhaia, in a pointed piece on retrieval architecture, points out that teams often mistake a vector database for a search engine, overlooking the need for lexical matching, filtering, and ranking signals.</p><h4>Troubleshooting Tips</h4><ul><li><strong>Chunking Strategy</strong>: Implement robust chunking strategies to ensure data is divided into meaningful units, facilitating more accurate retrieval.</li><li><strong>Embedding Quality</strong>: Focus on improving embedding quality with enhanced training datasets and fine-tuning techniques.</li><li><strong>Reranking Systems</strong>: Develop reranking systems that incorporate contextual and semantic relevance to improve final retrieval results.</li></ul><h3>Structural Limitations of Vector Search</h3><p>Vector search alone cannot solve certain types of queries, such as aggregations, cross-document comparisons, and multi-hop questions. These require a more sophisticated approach that combines vector search with structured retrieval methods. Sean Moran, writing in the Data Science Collective, highlights the limitations of cosine similarity, which ranks by semantic closeness rather than logical satisfaction of the query.</p><h4>Solutions and Workarounds</h4><ul><li><strong>Hybrid Retrieval Models</strong>: Use a combination of vector-based and traditional keyword search methods to capture both semantic and syntactic relevance.</li><li><strong>Structured Query Handling</strong>: Implement systems that can handle structured queries through logic-based retrieval approaches, enhancing the capability to perform aggregations and comparisons.</li></ul><h3>Expert Perspectives</h3><h3>The Role of Representation</h3><p>Yang Chen, author of the widely-shared analysis “The Representation Problem,” emphasizes that the field of retrieval is diversifying — not bifurcating into RAG vs. agentic, but rather expanding into five distinct paradigms. This diversity is driven by the need to represent different data types in their natural forms, whether through vector RAG, agentic search, or structured/graph/memory approaches. The choice of retrieval paradigm should be guided by the specific needs of the application and the nature of the data involved.</p><h4>Considerations for Choice</h4><ul><li><strong>Data Nature</strong>: Evaluate the intrinsic characteristics of the data to determine the most suitable retrieval method.</li><li><strong>Application Needs</strong>: Align retrieval strategies with the specific functional and performance requirements of the application.</li></ul><h3>Cost vs. Accuracy Trade-offs</h3><p>Sapota’s insights into the cost and accuracy trade-offs of agentic RAG underscore the importance of strategic decision-making. Running an agentic pipeline on queries that do not require it results in unnecessary expenses without accuracy gains. The key is to identify which queries truly benefit from agentic retrieval and deploy agentic processes judiciously.</p><h4>Strategic Guidelines</h4><ul><li><strong>Query Analysis</strong>: Implement tools for analyzing query complexity to determine the necessity of agentic retrieval.</li><li><strong>Adaptive Systems</strong>: Develop adaptive systems that can switch between traditional and agentic retrieval modes based on real-time assessment of query requirements.</li></ul><h3>Pattern Options</h3><h3>Architectural Patterns for Agentic RAG</h3><p>Agentic RAG can be implemented using various architectural patterns, each offering unique benefits:</p><ol><li><strong>Single-Agent Routers</strong>: Utilize a single intelligent agent to manage query routing and refinement.</li><li><strong>Multi-Agent Systems</strong>: Employ multiple agents with specialized roles, enhancing flexibility and problem-solving capabilities.</li><li><strong>Hierarchical Models</strong>: Structure agents in a hierarchy, allowing for complex decision-making processes and improved scalability.</li></ol><h3>Trade-Off Analysis</h3><h3>Traditional RAG vs. Agentic RAG</h3><p>Traditional RAG offers cost-effective solutions for simple queries but lacks the adaptability required for complex problem-solving. In contrast, Agentic RAG provides enhanced accuracy and adaptability but at a higher cost and complexity. The choice between these approaches should consider the specific needs of the application, balancing cost, accuracy, and complexity.</p><h3>Failure Modes</h3><h3>Potential Failure Modes in Agentic RAG</h3><p>Agentic RAG implementations can encounter several failure modes:</p><ol><li><strong>Agent Miscommunication</strong>: Agents may misinterpret user intent, leading to incorrect query refinement.</li><li><strong>Resource Overload</strong>: High complexity can lead to resource exhaustion, impacting performance.</li><li><strong>Scalability Issues</strong>: As systems grow, maintaining efficient agent coordination becomes challenging.</li></ol><h3>Decision Criteria</h3><h3>Criteria for Choosing Between RAG and Agentic RAG</h3><p>When deciding between traditional and Agentic RAG, consider the following criteria:</p><ol><li><strong>Query Complexity</strong>: Use Agentic RAG for complex, multi-step queries requiring nuanced understanding.</li><li><strong>Cost Constraints</strong>: Opt for traditional RAG when budget limitations outweigh the need for enhanced accuracy.</li><li><strong>System Flexibility</strong>: Choose Agentic RAG if adaptability to dynamic environments is a priority.</li></ol><h3>Key Takeaways</h3><ol><li><strong>Adaptability and Reasoning</strong>: Agentic RAG enhances retrieval processes by embedding reasoning capabilities, allowing systems to adapt to complex queries and manage information dynamically.</li><li><strong>Cost-Effectiveness</strong>: While agentic RAG offers significant accuracy improvements for complex queries, it is crucial to balance these gains against the increased costs and latency involved.</li><li><strong>Architectural Choices</strong>: The choice between traditional RAG and agentic RAG should be guided by the specific requirements of the application, focusing on the complexity and nature of the queries.</li><li><strong>Failure Mitigation</strong>: Addressing retrieval failures requires a comprehensive approach that includes hybrid retrieval methods, reranking, and intelligent query decomposition.</li><li><strong>Diverse Paradigms</strong>: The evolution of retrieval is not a binary choice but a spectrum of approaches, each suited to different data types and application contexts.</li><li><strong>Strategic Implementation</strong>: A router-then-agent architecture can effectively balance cost and accuracy by directing complex queries to agentic processes only when necessary.</li></ol><h4>Compelling Example</h4><p>Consider a multinational corporation implementing Agentic RAG to enhance its customer support system. By using agentic processes, the system can dynamically interpret and resolve complex customer queries, drawing from a vast array of internal resources. This not only improves customer satisfaction but also reduces response times, demonstrating the tangible benefits of agentic retrieval.</p><h3>Conclusion</h3><p>The transition from traditional RAG to Agentic Search marks a significant evolution in AI retrieval capabilities, offering new opportunities for adaptability, accuracy, and problem-solving. For enterprise architects and solution designers, the challenge lies in strategically implementing these advanced retrieval techniques to meet the specific needs of their systems while managing costs and complexity. As the field continues to evolve, staying informed about the latest developments and best practices will be crucial for leveraging the full potential of retrieval technologies.</p><p><em>Call to Action: As you explore the possibilities of Agentic Search, consider how its dynamic and reasoning capabilities can transform your applications. Engage with industry experts, participate in workshops, and experiment with different architectures to find the best fit for your needs.</em></p><p><em>If you found this article helpful, consider following me for more in-depth articles on AI, developer tools, and software engineering trends.</em></p><p><em>Have questions or a different perspective? Leave a comment below — I read every response and would love to discuss further.</em></p><p><em>You can also reach out to me directly or connect on LinkedIn. Let’s keep the conversation going.</em></p><p><em>Agentic #Search #Retrieval #AI #DeveloperTools #SoftwareEngineering #TechWriting #Productivity</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6321d23bc639" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Token Economics in Agentic AI: A Comprehensive Analysis]]></title>
            <link>https://medium.com/@manavghosh/token-economics-in-agentic-ai-a-comprehensive-analysis-b19631e4386b?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/b19631e4386b</guid>
            <category><![CDATA[tokenomics]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[token-economy]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Sat, 20 Jun 2026 09:14:51 GMT</pubDate>
            <atom:updated>2026-06-20T09:14:51.427Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c0sJUYtet0lVD60uUCqQkA.png" /></figure><blockquote>“The economics of autonomous agents depend less on the model and more on how much thinking, looping, and tool use you permit.” — David Linthicum, InfoWorld</blockquote><h3>Introduction</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*H5iLG3xcGm0Eqd-w_TZQ8g.png" /></figure><p>As the realm of artificial intelligence (AI) continues to advance, agentic AI is becoming a focal point of innovation and exploration. This transformation is characterized by intelligent agents capable of performing complex decision-making processes autonomously. The promise of agentic AI lies in its potential to dramatically enhance efficiency and productivity across various industries. However, this potential comes with a set of intricate economic considerations that cannot be overlooked. Token economics, which refers to the financial mechanisms underlying AI model operations, has emerged as a critical area of focus for enterprises eager to optimize the integration of agentic AI.</p><p>Token economics in agentic AI encompasses much more than just the cost of computational resources. It requires a deep understanding of token consumption patterns and financial implications of agentic workflows. Strategic decision-making can either propel or hinder project success. This comprehensive analysis will delve into foundational concepts, adopting strategic approaches, real-world examples, statistical insights, and potential pitfalls associated with token economics in agentic AI. By the end of this discussion, you will have a thorough understanding of the strategic considerations necessary for optimizing the economic performance of agentic systems.</p><h3>Core Concepts</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Q_Z6L0aKLRuau9TmuSUJBg.png" /></figure><h3>Understanding Token Consumption</h3><p>The operational dynamics of agentic AI differ significantly from traditional AI systems, with token consumption at the heart of these differences. As emphasized by David Linthicum, agentic AI incurs costs driven more by the complexity of tasks performed. These costs are not primarily due to the model itself. Unlike simple chatbot interactions, a sophisticated agentic workflow can consume hundreds of thousands, if not millions, of tokens. This consumption stems from the reliance on reasoning turns, context re-injection, and tool calls.</p><p>Each reasoning turn involves exchanging accumulated context back and forth, leading to a super-linear increase in token consumption. David Daniel’s research supports this, showing that even as token prices decline, total consumption can still result in escalating costs. For example, an agent tasked with customer service may need to access a wide array of tools and databases to formulate the best response, each access adding to the token tally.</p><h4>The Complexity of Reasoning Turns</h4><p>Reasoning turns are not simply about processing information but entail a series of complex calculations and data retrievals. For instance, when an AI agent is tasked with making a financial forecast, it not only taps into historical data but also continuously updates its predictions as new data comes in. Each update represents a new reasoning turn, contributing to token consumption.</p><h4>Context Re-injection and Its Implications</h4><p>Context re-injection is another key factor in token consumption. It involves re-introducing previously processed data into the decision-making process to maintain coherence and relevancy. For example, a medical diagnostic agent might need to revisit a patient’s past medical history multiple times to confirm a diagnosis, each time consuming additional tokens.</p><h3>The Orchestration Tax</h3><p>Agentic AI systems often comprise multiple agents working collaboratively, introducing what Deepanshu Gupta terms the “Orchestration Tax.” This refers to the additional token and latency overhead incurred purely from coordinating multiple agents. The orchestration layer, essential for maintaining state synchronization and messaging between agents, consumes tokens that do not provide immediate user value.</p><h4>Efficient Orchestration Strategies</h4><p>To mitigate the orchestration tax, efficient orchestration strategies are necessary. These include optimizing the communication pathways between agents and minimizing redundant data exchanges. For example, in a logistics company using multiple AI agents for tracking, inventory management, and route optimization, reducing unnecessary data exchanges between these agents can significantly cut down on token consumption.</p><h4>Managing State Synchronization</h4><p>State synchronization is critical for ensuring that all agents have a consistent understanding of the environment and objectives. However, this can lead to excessive token usage if not managed properly. Techniques such as state compression and smart caching can help reduce the need for frequent state updates, thereby lowering token consumption.</p><h3>TokenOps: A Framework for Economic Control</h3><p>TokenOps is an emerging discipline that applies FinOps principles — visibility, allocation, optimization, and governance — to manage large language model (LLM) token consumption. It involves systematically controlling token spend through factors like system prompts, context/memory management, model selection, and retry overhead.</p><h4>Implementing TokenOps in Practice</h4><p>The implementation of TokenOps begins with gaining visibility into token usage across different agents and workflows. Tools like dashboards and analytics platforms can provide real-time insights into where tokens are being consumed most. This visibility allows for better allocation of resources, ensuring that high-priority tasks receive the tokens they need.</p><h4>Optimization and Governance</h4><p>Optimization involves fine-tuning token usage by selecting the most efficient models for specific tasks. Governance, on the other hand, entails setting policies and guidelines to control token spend and align it with business objectives. For instance, establishing a governance policy might involve setting maximum token limits for certain operations and regularly reviewing these limits based on changing requirements.</p><h3>Risk and Exposure</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LYjh3s-lEkRSQXRWXzy7xg.png" /></figure><h3>Understanding Regulatory Risks</h3><p>The adoption of token economics in agentic AI brings potential regulatory risks. Compliance with data protection laws and financial regulations is crucial, as any breach can lead to significant legal and financial repercussions.</p><h3>Mitigating Financial Exposure</h3><p>To mitigate financial exposure, organizations must implement robust monitoring systems and set clear economic guardrails. This includes establishing per-agent budgets, spend caps, and circuit breakers to prevent unexpected financial liabilities.</p><h3>Strategic Approaches</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8BmUjEycHTa3umH6FE1O8Q.png" /></figure><h3>Cost Engineering and Budgeting</h3><p>Cost engineering is a crucial practice in the realm of agentic AI. According to Zylos Research, instrumenting per-agent and per-task token telemetry is essential for precise tracking of token consumption. This allows for the establishment of budgets and spend caps and facilitates the routing of tasks to the most cost-effective models that meet quality standards — a practice known as model tiering.</p><h4>Token Telemetry and Its Benefits</h4><p>Token telemetry involves monitoring and analyzing token usage in real-time. This can be achieved through integrated analytics tools that track consumption patterns and provide insights into potential inefficiencies. For example, if a particular agent consistently consumes a disproportionate number of tokens, telemetry can help identify the underlying cause, whether it’s inefficiencies in reasoning turns or excessive context re-injection.</p><h4>Model Tiering for Cost Reduction</h4><p>Model tiering involves categorizing AI models based on their cost and performance characteristics. By routing tasks to the most appropriate model tier, organizations can achieve significant cost reductions. For instance, routine tasks might be handled by lower-tier, cost-effective models, while complex tasks requiring higher accuracy are assigned to premium models.</p><h3>Adopting Economic Guardrails</h3><p>The potential for runaway costs in agentic AI underscores the necessity of adopting economic guardrails. Revenium’s analysis of a $47,000 runaway agent loop highlights the importance of establishing per-agent budgets, spend caps, and circuit breakers. These mechanisms act as safeguards against unexpected financial exposure by ensuring that token consumption remains within predefined limits.</p><h4>Circuit Breakers in Action</h4><p>Circuit breakers are automated mechanisms that halt operations when predefined thresholds are exceeded. In the context of agentic AI, a circuit breaker might stop an agent from making further API calls if it surpasses its daily token limit. This prevents runaway consumption and ensures that budgets are adhered to.</p><h4>Real-Time Monitoring and Alerts</h4><p>Real-time monitoring and alerts are also essential components of economic guardrails. By setting up automated alerts for unusual token consumption patterns, organizations can quickly identify and address potential issues before they escalate. For example, if an agent suddenly starts consuming tokens at an unusually high rate, an alert can prompt a review of its operations to diagnose and rectify the problem.</p><h3>Mitigating Token Bloat</h3><p>Token bloat, a byproduct of multi-agent systems, can significantly inflate costs. CostLayer’s research shows that coordination overhead in multi-agent designs can make them roughly four times more expensive than single-agent approaches. To mitigate this, enterprises should focus on minimizing shared context reprocessing and optimizing the handoff of intermediate results between agents.</p><h4>Streamlining Context Reprocessing</h4><p>Streamlining context reprocessing involves ensuring that only the necessary information is retained and used by agents. This can be achieved through techniques such as data pruning and context summarization. For example, instead of re-processing an entire customer interaction history, an AI agent might only use the most recent and relevant interactions to inform its decisions.</p><h4>Optimizing Intermediate Result Handoffs</h4><p>Optimizing the handoff of intermediate results between agents is another strategy for reducing token bloat. Techniques such as data compression and smart batching can reduce the amount of data transferred between agents, lowering token consumption without sacrificing performance.</p><h3>Real-World Examples</h3><h3>The Eight-Agent Customer Support Introduction</h3><p>An illustrative example of agentic AI in action is an eight-agent customer support introduction. This system includes agents for intake classification, knowledge retrieval, response drafting, and more. Each agent consumes approximately 2 million tokens per day, resulting in an annual token burn of around $2,190 per agent. This case demonstrates the scalability of token consumption as agents are added to the workflow, highlighting the importance of strategic budgeting and token management.</p><h4>Scalability Challenges and Solutions</h4><p>As the number of agents increases, so does the complexity of managing token consumption. To address this, companies can implement scalable token management systems that allocate tokens dynamically based on agent demand and priority. This ensures that critical operations are never starved of resources.</p><h3>The $47,000 Runaway Agent Loop</h3><p>A cautionary tale within the agentic AI domain is the $47,000 runaway agent loop. This incident occurred when a multi-agent system entered an unbounded recursive loop, accumulating excessive token charges before detection. The financial impact of this loop underscores the need for real-time observability and economic guardrails to prevent similar occurrences in the future.</p><h4>Diagnosing and Preventing Recursive Loops</h4><p>Recursive loops can be diagnosed by monitoring for unusual token consumption patterns and identifying agents that repeatedly execute the same operations. Preventing such loops involves implementing logic checks within the agent’s workflows to ensure that operations terminate when certain conditions are met.</p><h3>Pilot-to-Production Cost Explosion</h3><p>The transition from pilot to production in agentic AI projects can lead to a dramatic increase in token spend. An example from Finout illustrates how a project with a $10,000 monthly token budget during its pilot phase ballooned to $400,000 per month in production. This surge was not triggered by a single decision but rather by the cumulative effect of extended features and team expansions. It highlights the importance of proactive cost modeling and strategic oversight.</p><h4>Managing Cost Transitions</h4><p>Managing the transition from pilot to production requires a thorough understanding of the factors that contribute to cost increases. This includes scaling operations, integrating additional features, and expanding user bases. By modeling these factors in advance, organizations can develop strategies to mitigate cost explosions, such as phased rollouts and incremental feature additions.</p><h3>Statistics</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1WtG_HP8COsfHPzgX7aLDQ.png" /></figure><p>To fully grasp the implications of token economics in agentic AI, one must consider the following statistics:</p><ul><li><strong>100x Increase</strong>: Agentic workloads can consume roughly 100 times more tokens than conversational chat interactions. This increase is driven by the complexity of planning, memory requirements, and tool orchestration.</li></ul><h4>Analyzing the 100x Increase</h4><p>The 100x increase in token consumption reflects the added complexity of agentic workflows compared to simple chat interactions. In a conversational setting, an AI might only need to respond to direct user queries. However, in an agentic setting, the AI must plan and execute multi-step processes, each step consuming additional tokens.</p><ul><li><strong>50x Agent Tax</strong>: A seemingly trivial API call becomes approximately 50 times more expensive when wrapped in an agentic workflow. This phenomenon, known as the “Agent Tax,” results from reasoning tokens, context re-injection, and retries.</li></ul><h4>Understanding the Agent Tax</h4><p>The Agent Tax highlights the hidden costs of agentic workflows. Each layer of reasoning and context management adds to the token burden, turning simple operations into costly endeavors. Recognizing and managing the Agent Tax is essential for maintaining economic efficiency.</p><ul><li><strong>4x Cost of Multi-Agent Designs</strong>: Coordination overhead in multi-agent systems can make them four times more expensive than single-agent approaches, highlighting the need for efficient architecture.</li></ul><h4>Addressing Multi-Agent Coordination Challenges</h4><p>The 4x cost factor in multi-agent designs underscores the importance of efficient coordination mechanisms. By optimizing inter-agent communication and minimizing redundant operations, organizations can reduce costs and improve system performance.</p><ul><li><strong>$47,000 Runaway Loop</strong>: An unbounded multi-agent loop resulted in approximately $47,000 in token charges, emphasizing the importance of implementing economic guardrails.</li></ul><h4>Lessons Learned from the Runaway Loop</h4><p>The runaway loop serves as a stark reminder of the potential for uncontrolled token consumption in agentic systems. Implementing robust monitoring and control mechanisms can prevent similar incidents and safeguard against financial exposure.</p><ul><li><strong>$2,190 Annual Token Burn</strong>: An agent consuming 2 million tokens per day incurs an annual token burn of about $2,190, illustrating the financial implications of token consumption.</li></ul><h4>Calculating Token Burn and Its Implications</h4><p>Calculating token burn involves understanding the daily token usage patterns of each agent and projecting these patterns over time. This helps organizations forecast costs and allocate resources effectively.</p><p>These statistics highlight the financial complexities associated with agentic AI and underscore the importance of strategic decision-making in managing token economics.</p><h3>Common Pitfalls</h3><h3>The Agentic Inference Cost Trap</h3><p>One of the most significant pitfalls in agentic AI is the “Agentic Inference Cost Trap.” Teams often pilot agents on low-volume workloads, observing attractive economics, only to face escalating costs during production. This phenomenon occurs as reasoning depth, tool use, and concurrency push inference costs far beyond initial projections.</p><h4>Avoiding the Inference Cost Trap</h4><p>Avoiding this trap requires thorough modeling of production environments during the pilot phase. By simulating high-volume operations and considering scaling factors, organizations can develop realistic cost projections and implement appropriate controls.</p><h3>The Jevons Paradox in AI</h3><p>The Jevons Paradox, which posits that increased efficiency can lead to greater resource consumption, is evident in the AI sector. As token prices drop, enterprises are inclined to consume more tokens, driven by longer reasoning chains and increased agent autonomy.</p><h4>Monitoring for the Jevons Paradox</h4><p>To counteract the Jevons Paradox, continuous monitoring and optimization of token consumption are essential. By analyzing usage patterns and identifying areas of excessive consumption, organizations can implement measures to curb unnecessary token use.</p><h3>Expert Perspectives</h3><h3>David Linthicum on Economic Dependencies</h3><p>David Linthicum emphasizes that the economics of agentic AI hinge more on task complexity than on the model itself. This insight underscores the importance of optimizing workflows to manage token consumption effectively.</p><h3>Finout Team on Token Spend Dynamics</h3><p>The Finout team highlights the transition of token spend from a line item to a cost center. This transition, which can occur within a single quarter, necessitates strategic oversight and budgeting to manage financial exposure.</p><h3>Sasha Rogelberg on Rising AI Spend</h3><p>Sasha Rogelberg’s observations on the increase in AI spend despite falling token prices offer a cautionary tale for enterprises. The expansion of modality and increased autonomy lead to greater consumption, reinforcing the need for strategic cost management.</p><h3>Enterprise Tools for Monitoring Token Usage</h3><p>For executives, the gap between an attractive pilot and a defensible production business case is almost always <em>visibility</em>. You cannot govern what you cannot measure, and token spend is invisible without deliberate instrumentation. The good news is that a mature tooling market now exists to give finance and engineering a shared view of consumption, cost, and value. The categories below map to the three questions a CxO should be able to answer at any time: <em>Where are tokens going? Who can enforce limits? How does spend map to the business?</em></p><h3>LLM Observability &amp; Cost Tracking</h3><p>These platforms log every model call with per-request token and cost attribution — the foundation of TokenOps.</p><ul><li><strong>Helicone</strong> — Open-source observability that captures every LLM call with per-request token and cost data; fast to adopt as a drop-in proxy. <a href="https://www.helicone.ai/">helicone.ai</a></li><li><strong>Langfuse</strong> — Open-source LLM engineering platform with traces, cost and token dashboards, and budget analytics across models and teams. <a href="https://langfuse.com/">langfuse.com</a></li><li><strong>LangSmith</strong> — LangChain’s tracing and evaluation suite, with token-cost breakdowns per run, per feature, and per user. <a href="https://www.langchain.com/langsmith">langchain.com/langsmith</a></li><li><strong>Arize</strong> — Enterprise AI observability (and the open-source Phoenix project) that traces agent runs, cost, and output quality together. <a href="https://arize.com/">arize.com</a></li><li><strong>Datadog LLM Observability</strong> — Folds token spend and latency into the same APM dashboards many enterprises already run organization-wide. <a href="https://www.datadoghq.com/product/llm-observability/">datadoghq.com</a></li><li><strong>Weights &amp; Biases Weave</strong> — Trace-level logging of agent calls with token and cost rollups for teams building and tuning models. <a href="https://wandb.ai/site/weave">wandb.ai/site/weave</a></li></ul><h3>AI Gateways with Cost Governance</h3><p>Gateways sit in front of every model provider and turn budgets, spend caps, and routing policy into enforced controls.</p><ul><li><strong>Portkey</strong> — An AI gateway that centralizes routing, budgets, spend caps, and per-team cost governance across multiple providers. <a href="https://portkey.ai/">portkey.ai</a></li><li><strong>TrueFoundry</strong> — An LLM gateway with rate limits, budget controls, and usage analytics built for large enterprise agent fleets. <a href="https://www.truefoundry.com/">truefoundry.com</a></li><li><strong>Databricks Unity AI Gateway</strong> — Multi-model governance and cost control native to the Databricks platform. <a href="https://www.databricks.com/product/artificial-intelligence/unity-ai-gateway">databricks.com</a></li></ul><h3>FinOps / TokenOps &amp; Spend Allocation</h3><p>These tools connect raw token consumption to unit economics — the language a CFO and board expect.</p><ul><li><strong>Finout</strong> — Extends FinOps discipline to tokens (“TokenOps”), allocating LLM spend to teams, features, and products. <a href="https://www.finout.io/">finout.io</a></li><li><strong>CloudZero</strong> — Maps AI and cloud spend to unit economics so finance can tie token cost directly to business value. <a href="https://www.cloudzero.com/">cloudzero.com</a></li><li><strong>Revenium</strong> — Real-time metering and economic guardrails for agentic systems, with spend caps designed to stop runaway loops before they bill. <a href="https://www.revenium.ai/">revenium.ai</a></li></ul><p>A practical starting point: pair one observability platform (to <em>see</em> spend) with one gateway (to <em>enforce</em> limits), then layer FinOps allocation once consumption justifies the rigor. Most runaway-cost incidents trace back to missing one of these three layers, not to the price of any single model.</p><h3>Key Takeaways</h3><ol><li><strong>Strategic Budgeting Is Crucial</strong>: Establishing clear budgets and economic guardrails is essential to prevent runaway costs in agentic AI projects.</li><li><strong>Optimize Token Consumption</strong>: Employ strategies such as model tiering and minimizing shared context to reduce unnecessary token consumption.</li><li><strong>Monitor and Adjust Continuously</strong>: Adopt real-time observability and adjust strategies as token consumption patterns evolve.</li><li><strong>Understand the Orchestration Tax</strong>: Recognize and mitigate the orchestration tax by optimizing multi-agent coordination.</li><li><strong>Be Aware of the Jevons Paradox</strong>: As tokens become cheaper, resist the temptation to increase consumption without strategic oversight.</li><li><strong>Guard Against the Inference Cost Trap</strong>: Model production costs accurately, considering the full complexity of agentic workflows.</li></ol><h3>Conclusion</h3><p>The world of agentic AI offers tremendous potential for enhancing enterprise value, but the path to realizing this potential is fraught with economic challenges. Token economics is a critical factor that requires careful consideration and strategic management. By understanding the intricacies of token consumption, adopting strategic approaches, and guarding against common pitfalls, organizations can harness the power of agentic AI while maintaining control over their financial commitments.</p><p>Inaction in this area could lead to unsustainable cost structures and missed opportunities. Conversely, proactive engagement with token economics can create a competitive moat and drive enterprise success. As you navigate the complexities of agentic AI, consider the insights shared in this analysis and take decisive action to optimize your approach. The future of AI is agentic, and the time to refine your token economics strategy is now.</p><h3>Market Context</h3><p>The current market landscape for agentic AI is rapidly evolving. Enterprises across sectors such as finance, healthcare, and logistics are adopting agentic AI to drive efficiency and innovation. However, they must navigate the economic complexities that come with it. The competitive pressure to leverage agentic AI effectively is mounting, making strategic economic management more critical than ever.</p><h3>Strategic Options</h3><p>Organizations looking to leverage token economics in agentic AI have several strategic paths to consider. These include investing in advanced token management platforms, developing custom orchestration solutions, and partnering with AI service providers to optimize token usage. By exploring these options, enterprises can tailor their strategies to align with business objectives and capitalize on the transformative potential of agentic AI.</p><p><em>If you found this article helpful, consider following me for more in-depth articles on AI, developer tools, and software engineering trends.</em></p><p><em>Have questions or a different perspective? Leave a comment below — I read every response and would love to discuss further.</em></p><p><em>You can also reach out to me directly or connect on LinkedIn. Let’s keep the conversation going.</em></p><p><em>#AgenticAI #TokenEconomics #AICostManagement #FinOps #TokenOps #LLMOps #EnterpriseAI #AIStrategy #AILeadership #AIGovernance #CIO #CTO #AIObservability #GenAI</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b19631e4386b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Graphify + Claude Code: How I Cut Token Usage by 71x on a 50k-Line Codebase]]></title>
            <link>https://medium.com/@manavghosh/graphify-claude-code-how-i-cut-token-usage-by-71x-on-a-50k-line-codebase-74868ac67fd1?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/74868ac67fd1</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[token]]></category>
            <category><![CDATA[claude-code-hooks]]></category>
            <category><![CDATA[graphify]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Fri, 24 Apr 2026 18:12:01 GMT</pubDate>
            <atom:updated>2026-04-24T18:12:01.563Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gqNpB1RKd042xecSxSrHLQ.png" /></figure><p><em>Stop searching your codebase. Start reading its map.</em></p><p>Six tool calls to answer one question. That’s the tax you pay when your AI agent has no map.</p><p>You ask it to make a change. It runs Glob. Then Grep. Then reads the wrong file. Then reads another one. Then asks a clarifying question. Six tool calls later, it’s got enough context to take one step — and the next question starts the cycle over. By the time you finish the task, you’ve burned through a context window’s worth of tokens on navigation overhead, not on the actual work.</p><p>This isn’t a prompt engineering problem. It’s a structural one. Claude Code is fast and capable, but it starts every session blind. It has to discover your codebase the same way a new hire would on day one — by searching around and asking questions.</p><p>[<em>Graphify</em>](<em>https://github.com/safishamsi/graphify</em>) changes that. It pre-compiles your codebase into a knowledge graph and injects that graph as context before Claude ever touches a file. What used to take eight Glob calls to find now takes one.</p><p><strong>What Graphify Does (and Why It’s Not RAG)</strong></p><p><strong>Graphify 3-pass analysis pipeline: AST, Audio/Video, Semantic — with output artifacts</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*n4GbD9JPmF4_50OKYTHEEw.png" /></figure><p>The framing that clicked for me: Graphify is a compiler, not a retrieval system.</p><p>RAG chunks your code, embeds it, and retrieves at query time. Every session re-reads the same files. Every question triggers the same embedding lookup. The knowledge stays flat — no accumulated structure, no cross-file understanding, just semantic similarity scoring.</p><p>Graphify processes your codebase <em>*once*</em>, at build time, and produces a structured knowledge graph. Subsequent sessions query that pre-compiled graph — they don’t re-read your source files.</p><p>Three passes happen during that build:</p><p><strong>Pass 1 — AST Analysis (local)</strong>: tree-sitter parses your source code into abstract syntax trees. Functions, classes, imports, call graphs, dependency chains. 25+ languages supported. Your machine only. Nothing leaves.</p><p><strong>Pass 2 — Audio/Video (local)</strong>: Whisper transcribes any audio or video files in your corpus — demo recordings, design walkthroughs, meeting captures. Also local.</p><p><strong>Pass 3 — Semantic Analysis (LLM API)</strong>: This is the only network call. Documentation, comments, and transcripts are sent to the LLM API to extract semantic relationships. Source code never leaves your machine — only documentation and descriptions.</p><p>The output: `graph.json` (the machine-readable graph), `graph.html` (a visual explorer you can open in a browser), and `GRAPH_REPORT.md` (a plain-English summary of what was found).</p><p>The privacy boundary is explicit and worth noting: if you’re working on proprietary code, your actual implementation never hits a cloud API. Only the documentation layer does.</p><p><strong>Installing Graphify with Claude Code</strong></p><p>The project is open source at [github.com/safishamsi/graphify](https://github.com/safishamsi/graphify). Three commands to get running:</p><pre>pip install graphifyy<br>graphify install<br>graphify claude install</pre><p>That last command writes a `PreToolUse` hook to your Claude Code `settings.json`. You don’t have to configure anything manually.</p><p>Then build your first graph:</p><pre>cd your-project<br>graphify run</pre><p>On a 50K-line Python/TypeScript monorepo this takes roughly 90 seconds on first run. Subsequent incremental builds are faster — Graphify only reprocesses changed files.</p><p>The hook that gets written to `settings.json` looks like this:</p><pre>{<br> &quot;hooks&quot;: {<br>  &quot;PreToolUse&quot;: [<br>   {<br>    &quot;matcher&quot;: &quot;Glob|Grep&quot;,<br>    &quot;hooks&quot;: [<br>     {<br>      &quot;type&quot;: &quot;command&quot;,<br>      &quot;command&quot;: &quot;graphify hook-context&quot;<br>     }<br>    ]<br>   }<br>  ]<br> }<br>}</pre><p>Every time Claude Code is about to run Glob or Grep, this hook fires first. It queries the graph and returns a structured JSON payload with relevant nodes, edges, and community context. Claude receives that as a system message — a map of what’s nearby before it even starts searching.</p><p><strong>How the PreToolUse Hook Works</strong></p><p><strong>PreToolUse hook flow: from Glob/Grep call to graph context injection to targeted 1-hop search</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6iaTqES4sbcYjH7sOuqzqA.png" /></figure><p>The hook mechanism is what makes the whole thing elegant.</p><p>Claude Code fires hooks as shell commands and expects JSON back on stdout. The hook output can include an `additionalContext` field — and whatever’s in that field gets injected into Claude’s context as a system message before the tool runs.</p><p>When you ask Claude to find your authentication middleware, here’s what happens:</p><p>1. Claude decides to run Glob</p><p>2. `PreToolUse` hook fires — `graphify hook-context` runs</p><p>3. Graphify queries the graph for nodes relevant to the current task</p><p>4. It returns structured JSON with node names, edges, and the community cluster they belong to</p><p>5. Claude reads that context, identifies `AuthMiddleware → UserService → TokenValidator` as the relevant cluster</p><p>6. Claude runs a single, targeted Glob call pointed directly at the right files</p><p>Before Graphify: finding that middleware chain might take 6–8 Glob/Grep calls and 4,000+ tokens. After: one call, under 100 tokens.</p><p><strong>The Graph Up Close: Concepts Worth Understanding</strong></p><p>Once you’ve built a graph and opened `graph.html`, a few things are worth paying attention to.</p><p><strong>God nodes</strong> are the highly connected hubs — nodes with disproportionate incoming and outgoing edges. In most codebases, god nodes map directly to your core abstractions: a central service, a shared utility module, a configuration class that everything imports. Identifying them gives you an immediate read on your codebase’s architectural health. Too many god nodes is a smell. One or two well-named ones is often just good design.</p><p><strong>Edge classification</strong> is Graphify’s way of being honest about what it knows. Every edge gets tagged:</p><p>- EXTRACTED — directly observed from AST parsing (a function calls another function)</p><p>- INFERRED — derived from context (two modules in the same community likely interact)</p><p>- AMBIGUOUS — the relationship exists but the direction or type is uncertain</p><p>When Claude is navigating your graph, it’s working with these confidence levels. An `EXTRACTED` edge is a fact. An `INFERRED` edge is a strong guess. When you’re doing architectural analysis, the distinction matters.</p><p><strong>Leiden community detection</strong> clusters your nodes into communities based on connectivity density. In practice, these communities map well to functional modules — your auth cluster, your data layer, your API handlers. The graph visualizer color-codes them. Opening `graph.html` and looking at the community structure is often the fastest way to understand what a new codebase actually does.</p><p><strong>Real Numbers: What 71.5x Token Reduction Means</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Dq_d7rpWP8Sy6-SZopkWAw.png" /></figure><p>The 71.5x figure is Graphify’s own benchmark on a mixed corpus — source code, documentation, audio transcripts. Let me break down what it actually means in practice.</p><p>In a typical Claude Code session on a 200-file codebase, navigation overhead — Glob calls, Grep calls, reading wrong files, re-reading for context — runs somewhere between 80,000 and 150,000 tokens per hour of work. That’s not the work itself; that’s Claude trying to find its way around.</p><p>With a pre-built graph, that navigation overhead drops to graph lookups and single targeted reads. The 71.5x isn’t a cherry-picked best case — it’s the ratio that holds on mixed corpora where code, docs, and media are all in scope.</p><p>At current Sonnet pricing, a typical development session without Graphify might cost $0.30–0.60 in navigation tokens alone. With Graphify, that drops to under $0.01. The graph build itself costs roughly $0.001 on a 1,000-file repo. It pays for itself in the first five minutes.</p><p>The performance benefit matters too. Fewer tool calls means shorter round-trips. Sessions that used to feel sluggish — because Claude was spending half its time searching — run noticeably faster.</p><p><strong>Practical Tips for Senior Engineers</strong></p><p>A few things I’d tell my past self before running this on a production codebase:</p><p><strong>Rebuild after major refactors — not just incremental ones.</strong> Graphify’s incremental rebuild handles file-level changes well. But when you restructure modules or move things between layers, the graph topology changes in ways the diff doesn’t fully capture. 90-second full rebuild is worth it after any architectural move.</p><p><strong>Polyglot monorepos are where this earns its keep.</strong> Python services, TypeScript orchestration, Go infra — all in one Claude session. Graphify builds per-language AST graphs and then unifies them in the semantic pass. It handles cross-language traces (TypeScript calling a Python API, for instance) better than anything I’ve tried at the file-search level.</p><p><strong>God nodes are information, not accusations.</strong> If your shared config module shows up as a god node connecting to 80% of the codebase, the graph isn’t wrong. It’s just honest. Use that to understand the load-bearing parts of the architecture, not to start a refactoring spiral.</p><p><strong>Layer it with CLAUDE.md.</strong> Graphify answers “what is this codebase and how does it connect.” CLAUDE.md answers “how should you work in this codebase.” They don’t overlap. Run both.</p><p><strong>Read the source before using it on proprietary code.</strong> The privacy claim is real — source code doesn’t leave your machine — but verify it yourself before putting sensitive IP through any new tool. The v0.3 source is readable and short. Ten minutes of review is worth it.</p><p><strong>What It Doesn’t Do</strong></p><p>A few limitations worth knowing before you set expectations:</p><p><strong>Dynamic dispatch and runtime patterns are harder to capture.</strong> If your code relies heavily on dependency injection, factory patterns, or late-bound polymorphism, the static AST analysis will miss some connections. The graph will be incomplete in those areas. Semantic inference helps, but it’s working from documentation, not runtime behavior.</p><p><strong>Graph quality mirrors code clarity.</strong> A well-structured codebase with clear module boundaries produces a clean, useful graph. A codebase with circular dependencies, god modules everywhere, and undocumented utilities produces a noisy graph. Graphify doesn’t fix architectural problems — it reflects them accurately.</p><p><strong>It’s not a replacement for reading code.</strong> Before a complex refactor, you still need to read the relevant files. The graph helps you find them faster and understand how they connect. It doesn’t replace deep understanding of what the code actually does.</p><p><strong>My Numbers: What I Saw on My Own Projects</strong></p><p>I ran Graphify on my open-source [API2MCP](<a href="https://github.com/manavghosh/api2mcp"><em>https://github.com/manavghosh/api2mcp</em></a>) project — a universal API-to-MCP server converter with LangGraph orchestration (Python, ~20,000 lines, multiple modules). This is where the numbers got real for me.</p><p><strong>API2MCP (~20,000 lines, Python)</strong></p><p>API2MCP converts REST/GraphQL APIs into fully functional MCP servers. The architecture has clear vertical layers — parsers, generator, transport, orchestration, CLI — but they’re woven together by several cross-cutting concerns that make navigation genuinely non-trivial.</p><p>Input validation threads through every parser (OpenAPI 3.0/3.1, Swagger 2.0, GraphQL SDL, Postman Collections). The secret management layer — which handles environment variables, OS keychain, HashiCorp Vault, and AWS Secrets Manager — is called from four different authentication flows (API key, Bearer, Basic, OAuth 2.0 with PKCE). And the LangGraph orchestration layer’s three graph types (`ReactiveGraph`, `PlannerGraph`, `ConversationalGraph`) each reach into the `MCPToolAdapter` and `state/` modules independently, so changing one has ripple effects that aren’t obvious from reading any single file.</p><p>Before Graphify, every Claude Code session on this codebase started with the same 10-minute context dump. Here’s the parser structure. Here’s how the MCP Tool Generator maps JSON Schema types. Here’s where the LangGraph adapters live. I was burning 12,000–18,000 tokens per session just reconstructing what I already knew.</p><p>With Graphify, that stopped. One `graphify run` — 90 seconds — and the graph held all of it. Navigation overhead dropped to under 2,000 tokens per session.</p><p><strong>The architectural question that changed my workflow</strong></p><p>When I was adding a fourth graph type alongside `ReactiveGraph`, `PlannerGraph`, and `ConversationalGraph`, I asked Claude: <em>*”What would break if I added a new orchestration graph type?”*</em></p><p>Before Graphify, answering that required me to manually trace through four files and walk Claude through the relationships. With Graphify, the answer came back in one pass — fully cited, correct on the first try:</p><p>- `MCPToolRegistry` in `orchestration/adapters/` — the graph dispatch table needed a new entry</p><p>- `cli.py` — the ` — graph-type` argument had a hardcoded enum validator</p><p>- Two test fixtures in `tests/unit/orchestration/` that asserted against a fixed list of graph names</p><p>- The `ConversationalGraph` base class — the new type needed to inherit from it to get streaming support via `astream_events v2`</p><p>One question. Under 2,500 tokens. That same trace used to take me 20 minutes and three separate Grep sessions.</p><p><strong>What Graphify caught that I missed</strong></p><p>The graph surfaced something I hadn’t consciously registered: a high-connectivity cluster between `InputValidator` — which handles SQL injection and command injection protection — and the OpenAPI parser. The validator was being instantiated inside the parser rather than injected. Tight coupling I’d worked around in tests by mocking at a higher level, which masked the problem.</p><p>Graphify’s EXTRACTED edge count flagged it: the parser had 14 outgoing edges to the validator, an unusually dense cluster for two modules that should have been independent. I refactored the dependency injection in the next session. Parser test coverage went from 71% to 94% once I could test it with a stub validator.</p><p><strong>The sessions that compound</strong></p><p>The wins I notice most aren’t the big architectural traces — they’re the small ones that used to be annoying.</p><p>“Which checkpoint saver supports PostgreSQL?” — one hop to `SqliteSaver` and `PostgresSaver` in `orchestration/state/`, answered without pulling up the docs. “Where does the OAuth 2.0 PKCE flow live?” — direct answer: `src/api2mcp/security/auth/oauth2.py`, called from exactly two places, graph shows both. “What’s the difference between how `PlannerGraph` and `ReactiveGraph` handle tool execution?” — the graph’s community detection had placed them in separate clusters with distinct connection patterns to the `MCPToolAdapter`, which immediately explained why their streaming behavior differed.</p><p>Before Graphify, those questions were either answered by grep (fast but context-free) or by asking Claude to explore (slower and sometimes wrong). Now they’re just answered — fast, cited, and grounded in the actual graph structure of the codebase.</p><p><strong>Getting Started in 10 Minutes</strong></p><pre>pip install graphifyy<br>graphify install<br>graphify claude install<br><br>cd your-project<br>graphify run</pre><p>Then open Claude Code in that directory and ask something architectural — “what are the main modules in this codebase?” or “how does the data flow from API to database?”</p><p>The first thing to check in `graph.html`: find your god nodes. Those are your architecture. Everything else connects through them.</p><p><strong>The Shift Worth Making</strong></p><p>There’s a pattern that shows up across every productivity tool in software: the most valuable ones don’t make you faster at what you were already doing — they eliminate entire categories of work that shouldn’t have existed in the first place.</p><p>Graphify fits that pattern. The token savings are real and measurable. But the more meaningful change is subtler: you stop spending cognitive energy on navigation and spend it entirely on the work itself. You stop explaining your codebase to your AI agent before every session and start asking it harder questions instead.</p><p>On API2MCP, the sessions I described weren’t exceptional — they were typical. A 20-minute architectural trace becoming a 2-minute conversation. A dependency problem I’d worked around for months surfacing in a graph report after 90 seconds. Test coverage jumping because a structural problem was finally visible.</p><p>None of that happened because the LLM got smarter. It happened because the LLM finally had the map.</p><p>If you’re working on a codebase with more than a few thousand lines — particularly one with multiple modules, cross-cutting concerns, or polyglot layers — the 10-minute setup is worth it. The graph pays for itself before your first session is over.</p><p>And when you find your god nodes, you’ll recognize them immediately. They’re the files you already have open in every other tab.</p><p><em>I’ve been running Graphify on API2MCP for several weeks now. The token reduction is significant, but what I didn’t expect was how much it changed the quality of the questions I ask. If you’re seeing similar patterns — or different ones</em></p><p><em>*Building with Claude Code or working on MCP tooling? Connect on LinkedIn — always up for a conversation.*</em></p><p>#ClaudeCode #Graphify #KnowledgeGraph #AITools #DeveloperProductivity #SoftwareEngineering #TokenOptimization #AIAgents #MCP #OpenSource</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=74868ac67fd1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building an LLM Wiki with Claude Code and Obsidian]]></title>
            <link>https://medium.com/@manavghosh/building-an-llm-wiki-with-claude-code-and-obsidian-eb6c0990e723?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/eb6c0990e723</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[obsidian]]></category>
            <category><![CDATA[llm-wiki]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Fri, 17 Apr 2026 16:34:25 GMT</pubDate>
            <atom:updated>2026-04-17T16:34:25.752Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SrFDZckUy0cPdhEioXXnXA.png" /></figure><p>Every engineer I know has the same problem.</p><p>You’ve spent years accumulating knowledge — blog posts, research papers, architecture notes, post-mortems, design decisions. It lives in Notion, Confluence, bookmarks, scattered markdown files, and your own head. Every time you need to synthesize something — a new proposal, a tech evaluation, a blog post — you start from scratch. You rediscover what you already know.</p><p>RAG-based tools like NotebookLM or ChatGPT file uploads don’t solve this. They retrieve and forget. Ask a question today, get an answer. Ask the same question in a different way tomorrow — same retrieval process, same synthesis effort, zero compounding. Your knowledge base stays flat.</p><p>Andrej Karpathy posted a deceptively simple idea in April 2026 that went viral: use an LLM to <em>*compile*</em> your raw sources into a structured wiki — once — and then query that compiled knowledge forever. He called it an LLM Wiki. His personal wiki on a single research topic had grown to approximately 100 articles and 400,000 words without him writing a single line directly.</p><p>This post is a hands-on walkthrough for senior technical staff who want to set one up for their own corpus of work — using Claude Code as the agent and Obsidian as the viewer.</p><p><strong>The Core Insight: Compile, Don’t Retrieve</strong></p><p>The analogy Karpathy uses is a compiler. Your raw sources (articles, papers, notes) are source code. The LLM is the compiler. The wiki is the executable output.</p><p>In a RAG system, every query re-reads the source. In an LLM Wiki, the LLM processes sources <em>*at ingestion time*</em>, extracts concepts, creates structured pages, and builds cross-references. Subsequent queries read the already-compiled wiki — not the raw documents.</p><p>The result:</p><p>- <strong>Compounding knowledge</strong>— each new source integrates into what’s already there</p><p>- <strong>Cross-document synthesis</strong>— connections between documents are pre-built, not discovered on demand</p><p>- <strong>Zero retrieval overhead</strong> — you’re querying structured markdown, not chunking and embedding</p><p>- <strong>Human-readable</strong> — Obsidian’s graph view shows you your knowledge topology</p><p>The tradeoff (and it’s real): compiled knowledge can accumulate errors. If the LLM misunderstands a source during ingest, that misunderstanding propagates. We’ll address this with the lint operation and source-linking convention.</p><p><strong>What You’re Building</strong></p><p>your-wiki folder structure</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/866/1*78umVgGEVQ0Co6qrR848qA.png" /><figcaption>llm wiki folder structure</figcaption></figure><p>```</p><p>Three layers, each with a distinct role:</p><p>- <strong>`raw/`</strong> — source-of-truth, never touched after ingest. If the wiki gets corrupted, you can always rebuild from here.</p><p>- <strong>`wiki/`</strong> — LLM-generated, LLM-maintained. You read it but rarely write it directly.</p><p>- <strong>`CLAUDE.md`</strong> — the contract between you and the LLM agent. This is the most important file.</p><p><strong>Step 1: Install Prerequisites</strong></p><p>You need Claude Code and Obsidian. That’s it. No vector database, no embedding pipeline, no cloud service.</p><p><strong>Claude Code</strong></p><p>```bash</p><p>npm install -g @anthropic/claude-code</p><p>```</p><p>Claude Code requires Node.js 18+. Verify your install:</p><p>```bash</p><p>claude — version</p><p>```</p><p><strong>Obsidian</strong></p><p>Download from [obsidian.md](https://obsidian.md) — it’s free for personal use. When you open it, point it at your `your-wiki/` directory as a new vault. Obsidian treats the entire folder as a vault and will render all `.md` files with its graph view.</p><p><strong>Step 2: Write Your CLAUDE.md</strong></p><p>This is the file that transforms Claude Code from a generic assistant into a disciplined wiki curator. It defines page templates, naming conventions, source-linking requirements, and the exact commands the LLM follows.</p><p>Here’s a production-ready `CLAUDE.md` template. Customize the domain section to match your area:</p><p>```markdown</p><p><strong>Wiki Schema and Operating Instructions</strong></p><p><strong>Purpose</strong></p><p>This wiki compiles knowledge about [YOUR DOMAIN — e.g., “agentic AI systems,</p><p>enterprise architecture, and open-source developer tooling”].</p><p>It is maintained by an LLM agent (Claude Code). Humans add sources to raw/</p><p>and issue commands. The LLM handles all wiki writing and maintenance.</p><p><strong>Core Principles</strong></p><p>1. Every claim in the wiki MUST link back to a source in raw/ using [[wikilink]] syntax</p><p>2. Never invent connections not supported by source material</p><p>3. Prefer accuracy over completeness — a shorter correct page beats a longer speculative one</p><p>4. All wiki pages use the templates below — no exceptions</p><p><strong>Page Templates</strong></p><p><strong>### Concept Page (wiki/concepts/)</strong></p><p>Use for: technologies, frameworks, methodologies, domain terms</p><p>```</p><p><strong>— -</strong></p><p>title: [Concept Name]</p><p>type: concept</p><p>tags: [tag1, tag2]</p><p>sources: [raw/articles/source.md]</p><p>updated: YYYY-MM-DD</p><p><strong>— -</strong></p><p><strong>Summary</strong></p><p>One paragraph. What is it, why does it matter.</p><p><strong>How It Works</strong></p><p>Core mechanics. Diagrams as Mermaid where useful.</p><p><strong>Key Properties</strong></p><p>- Property 1: explanation</p><p>- Property 2: explanation</p><p><strong>When To Use / When Not To Use</strong></p><p>Concrete guidance, not platitudes.</p><p><strong>Related Concepts</strong></p><p>- [[ConceptA]] — how it relates</p><p>- [[ConceptB]] — how it relates</p><p><strong>Source References</strong></p><p>- [[raw/articles/source.md]] — what this source contributes</p><p>```</p><p>Project Page (wiki/projects/)</p><p>Use for: tools, systems, products you’ve built or evaluated</p><p>```</p><p><strong>— -</strong></p><p>title: [Project Name]</p><p>type: project</p><p>tags: [tag1, tag2]</p><p>sources: [raw/…]</p><p>updated: YYYY-MM-DD</p><p><strong>— -</strong></p><p><strong>What It Is</strong></p><p>One paragraph. Purpose and scope.</p><p><strong>Architecture</strong></p><p>High-level description. Mermaid diagram if helpful.</p><p><strong>Key Design Decisions</strong></p><p>Each decision with rationale.</p><p><strong>Status</strong></p><p>[Active / Deprecated / Evaluated]</p><p><strong>Related</strong></p><p>- [[ConceptA]]</p><p>- [[ProjectB]]</p><p><strong>Source References</strong></p><p>- [[raw/…]]</p><p>```</p><p>Pattern Page (wiki/patterns/)</p><p>Use for: recurring solutions, anti-patterns, architectural patterns</p><p>```</p><p><strong>— -</strong></p><p>title: [Pattern Name]</p><p>type: pattern</p><p>tags: [tag1, tag2]</p><p>sources: [raw/…]</p><p>updated: YYYY-MM-DD</p><p><strong>— -</strong></p><p><strong>Problem</strong></p><p>What situation does this address.</p><p><strong>Solution</strong></p><p>The pattern itself.</p><p><strong>When It Applies</strong></p><p>Concrete conditions.</p><p><strong>Trade-offs</strong></p><p>Honest assessment of downsides.</p><p><strong>Examples</strong></p><p>Real instances from the corpus.</p><p><strong>Related</strong></p><p>- [[PatternA]]</p><p>- [[ConceptB]]</p><p><strong>Source References</strong></p><p>- [[raw/…]]</p><p>```</p><p>— -</p><p>Operations</p><p>INGEST</p><p>Triggered by: “Ingest [filename]” or “Process all new files in raw/articles/”</p><p>Steps:</p><p>1. Read the source file completely</p><p>2. Identify: key concepts, projects mentioned, patterns described</p><p>3. For each concept not yet in wiki/concepts/ — create a page using the Concept template</p><p>4. For each concept already in wiki/ — update with new information, preserving existing content</p><p>5. Update wiki/index.md to include new pages</p><p>6. Add cross-links between related pages</p><p>7. Do NOT speculate beyond what the source states</p><p>QUERY</p><p>Triggered by: “Query: [question]”</p><p>Steps:</p><p>1. Read wiki/index.md to identify relevant pages</p><p>2. Read those pages</p><p>3. Synthesize an answer citing specific wiki pages</p><p>4. If the answer requires connecting multiple pages, explain the connections</p><p>5. If the answer is not in the wiki, say so — do not invent</p><p>LINT</p><p>Triggered by: “Lint the wiki” or run periodically</p><p>Steps:</p><p>1. Check for orphan pages (no incoming links) — list them</p><p>2. Check for broken wikilinks — list them</p><p>3. Check for pages missing source references — flag them</p><p>4. Identify contradictions between pages — flag with specific quotes</p><p>5. Identify concepts referenced in pages but without their own page — suggest new pages</p><p>6. Produce a lint report in wiki/lint-report.md</p><p>SUMMARIZE</p><p>Triggered by: “Summarize coverage of [topic]”</p><p>Produce a summary of everything the wiki knows about a topic,</p><p>citing source pages.</p><p>Naming Conventions</p><p>- Concept pages: TitleCase.md (e.g., ModelContextProtocol.md)</p><p>- Project pages: TitleCase.md (e.g., API2MCP.md)</p><p>- Pattern pages: Kebab-Case.md (e.g., Human-In-The-Loop.md)</p><p>- Raw files: keep original names, do not rename</p><p>What The LLM Should Never Do</p><p>- Edit files in raw/</p><p>- Create pages without source backing</p><p>- Remove content without flagging it first</p><p>- Merge two concept pages without explicit instruction</p><p>```</p><p><strong>— -</strong></p><p><strong>Step 3: Seed Your raw/ Directory</strong></p><p>Get your source material into `raw/`. For most senior engineers this means:</p><p><strong>Blog posts / articles</strong></p><p>If you write on Medium, use the export option (`Settings → Security and apps → Export your content`). Medium exports as a zip of HTML files. Convert to markdown:</p><p>```bash</p><p>pip install markdownify</p><p>python3 -c “</p><p>import os</p><p>from markdownify import markdownify</p><p>for f in os.listdir(‘medium-export/posts’):</p><p>if f.endswith(‘.html’):</p><p>with open(f’medium-export/posts/{f}’) as src:</p><p>md = markdownify(src.read())</p><p>out = f.replace(‘.html’, ‘.md’)</p><p>with open(f’raw/articles/{out}’, ‘w’) as dst:</p><p>dst.write(md)</p><p>print(‘Done’)</p><p>“</p><p>```</p><p><strong>PDFs and papers</strong></p><p>Drop them directly into `raw/`. Claude Code can read PDFs natively.</p><p><strong>Existing notes</strong></p><p>Copy markdown files from Notion exports, Obsidian vaults, or anywhere else directly into `raw/notes/`.</p><p>Keep `raw/` as a flat-ish structure — subdirectories by type are fine but deep nesting isn’t necessary.</p><p><strong>Step 4: Start Claude Code and Run First Ingest</strong></p><p>Open Claude Code in your wiki directory:</p><p>```bash</p><p>cd your-wiki</p><p>claude</p><p>```</p><p>Claude Code reads `CLAUDE.md` automatically at startup. Now run your first ingest:</p><p>```</p><p>&gt; Ingest raw/articles/my-first-article.md</p><p>```</p><p>You’ll see Claude Code read the file, identify concepts, create wiki pages, and update the index. For a typical 2,000-word article you might get 3–5 new concept pages and 1–2 project or pattern pages.</p><p>After a few articles, run:</p><p>```</p><p>&gt; Ingest all new files in raw/articles/</p><p>```</p><p>Claude Code will process them incrementally — updating existing pages rather than creating duplicates for concepts already in the wiki.</p><p><strong>— -</strong></p><p><strong>Step 5: Set Up Obsidian as the Viewer</strong></p><p>Open Obsidian and point it at `your-wiki/` as a vault. A few settings to configure immediately:</p><p><strong>Enable graph view</strong> — this is the killer feature. Once you have 20+ wiki pages, the graph view shows you the topology of your knowledge. Densely connected nodes are your core concepts. Isolated nodes are candidates for deeper development or deletion.</p><p><strong>Enable wikilinks</strong> — Obsidian renders `[[ConceptName]]` as clickable links by default. Make sure “Use [[Wikilinks]]” is on in Settings → Files and Links.</p><p><strong>Install the Dataview plugin</strong> — lets you query your wiki frontmatter as a database. Useful queries:</p><p>```dataview</p><p>TABLE updated, tags FROM “wiki/concepts”</p><p>SORT updated DESC</p><p>```</p><p>This gives you a live table of all concept pages sorted by recency — useful for spotting stale content.</p><p><strong>Do not edit wiki pages directly in Obsidian</strong> — treat it as a read-only viewer. All writes go through Claude Code. If you edit a page manually, add a `&lt;! — human-edited →` comment so you know to review that page during lint.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gRIoKde_UYdbLgdjvhCSLg.png" /><figcaption>Obsidian Graph View</figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*KUYHuv-2RqpFBPCF3QXtCg.png" /><figcaption>Graph View with Wiki Links</figcaption></figure><p><strong>The Three Core Operations in Practice</strong></p><p><strong>Ingest — Processing New Sources</strong></p><p>Every time you publish a new article or read something worth keeping:</p><p>1. Drop the source into `raw/articles/`</p><p>2. In Claude Code: `Ingest raw/articles/new-article.md`</p><p>3. Review the new/updated pages in Obsidian</p><p>The ingest operation should take 30–60 seconds per article. You’ll notice over time that later articles produce fewer new pages (concepts are already there) and more updates — that’s the compounding effect working as intended.</p><p><strong>Query — Asking Questions Across Your Corpus</strong></p><p>This is where the wiki pays off. Examples of queries that work well:</p><p>```</p><p>&gt; Query: What have I written about multi-agent orchestration patterns?</p><p>&gt; Query: What’s the relationship between MCP and enterprise integration</p><p>architecture in my writing?</p><p>&gt; Query: Where have I discussed the trade-offs of LangGraph versus</p><p>custom orchestration?</p><p>&gt; Query: What topics have I covered most and what are the obvious gaps?</p><p>```</p><p>Because the wiki is pre-compiled, these queries are fast and well-cited. The output tells you exactly which wiki pages contain the synthesized answer.</p><p><strong>Lint — Keeping the Wiki Healthy</strong></p><p>Run lint periodically — weekly is sufficient for a personal wiki:</p><p>```</p><p>&gt; Lint the wiki</p><p>```</p><p>The lint report catches:</p><p>- <strong>Orphan pages</strong> — you wrote about something once and never connected it to anything else</p><p>- <strong>Missing sources</strong> — a page exists but isn’t backed by raw material (potential hallucination)</p><p>- <strong>Broken links</strong> — a page references another that got renamed or deleted</p><p>- <strong>Contradictions</strong> — two pages make incompatible claims</p><p>- <strong>Stub concepts</strong> — referenced everywhere but never given their own page</p><p>Lint is your quality gate. It’s what keeps the “compiled knowledge can accumulate errors” problem manageable.</p><p><strong>— -</strong></p><p><strong>Enterprise Considerations</strong></p><p>If you’re using this pattern within a team or at enterprise scale, a few additional considerations:</p><p><strong>Sensitive content</strong> — be deliberate about what goes in `raw/`. Treat the wiki’s security posture like a shared drive. Architecture decision records, post-mortems, and internal design docs shouldn’t go into a wiki you run through a cloud API without reviewing your data handling policy.</p><p><strong>Multi-author wikis</strong> — the pattern works for teams but you need explicit conventions in `CLAUDE.md` about conflict resolution when two authors’ sources contradict each other. Add a `Conflicts` section to the lint report template.</p><p><strong>Version control</strong> — put the entire wiki directory in Git. This gives you full history, the ability to roll back a bad ingest, and diff-based review of what the LLM changed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rHq5oziM9riJJEelQpAZEA.png" /></figure><p>```bash</p><p>cd your-wiki</p><p>git init</p><p>echo “raw/ # Source material — committed but not tracked for changes” &gt;&gt; .gitignore</p><p>git add .</p><p>git commit -m “Initial wiki structure”</p><p>```</p><p><strong>Token cost</strong> — ingest of a 2,000-word article runs approximately 3,000–6,000 tokens on Claude Code (Sonnet). At current pricing, processing 50 articles costs roughly $0.15–0.30 total. Query operations are cheaper. Lint of a 100-page wiki runs around $0.10. It’s not free but it’s cheap at this scale.</p><p><strong>What This Is Not</strong></p><p>This pattern works best for a focused corpus on a specific domain. It’s not a replacement for RAG at enterprise data scale (millions of documents, frequent updates, strict accuracy requirements). It’s a personal or small-team knowledge compiler for the knowledge you actively curate.</p><p>The tradeoff is real: RAG’s stateless nature is actually an advantage when you need provenance on every claim, or when your source material changes frequently. LLM Wikis work best when your raw material is relatively stable and you want synthesis across it, not just retrieval from it.</p><p>Use RAG when you need accuracy guarantees and source grounding on every query. Use an LLM Wiki when you want accumulated, compounding insight across a body of work you’ve curated.</p><p><strong>Getting Started in the Next 30 Minutes</strong></p><p>1. `npm install -g @anthropic/claude-code` — install Claude Code</p><p>2. Create the directory structure above</p><p>3. Copy the `CLAUDE.md` template and customize the domain section</p><p>4. Drop 5–10 of your best articles into `raw/articles/`</p><p>5. `cd your-wiki &amp;&amp; claude`</p><p>6. `Ingest all files in raw/articles/`</p><p>7. Open Obsidian, point it at the vault, open Graph View</p><p>After 10 articles ingested, run your first Query: <em>*”What are the core themes across my writing?”*</em></p><p>The answer will probably surprise you. Not because the LLM is smart — but because you’ve never synthesized your own corpus before.</p><p><em>I’ve been building my own LLM wiki for my writing on agentic AI and enterprise architecture. Happy to share what’s worked and what hasn’t — drop a comment or connect on LinkedIn.*</em></p><p><em>#ClaudeCode #KnowledgeManagement #LLM #SoftwareArchitecture #AIEngineering #DeveloperProductivity #Obsidian #AgenticAI</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=eb6c0990e723" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introduction to Agentic Development Lifecycle (ADLC)]]></title>
            <link>https://medium.com/@manavghosh/introduction-to-agentic-development-lifecycle-adlc-9a7232341792?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/9a7232341792</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[adlc]]></category>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Tue, 14 Apr 2026 03:41:31 GMT</pubDate>
            <atom:updated>2026-04-14T03:41:31.037Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*c_S5VeDefUz1yy62WoxqOw.png" /></figure><p>Did you know that 84% of developers are using or planning to use AI tools, indicating a significant change in development workflows? Adopting the Agentic Development Lifecycle (ADLC) requires a careful evaluation of resource allocation and project prioritization. It’s more than tech — it’s a transition in how your team operates. The ADLC Manifesto states,<em> “The SDLC was designed for a world where humans were the primary execution unit.”</em> That world is over. With AI becoming central to our systems, the traditional Software Development Lifecycle (SDLC) struggles to keep up. ADLC represents a significant change, redefining how we think about, build, and deploy software in an AI-centric world.</p><p>This discussion unpacks ADLC’s core concepts, best practices for implementation, real-world examples, and crucial statistics driving this change. We’ll also highlight common pitfalls and gather expert insights, equipping engineering leaders to navigate this new software development era.</p><p><strong>Core Concepts of ADLC</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qiPisb_rHKjpPtvWjbsd1g.png" /></figure><p>Transitioning to the Agentic Development Lifecycle (ADLC) requires your team to rethink its approach to AI-driven systems. Unlike the SDLC, which relies on upfront planning, ADLC embraces the unpredictability and adaptability of agentic AI systems. ADLC values adaptability over fixed plans.</p><p><strong>Differences from SDLC</strong></p><p>The SDLC assumes that behavior is fully defined at build time with validation before release. Agentic systems are different — they adapt and operate independently across various environments. This fundamental difference forces a reevaluation of our development approach. ADLC restructures the pipeline into a continuous loop, making iterative development and feedback essential parts of the process.</p><p><strong>The Pipeline-to-Loop Transformation</strong></p><p>ADLC moves from a fixed sequence to a feedback-driven cycle. In SDLC, everything is linear: Requirements → Design → Develop → Test → Deploy → Maintain. This order can slow response to changes. ADLC functions as a loop, where each stage informs the next. This setup allows systems to adapt and improve with new data and insights.</p><p><strong>Agent as the Primary Execution Unit</strong></p><p>In ADLC, agents take the lead as the primary execution units, transforming the development process. Unlike traditional software, which follows predefined tasks, these agents operate autonomously, making decisions based on live data. This shift demands a new approach to governance, security, and deployment, focusing on the unique capabilities and risks of autonomous agents. Developers now need to create systems that operate independently and adapt to new challenges and environments.</p><p><strong>Best Practices for ADLC Implementation</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*S5UX8f-0V3lPZcSJ57YmCg.png" /></figure><p>Implementing ADLC requires understanding its demands and aligning with best practices focused on ongoing evaluation, observability, and adaptive security to ensure agentic systems are effective and reliable.</p><p><strong>Continuous Evaluation and Iterative Improvement</strong></p><p>Continuous evaluation is a core ADLC principle. Unlike traditional cycles where testing is the final step, ADLC requires assessment at every phase. This ensures agents are always learning and adapting, leading to more capable systems. Ian McGraw notes, “Treating agent improvement as a structured engineering discipline rather than guesswork is the core idea behind the Agent Development Lifecycle.” This approach promotes perpetual refinement where feedback loops drive innovation.</p><p><strong>Observability as a Control Plane</strong></p><p>Observability is critical in ADLC, offering transparency into autonomous actions. It extends beyond standard monitoring, providing insights into the inner workings of agentic systems. This helps developers understand not just what happened, but why. Arthur AI’s Observability Playbook highlights the importance of strong observability frameworks for maintaining reliability and performance.</p><p><strong>Secure and Adaptive Governance</strong></p><p>ADLC extends security frameworks to fit the complexities of agentic systems. Cycode points out, “Human-led security teams alone cannot keep pace with agentic development. The security itself has to be agentic.” This means integrating security measures throughout the lifecycle, ensuring agents operate within ethical and operational boundaries. Adaptive governance involves updating security protocols as agentic systems evolve.</p><p><strong>Team Impact</strong></p><p>Adopting ADLC significantly impacts team dynamics and workload. Teams must embrace a culture of continuous learning and adaptability, fostering collaboration across different roles. This shift can lead to more innovative solutions and a more agile response to market changes. Workload may initially increase as teams adapt, but long-term efficiencies and productivity gains are expected.</p><p><strong>Real-World Examples of ADLC</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2sk3MM28ahtDDzaDXGymtQ.png" /></figure><p>Understanding ADLC’s application becomes clearer with real-world examples illustrating its practical implementation and benefits.</p><p><strong>EPAM Systems’ Success with 1,000+ Agentic Deployments</strong></p><p>EPAM Systems has rolled out over 1,000 agentic systems, developing a strong ADLC framework through extensive experience. Their iterative learning and adaptation approach shows how ADLC can scale across diverse environments, enhancing operational efficiencies and innovation.</p><p><strong>Amazon’s Internal Transformation with AI Tools</strong></p><p>Amazon’s shift to AI tools like Amazon Q Developer showcases ADLC’s impact on internal workflows. Moving from SDLC to an AI-driven lifecycle, Amazon has optimized processes, achieving significant productivity and strategic gains. This transition highlights the strategic benefits of ADLC.</p><p><strong>SumatoSoft’s 7-Phase ADLC Framework</strong></p><p>SumatoSoft’s ADLC framework includes unique phases like Red-Teaming and AgentOps, focusing on testing agents under adversarial conditions and maintaining operational effectiveness. These phases ensure robust and secure deployments, demonstrating resilience in diverse environments.</p><p><strong>Statistics: The Impetus for Change</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JqPOFKyIZtDQfFsOSbLGnA.png" /></figure><p>AI adoption statistics highlight the shift to ADLC, revealing traditional development models’ limitations.</p><p>- <strong>84% of developers</strong> are using or planning to use AI tools, indicating a move to AI-native development workflows. This reflects AI’s potential to enhance processes and drive innovation.</p><p>- <strong>GitHub research</strong> indicates a <strong>55% faster completion rate</strong> for coding tasks with AI assistance, shifting the bottleneck to evaluation and governance. This speed emphasizes the need for ADLC to manage AI-driven workflows.</p><p>- <strong>McKinsey research</strong> shows AI tools boost developer productivity by <strong>20–45%</strong>, especially in code generation and testing. This productivity gain underscores ADLC’s strategic advantage.</p><p>These numbers underscore AI’s potential and the need for ADLC to effectively harness these capabilities.</p><p><strong>Common Pitfalls and Solutions</strong></p><p>Transitioning to ADLC isn’t without its challenges. Common pitfalls include weak governance frameworks and organizational resistance.</p><p><strong>Inadequate Governance</strong></p><p>Strong governance is crucial for ADLC adoption, accommodating agentic systems’ dynamic nature. Governance must be integrated into every lifecycle phase, adapting to new insights and regulations. Policies need flexibility to evolve with agentic systems, ensuring compliance and ethical operation.</p><p><strong>Resistance to Change</strong></p><p>Resistance within organizations can slow ADLC adoption. Leaders must cultivate a culture of innovation and learning, emphasizing ADLC’s strategic benefits. This involves educating stakeholders and demonstrating value through pilot projects and success stories.</p><p><strong>Expert Perspectives on ADLC</strong></p><p>Industry experts’ insights deepen our understanding of ADLC and its implications.</p><p>- Adam Mattis stresses, “CIOs who keep mapping AI initiatives onto SDLC assumptions are structurally misaligned with how value is created now.” This misalignment highlights the urgency of adopting ADLC.</p><p>- EPAM Systems points out, “Traditional SDLCs assume behavior is fully specified at build time,” a notion incompatible with agentic systems’ adaptive nature.</p><p>These perspectives emphasize the strategic necessity of aligning development models with AI systems’ capabilities and demands.</p><p><strong>Expanding on Statistics with Deeper Analysis</strong></p><p>AI adoption stats indicate a shift in developer skillsets. As AI integrates into processes, demand for developers who can use these tools effectively will rise, requiring a reevaluation of training programs.</p><p>The 55% faster completion rate for coding tasks necessitates rethinking project management strategies. With faster cycles, teams need agile approaches to capitalize on rapid innovation, crucial for maintaining a competitive edge.</p><p><strong>Practical Implementation Details</strong></p><p>Implementing ADLC demands careful planning and evaluation of current processes to identify where AI can add value. This involves assessing workflows, pinpointing bottlenecks, and determining how AI tools can enhance efficiency.</p><p>Organizations should start with pilot projects to experiment with AI-driven workflows, gathering insights for broader application. This gradual integration ensures a smooth transition to ADLC.</p><p>Building a culture supporting continuous learning and adaptation is vital. Encouraging experimentation, collaboration, and a mindset of improvement maximizes ADLC’s benefits, positioning organizations for long-term success.</p><p><strong>Troubleshooting Tips and Common Scenarios</strong></p><p>Implementing ADLC presents challenges, but understanding common scenarios and troubleshooting tips can ease the transition.</p><p><strong>Scenario 1: Integrating AI Tools</strong></p><p>Start small with pilot projects to integrate AI tools into existing processes. As teams gain comfort, expand their use across more projects.</p><p><strong>Scenario 2: Ensuring Robust Governance</strong></p><p>Develop flexible governance frameworks that evolve with agentic systems, updating policies and procedures to align with AI capabilities and risks.</p><p><strong>Scenario 3: Overcoming Resistance to Change</strong></p><p>Communicate ADLC’s strategic benefits and demonstrate value through pilot projects and success stories to overcome resistance and build support.</p><p><strong>Key Takeaways</strong></p><p>- <strong>Shift to Agentic Execution</strong>: ADLC redefines development by positioning agents as the primary units, requiring a new development and governance approach.</p><p>- <strong>Continuous Evaluation</strong>: Integrating continuous evaluation ensures agents learn and adapt, improving reliability and performance.</p><p>- <strong>Observability</strong>: Strong observability frameworks maintain transparency and control over agentic systems.</p><p>- <strong>Adaptive Security</strong>: Security measures must evolve with autonomous agents, integrating into the lifecycle.</p><p>- <strong>Cultural Transformation</strong>: Successful ADLC requires a cultural shift, embracing innovation and adaptability.</p><p>- <strong>Strategic Alignment</strong>: Aligning strategies with ADLC principles harnesses AI’s potential, driving innovation and competitiveness.</p><p><strong>Conclusion and Call to Action</strong></p><p>Moving to ADLC isn’t just an upgrade — it’s a fundamental evolution in software development, characterized by the integration of AI as a central component in development processes. As AI reshapes the tech landscape, adopting ADLC becomes essential. Leaders must prioritize this transition, fostering innovation and adaptability to stay competitive in an AI-driven world.</p><p><strong>Adoption Risk</strong></p><p>While ADLC offers numerous advantages, potential risks include increased complexity in managing autonomous systems and the need for robust security measures. Organizations must be prepared to address these challenges proactively.</p><p><strong>What Breaks</strong></p><p>Transitioning to ADLC might disrupt existing workflows and require significant changes in team roles and responsibilities. It’s crucial to anticipate these disruptions and plan for a smooth transition.</p><p><strong>Maturity Checklist</strong></p><p>To assess readiness for ADLC adoption, consider the following checklist:</p><p>- Evaluate current AI integration levels and identify gaps.</p><p>- Ensure robust governance frameworks are in place.</p><p>- Foster a culture of continuous learning and adaptation.</p><p>- Implement strong observability and security measures.</p><p>- Prepare for changes in team dynamics and roles.</p><p>For those ready to embark on this journey, the path is clear: embrace ADLC principles, invest in continuous evaluation and observability, and cultivate a culture valuing adaptability and strategic alignment. As we stand on the brink of this new era, the choice isn’t whether to adopt ADLC, but how quickly and effectively it can be implemented.</p><p><em>If you found this article helpful, consider following me for more in-depth articles on AI, developer tools, and software engineering trends.</em></p><p><em>Have questions or a different perspective? Leave a comment below — I read every response and would love to discuss further.</em></p><p><em>You can also reach out to me directly or connect on LinkedIn. Let’s keep the conversation going.</em></p><p><em>#Introduction #Agentic #Development #AI #DeveloperTools #SoftwareEngineering #TechWriting #Productivity</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9a7232341792" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What is MARP and How to Use It with Claude Code]]></title>
            <link>https://medium.com/@manavghosh/what-is-marp-and-how-to-use-it-with-claude-code-3d7ca2aae204?source=rss-37f405263f94------2</link>
            <guid isPermaLink="false">https://medium.com/p/3d7ca2aae204</guid>
            <dc:creator><![CDATA[manav ghosh]]></dc:creator>
            <pubDate>Mon, 13 Apr 2026 14:53:34 GMT</pubDate>
            <atom:updated>2026-04-13T14:53:34.152Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*V3__GE9DSGH0_2ZOTwctHg.png" /></figure><p>“The blank-deck problem is particularly acute for developers who must present technical content — architecture diagrams, system designs, API documentation — that exists as code or markdown but must be translated into slides. Claude Code bridges this gap.”</p><p>— Omer Rosenbaum, <em>*FreeCodeCamp, March 2026</em></p><p><strong>Introduction</strong></p><p>You have an architecture review in two hours. The decision record lives in your repo as a Markdown ADR. The proposal is a README. The migration plan is a numbered list in a GitHub issue. Now someone wants slides.</p><p>This is the silent tax on every technical decision: everything important gets written in Markdown, then rewritten as a PowerPoint the moment it needs to leave the engineering org. Two tools in your terminal can eliminate that tax permanently.</p><p><strong>MARP</strong> (Markdown Presentation Ecosystem) renders `.md` files directly into HTML, PDF, or PPTX — no GUI, no drag-and-drop, no design tokens lost in translation. Pair it with Claude Code, and you can hand it a raw ADR or a set of bullet points and receive a structured, theme-consistent slide deck in seconds. The Markdown stays in Git, the slides build in CI, and nothing drifts out of sync with the documentation it came from.</p><p>This article covers how MARP works under the hood, the exact prompts and CLI commands to turn Claude Code into a slide-generation engine, and the specific trade-offs that matter when you’re evaluating this for a team or a pipeline — not just a one-off deck.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*yGt_TEEfbly2NwadKh9kwg.png" /></figure><p><strong>Core Concepts</strong></p><p>Understanding MARP’s architecture enables the transformation of Markdown into professional presentations by providing a structured approach to design and content integration.</p><p><strong>The MARP Ecosystem</strong></p><p>MARP functions as an ecosystem, comprising multiple components that synergize to facilitate the Markdown-to-presentation conversion.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xndXCnsFv6EcivnwZp8sQQ.png" /></figure><p><strong>Marpit: The Foundation</strong></p><p>Marpit provides the foundational framework for slide creation, utilizing Markdown syntax to define slides. This allows users to work within a familiar environment while benefiting from specialized slide formatting.</p><p><strong>Marp Core: Enhanced Capabilities</strong></p><p>Building on Marpit, Marp Core incorporates built-in themes and enhanced rendering options. It supports outputs in various formats such as HTML, PDF, and PowerPoint, catering to diverse presentation requirements.</p><p><strong>Marp CLI: Command-Line Efficiency</strong></p><p>The Marp CLI is an indispensable tool for developers who prefer command-line operations. It converts Markdown files into presentations through concise commands. It also supports custom themes and animations, proving invaluable in automated workflows.</p><p><strong>Extensions for Code Editors</strong></p><p>MARP extends its functionality through integrations with popular code editors like Visual Studio Code. This provides real-time slide previews and additional capabilities, ensuring iterative slide development without interrupting coding workflows.</p><p><strong>Directives and Themes</strong></p><p>MARP’s strength lies in its directives and themes, providing granular control over slide design and behavior.</p><p><strong>Global Directives</strong></p><p>Global directives are YAML-based instructions applied across an entire presentation, covering elements such as theme, size, and structural components, ensuring a consistent aesthetic throughout slide decks.</p><p><strong>Local Directives</strong></p><p>Local directives enable slide-specific customization, accommodating unique content requirements like code block highlights or background images.</p><p><strong>Theme Customization</strong></p><p>Themes in MARP, driven by CSS, allow extensive customization of slide aesthetics. Users can utilize built-in themes or create custom ones to align with brand guidelines or personal preferences, maintaining a professional appearance without needing design expertise.</p><p><strong>Best Practices</strong></p><p>To fully harness MARP’s capabilities, adherence to best practices is crucial, ensuring technical efficiency and high-quality presentations.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iDcb71v2OxFrlyJ395P03A.png" /></figure><p><strong>Optimizing Workflow with Marp CLI</strong></p><p>The Marp CLI is central to streamlining slide creation. Here are strategies for its effective use:</p><p><strong>Utilizing Built-in Animations</strong></p><p>MARP CLI includes 33 built-in animations that enhance visual engagement without manual coding, making them accessible across varying technical skill levels.</p><p><strong>Organizing Themes</strong></p><p>A dedicated theme directory simplifies theme management, crucial in CI/CD workflows, ensuring consistent theming across automated builds.</p><p><strong>Leveraging Marp for VS Code</strong></p><p>The Marp extension for Visual Studio Code enhances the development workflow with real-time slide previews:</p><p><strong>Enabling Live Preview</strong></p><p>Activating live previews with `marp: true` in the front matter of Markdown files allows for iterative improvements, ensuring presentations evolve alongside content.</p><p><strong>Security Considerations</strong></p><p>When enabling HTML rendering, security implications must be considered. Proper configuration of workspace settings can mitigate risks, maintaining presentation security.</p><p><strong>Integrating with Git Workflows</strong></p><p>MARP’s compatibility with Git facilitates version-controlled, collaborative presentation development:</p><p><strong>Version Control</strong></p><p>Storing slide decks in the same repository as source code ensures consistency and simplifies collaboration, aligning with best practices in software development.</p><p><strong>Automated Builds</strong></p><p>GitHub Actions can automate Markdown-to-presentation conversions, ensuring the latest versions are always accessible. This process saves time and maintains accuracy, enhancing team communication.</p><p><strong>Step-by-Step: Building a MARP Deck with Claude Code</strong></p><p>Here is a complete walkthrough — from a blank terminal to a rendered slide deck — using MARP CLI and Claude Code.</p><p><strong>Step 1: Install MARP CLI</strong></p><p>MARP CLI is distributed as an npm package. Install it globally:</p><p>```bash</p><p>npm install -g @marp-team/marp-cli</p><p>```</p><p>Verify the installation:</p><p>```bash</p><p>marp — version</p><p>```</p><p>For VS Code, install the <strong>**Marp for VS Code**</strong> extension from the Extensions marketplace (`yhatt.marp-vscode`). This gives you a live preview panel alongside your Markdown editor.</p><p><strong>Step 2: Write Your First MARP Slide File</strong></p><p>Create a file called `slides.md`. MARP uses standard Markdown with a `marp: true` front matter flag and ` — -` as a slide separator:</p><p>```markdown</p><p><strong>— -</strong></p><p>marp: true</p><p>theme: default</p><p>paginate: true</p><p><strong>— -</strong></p><p><strong>My Architecture Review</strong></p><p><strong>Q2 2026 — Platform Team</strong></p><p><strong>— -</strong></p><p><strong>Agenda</strong></p><p>- Current state</p><p>- Proposed changes</p><p>- Migration path</p><p>- Timeline</p><p><strong>— -</strong></p><p><strong>Current Architecture</strong></p><p>![bg right:40%](diagram.png)</p><p>- Monolith: 3.2M lines of code</p><p>- 14 teams, one deploy pipeline</p><p>- Average deploy: 47 minutes</p><p><strong>— -</strong></p><p><strong>Proposed Change</strong></p><p>Move to <strong>**domain-owned services**</strong> with:</p><p>1. Independent deploy pipelines</p><p>2. Bounded context ownership</p><p>3. Async event bus for cross-domain comms</p><p><strong>— -</strong></p><p><strong>Thank You</strong></p><p>Questions? Reach me at <strong>**@handle**</strong> on Slack</p><p>```</p><p>Each ` — -` creates a new slide. The `bg right:40%` directive positions an image on the right side of the slide — no CSS required.</p><p><strong>— -</strong></p><p><strong>Step 3: Prompt Claude Code to Generate the Deck</strong></p><p>Instead of writing slides manually, hand Claude Code your notes or a document and let it generate the MARP Markdown. Open Claude Code and run:</p><p>```</p><p>&gt; “Convert the following architecture document into a MARP slide deck.</p><p>Use marp: true front matter, the ‘gaia’ theme, paginate: true.</p><p>Create one slide per major section. Add speaker notes using HTML</p><p>comment blocks. Keep each slide to 5 bullet points maximum.</p><p>[paste your document or talking points here]”</p><p>```</p><p>Claude Code understands MARP syntax natively — it will output valid `.md` with correct directives, theme settings, and structured content. You can be more specific:</p><p>```</p><p>&gt; “Generate a 10-slide MARP deck for a senior engineering audience on</p><p>‘migrating a monolith to microservices’. Include:</p><p>- A title slide</p><p>- An agenda slide</p><p>- One slide per migration phase (Strangler Fig pattern)</p><p>- A risks and mitigations slide</p><p>- A closing CTA slide</p><p>Use the ‘uncover’ theme, 16:9 aspect ratio, and paginate each slide.”</p><p>```</p><p>Save the output directly as `slides.md`.</p><p><strong>— -</strong></p><p><strong>Step 4: Render the Deck</strong></p><p><strong>**HTML**</strong> (interactive, browser-based):</p><p>```bash</p><p>marp slides.md — html</p><p># outputs: slides.html</p><p>```</p><p><strong>**PDF**</strong> (shareable, print-ready):</p><p>```bash</p><p>marp slides.md — pdf</p><p># outputs: slides.pdf</p><p>```</p><p><strong>**PowerPoint**</strong> (for stakeholders who need .pptx):</p><p>```bash</p><p>marp slides.md — pptx</p><p># outputs: slides.pptx</p><p>```</p><p><strong>**Set the aspect ratio**</strong> (default is 4:3; use 16:9 for widescreen):</p><p>```bash</p><p>marp slides.md — pdf — theme-set ./themes/ — slides.md</p><p>```</p><p>Or declare it in front matter:</p><p>```markdown</p><p><strong>— -</strong></p><p>marp: true</p><p>theme: gaia</p><p>size: 16:9</p><p><strong>— -</strong></p><p>```</p><p><strong>— -</strong></p><p><strong>Step 5: Preview Live in VS Code</strong></p><p>With the Marp for VS Code extension installed:</p><p>1. Open `slides.md` in VS Code</p><p>2. Click the <strong>**preview icon**</strong> in the top-right toolbar (or `Ctrl+Shift+V`)</p><p>3. A rendered slide panel opens beside your editor</p><p>4. Every save updates the preview instantly</p><p>Enable HTML rendering in your workspace settings if your slides use custom HTML elements:</p><p>```json</p><p>// .vscode/settings.json</p><p>{</p><p>“markdown.marp.enableHtml”: true</p><p>}</p><p>```</p><p><strong>**Security note:**</strong> Only enable `enableHtml` in trusted repositories. HTML rendering can execute arbitrary scripts in the preview pane.</p><p><strong>— -</strong></p><p><strong>Step 6: Automate with GitHub Actions</strong></p><p>Add this workflow to auto-generate a PDF on every push to `main`:</p><p>```yaml</p><p>.github/workflows/slides.yml</p><p>name: Build Slides</p><p>on:</p><p>push:</p><p>branches: [main]</p><p>paths: [“**.md”]</p><p>jobs:</p><p>build:</p><p>runs-on: ubuntu-latest</p><p>steps:</p><p>- uses: actions/checkout@v4</p><p>- name: Build PDF with MARP CLI</p><p>uses: docker://marpteam/marp-cli:latest</p><p>with:</p><p>args: slides.md — pdf — allow-local-files -o output/slides.pdf</p><p>- name: Upload artifact</p><p>uses: actions/upload-artifact@v4</p><p>with:</p><p>name: slides</p><p>path: output/slides.pdf</p><p>```</p><p>Every commit that touches a `.md` file triggers a fresh PDF build. Teammates always pull the latest deck from the Actions artifacts tab — no manual exports needed.</p><p><strong>Full Claude Code + MARP Workflow at a Glance</strong></p><p>```</p><p>Your notes / docs</p><p>↓</p><p>Claude Code prompt → slides.md (MARP Markdown)</p><p>↓</p><p>marp slides.md — pdf → slides.pdf</p><p>↓</p><p>git push → GitHub Actions → artifact published</p><p>```</p><p>This entire pipeline — from raw notes to a versioned, shareable PDF — takes under five minutes once set up.</p><p><strong>Real-World Examples</strong></p><p><strong>ADR-to-Slides in a Monorepo</strong></p><p>A platform team at a fintech company maintains all Architecture Decision Records in `docs/adr/` as numbered Markdown files. Before every architectural review board meeting, an engineer runs a single Claude Code prompt against the relevant ADR:</p><p>```</p><p>&gt; “Convert docs/adr/0042-event-driven-migration.md into a MARP deck.</p><p>Use the ‘uncover’ theme, 16:9 size, paginate: true.</p><p>Structure: title → context → decision drivers → options considered →</p><p>decision → consequences. One slide per section.</p><p>Add speaker notes from the ‘Rationale’ paragraphs.”</p><p>```</p><p>The output is a valid `slides.md` committed alongside the ADR. A GitHub Actions workflow converts it to PDF on every merge to `main`. Reviewers pull the PDF from the Actions artifacts tab — the source of truth never leaves the repo, and the slide deck is always in sync with the decision record.</p><p><strong>**Repo structure after setup:**</strong></p><p>```</p><p>docs/</p><p>└── adr/</p><p>├── 0042-event-driven-migration.md # source document</p><p>└── 0042-event-driven-migration/</p><p>└── slides.md # MARP output, committed</p><p>.github/</p><p>└── workflows/</p><p>└── slides.yml # builds PDF on push</p><p>```</p><p><strong>On-Call Runbook → Incident Brief</strong></p><p>An SRE team stores runbooks in Markdown. When a P1 fires and the incident commander needs to brief stakeholders, they paste the runbook into Claude Code:</p><p>```</p><p>&gt; “Convert this runbook into a 6-slide MARP brief for a non-technical</p><p>audience. Lead with current impact, then timeline, mitigation steps,</p><p>and next actions. Theme: default. Remove all bash commands — describe</p><p>steps in plain English. Flag any SLA breaches on their own slide.”</p><p>```</p><p>Result: a stakeholder-facing deck generated in under 30 seconds from existing operational documentation, without touching the runbook itself.</p><p><strong>API Changelog → Release Notes Deck</strong></p><p>A developer platform team publishes major API changes quarterly. Their changelog is a `CHANGELOG.md` with semantic version sections. Claude Code converts the latest version block into a partner-facing deck:</p><p>```</p><p>&gt; “Read the v3.2.0 section of CHANGELOG.md. Generate a MARP deck</p><p>for external API consumers: breaking changes first (red background</p><p>via local directive), then new features, then deprecation timeline.</p><p>Use ‘gaia’ theme. Max 3 bullets per slide.”</p><p>```</p><p><strong>Statistics: Context and Implications</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HJDU30UE7r7QwWRjlLgJuw.png" /></figure><p>A few numbers worth knowing before you commit to the toolchain:</p><p>- <strong>3,300+ GitHub stars on marp-cli</strong> — meaningful signal for a developer tooling project; indicates real adoption, not just bookmarks. The issue tracker is active, PRs merge regularly, and releases follow a predictable cadence.</p><p>- <strong>126 published npm versions</strong> — the team ships point releases frequently, usually in response to upstream Chromium/Puppeteer changes that affect PDF rendering. This also means you should pin your version in CI (`@marp-team/marp-cli@3.4.0`, not `latest`) to avoid rendering drift between environments.</p><p>- <strong>33 built-in slide transition animations</strong> — available in the Bespoke HTML output (browser-based). These do <em>*not*</em> carry over to PDF or PPTX exports, which matters if your primary output is a shareable document rather than a live presenter view.</p><p>- <strong>80% of professional developers use Markdown regularly</strong>(Stack Overflow Developer Survey 2024) — this is the core argument for MARP’s adoption curve. If your team already writes docs in Markdown, the marginal learning cost for MARP is near zero.</p><p>- <strong>Sub-5-second builds for typical decks</strong> — a 20-slide deck with custom themes and local images converts to PDF in under 5 seconds on a standard GitHub Actions runner. This makes it practical as a PR check, not just a manual step.</p><p><strong>Common Pitfalls and Solutions</strong></p><p>While MARP offers numerous advantages, challenges exist. Understanding common pitfalls aids in effective navigation.</p><p><strong>Complexity of Custom Themes</strong></p><p>Custom theme design requires CSS proficiency. Mitigate this by starting with built-in themes and gradually introducing customizations, allowing familiarity with theme structures before complex design work.</p><p><strong>Directive Overhead</strong></p><p>Managing numerous directives can be cumbersome. Streamline by defining global directives for most cases, reserving local directives for exceptions, reducing complexity and ensuring manageability.</p><p><strong>Architectural Analysis</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1RVQGsBj4XYUZH_99nGARg.png" /></figure><p><strong>**Choose MARP when**</strong>: your team is already in Markdown, you need PPTX output for stakeholders, and you want zero JavaScript runtime complexity in your pipeline.</p><p><strong>**Choose Slidev when**</strong>: you need live code execution in slides, embedded Vue components, or more sophisticated interactive demos. Slidev’s output is richer but requires Node/Vue knowledge and a heavier build pipeline.</p><p><strong>**Choose reveal.js when**</strong>: you control the hosting and need maximum CSS flexibility — reveal.js is the most battle-tested option for bespoke conference-quality decks.</p><p><strong>**GitPitch**</strong> is largely unmaintained at this point; don’t add it to a new pipeline.</p><p><strong>Trade-Off Analysis</strong></p><p><strong>Where MARP wins:</strong></p><p>- Minimal toolchain surface area — one npm package, one CLI command</p><p>- PPTX output is genuinely useful for stakeholder audiences who need to annotate or modify slides</p><p>- Integrates cleanly into existing documentation-as-code workflows</p><p>- Content is version-controlled and diffable as plain text</p><p><strong>Where MARP breaks down:</strong></p><p><em>*Complex layouts.*</em> MARP uses a single-column CSS grid per slide. Multi-panel layouts — side-by-side code and diagram, or three-column comparison grids — require raw CSS in your theme file. It’s achievable but not composable from Markdown alone.</p><p><em>*Embedded video.*</em> PDF output has no video support. HTML output can embed `&lt;video&gt;` tags if you enable `markdown.marp.enableHtml`, but this opens a security surface that isn’t appropriate for untrusted content pipelines.</p><p><em>*Pixel-perfect brand compliance.*</em> If your design team has a 47-page brand guide with specific padding values, line-height rules, and custom font stacks, MARP’s CSS theming can satisfy them — but it requires a CSS engineer, not a Markdown author. You’re not saving time on the design work; you’re just moving it into a CSS file.</p><p><em>*Presenter notes in PDF.*</em> Speaker notes render in the HTML presenter view but are stripped from PDF output. If your audience regularly works from printed slides with notes, this is a blocker.</p><p><strong>Failure Modes</strong></p><p><strong>**Rendering drift between environments.**</strong> MARP’s PDF engine is Puppeteer/Chromium. Different Chromium versions produce subtly different PDF outputs — font rendering, table borders, background colors can all shift. Fix: pin your MARP CLI version in `package.json` and use the official Docker image (`marpteam/marp-cli:latest`) in CI so the renderer is identical across developer machines and build servers.</p><p><strong>**Theme coupling.**</strong> If you inline `&lt;style&gt;` blocks in individual Markdown files rather than extracting a proper CSS theme, you accumulate non-reusable presentation-specific CSS scattered across your repo. This makes brand updates expensive. Fix: enforce a single ` — theme-set` directory in CI and ban `&lt;style&gt;` in Markdown via a Vale or custom linting rule.</p><p><strong>**Claude Code prompt quality.**</strong> Claude Code’s MARP output quality degrades with underspecified prompts. If you give it a long document without a slide structure constraint, it will generate too many slides with too much text per slide — which is exactly the failure mode you’re trying to avoid. Fix: always specify `max N bullet points per slide`, the target slide count, and whether the output is for a live presenter or an async-read deck. These constraints dramatically improve the output.</p><p><strong>**Large image assets in CI.**</strong> MARP embeds local images at build time. If your `docs/` directory contains high-res PNGs from Figma exports, PDF builds in CI can silently time out or OOM on small runners. Fix: add an image optimization step before MARP builds, or use ` — allow-local-files` with an explicit asset size limit check in your workflow.</p><p><strong>Decision Criteria</strong></p><p>Use MARP in your pipeline if all of the following hold:</p><p>1. Your team already writes documentation in Markdown and stores it in Git</p><p>2. You need PDF or PPTX output (not just browser-based HTML)</p><p>3. Your slides are primarily text, code blocks, and single images — not complex multi-panel layouts</p><p>4. You want presentations to stay in sync with documentation without a manual sync step</p><p>Don’t add MARP if:</p><p>- Your organization’s brand compliance requirements need pixel-perfect control — use a design system with an export plugin instead</p><p>- You need embedded video or interactive code execution in the deck itself — Slidev is a better fit</p><p>- Your primary audience is non-technical stakeholders who will edit the deck in PowerPoint — the PPTX output is clean, but round-tripping edits back to Markdown is not a workflow MARP supports</p><p><strong>Key Takeaways</strong></p><p>1. <strong>**MARP eliminates the Markdown-to-PowerPoint translation tax**</strong> — keep your documentation in Git and render slides on demand from the same source.</p><p>2. <strong>**Claude Code is a force multiplier**</strong> — specify slide count, theme, structure constraints, and max bullets per slide in your prompt; underspecified prompts produce overcrowded, unstructured decks.</p><p>3. <strong>**Pin your MARP CLI version in CI**</strong> — Puppeteer/Chromium updates silently shift PDF rendering; use the official Docker image for consistent builds across environments.</p><p>4. <strong>**Extract themes, never inline CSS**</strong> — scattered `&lt;style&gt;` blocks create a maintenance burden; enforce a ` — theme-set` directory and treat themes like shared infrastructure.</p><p>5. <strong>**PPTX output works; round-trips don’t**</strong> — MARP generates clean `.pptx` files for stakeholders, but edits made in PowerPoint won’t propagate back to the Markdown source.</p><p>6. <strong>**Evaluate against Slidev for interactive content**</strong> — if your deck needs live code execution, embedded Vue components, or complex animations, Slidev is the better tool despite the higher setup cost.</p><p><strong>Conclusion</strong></p><p>The next time you’re 90 minutes from an architectural review and your only source of truth is a Markdown file, you shouldn’t have to open PowerPoint. The tools in this article give you a repeatable, Git-native path from documentation to deck — and Claude Code removes the manual translation step entirely.</p><p>Start with the GitHub Actions workflow from Step 6. Point it at one existing ADR or runbook. Run it. If the PDF output meets your bar for that one document, you have your proof of concept. From there, the path to a team-wide standard is a shared CSS theme file and a prompt template in your runbook — not a new tool, not a new process, just one more artifact that builds alongside your code.</p><p>The architectural fit test is simple: if your team writes in Markdown and reviews in Git, MARP belongs in your pipeline. If your stakeholders need to own and edit the deck, it doesn’t.</p><p><em>Sources: [MARP Official Site](</em>https://marp.app<em>), [GitHub — marp-team/marp-cli](</em>https://github.com/marp-team/marp-cli<em>), [Marp CLI Bespoke Transitions Documentation](</em>https://github.com/marp-team/marp-cli/tree/main/docs/bespoke-transitions<em>), [Professional Developers | 2024 Stack Overflow Developer Survey](</em>https://stackoverflow.com/developer-survey/2024<em>)</em></p><p><em>If you found this article helpful, consider following me for more in-depth articles on AI, developer tools, and software engineering trends.</em></p><p><em>Have questions or a different perspective? Leave a comment below — I read every response and would love to discuss further.</em></p><p><em>You can also reach out to me directly or connect on LinkedIn. Let’s keep the conversation going.</em></p><p>#Marp #Claude #Code #AI #DeveloperTools #SoftwareEngineering #TechWriting #Productivity</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3d7ca2aae204" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>