<?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 Alexandr  Dzhumurat on Medium]]></title>
        <description><![CDATA[Stories by Alexandr  Dzhumurat on Medium]]></description>
        <link>https://medium.com/@alexandrdzhumurat?source=rss-7eae5e3bc0f3------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*ASB77GTR_BGyRiI2.</url>
            <title>Stories by Alexandr  Dzhumurat on Medium</title>
            <link>https://medium.com/@alexandrdzhumurat?source=rss-7eae5e3bc0f3------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 06:57:36 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@alexandrdzhumurat/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[Building Production-Ready Multi-User AI Agents: pydantic-ai]]></title>
            <link>https://medium.com/@alexandrdzhumurat/building-production-ready-multi-user-ai-agents-pydantic-ai-e9021daede5f?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/e9021daede5f</guid>
            <category><![CDATA[perplexity]]></category>
            <category><![CDATA[redis]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[pydantic-ai]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Sat, 03 Jan 2026 09:05:37 GMT</pubDate>
            <atom:updated>2026-01-03T09:05:37.754Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How to handle concurrent users, session management, and streaming responses without losing your mind</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*63m1Pi8_VaCvyb2eIUFAlQ.png" /></figure><p>When I set out to build an AI agent that helps users discover events in any city, I thought it would be straightforward: spin up FastAPI, add PydanticAI, done. Three days and countless race conditions later, I learned that <strong>building a single-user AI agent is easy; building a multi-user production system is an entirely different beast</strong>.</p><p>Here’s what I learned building a real-time event discovery agent that handles concurrent users, streams responses word-by-word, and never loses conversation context — even when users spam the send button.</p><h3>The Deceptive Simplicity of AI Agents</h3><p>Most AI agent tutorials show you this:</p><pre>from pydantic_ai import Agent<br><br>agent = Agent(&#39;openai:gpt-4o&#39;)<br>result = agent.run_sync(&#39;Find events in Paris&#39;)<br>print(result.output)</pre><p>This works beautifully. For one user. Once.</p><p>But what happens when:</p><ul><li><strong>Alice</strong> and <strong>Bob</strong> both ask about events simultaneously?</li><li>Alice sends three messages in rapid succession without waiting for responses?</li><li>You deploy with --workers 4 to handle scale?</li></ul><p><strong>Everything breaks.</strong> Sessions get mixed up. Messages vanish. Context is lost. Welcome to production.</p><h3>The Multi-User Minefield</h3><h3>Problem #1: The Race Condition</h3><p>When a user sends two messages rapidly, here’s what happens without protection:</p><pre>Time    Message 1 &quot;What&#39;s in Paris?&quot;    Message 2 &quot;And in London?&quot;<br>────────────────────────────────────────────────────────────────────<br>t0      Reads history: []<br>t1                                       Reads history: []  ← Same!<br>t2      Processes...<br>t3                                       Processes...<br>t4      Updates history: [Q1, A1]<br>t5                                       Updates history: [Q2, A2]</pre><pre>Result: History = [Q2, A2] only. Lost [Q1, A1]! 💥</pre><p><strong>The fix:</strong> A message queue. Each user session gets its own queue that processes messages sequentially:</p><pre>class QueuedUserSession:<br>    def __init__(self, session_id: str, agent: Agent):<br>        self.queue = asyncio.Queue()<br>        self._processor_task = asyncio.create_task(self._process_queue())<br>    <br>    async def _process_queue(self):<br>        while True:<br>            queued_msg = await self.queue.get()<br>            result = await self.agent.run(<br>                queued_msg.message,<br>                message_history=self.messages  # Always consistent!<br>            )<br>            self.messages.extend(result.new_messages())<br>            queued_msg.future.set_result(result.output)</pre><p>Now messages are processed in order, with perfect context preservation. Crisis averted.</p><h3>Problem #2: Uvicorn Workers Are Processes, Not Threads</h3><p>Here’s a trap I fell into:</p><pre>uvicorn app:app --workers 4  # Seems good for scaling, right?</pre><p><strong>Wrong.</strong> Those 4 workers are <strong>separate processes with isolated memory</strong>.</p><p>When you do this:</p><pre>sessions: Dict[str, UserSession] = {}  # Global in-memory dict</pre><p>Each worker gets its <strong>own</strong> sessions dict. Alice&#39;s first message goes to Worker 1, her second to Worker 2—which has no idea Alice exists. New session created. Context lost.</p><p><strong>The fix:</strong> Redis. Share sessions across all workers:</p><pre>class RedisSessionStore:<br>    async def save_session(self, session_id: str, session_data: dict):<br>        await self.redis_client.setex(<br>            f&quot;session:{session_id}&quot;,<br>            timedelta(hours=24),<br>            pickle.dumps(session_data)<br>        )<br>    <br>    async def load_session(self, session_id: str):<br>        data = await self.redis_client.get(f&quot;session:{session_id}&quot;)<br>        return pickle.loads(data) if data else None</pre><p>Now all workers share the same session state. Any worker can handle any request.</p><p><strong>Bonus discovery:</strong> For 5–10 concurrent users, you don’t need multiple workers at all. Just use --workers 1 and keep it simple. I learned this after over-engineering.</p><h3>Problem #3: The exhaustive Mystery</h3><p>My agent would say “I’ll search for events…” but never actually call the search tool. Turns out, when the LLM returns multiple tool calls in parallel (like logging + searching + final answer), the default behavior is to stop as soon as a final answer is found.</p><p><strong>The fix:</strong></p><pre>agent = Agent(<br>    &#39;gemini-2.0-flash-exp&#39;,<br>    end_strategy=&#39;exhaustive&#39;  # Execute ALL tools!<br>)</pre><p>With end_strategy=&#39;exhaustive&#39;, the agent executes every tool call—perfect for logging, analytics, and side effects that must always run.</p><h3>Streaming Without Suffering</h3><p>Users expect real-time responses. Not “processing…” for 30 seconds, then a wall of text. I implemented Server-Sent Events (SSE) for word-by-word streaming:</p><pre>@router.post(&quot;/{session_id}/messages/stream&quot;)<br>async def send_message_stream(session_id: str, request: SendMessageRequest):<br>    async def generate():<br>        async for chunk in manager.send_message_stream(session_id, message):<br>            yield f&quot;data: {json.dumps(chunk)}\n\n&quot;<br>        yield &quot;data: [DONE]\n\n&quot;<br>    <br>    return StreamingResponse(generate(), media_type=&quot;text/event-stream&quot;)</pre><p>The client sees text appear as it’s generated. Slick. Professional. Users love it.</p><p><strong>Bonus:</strong> I added status heartbeats every 3 seconds during long operations:</p><pre>if elapsed &gt;= 3.0:<br>    yield {&quot;type&quot;: &quot;status&quot;, &quot;content&quot;: &quot;Still searching events...&quot;}</pre><p>No more wondering if the app crashed.</p><h3>The Final Architecture</h3><p>Here’s what works in production:</p><pre>User Request<br>    ↓<br>FastAPI (Single Worker for 5-10 users)<br>    ↓<br>Session Manager (per-user message queues)<br>    ↓<br>Redis (shared session state, 24hr TTL)<br>    ↓<br>PydanticAI Agent (with tools: Perplexity AI, Mapbox)<br>    ↓<br>Streaming Response (SSE)</pre><p><strong>Key decisions:</strong></p><ul><li>✅ One worker for small scale: less then 100 simulteneous users (simple beats clever)</li><li>✅ Redis for session persistence (works across restarts)</li><li>✅ Message queues per user (prevents race conditions)</li><li>✅ SSE for streaming (better UX than polling)</li><li>✅ exhaustive strategy (side effects always execute)</li></ul><h3>The Result</h3><p>Users can now:</p><ol><li>Ask “Find events in Limassol, Cyprus”</li><li>See the agent search in real-time</li><li>Get a numbered list of events</li><li>Select favorites: “1, 3, 5”</li><li>Receive Google Maps links instantly</li></ol><p>All while supporting multiple concurrent users, handling rapid-fire messages, and never losing context.</p><h3>Lessons Learned</h3><ul><li><strong>Start simple.</strong> One worker handles more than you think.</li><li><strong>Use Redis early.</strong> In-memory state doesn’t scale. Redis does.</li><li><strong>Queue messages.</strong> Race conditions are inevitable without queues.</li><li><strong>Stream everything.</strong> Users love seeing progress. SSE is your friend.</li><li><strong>Test concurrency.</strong> Send 20 messages at once. You’ll find bugs immediately.</li><li><strong>Read the docs.</strong> end_strategy=&#39;exhaustive&#39; saved me hours of debugging.</li></ul><h3>Try It Yourself</h3><p>The full project is <a href="https://github.com/aleksandr-dzhumurat/google_adk_travel_assistant">open source on GitHub</a> with complete setup instructions. It uses:</p><ul><li><strong>PydanticAI</strong> for the agent framework</li><li><strong>FastAPI</strong> for the REST API</li><li><strong>Redis</strong> for session management</li><li><strong>Google Gemini 2.0 Flash</strong> for the LLM</li><li><strong>Perplexity AI</strong> for event search</li><li><strong>Mapbox</strong> for geocoding</li></ul><p>Clone it, add your API keys, and you’ll have a production-ready multi-user AI agent running in minutes.</p><p>Building AI agents is fun. Building <strong>production</strong> AI agents that handle real users? That’s where the real learning happens.</p><p><strong>Want more AI engineering deep-dives?</strong> Follow me for practical lessons from building real-world LLM applications.</p><p><em>Questions? Drop them in the comments. I’d love to hear about your multi-user agent challenges.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e9021daede5f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a production-ready AI travel agent using Google ADK and Langfuse]]></title>
            <link>https://medium.com/@alexandrdzhumurat/building-a-production-ready-ai-travel-agent-using-google-adk-and-langfuse-fc08f8ac1b3c?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/fc08f8ac1b3c</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[perplexity]]></category>
            <category><![CDATA[langfuse]]></category>
            <category><![CDATA[google-adk]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Tue, 02 Dec 2025 11:15:27 GMT</pubDate>
            <atom:updated>2025-12-02T11:15:27.530Z</atom:updated>
            <content:encoded><![CDATA[<p>🚀 <strong>Don’t miss this!</strong> I just built a production-ready AI travel agent using <a href="https://google.github.io/adk-docs/agents/">Google ADK</a>, and the results are mind-blowing.</p><p><strong>Here’s what you’ll learn:</strong></p><ul><li>✅ Why Google ADK crushes LangChain, CrewAI &amp; AutoGPT for production agents</li><li>✅ Real-time event discovery with Perplexity AI integration</li><li>✅ Precision geocoding with MapBox API (98% accuracy!)</li><li>✅ Complete observability setup with Langfuse</li></ul><p>This isn’t theory — this is <strong>**battle-tested architecture**</strong> running in production.</p><p>I’m sharing:</p><ul><li>Complete system architecture diagrams</li><li>Code examples that actually work</li><li>Cost optimization strategies from real data</li><li>How to orchestrate external APIs (Perplexity + MapBox) seamlessly</li></ul><p>Don’t miss link to repo at the end of the post!</p><p>After building an event discovery and route planning agent, I want to share why <strong>Google’s Agent Development Kit (ADK)</strong> has become my go-to framework for production-grade AI agents — and how it simplifies complex travel tasks through smart integrations.</p><h3><strong>The Challenge: Intelligent Event Discovery for Travelers</strong></h3><p>Imagine you’re visiting a new city — say Limassol (Cyprus), or Paris (France). You want to:</p><ul><li>Discover popular events happening during your visit</li><li>Get accurate location coordinates for each venue</li><li>Plan your route efficiently</li></ul><p>Sounds simple, but it requires orchestrating multiple external services while maintaining accuracy and reliability. Here’s where Google ADK truly shines.</p><p><strong>Why Google ADK Over LangChain, CrewAI, or AutoGPT?</strong></p><p>Having worked with several agent frameworks, Google ADK stands out for three critical reasons:</p><p><strong>1. Native Integration with Gemini Models</strong></p><p>Unlike LangChain’s model-agnostic approach (which adds abstraction layers), Google ADK is <strong>purpose-built for Gemini</strong>. This means:</p><ul><li>Zero friction with function calling — it just works</li><li>Optimal token usage and context management</li><li>Built-in support for Gemini’s multi-turn conversations</li><li>Native streaming with proper event handling</li></ul><pre># With Google ADK - clean and direct<br>agent = Agent(<br>  name=&quot;event_agent&quot;,<br>  model=&quot;gemini-2.0-flash-exp&quot;,<br>  instruction=&quot;Your system prompt here&quot;,<br>  tools=[FunctionTool(geocode_address), FunctionTool(search_events)]<br>)</pre><p><strong>2. Production-Ready Architecture from Day One</strong></p><p>While frameworks like AutoGPT focus on experimental autonomy, Google ADK provides:</p><ul><li><strong>Persistent session management</strong> via InMemoryRunner</li><li><strong>Built-in state tracking</strong> across conversations</li><li><strong>Event-driven architecture</strong> for real-time streaming</li><li><strong>Type-safe tool definitions</strong> with automatic schema generation</li></ul><p><strong>3. Simplified Tool Integration</strong></p><p>Compared to LangChain’s verbose tool definitions or CrewAI’s task-based complexity, Google ADK uses simple Python functions:</p><pre>def get_city_center(city: str, country: str) -&gt; dict:<br>  &quot;&quot;&quot;Get city center coordinates for reference point.&quot;&quot;&quot;<br>  # Implementation here<br>  return {&quot;latitude&quot;: lat, &quot;longitude&quot;: lon}<br>  # That&#39;s it - ADK automatically generates the schema<br><br>agent.tools = [FunctionTool(get_city_center)]</pre><p>No decorators, no complex inheritance, no boilerplate.</p><h3><strong>Real-World Integration: Perplexity for Real-Time Event Discovery</strong></h3><p>One of the biggest advantages? Seamless integration with external AI services. My agent uses <strong>Perplexity AI’s Sonar model</strong> for real-time event search:</p><p><strong>Why Perplexity?</strong></p><ul><li><strong>Real-time web search</strong>: Gets current event data, not training cutoff data</li><li><strong>Structured responses</strong>: Returns formatted event listings with dates, venues, descriptions</li><li><strong>Source citations</strong>: Provides verifiable sources for each event</li></ul><p>You can call Perplexity API with justrequests lib</p><pre>        payload = {<br>            &quot;model&quot;: &quot;sonar&quot;,<br>            &quot;messages&quot;: [<br>                {&quot;role&quot;: &quot;system&quot;, &quot;content&quot;: system_prompt},<br>                {&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: user_prompt},<br>            ],<br>            &quot;max_tokens&quot;: max_tokens,<br>            &quot;temperature&quot;: temperature,<br>            &quot;top_p&quot;: 0.9,<br>            &quot;search_domain_filter&quot;: [<br>                &quot;perplexity.ai&quot;<br>            ],<br>            &quot;return_images&quot;: False,<br>            &quot;return_related_questions&quot;: True,<br>            &quot;search_recency_filter&quot;: &quot;month&quot;,<br>        }<br><br>        response = requests.post(<br>            self.base_url, headers=self.headers, json=payload, timeout=30<br>        )</pre><h3><strong>Geocoding with MapBox API</strong></h3><p>Getting accurate venue locations is critical for travel planning. A naive geocoding approach might return “Rialto Theatre” in the wrong country. My agent uses a <strong>three-layer constraint system</strong>:</p><p><strong>1. Enhanced Query Construction</strong></p><pre># Input: &quot;Rialto Theatre&quot;<br># Enhanced: &quot;Rialto Theatre, Limassol, Cyprus&quot;<br>enhanced_query = f&quot;{venue}, {city}, {country}&quot;</pre><p><strong>2. Bounding Box Constraints</strong></p><pre># Restricts results to ~50km radius from city center<br>bbox_delta = 0.45 # degrees (~50km)<br>bbox = f&quot;{center_lon - bbox_delta},{center_lat - bbox_delta},&quot;<br>f&quot;{center_lon + bbox_delta},{center_lat + bbox_delta}&quot;</pre><p><strong>3. Proximity Bias</strong></p><pre># Ranks results closer to city center higher<br>params = {<br>  &quot;proximity&quot;: f&quot;{center_lon},{center_lat}&quot;,<br>  &quot;bbox&quot;: bbox<br>}</pre><p>This ensures the agent <strong>always returns venues from the correct city</strong>, even when names overlap across countries.</p><h3><strong>Complete Workflow Architecture</strong></h3><p>Here’s how everything comes together:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Vjk4ZO_54jwHGpueeafNMQ.png" /></figure><p><strong>Smart Reliability with Exponential Backoff</strong></p><p>APIs fail. Networks timeout. Production agents need to handle this gracefully:</p><pre>@backoff.on_exception(<br>  backoff.expo,<br>  (requests.exceptions.Timeout, requests.exceptions.ConnectionError),<br>  max_tries=3,<br>  max_time=90<br>)<br>def search_events(city: str, country: str) -&gt; dict:<br>&quot;&quot;&quot;Search for events with automatic retry on failures.&quot;&quot;&quot;<br># Perplexity API call here</pre><p>This simple decorator provides:</p><p>- Automatic retries (up to 3 attempts)</p><p>- Exponential wait times (~1s, ~2s, ~4s)</p><p>- Graceful degradation on persistent failures</p><h3><strong>Observability: Langfuse for Production Monitoring</strong></h3><p>Running agents in production without observability is like flying blind. This is where <strong>Langfuse</strong> becomes indispensable:</p><p><strong>What Langfuse Tracks</strong></p><ul><li>✅ <strong>Cost per conversation</strong>: Token usage × model pricing</li><li>✅ <strong>Response latency</strong>: Tool call timing, end-to-end performance</li><li>✅ <strong>Tool execution logs</strong>: Which tools were called, with what parameters</li><li>✅ <strong>Error rates</strong>: Failed API calls, timeout patterns</li><li>✅ <strong>User interaction patterns</strong>: Most common queries, drop-off points</li></ul><p><strong>Integration is Effortless</strong></p><p>Thanks to OpenTelemetry standards, integration is literally three lines:</p><pre>from openinference.instrumentation.google_adk import GoogleADKInstrumentor<br># That&#39;s it - all traces are now sent to Langfuse<br>GoogleADKInstrumentor().instrument()</pre><h3><strong>System Architecture: The Complete Picture</strong></h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9YXEqiyQ7cPYR8a7KglJyQ.png" /><figcaption>Google ADK architecture</figcaption></figure><p><strong>Tech Stack:</strong></p><ul><li><strong>Agent Framework</strong>: Google ADK (Agent Development Kit)</li><li><strong>LLM</strong>: Gemini 2.0 Flash Experimental</li><li><strong>Event Search</strong>: Perplexity AI Sonar Model</li><li><strong>Geocoding</strong>: MapBox Geocoding API</li><li><strong>Observability</strong>: Langfuse + OpenTelemetry</li><li><strong>Deployment</strong>: InMemoryRunner (local), scalable to distributed</li></ul><p><strong>Key Architectural Benefits</strong></p><p>1. <strong>Separation of Concerns</strong>: Agent logic separated from tool implementation</p><p>2. <strong>Easy Testing</strong>: Each tool is a pure function, easily unit testable</p><p>3. <strong>Observable</strong>: Every layer instrumented via OpenTelemetry</p><p>4. <strong>Scalable</strong>: InMemoryRunner can be swapped for distributed runner</p><p>5. <strong>Maintainable</strong>: Adding new tools requires only defining Python functions</p><p><strong>## Performance in Production</strong></p><p>After deploying this architecture for event discovery:</p><h3><strong>Key Takeaways</strong></h3><p>If you’re building production AI agents:</p><p>1. <strong>Choose Google ADK</strong> for Gemini-based agents — native integration beats abstraction layers</p><p>2. <strong>Integrate specialized AI services</strong> like Perplexity for tasks beyond LLM capabilities</p><p>3. <strong>Implement smart constraints</strong> for external APIs (bounding boxes, proximity, retries)</p><p>4. <strong>Use Langfuse from day one</strong> — observability isn’t optional for production</p><p>5. <strong>Design stateless tools</strong> — makes testing and scaling trivial</p><p><strong>What’s Next?</strong></p><p>I’m exploring:</p><ul><li>Multi-city route optimization (traveling between Paris → Lyon → Marseille)</li><li>Calendar integration (sync event bookings automatically)</li><li>Collaborative planning (multiple users planning trips together)</li><li>Cost optimization (caching strategies, batch requests)</li></ul><p><strong>GitHub</strong>: <a href="https://github.com/aleksandr-dzhumurat/google_adk_travel_assistant">https://github.com/aleksandr-dzhumurat/google_adk_travel_assistant</a></p><p>Have you built agents with Google ADK or other frameworks? What challenges did you face? Let’s discuss in the comments!</p><p>#AI #MachineLearning #GoogleADK #GenAI #TravelTech #AgenticAI #Gemini #Observability #ProductionML</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fc08f8ac1b3c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[️ Analytics Agent: integrate AI with the semantic layer]]></title>
            <link>https://medium.com/@alexandrdzhumurat/%EF%B8%8F-analytics-agent-integrate-ai-with-the-semantic-layer-3398440a8a84?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/3398440a8a84</guid>
            <category><![CDATA[autogen]]></category>
            <category><![CDATA[data-analysis]]></category>
            <category><![CDATA[openai]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Sun, 21 Sep 2025 10:53:28 GMT</pubDate>
            <atom:updated>2025-09-21T10:53:28.482Z</atom:updated>
            <content:encoded><![CDATA[<p>Building Agentic analytics pipeline could be hard: designing a whole set of agents for things like DWH interaction, Confluence, and more is not an easy task.<br>It made me think about the role of a semantic layer 🧩</p><p>That’s the idea behind Cube Analyst, a proof-of-concept conversational BI agent I’ve been building! 🤖 It uses an LLM to understand user questions, explore a semantic layer, and build structured queries for data analysis.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*y5_EX46rLwLn-ay_zAGkWw.png" /></figure><h3>Key Features:</h3><ul><li>🗣️ Natural Language Interface: No more SQL! Just ask questions and get answers.</li><li>🧠 DIY Semantic Layer: It’s powered by a simple text file that defines business logic (cubes, measures, dimensions). This makes it a lightweight, build-it-yourself alternative to a full Metric Compute Protocol (MCP) server.</li><li>🚀 AutoGen &amp; Python: Built with a modern, agentic stack using Microsoft’s AutoGen framework. The agent generates queries compatible with data API tools like Cube.js.</li></ul><p>Code available: <a href="https://github.com/aleksandr-dzhumurat/agentic_analyst">https://github.com/aleksandr-dzhumurat/agentic_analyst</a></p><h3>The Vision</h3><p>The goal is to democratize data access and speed up decision-making. Our demo is tailored for the pharmacy industry 💊, but the architecture is domain-agnostic and can be adapted for finance, e-commerce, logistics, and more simply by changing the semantic layer file.</p><p>This project was built with the powerful Microsoft AutoGen library: <a href="https://github.com/microsoft/autogen">https://github.com/microsoft/autogen</a></p><p>It’s also inspired by the concepts in Microsoft’s Model Context Protocol (MCP) for Beginners course, a great resource for building connected AI applications:<a href="https://github.com/microsoft/mcp-for-beginners">https://github.com/microsoft/mcp-for-beginners</a></p><p><strong>Business case</strong>: imagine a manager for a chain of pharmacies. They need to make quick, data-informed decisions but don’t have the time or SQL skills to dig into the data warehouse. With Cube Analyst, they can get answers instantly:</p><ul><li>Inventory Management: A store manager could ask, <em>“Show me the current quantity and turnover days for prescription drugs in the Goods cube.”</em> This helps them optimize stock levels and prevent shortages.</li><li>Sales &amp; Performance: A regional director might ask, <em>“I need a report of net sales and gross margin for the top 5 selling products last month, grouped by store name.”</em> This allows for quick performance comparisons.</li><li>Patient Demographics: A marketing analyst could ask, <em>“What is the age and gender distribution of Buyers for our new promotional campaign?”</em> This helps in targeting marketing efforts more effectively.</li></ul><p>In each case, the agent understands the user’s intent, helps them select the right metrics from the semantic layer (Orders.net_sales, Goods.turnover_days, Buyer.customer_age), and generates a structured query.</p><h3>Project architecture</h3><p>Key repository components</p><ol><li>streamlit_app.py: The entry point for the application. This simple, chat-based web interface remains in the project root.</li><li>src Directory: Contains all Python source code, promoting a clean and scalable project structure.</li><li>assets Directory: Contains all non-code files, including the semantic layer definition and configuration.</li><li>prompts Directory: Contains the agent&#39;s system prompt, externalized for easy editing.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/299/1*60CQTO-iY0vqdQ2MXq2aQQ.jpeg" /></figure><p>In the repo pharmacy example is just a starting point. Because the agent’s knowledge is entirely defined by the semantic_layer.txt file, this architecture is highly adaptable. You could replace the pharmacy data with a semantic layer for e-commerce, logistics, finance, or any other domain, and the agent would instantly become an expert in that area. The core logic remains the same; only the metadata changes.</p><h3>The Semantic Layer: The Brains of the Operation</h3><p>The most important concept in this architecture is the semantic layer. It’s a business-friendly representation of your data. Instead of tables and columns, it defines concepts like:</p><ul><li>Cubes: Functional areas of the business (e.g., Orders, Goods, Buyer).</li><li>Measures: Quantitative metrics (e.g., Orders.net_sales, Goods.quantity).</li><li>Dimensions: Attributes to group and filter by (e.g., Orders.product_brand, Buyer.customer_city).</li></ul><p>By giving the agent access to tools that can query this layer, we ensure it is grounded in the actual data model and can intelligently suggest relevant metrics to the user.</p><h3>Motivation: A Lightweight, DIY Semantic Layer</h3><p>While many in the data world talk about the Metric Compute Protocol (MCP), what if you could build a similar experience yourself with lightweight tools? This project explores that idea.</p><p>Here’s how this project differs from a “real” MCP server (like Cube or dbt Semantic Layer):</p><ul><li>What is Served: A true MCP server connects to a data warehouse and serves <em>computed metric data</em> via an API. This project’s DataPlatformSemanticServer doesn&#39;t compute anything. Instead, it serves <em>metadata</em> from a text file to an LLM agent. The agent reasons about what metrics are needed, and its final output is a structured request (a JSON object) that a downstream system could use to actually fetch the data.</li><li>Simplicity &amp; Speed: Our semantic layer is a simple JSONL text file. It&#39;s incredibly fast to set up and can be version-controlled with Git. This is a stark contrast to the complex infrastructure required for a full MCP server.</li><li>Use Case: This project is ideal for rapid prototyping or for teams that want to build a natural language front-end without committing to heavy backend infrastructure.</li></ul><p>In essence, Cube Analyst simulates the <em>discovery and query-building</em> part of a metrics platform, offloading the reasoning to an LLM. The final JSON output is designed to be compatible with the query format used by data API tools like Cube.js, effectively acting as a natural language layer on top of them.</p><h3>Building the Agent with AutoGen</h3><p>We defined a BIAnalystAgent class that encapsulates the agent&#39;s setup. The core of this is the ConversableAgent from AutoGen, which is given its persona and instructions via an external prompt file.</p><pre># From src/semantic_layer_mcp.py<br># Load the prompt from an external file<br>with open(&quot;prompts/bi_analyst_prompt.txt&quot;, &quot;r&quot;) as f:<br>    system_message = f.read()<br>self.bi_analyst = ConversableAgent(<br>    name=&quot;BIAnalyst&quot;,<br>    system_message=system_message,<br>    llm_config=self.llm_config,<br>    human_input_mode=&quot;NEVER&quot;,<br></pre><p>The power of this approach lies in the system_message, which is loaded from prompts/bi_analyst_prompt.txt. This prompt gives the agent its personality, its capabilities, and its rules of engagement, including the instruction to generate JSON reports.</p><h3>Understanding AutoGen’s Agents</h3><p>To understand how our BIAnalystAgent works, it&#39;s helpful to know the roles of the two core AutoGen agent types we use:</p><ul><li><a href="https://microsoft.github.io/autogen/docs/reference/agentchat/conversable_agent">ConversableAgent</a>: This is the standard, general-purpose agent. It can have a conversation, use tools, and has a system prompt that defines its persona and skills. Our bi_analyst is a ConversableAgent. It&#39;s the &quot;expert&quot; that has the knowledge of the semantic layer and the tools to query it.</li><li><a href="https://microsoft.github.io/autogen/docs/reference/agentchat/user_proxy_agent">UserProxyAgent</a>: This agent acts as a proxy for the human user. In a typical AutoGen setup, it&#39;s responsible for soliciting input from the user and, importantly, executing code or tool calls on the user&#39;s behalf. In our project, the user_proxy serves a more subtle but critical role. Since our BIAnalystAgent is not allowed to execute code itself for security reasons, it tells the user_proxy which tool to run. The user_proxy then executes the tool (like get_cubes) and sends the result back to the BIAnalystAgent.<br>This separation of &quot;thinking&quot; (the ConversableAgent) and &quot;doing&quot; (the UserProxyAgent) is a fundamental concept in AutoGen that enables safe and powerful agentic workflows.<br>)</li></ul><h3>Technical Deep Dive: Overcoming Integration Hurdles</h3><p>Integrating a conversational agent framework with a web framework like Streamlit required solving several common challenges.</p><h4>Challenge 1: The Stateless Web</h4><p>Problem: The agent had no memory between user messages. Solution: We re-architected the chat logic to be stateful. Instead of using AutoGen’s initiate_chat for every message, we switched to generate_reply and passed the full conversation history (stored in Streamlit&#39;s session state) with every turn.</p><h4>Challenge 2: The Frozen UI</h4><p>Problem: The app froze while waiting for the LLM to respond. Solution: We moved the agent call to a separate thread using Python’s concurrent.futures.ThreadPoolExecutor. This allows the UI to remain responsive and show a spinner while the agent works in the background.</p><h3>How to Run This Project</h3><ol><li>Install Dependencies:</li></ol><ul><li>pip install -r requirements.txt</li></ul><ol><li>Set Environment Variable: Create a .env file and add your OpenAI API key:</li></ol><pre>OPENAI_API_KEY=&quot;your-key-here&quot;</pre><ol><li>Configure: Review assets/config.yaml to ensure the settings are to your liking.</li><li>Run the App:</li></ol><pre>streamlit run streamlit_app.py</pre><h3>Developer Tools: Testing the Semantic Layer</h3><p>For developers, the project includes a simple command-line tool for inspecting the semantic layer directly: src/main_simple.py. This is the best way to verify that your assets/semantic_layer.txt file is correctly structured and that the data is what you expect the agent to see.</p><p>For example, to get all the details for the “Orders” cube, run this command from your project root:</p><pre>python -m src.main_simple --cube &quot;Orders&quot;</pre><p>This will print a clean JSON object to your terminal describing the cube’s measures and dimensions, allowing you to debug the agent’s knowledge base directly.</p><h3>Conclusion</h3><p>This project demonstrates a powerful and flexible architecture for building conversational data assistants. By separating the UI, the agent logic (src), and the data/config (assets), we&#39;ve created a system that is both capable and easy to maintain. The journey also highlighted key technical challenges and solutions that are critical for anyone building real-world agentic applications.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3398440a8a84" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[ Exploring RAG with FAISS and OpenAI — All on Google Colab!]]></title>
            <link>https://medium.com/@alexandrdzhumurat/exploring-rag-with-faiss-and-openai-all-on-google-colab-9a2875dace22?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/9a2875dace22</guid>
            <category><![CDATA[google-colab]]></category>
            <category><![CDATA[langchain]]></category>
            <category><![CDATA[faiss]]></category>
            <category><![CDATA[openai]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Tue, 05 Aug 2025 15:00:55 GMT</pubDate>
            <atom:updated>2025-08-05T15:00:55.965Z</atom:updated>
            <content:encoded><![CDATA[<h3>🔍 Exploring RAG with FAISS and OpenAI — all on Google Colab!</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MFqL4sKMiyobSL5ZgOBbww.png" /></figure><p><strong>RAG (Retrieval-Augmented Generation)</strong> exploded in popularity in 2024 — and for good reason. It’s the bridge between large language models and grounded, context-rich responses.</p><p>In this post, we’ll walk through a <strong>reproducible RAG pipeline</strong> using <strong>FAISS</strong>, <strong>OpenAI embeddings</strong>, and <strong>Google Colab</strong> — complete with free GPU, and persistent storage support.</p><p>We’ll build a <strong>question-answering system</strong> backed by a custom knowledge base. While this is a basic implementation, it forms the foundation for more advanced setups like <strong>agentic RAG</strong>, <strong>graph-RAG</strong>, or even <strong>Gemini 1M-token context loading</strong>.</p><p>Let’s dive in 👇</p><h3>🛠️ Step 1: Upload and Mount Your Data</h3><p>Before anything else, upload your dataset (i prefer to use `.json` files) to your Colab instance.</p><p>Then, mount your <strong>Google Drive</strong>:</p><pre>import hashlib<br>import json<br>import os<br>import time<br>from dataclasses import dataclass<br>from typing import List, Set, Optional, Iterable, TypedDict<br><br>import polars as pl<br>from dotenv import load_dotenv<br>from google.colab import userdata<br>from openai import OpenAI<br>from tqdm import tqdm<br>from transformers import AutoTokenizer<br># LangChain imports<br>from langchain.docstore.document import Document<br>from langchain.text_splitter import RecursiveCharacterTextSplitter<br>from langchain_community.embeddings import HuggingFaceEmbeddings<br>from langchain_community.vectorstores import FAISS<br>from langchain_community.vectorstores.utils import DistanceStrategy<br><br>from google.colab import drive<br>ROOT_DIR = &#39;/content/drive&#39;<br>drive.mount(ROOT_DIR)<br>print(&#39;Drive was connected&#39;)<br>root_data_dir = os.path.join(ROOT_DIR, &#39;MyDrive&#39;, &#39;your_data&#39;)<br>if not os.path.exists(root_data_dir):<br>  raise RuntimeError(&#39;Data dir not exists&#39;)<br>else:<br>  print(&#39;Dir connection %s: %s&#39; % (root_data_dir, &#39;, &#39;.join(os.listdir(root_data_dir))))</pre><p>We’ll store our documents <strong>and</strong> models here for faster re-use (e.g., HuggingFace transformers and embeddings).</p><blockquote><strong><em>💡 Tip:</em></strong><em> Make sure your Drive has enough space to hold both the documents and PyTorch model weights.</em></blockquote><h3>📄 Step 2: Ingest Documents</h3><p>Create a list of documents by loading your data into memory. Optionally, compute a <strong>data hash</strong> (e.g., SHA256) to track changes for versioning.</p><pre><br>class TextSourceDict(TypedDict):<br>    text: str<br>    source: str<br><br>knowledgebase_path = os.path.join(root_data_dir, &#39;meta_696efe98398fc3de97d2037ea4861c83.json&#39;) # type: Iterable[TextSourceDict]<br><br>MIN_PAGE_LENGTH = 50<br>documents = [<br>    Document(page_content=doc[&quot;text&quot;], metadata={&quot;source&quot;: doc[&quot;source&quot;]})<br>    for doc in load_json(knowledgebase_path)<br>    if len(doc[&#39;text&#39;]) &gt; MIN_PAGE_LENGTH<br>]<br>index_name = generate_id(&#39; &#39;.join([i.page_content for i in documents]))<br><br>vector_db_path = os.path.join(vector_db_root, index_name)<br>os.makedirs(vector_db_path, exist_ok=True)<br><br>print(f&#39;Num docs: {len(documents)}, index name: {index_name}&#39;)</pre><h3>✂️ Step 3: Chunking</h3><p>Documents are too large for most LLM contexts, so we need to <strong>chunk</strong> them.</p><p>We’ll use a simple sliding window approach — feel free to tune this later for better semantic overlap and performance.</p><pre><br>def get_tokenizer(models_dir, model_name=&quot;thenlper/gte-small&quot;):<br>    global tokenizer<br><br>    if tokenizer is None:<br>        tokenizer = AutoTokenizer.from_pretrained(<br>            model_name, cache_folder=models_dir<br>        )<br>    return tokenizer<br><br><br>def get_text_splitter(models_dir):<br>    chunk_size = 200<br>    chunk_overlap = 20<br><br>    text_splitter = RecursiveCharacterTextSplitter.from_huggingface_tokenizer(<br>        tokenizer=get_tokenizer(models_dir),<br>        chunk_size=chunk_size,<br>        chunk_overlap=chunk_overlap,<br>        add_start_index=True,<br>        strip_whitespace=True,<br>        separators=[&quot;\n\n&quot;, &quot;\n&quot;, &quot;.&quot;, &quot; &quot;, &quot;&quot;],<br>    )<br>    return text_splitter<br><br>def chunk_documents(documents: List[Document], models_dir) -&gt; List[Document]:<br>    &quot;&quot;&quot;Split documents into chunks&quot;&quot;&quot;<br>    print(&quot;Splitting documents...&quot;)<br>    text_splitter = get_text_splitter(models_dir)<br>    docs_processed = []<br>    unique_texts: Set[str] = set()<br><br>    for doc in tqdm(documents, desc=&quot;Chunking documents&quot;):<br>        new_docs = text_splitter.split_documents([doc])<br>        for new_doc in new_docs:<br>            if new_doc.page_content not in unique_texts:<br>                unique_texts.add(new_doc.page_content)<br>                docs_processed.append(new_doc)<br><br>    print(f&quot;Created {len(docs_processed)} unique document chunks&quot;)<br>    return docs_processed<br><br>chunked_docs = chunk_documents(documents, models_dir=models_dir)</pre><h3>🔌 Step 4: Generate Embeddings with Hugginface</h3><p>Use Huggingfaces’s transformers to vectorize each chunk. Save embeddings locally to avoid re-processing on each run.</p><p>Create a FAISS index from the chunk embeddings:</p><pre><br>def save_vector_db(vector_db: FAISS, path: str, model_name = &quot;thenlper/gte-small&quot;):<br>    &quot;&quot;&quot;Save vector database to disk&quot;&quot;&quot;<br>    os.makedirs(os.path.dirname(path), exist_ok=True)<br>    vector_db.save_local(path)<br>    print(f&quot;Vector database saved to: {path}&quot;)<br><br>def create_vector_database(docs_processed: List[Document], models_dir: str, model_name = &quot;thenlper/gte-small&quot;) -&gt; FAISS:<br>    &quot;&quot;&quot;Create a vector database from processed documents&quot;&quot;&quot;<br>    print(&quot;Embedding documents... This may take a few minutes&quot;)<br>    embedding_model = HuggingFaceEmbeddings(<br>        model_name=model_name, cache_folder=models_dir<br>    )<br>    return FAISS.from_documents(<br>        documents=docs_processed,<br>        embedding=embedding_model,<br>        distance_strategy=DistanceStrategy.COSINE,<br>    )<br><br>vector_db = create_vector_database(chunked_docs, models_dir=models_dir)<br>save_vector_db(vector_db, vector_db_path)</pre><h3>🔎 Step 6: Retrieve Relevant Context for a Query</h3><p>Now, test retrieval:</p><pre><br>def run_query(query, vector_db):<br>    docs = vector_db.similarity_search(<br>        query,<br>        k=10<br>    )<br>    results = []<br>    for i, doc in enumerate(docs):<br>        results.append({<br>            &quot;index&quot;: i,<br>            &quot;content&quot;: doc.page_content,<br>            &quot;doc_id&quot;: doc.metadata[&#39;source&#39;],<br>            &quot;metadata&quot;: doc.metadata,<br>            &quot;preview&quot;: doc.page_content[:200] + &quot;...&quot; if len(doc.page_content) &gt; 200 else doc.page_content,<br>            &quot;length&quot;: len(doc.page_content)<br>        })<br>    return results<br><br>def prepare_relevant_dialogs(search_results, knowledgebase):<br>  doc_ids = set([i[&#39;doc_id&#39;] for i in search_results])<br>  relevant_dialogs = &#39;\n&#39;.join([i[&#39;text&#39;] for i in knowledgebase if i[&#39;source&#39;] in doc_ids])<br>  return relevant_dialogs<br><br>q = &#39;hi. Is there a way to run a report that shows expiration dates for my inventory?&#39;<br><br>search_results = run_query(q, vector_db)<br>relevant_dialogs = prepare_relevant_dialogs(search_results, knowledgebase)<br>print(&#39;Dialogs prepared&#39;)</pre><h3>✍️ Step 7: Generate an Answer using OpenAI</h3><p>Take the retrieved docs and pass them as context to OpenAI for answer generation.</p><pre>@dataclass<br>class GenAIResponse:<br>    text: str<br>    total_tokens: str<br>    model: str<br><br><br>def generate_prompt(query, convs):<br>  user_prompt = f&quot;&quot;&quot;<br>      You are an AI assistant. Your task is to answer the user&#39;s question **solely based on the provided knowledge base**.<br>      If the answer cannot be found in the provided knowledge base, explicitly state that the information is not available within the provided context.<br>      Do not use any external knowledge.<br><br>      QUESTION: {query}<br><br>      sweed knowldge base:<br>      {convs}<br>  &quot;&quot;&quot;<br>  return user_prompt<br><br>def generate(client, user_prompt, system_prompt = &quot;You are skilled suppport engigneer from e-commerse domain&quot;, model=&quot;gpt-3.5-turbo&quot;):<br>  gpt_params = {<br>      &quot;model&quot;: model,<br>      &quot;max_tokens&quot;: 500,<br>      &quot;temperature&quot;: 0.7,<br>      &quot;top_p&quot;: 0.5,<br>      &quot;frequency_penalty&quot;: 0.5,<br>  }<br>  messages = [<br>      {<br>          &quot;role&quot;: &quot;system&quot;,<br>          &quot;content&quot;: system_prompt,<br>      },<br>      {<br>          &quot;role&quot;: &quot;user&quot;,<br>          &quot;content&quot;: user_prompt,<br>      },<br>  ]<br>  gpt_params.update({&quot;messages&quot;: messages})<br><br>  response = client.chat.completions.create(**gpt_params)<br>  response = GenAIResponse(<br>      text=response.choices[0].message.content,<br>      total_tokens=response.usage.total_tokens,<br>      model=model<br>  )<br><br>  return response</pre><h3>✅ What You Built</h3><ul><li>A working <strong>Retrieval-Augmented Generation (RAG)</strong> pipeline</li><li>Fast vector search using <strong>FAISS</strong></li><li>Lightweight question answering over custom data (not too much langchai code included</li><li>All powered by <strong>OpenAI</strong>, running on <strong>Google Colab</strong> with free GPU</li></ul><p>Happy building! ✌️</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9a2875dace22" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Stop wasting your life in query debugging — use code agents instead.]]></title>
            <link>https://medium.com/@alexandrdzhumurat/stop-wasting-your-life-in-query-debugging-use-code-agents-instead-810e8de2fa7a?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/810e8de2fa7a</guid>
            <category><![CDATA[claude-ai]]></category>
            <category><![CDATA[agents]]></category>
            <category><![CDATA[analytics]]></category>
            <category><![CDATA[codex-cli]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Sun, 29 Jun 2025 10:48:38 GMT</pubDate>
            <atom:updated>2025-06-29T19:27:18.155Z</atom:updated>
            <content:encoded><![CDATA[<h3>Stop wasting your life in query debugging — use code agents instead.</h3><p>Let’s be honest: you didn’t sign up for analytics just to spend your days tweaking broken SQL and copy-pasting charts into slides. Yet here we are — dashboards rot in Confluence, tickets pile up, and you’re stuck writing another query to calculate last month’s retention rate.</p><p>But what if I told you that you can <strong>replace your entire analytics workflow with a coding agent</strong>?</p><p>Yes, the hype is real. And yes, most AI tools feel disappointing after the first “wow” moment. But that’s only because most people use code agents like they vibe code on Fridays — no structure, no strategy, just vibes.</p><p>Let’s switch gears from hype to engineering.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TEcPwjp6r_q52E8BEcY6Zg.png" /></figure><h3>Analytics Isn’t Magic. It’s a Workflow.</h3><p>Imagine that you goal is perform some marketing analytics report for you stakeholders. You have Google BigQuery database with ~200 tables and pure documentation. What will be your steps?</p><p>If you’re good at analytics, you can explain your process to a five-year-old.</p><p>Here’s what we <em>really</em> do as analysts:</p><ul><li>Explore a few tables (if we’re lucky, with a data catalog like OpenMetaData),</li><li>Write and run queries to understand what’s going on,</li><li>Create reports and add some commentary,</li><li>Get feedback from stakeholders and repeat.</li></ul><p>The input? A problem statement form stakeholder and maybe some example data.<br>The context? Table schemas, data samples, business logic.</p><p>That’s it. It’s not rocket science — it’s reproducible, structured, and automatable.</p><h3>Wrapping the Workflow in Code</h3><p>Let’s turn this process into a repo with the followed structure:</p><pre>.<br>|-- Dockerfile<br>|-- Makefile<br>|-- README.md<br>|-- requirements.txt<br>|-- results.csv<br>|-- agentic_prompts<br>|   |-- ...<br>|-- assets<br>|   |-- ...<br>|-- jupyter_notebooks<br>|   |-- ...<br>|-- reports<br>|   |-- ...<br>|-- sql<br>|   |-- ...<br>|-- sql_results<br>|   |-- ...<br>|-- src<br>|   |-- ...</pre><p>That’s it! Most of this directories are empty</p><ul><li>sql is for queries that will be generated by your agent</li><li>`sql_results` stores result of executed queries (for data exploration)</li><li>`reports` is for human review after task finished</li><li>`assets` contains problem statement you got from stakeholder</li></ul><p>This is your analytics “factory”. And at the heart of it? A <strong>prompt </strong>(stored in `prompts` directory). Not just any prompt — a carefully engineered one that turns a code agent into your analytics partner.</p><h3>The Prompt That Replaces a Team</h3><p>Let’s break it down:</p><blockquote>Your goal is to write a SQL query to get this data from the provided database with explanations based on provided table descriptions and data samples from tables. \<br>Carefully read the example of data in the assets/marketing_table.md file. |<br>Table fields are provided in the json file assets/db_config.jsonl. The final SQL should be based only on table names and table columns you find in assets/db_config.jsonl. |<br>Table names in the final SQL should have database “import”, don’t forget to wrap it in quotes like import.marketing_campaigns. <br>Every file you generate (like report or final sql) should include postfix <em>XXXXXXXX. XXXXXXXX should be a random string to distinguish different runs. After SQL is created, save it to file sql/marketing_analytics_</em>XXXXXXXX.sql and run the final query with command: cat sql/marketing_analytics_XXXXXXXX.sql | bq query — use_legacy_sql=false — format=csv &gt; sql_results/marketing_analytics_XXXXXXXX.tsv<br>If any errors occur in output, try to rewrite the query. Examples of data are provided in dir assets/bq_tables_sample. Save the result with an SQL explanation to ./reports/REPORT_CLAUDE_XXXXXXXX.MD. <br>Render table sql_results/marketing_analytics_XXXXXXXX.tsv and include it in the report.<br>Note: avoid adding Generated with Claude Code or any other references to agents.<br>Good luck!</blockquote><p>This isn’t GPT playing around. This is a pipeline:</p><ol><li>Use schema files (./assets/db_config.jsonl) and data samples (./assets/bq_tables_sample/) to understand the structure.</li><li>Generate SQL using that context — no hallucinations allowed.</li><li>Save query to ./sql/marketing_analytics_XXXXXXXX.sql (where XXXXXXXXis a data version, use this postfix for all generated files)</li></ol><p>Note: give your agent a tools to run query via CLI (I used Google BQ, but in could be any python script):</p><ul><li>cat sql/marketing_analytics_XXXXXXXX.sql | bq query --use_legacy_sql=false --format=csv &gt; sql_results/marketing_analytics_XXXXXXXX.tsv</li></ul><p>This approach allows Debug and retry on error automatically.</p><p>Finally report in Markdown ./reports/REPORT_CLAUDE_XXXXXXXX.md that includes the query, explanation, and rendered table.</p><p>Now you’ve got:</p><ul><li>SQL queries</li><li>results (data in csv )</li><li>commentary</li></ul><p>All wrapped in one neat package. Push it to Git. Done. Have your coffee.</p><h3>Why This Works</h3><p>The trick isn’t magic, it’s <strong>context + structure + control</strong>:</p><ul><li><strong>Context</strong>: give your agent table schemas, sample data, and a clear problem statement.</li><li><strong>Structure</strong>: build a folder layout and naming convention that lets agents read/write predictably.</li><li><strong>Control</strong>: let agents run code, catch SQL errors, and regenerate outputs.</li></ul><p>This is how we stop “prompt engineering” and start actual engineering.</p><h3>No More Data Heroics</h3><p>Most analytics teams waste hours manually debugging SQL and formatting slides. With the setup above, your agent becomes:</p><ul><li>Your junior analyst (writing the query),</li><li>Your data engineer (handling errors),</li><li>Your documentation bot (writing reports).</li></ul><p>All you do is review and merge.</p><h3>Final Thought</h3><p>If you’re still manually writing every query and formatting every report — you’re working in the sand. It’s time to automate the grind and reclaim your time.</p><p>You can use provided approach with different code agents</p><ul><li>claude code</li><li>openai codex</li><li>gemini cli</li></ul><p>Don’t forget to monitoring costs</p><ul><li><a href="https://console.anthropic.com/cost">https://console.anthropic.com/cost</a></li><li><a href="https://platform.openai.com/settings/organization/usage">https://platform.openai.com/settings/organization/usage</a></li></ul><p>Your new analytics teammate? It doesn’t sleep, doesn’t forget semicolons, and doesn’t mind reading JSON.</p><p>Just give it a good prompt, some context, and watch it replace your daily standup.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=810e8de2fa7a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Smarter multi-label predictions with adaptive few-shot prompting]]></title>
            <link>https://medium.com/@alexandrdzhumurat/smarter-multi-label-predictions-with-adaptive-few-shot-prompting-2b3da7e08239?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/2b3da7e08239</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[fastapi]]></category>
            <category><![CDATA[llm]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Tue, 13 May 2025 15:48:55 GMT</pubDate>
            <atom:updated>2025-05-13T15:48:55.830Z</atom:updated>
            <content:encoded><![CDATA[<p>A modern approach to solving text-based multi-label classification tasks is to leverage large language models (LLMs). In a zero-shot setting, you can simply describe the target labels and let the model generate predictions without any examples. While this is convenient, adding a few carefully selected examples — known as <strong>few-shot prompting</strong> — can significantly improve accuracy.</p><p>Few-shot prompting is generally much more effective than zero-shot, especially for nuanced or domain-specific labels. However, it introduces a new challenge: <strong>how do you choose the most helpful examples?</strong> This is where <strong>adaptive prompting</strong> comes in. By dynamically selecting examples based on model performance, adaptive prompting refines the prompt over time to improve results.</p><p>This article explores the core ideas behind adaptive prompting and how it can be used to boost performance in multi-label classification tasks.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ra-tR421u1oZvy_-YQunrQ.png" /></figure><p>At the core of our task is the challenge of assigning meaningful labels to customer-manager dialogs in order to evaluate the quality and structure of those conversations. Each dialog can contain multiple relevant actions or intentions — such as greeting the customer, confirming an appointment, or handling objections — which we aim to detect and tag. This setup naturally falls under the category of <strong>multi-label classification</strong>, where a single text sample (a dialog) can be associated with <strong>multiple labels</strong> simultaneously. In our case, we’re working with a predefined set of up to <strong>20 distinct labels</strong>, covering the key steps and checkpoints in a high-quality client interaction.</p><ul><li><strong>0:</strong> Greeting by name: “name, good afternoon!…”</li><li><strong>1:</strong> Performance: “my name is …, ballet and…”</li><li><strong>2:</strong> Confirmation of application: “you left us an application…”</li><li>…</li><li><strong>19:</strong> Did the client have any objections?</li><li><strong>20:</strong> The manager tried to work through the objections</li></ul><p>My first idea was to apply an <strong>agentic Retrieval-Augmented Generation (RAG)</strong> pattern to automate multi-label dialog evaluation (look at the picture above). The goal was to streamline the process into a clear, modular pipeline. I simplified the architecture by removing the feedback loop and its complexities, resulting in a linear, top-down flow with four key components:</p><ol><li><strong>Knowledge base index</strong> — a structured repository of labeled dialogs and metadata.</li><li><strong>Few-Shot example generation</strong> — an agent retrieves relevant samples using RAG and query rewriting to construct few-shot prompts tailored to each label.</li><li><strong>Evaluation</strong> — the agent uses those prompts to score new dialogs via LLM-based evaluation.</li><li><strong>Targeted improvement</strong> — the system identifies the next label to refine, enabling focused and measurable prompt optimization.</li></ol><p>This structure laid the groundwork for a dynamic, label-aware prompting system without relying on manual data curation or retraining.</p><p>To support this workflow, I implemented a <strong>FastAPI service</strong> that exposes the necessary endpoints for managing data, generating prompts, evaluating dialogs, and iterating through the optimization loop. This API acts as the core toolset for my agent, allowing seamless integration of scoring logic, prompt updates, and evaluation results in a modular and extensible way.</p><p>So, agent can initiate the prompt optimization by calling the scoring endpoint, updating the prompt based on returned scores, and repeating the evaluation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pw8dvntsN0nTR4dJJLwC_A.png" /></figure><p>As I explored the agentic RAG pattern, I quickly realized it introduced unnecessary complexity for what is essentially a structured scoring task. Instead, I pivoted to a simpler, more effective approach: <strong>few-shot prompt optimization</strong>. Here’s how it works:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hP13tb3csX_MaH9Z6uk91w.png" /></figure><p>The whole system looks like</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-nk_FAmK9wjSe8ZjKmvCEw.jpeg" /></figure><p>The core prompt is presented below.:</p><pre>You are an analytical system evaluating the dialogue between a manager and a customer based on predefined criteria.<br>Your task is to check which items from the list are present in the dialogue.<br><br>Instructions:<br>Analyze the dialogue and determine which of the specified items are present in it.<br><br>The available points for recognition are listed below, each point is numbered and enclosed in the symbols &lt; ... &gt;<br><br>${points_table}<br><br>If the manager&#39;s phrase matches one of the points, add it to the result.<br><br>${few_shots}<br><br>Ignore the customer&#39;s phrasing — evaluate only the manager&#39;s replies.<br><br>The answer must be a JSON object containing only the present items in the form of an array.<br><br>Evaluate the dialogue strictly according to the points. Do not add any extra information in the response.<br><br>Output object format:<br><br>{{&quot;scores&quot;: [&quot;&lt;1&gt;&quot;, &quot;&lt;5&gt;&quot;]}}</pre><p>After first iteration we initial errors distribution</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0Z4LKPZY9CnJ5tuD531jEw.png" /></figure><p>Once the iterations were completed, the error rate dropped significantly.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*amON4t9yJuwGnbGS5a9WcA.png" /></figure><p><strong>Note</strong>: The label <em>&lt;clarification of the address&gt;</em> shows the highest error rate. To address this, we can add a final iteration to the pipeline that merges the most successful prompts.</p><h3>Conclusion</h3><p>In the schema above, I still use a large language model (LLM) for generating few-shot examples, but all other steps are deterministic. This approach minimizes token usage during the agentic iteration, which not only reduces costs but also makes the entire process more transparent. By leveraging deterministic methods for most of the workflow, we can enhance control and predictability, allowing for a more efficient and streamlined process overall.</p><p>Manual few-shot prompting works well only in small, static contexts. <strong>Dynamic few-shot prompting</strong> offers:</p><ul><li><strong>Automated prompt curation</strong></li><li><strong>Label-specific improvements</strong></li><li><strong>Continuous learning without retraining</strong></li></ul><p>The whole pipeline presinted below</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dFkfvZkv7tOgCS0YQ2y0Vw.jpeg" /></figure><p>This approach ensures the few-shot prompt is <strong>task-specific and grounded in real data</strong>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2b3da7e08239" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Efficient inventory management in retail: ABC-XYZ approach using python and Polars.]]></title>
            <link>https://medium.com/@alexandrdzhumurat/efficient-inventory-management-in-retail-abc-xyz-approach-using-python-and-polars-c47ca74fc721?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/c47ca74fc721</guid>
            <category><![CDATA[forecasting]]></category>
            <category><![CDATA[retail]]></category>
            <category><![CDATA[polars-dataframe]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Sat, 15 Mar 2025 07:38:45 GMT</pubDate>
            <atom:updated>2025-03-15T08:54:48.605Z</atom:updated>
            <content:encoded><![CDATA[<p>Effective inventory management is crucial for retail businesses to prevent stockouts, minimize overstocking, and optimize cash flow. Enter <a href="https://pola.rs/"><strong>polars</strong></a>, a high-performance DataFrame library for Python, designed for speed and scalability. The focus of this article is to demonstrate how Polars can advance inventory management by implementing end-to-end inventory stock forecasting based on ABC-XYZ analysis..</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*barVfd5ny-UgSdT8TQQSYw.png" /><figcaption>selled QTy</figcaption></figure><h3>What inventory management?</h3><p>Inventory management in e-commerce is the process of tracking, storing, and replenishing products to ensure optimal stock levels while minimizing costs and inefficiencies. Unlike traditional retail, e-commerce businesses must handle dynamic demand fluctuations, multi-channel sales, and rapid fulfillment expectations.</p><p>The chart at the top of this post illustrates daily sales figures for specific product category. Our aim is to estimate the amount of products we should order from suppliers to fulfill the demand for the next one month.</p><p>The algorithm should include the following steps</p><ol><li><strong>Demand Fforecasting</strong>: the system will use historical sales data to forecast future demand, allowing stock levels to be adjusted in advance to avoid shortages or overstock.</li><li><strong>Stock prioritization for purchase orders</strong>: based on sales velocity, the system will prioritize high-demand products for the next purchase order, ensuring popular items are always in stock.</li><li><strong>Safety stock calculation</strong>: to mitigate the risk of sudden demand spikes, the system will calculate an appropriate safety stock level, providing a buffer that keeps products available during unforeseen demand fluctuations.</li><li><strong>Lead time calculation</strong>: the system will account for supplier lead times, ensuring that orders are placed well in advance so stock arrives before current levels are depleted.</li></ol><h3>Step 1: <strong>Demand Forecasting</strong></h3><p>Let’s walk through a simple example where we analyze product stock levels and identify items that need restocking.</p><p>Our prediction will be based on a basic formula:</p><p>(<em>average daily sales)</em> x <em>the (total number of days in the upcoming period)</em></p><p><em>average daily sales </em>is evaluating based on previous periods</p><p>Do not forget to clear your data (I used simple quantiles-based approach)</p><pre>def prepare_forecast_features(input_df, group_keys, target_col=&#39;Qty&#39;):<br>  forecast_features_df = input_df.group_by(group_keys).agg([<br>      pl.col(target_col).sum().alias(&#39;total_sales&#39;),<br>      pl.n_unique(&#39;dt&#39;).alias(&#39;num_days&#39;),<br>      pl.col(target_col).std().alias(&#39;std&#39;),<br>      pl.col(target_col).quantile(0.05).alias(&#39;q05&#39;),<br>      pl.col(target_col).quantile(0.95).alias(&#39;q90&#39;)<br>  ]).with_columns([<br>      (pl.col(&#39;total_sales&#39;) / pl.col(&#39;num_days&#39;)).alias(&#39;sales_per_day&#39;)<br>  ]).sort(&#39;total_sales&#39;, descending=True)<br>  return forecast_features_df<br><br>def adjust_sales(sales_df, train_period_sales_agg, group_keys):<br>    res = (<br>        sales_df<br>        .join(train_period_sales_agg, on=group_keys)<br>        .with_columns(<br>            pl.when(pl.col(&#39;Qty&#39;) &lt; pl.col(&#39;q05&#39;)).then(pl.col(&#39;q05&#39;))<br>              .when(pl.col(&#39;Qty&#39;) &gt; pl.col(&#39;q90&#39;)).then(pl.col(&#39;q90&#39;))<br>              .otherwise(pl.col(&#39;Qty&#39;))<br>          .alias(&#39;Qty_adjusted&#39;)<br>        )<br>    )<br>    return res</pre><h3>Step 2: s<strong>tock prioritization for purchase orders</strong></h3><p>ABC-XYZ analysis is a powerful inventory management technique that helps businesses prioritize products for reordering based on their value (ABC) and demand variability (XYZ). Combining these two methods ensures that high-value, consistently selling items are always in stock while optimizing inventory levels for less predictable products.</p><p>ABC classification (value-based segmentation) categorizes products based on their contribution to revenue or profit:</p><ul><li><strong>A-Class (High Value, Low Quantity)</strong>: Top 20% of products generating 80% of revenue. These require close monitoring and frequent reordering.</li><li><strong>B-Class (Moderate Value, Moderate Quantity)</strong>: Mid-tier products contributing to 15% of revenue. Reordering is done periodically.</li><li><strong>C-Class (Low Value, High Quantity)</strong>: The bottom 50% of products contributing only 5% of revenue. These have lower priority and can be stocked in bulk.</li></ul><p>XYZ classification (demand variability segmentation) categorizes items based on demand predictability:</p><ul><li><strong>X-Class (Stable Demand)</strong>: Products with consistent sales patterns, making them easy to forecast and reorder with confidence.</li><li><strong>Y-Class (Moderate Variability)</strong>: Items with some demand fluctuations, often seasonal, requiring flexible restocking strategies.</li><li><strong>Z-Class (High Variability)</strong>: Products with unpredictable sales, making them riskier to keep in stock without demand-driven triggers.</li></ul><h4>Reorder strategy using ABC-XYZ</h4><p>By combining ABC and XYZ analysis, businesses can create tailored reorder strategies:</p><ul><li><strong>A-X Products</strong> (High Value, Stable Demand) → <strong>Frequent automated reordering</strong> to ensure constant availability.</li><li><strong>B-Y Products</strong> (Moderate Value, Seasonal Demand) → <strong>Flexible reordering based on sales trends</strong> to prevent excess stock.</li><li><strong>C-Z Products</strong> (Low Value, Unpredictable Demand) → <strong>Minimal stocking or on-demand purchasing</strong> to reduce inventory costs.</li></ul><p>Implementing ABC-XYZ analysis helps businesses optimize stock levels, reduce inventory holding costs, and improve service levels by ensuring the right products are available at the right time.</p><pre>def abc_xyz_analysis(df, value_col, date_col, item_col):<br>    &quot;&quot;&quot;<br>    Perform ABC-XYZ analysis on product data using Polars.<br>    <br>    Parameters:<br>    df (pl.DataFrame): Polars DataFrame containing sales data<br>    value_col (str): Column name containing the value metric (revenue, quantity, etc.)<br>    date_col (str): Column name containing the date<br>    item_col (str): Column name containing the product/item identifier<br>    <br>    Returns:<br>    Tuple: (result DataFrame with classifications, classification summary DataFrame)<br>    &quot;&quot;&quot;<br>    product_totals = df.group_by(item_col).agg(<br>        pl.col(value_col).sum().alias(&#39;total_value&#39;)<br>    ).sort(&#39;total_value&#39;, descending=True)<br>    total_sum = product_totals.select(pl.sum(&#39;total_value&#39;)).item()<br>    product_totals = product_totals.with_columns([<br>        (pl.col(&#39;total_value&#39;) / total_sum).alias(&#39;value_pct&#39;)<br>    ])<br>    product_totals = product_totals.with_columns(<br>        pl.col(&#39;value_pct&#39;).cum_sum().alias(&#39;cumulative_pct&#39;)<br>    )<br>    product_totals = product_totals.with_columns(<br>        pl.when(pl.col(&#39;cumulative_pct&#39;) &lt;= 0.20).then(pl.lit(&#39;A&#39;))<br>        .when(pl.col(&#39;cumulative_pct&#39;) &lt;= 0.80).then(pl.lit(&#39;B&#39;))<br>        .otherwise(pl.lit(&#39;C&#39;))<br>        .alias(&#39;ABC_class&#39;)<br>    )<br>    time_series = df.with_columns(<br>        pl.col(date_col).dt.truncate(&#39;1mo&#39;).alias(&#39;month&#39;)<br>    ).group_by([&#39;month&#39;, item_col]).agg(<br>        pl.col(value_col).sum().alias(value_col)<br>    )<br>    cv_df = time_series.group_by(item_col).agg([<br>        pl.col(value_col).mean().alias(&#39;mean&#39;),<br>        pl.col(value_col).std().alias(&#39;std&#39;)<br>    ])<br>    cv_df = cv_df.with_columns(<br>        (pl.col(&#39;std&#39;) / pl.col(&#39;mean&#39;)).fill_null(0).alias(&#39;cv&#39;)<br>    )<br>    q1 = cv_df[&#39;cv&#39;].quantile(0.20)<br>    q2 = cv_df[&#39;cv&#39;].quantile(0.60)<br><br>    cv_df = cv_df.with_columns(<br>        pl.when(pl.col(&#39;cv&#39;) &lt;= q1).then(pl.lit(&#39;X&#39;))<br>        .when(pl.col(&#39;cv&#39;) &lt;= q2).then(pl.lit(&#39;Y&#39;))<br>        .otherwise(pl.lit(&#39;Z&#39;))<br>        .alias(&#39;XYZ_class&#39;)<br>    )<br>    abc_xyz = product_totals.join(<br>        cv_df.select([item_col, &#39;cv&#39;, &#39;XYZ_class&#39;]), <br>        on=item_col<br>    )<br>    abc_xyz = (<br>        abc_xyz.with_columns(<br>          (pl.col(&#39;ABC_class&#39;) +&#39;/&#39; + pl.col(&#39;XYZ_class&#39;)).alias(&#39;ABC_XYZ&#39;)<br>        )<br>        .with_columns(pl.col(&#39;ABC_XYZ&#39;).replace(priority_map, default=10).alias(&#39;priority_score&#39;))<br>    )<br>    return abc_xyz</pre><p>When applying the <strong>ABC-XYZ</strong> analysis for reordering, it’s crucial to segment items <strong>within the same category</strong> rather than applying the algorithm across the entire sales table. This is because <strong>consumer purchasing patterns vary significantly between different product categories</strong>.</p><p>Almost done! Finally, we need to <strong>filter out low-priority items</strong> and focus on <strong>top-priority items within each category</strong>. This ensures that inventory management efforts are directed toward high-impact products while minimizing excess stock.</p><pre>classification_filtered_df = classification_df.filter(~pl.col(&#39;priority_score&#39;).is_in(excluded_categories))<br>reorder_df = None<br>for param_set in params:<br>  category_df = (<br>      filter_sales_by_params(forecast_using_adjusted_features_df, sort=None, **param_set)<br>      .select(group_keys + [&#39;avg_unique_products&#39;, &#39;reorder_qty&#39;])<br>      .join(products_shares_df.select(group_keys+[&#39;ProductFullName&#39;, &#39;product_share&#39;]), on=group_keys)<br>      .join(classification_filtered_df.select([&#39;ProductFullName&#39;,&#39;priority_score&#39;]), on=&#39;ProductFullName&#39;)<br>      .sort(&#39;product_share&#39;, descending=True)<br>  )<br>  if category_df.height &gt; 0:<br>    if reorder_df is None:<br>      reorder_df = prepare_reorder(category_df)<br>    else:<br>      reorder_df = pl.concat([reorder_df, prepare_reorder(category_df)], how=&quot;vertical&quot;)</pre><h3>Step 3: forecast quality</h3><p>Almost done! Just add a quality check to ensure the algorithm performs well in real-world scenarios.</p><p>We use hold-out control to validate our forecast.</p><pre>def category_forecast(input_df, test_df, keys):<br>  test_period_df = (<br>      test_df.group_by(keys)<br>      .agg(pl.col(&#39;Qty&#39;).sum())<br>      .sort(by=&#39;Qty&#39;, descending=True)<br>  )<br>  forecast_df = (<br>      input_df<br>      .select(group_keys + [&#39;reorder_qty&#39;])<br>      .group_by(keys)<br>      .agg(pl.col(&#39;reorder_qty&#39;).sum())<br>      .sort(by=&#39;reorder_qty&#39;, descending=True)<br>      .join(test_period_df, on=keys)<br>      .with_columns([<br>          ((pl.col(&#39;Qty&#39;) - pl.col(&#39;reorder_qty&#39;)) / pl.col(&#39;Qty&#39;)).alias(&#39;forecast_error&#39;)<br>      ])<br>      .sort(&#39;reorder_qty&#39;, descending=True)<br>  )<br>  return forecast_df</pre><p>By doing this, you will avoid providing incorrect forecasts to your clients.</p><h3>Conclusion</h3><p>In the real world, inventory management isn’t just about categorizing items — it’s about ensuring your algorithm performs well over time. To make your <strong>ABC-XYZ analysis</strong> more robust, you should:</p><p><strong>Measure Algorithm Quality</strong></p><ul><li>Track metrics like <strong>stockout rates</strong>, <strong>service levels</strong>, and <strong>forecast accuracy</strong> to evaluate performance.</li><li>Use historical data to compare predicted reorder points with actual demand.</li></ul><p><strong>Incorporate Real-World Adjustments:</strong><br> To handle uncertainties, apply these adjustments to your reorder calculations:</p><ul><li><strong>Safety Stock:</strong> Add buffer stock to cover unexpected demand spikes.</li><li><strong>Lead Time Adjustment:</strong> Account for supplier delivery times by placing orders earlier.</li><li><strong>Demand Variability Correction:</strong> Adjust reorder quantities based on past forecast errors (e.g., Mean Absolute Percentage Error — MAPE).</li></ul><ol><li><strong>Continuous Improvement:</strong></li></ol><ul><li>Regularly <strong>re-evaluate and update parameters</strong> to adapt to changes in consumer behavior or supply chain conditions.</li><li>Consider using <strong>feedback loops</strong> to fine-tune the model over time.</li></ul><p>By <strong>measuring performance</strong> and <strong>integrating real-world adjustments</strong>, you’ll build a system that balances accuracy with resilience,</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c47ca74fc721" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Agentic workflow: I crafted the GoogleMapTool for the SmolAgents library by HuggingFace]]></title>
            <link>https://medium.com/@alexandrdzhumurat/agentic-workflow-i-crafted-the-googlemaptool-for-the-smolagents-library-by-huggingface-6a45e1d37462?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/6a45e1d37462</guid>
            <category><![CDATA[agents]]></category>
            <category><![CDATA[hugging-face]]></category>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Tue, 04 Mar 2025 09:58:35 GMT</pubDate>
            <atom:updated>2025-03-04T09:58:35.374Z</atom:updated>
            <content:encoded><![CDATA[<p>Agents are everywhere! It is a new part of the AI puzzle. When HuggingFace released their new Agent Framework I was very exited to try it.</p><p>I have desided to revisit the app I built a year ago (pls access <a href="https://medium.com/@alexandrdzhumurat/another-one-ai-assistant-gpt-based-schedule-generator-d072feb892d6">this article</a> for a recap) and re-charge it with the <a href="https://smolagents.org/">SmolAgents</a> library. Consequently, I developed two useful tools for city exploration utilizing the Google Maps API. Let’s dive into code!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*es_plkaNmgRVq8VZ" /></figure><p>To begin with: smollagents are fantastic! Please begin by exploring the <a href="https://smolagents.org/docs/agents-guided-tour/">guided tour</a> they have prepared.</p><p>The key concept is to assign LLM the task of writing code to solve a specific problem. Let’s choose an LLM, supply a set of well-documented Python classes under the name Tools, and set a clear objective. Then LLM run a continuous cycle of: <strong>thinking (Thought) → acting (Act) and observing (Observe)</strong>.</p><ol><li><strong>Thought</strong>: The LLM part of the Agent decides what the next step should be.</li><li><strong>Action:</strong> The agent takes an action, by calling the tools with the associated arguments.</li><li><strong>Observation:</strong> The model reflects on the response from the tool.</li></ol><p>My intention was to discover Michelin restaurants in Belgrade that have late closing times. While the SmolAgents library has a useful <a href="https://huggingface.co/docs/smolagents/v1.9.2/en/reference/tools#smolagents.GoogleSearchTool">GoogleSearchTool</a>, it does not meet my requirements. Therefore, I crafted two new tools: one for exploring Google Maps and another for extracting opening hours using Google map API. Let’s explore tool for extracting opening hours using the Google Maps API.</p><pre>import os<br>import requests<br>from typing import Dict, Any, List, Optional, Tuple<br><br>from smolagents import tool<br><br><br>@tool<br>def get_place_working_hours(place_id: str) -&gt; dict:<br>    &quot;&quot;&quot;<br>    Fetches working hours for a place using the Google Places API.<br>    <br>    This function retrieves information about opening hours and closing hours and return a dict with fields: <br>            - open_time (str): Opening time in 24-hour format (e.g., &#39;0900&#39;)<br>            - close_time (str): Closing time in 24-hour format (e.g., &#39;1700&#39;)<br>    <br>    Args:<br>        place_id: The Google Place ID for the location you want information about<br>    <br>    Returns:<br>        dict: A dictionary containing the place&#39;s operating hours with the keys:<br>            - open_time (str): Opening time in 24-hour format (e.g., &#39;0900&#39;)<br>            - close_time (str): Closing time in 24-hour format (e.g., &#39;1700&#39;)<br>            <br>    Example:<br>        &gt;&gt;&gt; result = get_place_working_hours(place_id=&quot;ChIJj61dQgK6j4AR4GeTYWZsKWw&quot;)<br>        &gt;&gt;&gt; print(result)<br>        {&#39;open_time&#39;: &#39;0900&#39;, &#39;close_time&#39;: &#39;1700&#39;}<br>    &quot;&quot;&quot;<br>    google_api_key = os.environ[&#39;GOOGLE_API_KEY&#39;]<br>    fields=&#39;name,url,opening_hours&#39;<br>    print(fields)<br>    params = {<br>        &quot;place_id&quot;: place_id,<br>        &quot;fields&quot;: fields,<br>        &quot;key&quot;: google_api_key<br>    }<br>    url = f&quot;https://maps.googleapis.com/maps/api/place/details/json&quot;<br>    headers = {}<br>    response = requests.get(url, params=params, headers=headers).json()<br>    hours = response[&#39;result&#39;][&#39;opening_hours&#39;][&#39;periods&#39;][0]<br>    res = {&#39;open_time&#39;: hours[&#39;open&#39;][&#39;time&#39;], &#39;close_time&#39;: hours[&#39;close&#39;][&#39;time&#39;]}<br>    return res</pre><p>You might notice that the docstring is considerably longer than the function body. Writing detailed documentation is essential when building a tool for Smolagents because basically LLM parses source code to grasp how to invoke Python functions and what outcome is expected.</p><p>Next, create an agent and execute it. Write the output to a text file to access the pipeline result after the code has finished.</p><pre>    adress_tool = GooglePlacesTool(api_key=api_key)<br>    agent = CodeAgent(<br>        tools=[adress_tool, get_place_working_hours],<br>        model=openai_model,<br>        additional_authorized_imports=[<br>            &quot;json&quot;,<br>        ],<br>    )<br>    result = agent.run(<br>        &quot;&quot;&quot;List of Michelin restaurants in Belgrade with lnks and working hours and adresses<br><br>        Use adress_tool tool to get a restaurants list<br><br>        Once you have a list of restaurants, utilize the get_place_working_hours tool to retrieve working hours by passing the place ID in the tool one by one.<br>        <br>        After identifying a restaurant with the latest closing time, print only this specific restaurant.<br>        &quot;&quot;&quot;<br>    )<br>    with open(&#39;output.txt&#39;, &#39;w&#39;, encoding=&#39;utf8&#39;) as f:<br>        f.write(result)</pre><p>After the pipeline was completed, I was delighted to observe the response.</p><pre>The restaurant in Belgrade with the latest closing time among the Michelin restaurants<br>is &#39;Bela Reka Restaurant&#39; with a closing time of 23:45.</pre><p>Conclusion</p><ul><li>exploring agents can feel like encountering magic until you grasp the underlying mechanics.</li><li>when trying to build a pipeline yourself, ensure you write well-documented code.</li><li>having a clear understanding of the algorithm to address your problem is key to defining a toolset for agents.</li></ul><p>BONUS: review the repository containing implemented tools <a href="https://github.com/aleksandr-dzhumurat/smol-google-tools">https://github.com/aleksandr-dzhumurat/smol-google-tools</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6a45e1d37462" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to use notion as a database for telegram-bot]]></title>
            <link>https://medium.com/@alexandrdzhumurat/how-to-use-notion-as-a-database-for-telegram-bot-151acafb0445?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/151acafb0445</guid>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Sat, 18 Jan 2025 17:56:23 GMT</pubDate>
            <atom:updated>2025-01-18T18:05:40.568Z</atom:updated>
            <content:encoded><![CDATA[<p>If you’ve ever wondered how to use Notion as a database and leverage its simplicity for dynamic content management, this guide is for you. One of the great perks of Notion is that you can publish a Notion page as a website, making it a powerful yet straightforward tool for your projects.</p><p>Start by creating a new database in Notion. You can choose the table format for structured data organization. This will act as the backbone of your “database” and store the rows of information you want to manage.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/921/1*o5RSoRNfTO66Go4CywzeWg.png" /></figure><p>To programmatically interact with your Notion database, you’ll need an integration token. Follow these steps:</p><ol><li>Go to <a href="https://www.notion.so/my-integrations">Notion Integrations</a> and create a new integration.</li><li>Name your integration and specify the workspace it will access.</li><li>Once the integration is set up, <strong>copy the token</strong> provided at the final step. Keep it secure as this token allows your application to interact with your Notion workspace.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/669/1*KHrU6lYNZ2T25GBdkrexYw.png" /></figure><p>For the integration to have access to your database, you need to invite it:</p><ol><li>Open the database you created in Step 1.</li><li>Click the “+ Share” button in the top-right corner.</li><li>Search for your integration’s name and invite it with the appropriate permissions (usually “Can Edit”).</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QHPEtDrYazyMbKxc-m_6zA.png" /></figure><p>Here’s how you can use the token and Notion API to programmatically add rows to your table. Below is a Python example:</p><pre>import requests<br>import json<br>NOTION_TOKEN = &quot;your-integration-token&quot;  # Replace with your token<br>DATABASE_ID = &quot;your-database-id&quot;         # Replace with your database ID<br>url = f&quot;https://api.notion.com/v1/pages&quot;<br>headers = {<br>    &quot;Authorization&quot;: f&quot;Bearer {NOTION_TOKEN}&quot;,<br>    &quot;Content-Type&quot;: &quot;application/json&quot;,<br>    &quot;Notion-Version&quot;: &quot;2022-06-28&quot;<br>}<br>def add_row(properties):<br>    payload = {<br>        &quot;parent&quot;: {&quot;database_id&quot;: DATABASE_ID},<br>        &quot;properties&quot;: properties<br>    }<br>    response = requests.post(url, headers=headers, json=payload)<br>    if response.status_code == 200:<br>        print(&quot;Row added successfully!&quot;, response.json())<br>    else:<br>        print(f&quot;Failed to add row: {response.status_code} - {response.text}&quot;)<br># Example row (replace with your actual property structure)<br>properties = {<br>    &quot;Name&quot;: {<br>        &quot;title&quot;: [<br>            {&quot;text&quot;: {&quot;content&quot;: &quot;Sample Entry&quot;}}<br>        ]<br>    },<br>    &quot;Description&quot;: {<br>        &quot;rich_text&quot;: [<br>            {&quot;text&quot;: {&quot;content&quot;: &quot;This is a sample description&quot;}}<br>        ]<br>    }<br>}<br>add_row(properties)</pre><p>The properties object in the example above represents a JSON-formatted row for your database table. Each key corresponds to a column name in your Notion database, and the value defines the content for that column.</p><p>For instance:</p><ul><li>A “Name” column might expect a title type.</li><li>A “Description” column might expect a rich_text type.</li><li>Additional columns can include dates, URLs, numbers, and more, depending on your table structure.</li></ul><pre>{<br>    &quot;descr&quot;: {<br>        &quot;title&quot;: [<br>            {<br>                &quot;text&quot;: {<br>                    &quot;content&quot;: &quot;${title}&quot;<br>                }<br>            }<br>        ]<br>    },<br>    &quot;URL&quot;: {<br>        &quot;url&quot;: &quot;${url}&quot;<br>    },<br>    &quot;date&quot;: {<br>        &quot;date&quot;: {<br>            &quot;start&quot;: &quot;${date_start}&quot;<br>        }<br>    }<br>}</pre><h3>Final Thoughts</h3><p>With these steps, you’ve turned Notion into a powerful database and learned how to automate updates to it using code. The ability to publish a Notion page as a website makes this approach particularly useful for dynamic content management or lightweight web applications. Happy coding!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=151acafb0445" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a metrics tree with Python and Polars]]></title>
            <link>https://medium.com/@alexandrdzhumurat/building-a-metrics-tree-with-python-and-polars-4b690d63494b?source=rss-7eae5e3bc0f3------2</link>
            <guid isPermaLink="false">https://medium.com/p/4b690d63494b</guid>
            <category><![CDATA[python-polars]]></category>
            <category><![CDATA[metrics-and-analytics]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[e-commerce-business]]></category>
            <dc:creator><![CDATA[Alexandr  Dzhumurat]]></dc:creator>
            <pubDate>Sun, 17 Nov 2024 06:25:51 GMT</pubDate>
            <atom:updated>2024-11-17T06:25:51.307Z</atom:updated>
            <content:encoded><![CDATA[<p>In e-commerce, particularly in food delivery, a <strong>metrics tree</strong> is a structured breakdown of key business metrics that help track performance and identify areas for improvement. It starts with high-level business outcomes and branches into detailed, actionable metrics. The goal of the metrics tree is to establish a clear relationship between different metrics to ensure the company can monitor and optimize each level effectively.</p><p>We’ll explore how to build a metrics tree using Python and Polars. By the end, we’ll also discuss potential applications of a metrics tree in real-world scenarios. Let’s get started!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*q99vfyv0XpJDcWPlXI1PWw.png" /></figure><p>As an example, here’s how a metrics tree could be structured for the food delivery industry</p><pre>Metrics Tree<br>├── Revenue<br>│   ├── Number of Orders<br>│   │   ├── Total Active Users<br>│   │   ├── New Users<br>│   │   └── Returning Users<br>│   ├── Order Frequency<br>│   │   ├── Repeat Purchase Rate<br>│   │   └── Customer Retention Rate<br>│   ├── Average Order Value (AOV)<br>│   │   ├── Basket Size<br>│   │   ├── Price per Item<br>│   │   └── Discounts Applied<br>├── Customer Acquisition<br>│   ├── Customer Acquisition Cost (CAC)<br>│   ├── Marketing Spend per Channel<br>│   ├── Cost per Install/Registration<br>│   ├── Conversion Rate<br>│   │   ├── Visitors to Registrations<br>│   │   └── Registrations to First Order</pre><p>Feel free to add more nodes:</p><ul><li><strong>Customer Retention (</strong>Repeat Purchase Rate, Churn Rate, Lifetime Value<strong>)</strong></li><li><strong>Delivery Performance (</strong>On-time Delivery Rate Delevery Time)</li><li><strong>Operational Efficiency (</strong>Order Fulfillment Time, Delivery Partner Efficiency, Cost per Delivery)</li><li><strong>Customer Satisfaction (</strong>Customer Ratings, Customer Support Tickets, Net Promoter Score (NPS))</li></ul><p>But how how a metrics tree is useful?</p><ul><li><strong>Tracking Key Drivers:</strong> It helps break down high-level outcomes (like revenue) into actionable sub-metrics (e.g., order frequency, basket size).</li><li><strong>Identifying Issues:</strong> If revenue drops, the tree helps quickly identify whether it’s due to fewer orders, a drop in average order value, or customer churn.</li><li><strong>Optimization:</strong> Businesses can use the tree to focus on improving specific metrics, like increasing order frequency or improving delivery times, which leads to better overall performance.</li></ul><p>By visualizing how different elements contribute to the overall business performance, a metrics tree allows food delivery businesses to make data-driven decisions and optimize operations.</p><h3>Idea for Metrics Tree: Alerting and Root Cause Analysis</h3><h4>Idea #1: Implement Alerting for Changes in Metrics Level</h4><ul><li><strong>Set Thresholds</strong>: Define acceptable ranges or thresholds for each key metric in the metrics tree (e.g., sales, customer acquisition cost, churn rate).</li><li><strong>Automate Monitoring</strong>: Use a monitoring system (like Prometheus, Grafana, or a custom solution) to continuously track these metrics.</li><li><strong>Trigger Alerts</strong>: Set up alerts that notify stakeholders (via email, Slack, or SMS) whenever a metric exceeds or falls below the defined threshold. This can be done using:</li><li><strong>Static Alerts</strong>: Fixed thresholds (e.g., alert if daily sales drop below $10,000).</li><li><strong>Dynamic Alerts</strong>: Alerts based on historical data and trends (e.g., alert if sales decrease by more than 20% compared to the previous week).</li></ul><p>Below is an example Python code snippet to help you evaluate a metrics tree using</p><pre>import datetime<br><br>from_dt = &#39;2024-08-31&#39;<br><br>metrics_tree_df = (<br>    baskets_df<br>    .filter(pl.col(&#39;weekstart&#39;) &gt; datetime.datetime.strptime(from_dt, &#39;%Y-%m-%d&#39;))<br>    .group_by(&#39;weekstart&#39;)<br>    .agg([<br>        pl.col(&#39;CustomerID&#39;).count().alias(&#39;num_purchases&#39;),<br>        pl.col(&#39;CustomerID&#39;).n_unique().alias(&#39;num_unique_customers&#39;),<br>        pl.col(&quot;NetSales&quot;).sum().alias(&quot;net_sales&quot;),<br>        pl.col(&#39;first_order_NetSales&#39;).sum().alias(&#39;1st_order_net_sales&#39;),<br>        (<br>            pl.when(pl.col(&#39;order_rank&#39;) == 2)<br>                .then(pl.col(&#39;NetSales&#39;))<br>                .otherwise(0)<br>        ).sum().alias(&#39;2nd_order_net_sales&#39;),<br>        (<br>            pl.when(pl.col(&#39;order_rank&#39;) == 2)<br>                .then(pl.col(&#39;days_after_last_order&#39;))<br>                .otherwise(0)<br>        ).mean().alias(&#39;2nd_order_days&#39;),<br>        (<br>            pl.when((pl.col(&#39;order_rank&#39;) &gt; 2) &amp; (pl.col(&#39;order_rank&#39;) &lt;= 5))<br>                .then(pl.col(&#39;NetSales&#39;))<br>                .otherwise(0)<br>        ).sum().alias(&#39;3_5_orders_net_sales&#39;),<br>        (<br>            pl.when(pl.col(&#39;order_rank&#39;) &gt; 5)<br>                .then(pl.col(&#39;NetSales&#39;))<br>                .otherwise(0)<br>        ).sum().alias(&#39;over_5_order_net_sales&#39;)<br>    ])<br>    .with_columns([<br>        (pl.col(&#39;1st_order_net_sales&#39;) / pl.col(&quot;net_sales&quot;)).alias(&#39;first_orders_share&#39;),<br>        (pl.col(&#39;2nd_order_net_sales&#39;) / pl.col(&quot;1st_order_net_sales&quot;)).alias(&#39;2nd_order_uplift&#39;),<br>        (pl.col(&#39;net_sales&#39;) / pl.col(&quot;num_purchases&quot;)).alias(&#39;aov&#39;),<br>        (pl.col(&#39;net_sales&#39;) / pl.col(&quot;num_unique_customers&quot;)).alias(&#39;net_sales_per_unique&#39;),<br>    ])<br>    .sort([&#39;weekstart&#39;])<br>)</pre><h4>Idea #2: Finding the Root Cause of Metric Changes</h4><p><strong>Link Metrics in the Tree</strong>: utilize the structure of the metrics tree to identify relationships between metrics. For example:</p><ul><li>If sales drop, look at conversion rates, average order values, and customer traffic.</li><li>If customer churn increases, analyze customer satisfaction scores, support ticket volumes, and product return rates.</li></ul><p><strong>Drill Down Analysis</strong>: Create a process to drill down into affected metrics. This could include:</p><ul><li><strong>Filtering</strong>: Break down metrics by segments (e.g., by product category, geographical location, or customer segment) to see where changes are most significant.</li><li><strong>Time Series Analysis</strong>: Analyze the trend over time to identify patterns or anomalies preceding the change.</li></ul><p><strong>Use Correlation Analysis</strong>: Apply statistical methods to find correlations between metrics to uncover potential root causes. For example:</p><ul><li>If there’s a significant drop in customer engagement, correlate it with marketing spend or promotional activities.</li></ul><p><strong>Feedback Loop</strong>: Incorporate feedback from customer support or sales teams to understand contextual factors that might not be evident from the metrics alone.</p><p>In next articles we will implement alerting rules above in Python, stay tuned!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4b690d63494b" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>