<?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 DanShw on Medium]]></title>
        <description><![CDATA[Stories by DanShw on Medium]]></description>
        <link>https://medium.com/@kofsitho?source=rss-14df520bbc24------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*LBrVbY5TZgsGthCl.jpg</url>
            <title>Stories by DanShw on Medium</title>
            <link>https://medium.com/@kofsitho?source=rss-14df520bbc24------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 19:34:55 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@kofsitho/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[How We Built an AI That Answers Hospital Phone Calls]]></title>
            <link>https://medium.com/@kofsitho/how-we-built-an-ai-that-answers-hospital-phone-calls-933b489fc29b?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/933b489fc29b</guid>
            <category><![CDATA[livekit]]></category>
            <category><![CDATA[voice-ai]]></category>
            <category><![CDATA[ai-voice-agent]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Fri, 07 Aug 2026 00:00:34 GMT</pubDate>
            <atom:updated>2026-08-07T03:14:05.851Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fXc9UQko8bew_MDSvm2iYQ.png" /></figure><p>A patient finishes speaking.</p><p>From that moment, the system has only a brief window to decide whether the caller is truly done, transcribe the audio, understand the request, retrieve real information, generate a response, and begin playing speech.</p><p>If the silence lasts too long, the caller may think the line has dropped. If the AI responds too early, it interrupts the patient. If it says an appointment is available without checking the booking system, the conversation may sound convincing while producing the wrong real-world result.</p><p>This is what makes phone-based AI different from a chatbot.</p><p>For a voice agent, audio is not merely another input and output format. <strong>Latency, silence, interruption, call state, and shutdown behavior are all part of the user experience.</strong></p><p>Our team is building an inbound voice AI that answers calls to hospitals and can:</p><ul><li>Play greetings and recording disclosures</li><li>Route requests through speech or DTMF keypad input</li><li>Check appointment availability and create bookings</li><li>Look up, reschedule, or cancel existing appointments</li><li>Answer approved questions about hospital hours and services</li><li>Transfer callers to a human agent when necessary</li><li>Send recordings and conversation events to a post-call analysis pipeline</li></ul><p>The real-time communications foundation is <a href="https://docs.livekit.io/intro/about/">LiveKit</a>. The framework that lets the AI listen, reason, act, and speak inside that environment is <a href="https://docs.livekit.io/agents/">LiveKit Agents</a>.</p><p>The language model matters, but it is only one component of the system.</p><h3>The Mental Model: Room, Participant, and Track</h3><p>LiveKit is an open-source real-time communications framework and cloud platform. Under the hood, it handles problems such as WebRTC media transport, routing, session management, and adaptation to changing network conditions.</p><p>The easiest comparison is a video conference, but the same model can power telephone services and real-time AI assistants.</p><p>Three concepts make the architecture easier to understand:</p><ul><li>A <strong>Room</strong> is one real-time session. In our system, one patient call becomes one Room.</li><li>A <strong>Participant</strong> is a person or program connected to that Room. The patient, the AI agent, and a human representative can all be Participants.</li><li>A <strong>Track</strong> is a stream published or received by a Participant. The patient’s voice and the AI’s synthesized speech are audio Tracks.</li></ul><p>This model is useful because the caller and the AI do not need entirely separate abstractions. They are simply participants exchanging audio inside the same real-time space.</p><p>A normal HTTP interaction ends after a request and a response. A call is continuous. Audio keeps flowing, while participants join, leave, publish media, stop speaking, interrupt, or disconnect.</p><p>LiveKit gives us a structured way to manage that changing state.</p><h3>LiveKit Connects the Call. LiveKit Agents Runs the AI.</h3><p>The names are similar, but their responsibilities are different.</p><p>LiveKit provides the communication layer:<br>LiveKit Agents provides the AI application layer:<br>One way to think about it is this:</p><blockquote><strong><em>LiveKit is the call room. LiveKit Agents is the AI representative working inside it.</em></strong></blockquote><p>A Python or Node.js agent joins a Room as a Participant. It receives the caller’s audio, processes it through AI models, and publishes synthesized speech back into the same Room.</p><p>That sounds straightforward. The details are not.</p><h3>How a Regular Phone Call Reaches the AI</h3><p>Patients do not open a browser or install a special application. They call the hospital’s regular phone number.</p><p>The bridge between the telephone network and LiveKit is <strong>SIP</strong>, or Session Initiation Protocol. A call from the public switched telephone network reaches a LiveKit SIP endpoint through a carrier or SIP trunk provider.</p><p>The connection sequence looks like this:</p><pre>1. The patient calls the hospital number. <br>2. The carrier or SIP provider sends a SIP INVITE to LiveKit. <br>3. A dispatch rule creates or assigns a Room. <br>4. LiveKit requests a job from the agent server. <br>5. The server starts an AgentSession for that call. <br>6. The voice AI joins the Room and begins the greeting.</pre><p>An inbound trunk defines which calls LiveKit should accept. A dispatch rule decides which Room and agent should handle each call. The connected caller appears in the Room as a SIP Participant.</p><p>This abstraction keeps the business logic from becoming tightly coupled to the access channel. Whether someone arrives through the telephone network or a microphone in a web application, the agent can focus on the audio and state available inside the Room.</p><p>LiveKit’s <a href="https://docs.livekit.io/reference/telephony/sip-primer/">SIP primer</a> and <a href="https://docs.livekit.io/telephony/accepting-calls/">guide to accepting calls</a> explain the telephony layer in more detail.</p><h3>How the AI Listens, Thinks, Acts, and Speaks</h3><p>It is tempting to imagine a single model that hears speech and immediately responds with speech. Real-time speech-to-speech models can work that way, but our current system uses a modular <strong>STT-LLM-TTS pipeline</strong>.</p><h3>STT: Turning Telephone Audio into Text</h3><p>The speech-to-text model receives the patient’s audio as a live stream. Telephone audio is difficult: it can contain background noise, quiet speech, compression artifacts, names, hospital departments, and physician names.</p><p>Accuracy matters, but so do streaming performance and language-specific quality.</p><h3>LLM: Understanding the Request</h3><p>The LLM uses the transcript, conversation history, and hospital configuration to decide what should happen next.</p><p>In production, its role is not limited to writing a helpful sentence. If the patient wants an appointment, the system must use a booking tool. If the caller asks about hospital information, the response must stay within approved data. If the request needs human judgment, the agent must enter a transfer workflow.</p><h3>Tools and Tasks: Where Language Becomes Real Work</h3><p>There is a critical difference between saying “I booked that for you” and successfully creating an appointment in the hospital’s system.</p><p>Tools and Tasks connect the model’s intent to operations that can be verified.</p><p>A booking flow might:</p><ol><li>Collect the department, physician, date, and time constraints.</li><li>Query the booking API for slots that are actually available.</li><li>Present only valid options.</li><li>Ask for final confirmation.</li><li>Create the appointment.</li><li>Record the API result as a conversation event.</li></ol><p>The API result-not the model’s confidence-determines whether the booking succeeded.</p><h3>TTS: Producing Speech That Works on a Call</h3><p>The text-to-speech model turns generated responses and predefined prompts into audio.</p><p>Naturalness is only one requirement. We also care about:</p><ul><li>How quickly the first audio begins</li><li>Whether dates, times, and numbers are pronounced correctly</li><li>Whether playback stops when the caller interrupts</li><li>Whether critical disclosures and confirmations play completely</li></ul><p>A modular pipeline lets us choose each model independently and trace errors or latency to a specific stage. The tradeoff is accumulated delay, which makes streaming and preemptive generation important.</p><h3>The Runtime Architecture</h3><p>LiveKit connects the patient and the AI. The application layer above it executes each hospital’s call flow and business rules.</p><p>Our runtime centers on three components:</p><ul><li>AgentServer waits for dispatch requests and starts one job per call.</li><li>AgentSession combines STT, LLM, TTS, VAD, turn detection, and interruption settings into one live conversation.</li><li>SingleAgent follows the hospital&#39;s flow_config and runs the Tools and Tasks for booking, FAQ responses, and human transfer.</li></ul><p>The full path looks like this:</p><pre>1. Patient call <br>2. SIP / LiveKit Telephony <br>3. LiveKit Room <br>4. AgentServer - per-call job AgentSession - STT, LLM, TTS, and turn handling <br>5. SingleAgent - executes flow_config <br>├── Greeting and DTMF <br>├── Booking Tools and Tasks → Booking API <br>├── Hospital FAQ → Approved hospital information <br>└── Human transfer → Human agent <br>6. LiveKit Room → Recording through Egress → S3 <br>7. AgentSession → Conversation and tool events → Kafka → Post-call analysis</pre><p>The real-time path focuses on the current conversation. Recording, classification, summarization, and quality analytics can continue asynchronously after the call.</p><p>That separation protects response time. Expensive analysis does not need to block a patient waiting on the phone.</p><h3>Why the Call Flow Is Configuration-Driven</h3><p>Hospitals do not all answer calls in the same way.</p><p>One hospital may begin with “Press 1 for appointments.” Another may want the caller to speak immediately. Transfer policies can change outside business hours. Appointment, information, and escalation rules vary by site.</p><p>Hard-coding every variation would require a deployment whenever a hospital changes its policy. We therefore define the high-level call flow in flow_config.</p><p>The configuration can include nodes such as:</p><ul><li>greeting to play an announcement and optionally collect DTMF input</li><li>condition to choose a path using business hours or session state</li><li>agent to enter an open-ended conversational section</li><li>action to transfer a call or record an event</li><li>exit to play a closing message and shut down safely</li></ul><p>This creates a useful division of responsibility:</p><blockquote><strong><em>Configuration controls what happens and in what order. The LLM and agent determine how to understand and respond to natural language.</em></strong></blockquote><p>DTMF and conversational AI also work better together than either does alone. Keypad input is useful when exact digits or deterministic menu choices matter. Natural language is better for a request such as, “I’d like an orthopedics appointment next Monday afternoon.”</p><p>The goal is not to replace every phone interaction with free-form AI. It is to use deterministic controls where certainty matters and language models where flexibility matters.</p><h3>The Hardest Problems Often Exist Outside the LLM</h3><p>A strong language model does not automatically create a good phone service. Much of the difficult engineering work happens at conversation boundaries and in asynchronous state management.</p><h3>Knowing When the Caller Has Finished</h3><p>Voice activity detection can tell whether sound is present. It cannot always tell whether a thought is complete.</p><p>Consider a patient saying:</p><blockquote><em>“Next week… one moment… Wednesday.”</em></blockquote><p>If the system treats the middle pause as the end of the turn, the AI starts answering too early.</p><p>Turn detection and endpointing combine speech activity, context, and timing. The system must avoid interrupting the caller without leaving an awkward silence after every sentence.</p><h3>Handling Interruptions Without Reacting to Every Noise</h3><p>People interrupt naturally:</p><blockquote><em>“No, not the morning-the afternoon.”</em></blockquote><p>The agent should stop its current response and process the correction. But if every cough, acknowledgment, or background sound interrupts playback, the AI becomes unusable.</p><p>We need policies for minimum speech duration, minimum word count, and false-interruption recovery. Critical messages, including recording disclosures and final booking confirmations, may need different rules from ordinary dialogue.</p><h3>Measuring the Latency Callers Actually Feel</h3><p>The delay after the caller stops speaking is not a single metric.</p><p>Even when every component seems reasonably fast, the total can feel slow. We measure each stage separately, stream generated audio, preload what we can, and provide a short progress message when an external API takes noticeable time.</p><h3>Ending a Call Safely</h3><p>A caller can hang up while the AI is speaking, a booking request is running, a recording is finalizing, the Room is closing, and a Kafka event is being published.</p><p>Those operations do not complete as one atomic event.</p><p>Shutdown that is too slow leaves workers occupied. Shutdown that is too aggressive can lose the last audio or analysis event. The order of disconnect handling, session shutdown, recording completion, and downstream publication has to be designed explicitly and made safe to execute more than once.</p><h3>Transferring to a Human</h3><p>Cold transfer sends the caller to a human and removes the AI. Warm transfer introduces the human first, shares context, and manages the transition until the caller and representative are safely connected.</p><p>During a warm transfer, the patient, AI, and human can occupy different states inside the same call. The system must control who hears whom, decide what happens if the human does not answer, and prevent multiple transfer attempts from racing with one another.</p><p>This is less a phone-number-forwarding problem than a distributed state and concurrency problem.</p><h3>Why LiveKit Fit Our Use Case</h3><p>Several aspects of LiveKit and LiveKit Agents matched the way we wanted to build the service:</p><p>The <a href="https://docs.livekit.io/agents/server/lifecycle/">agent server lifecycle</a> is particularly useful here. The server waits for dispatch requests and starts a separate job for each call, allowing one service to handle multiple calls with process-level isolation.</p><p>But LiveKit does not solve every product problem for us.</p><p>We still need to:</p><p>LiveKit is a strong real-time foundation. It is not a finished hospital workflow product.</p><p>Reliable voice AI emerges only when communications infrastructure, AI models, business rules, and observability work together.</p><h3>The Most Useful Shift in Perspective</h3><p>The most useful architectural idea for us was to stop treating the AI as a request-response API and start treating it as <strong>a participant in a live call</strong>.</p><p>The patient and AI join the same Room. They exchange audio through Tracks. LiveKit Agents connects listening, turn detection, response generation, speech playout, and tool execution. Our service layer adds hospital-specific workflows for booking, information, DTMF, human transfer, recording, and post-call analysis.</p><p>The quality of the result cannot be explained by the choice of LLM alone.</p><p>The system must know when the caller has finished. It must stop speaking at the right moment. It must offer only appointments that are actually available. It must transfer safely to a person. And it must preserve critical data when the call disconnects.</p><p>LiveKit provides the real-time communications foundation. LiveKit Agents turns the AI into a conversational Participant. The application layer turns that Participant into something more useful than a talking chatbot:</p><blockquote><strong><em>A voice AI that answers the phone and completes real work.</em></strong></blockquote><h3>Further Reading</h3><ul><li><a href="https://docs.livekit.io/intro/about/">About LiveKit</a></li><li><a href="https://docs.livekit.io/intro/basics/rooms-participants-tracks/">Rooms, participants, and tracks</a></li><li><a href="https://docs.livekit.io/agents/">Introduction to LiveKit Agents</a></li><li><a href="https://docs.livekit.io/reference/telephony/sip-primer/">LiveKit SIP primer</a></li><li><a href="https://docs.livekit.io/telephony/accepting-calls/">Accepting calls with LiveKit Telephony</a></li><li><a href="https://docs.livekit.io/agents/models/pipelines/">Voice pipeline types</a></li><li><a href="https://docs.livekit.io/agents/logic/turns/turn-detector/">Turn detection</a></li><li><a href="https://docs.livekit.io/agents/logic/turns/">Turns and interruptions</a></li><li><a href="https://docs.livekit.io/agents/server/lifecycle/">Agent server lifecycle</a></li></ul><p><em>Originally published at </em><a href="https://kofsitho87.github.io/my-tech-blog/blog/how-we-built-ai-that-answers-hospital-phone-calls/"><em>https://kofsitho87.github.io</em></a><em> on August 7, 2026.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=933b489fc29b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Config-Driven Voice AI Agent: Beyond IVR Call Flows]]></title>
            <link>https://medium.com/@kofsitho/config-driven-voice-ai-agent-beyond-ivr-call-flows-e89f57d18d01?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/e89f57d18d01</guid>
            <category><![CDATA[call-center]]></category>
            <category><![CDATA[voice-ai]]></category>
            <category><![CDATA[livekit]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Mon, 20 Apr 2026 11:02:30 GMT</pubDate>
            <atom:updated>2026-04-20T11:10:37.967Z</atom:updated>
            <content:encoded><![CDATA[<h3>Beyond IVR: Building a Config-Driven Voice AI Agent with Declarative Call Flows</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Oh9jaqoplfTWkDuusbGYdQ.png" /></figure><h3>1. Introduction: The Problem with Two Extremes</h3><p>Every hospital, clinic, and medical office faces the same daily challenge: the phone rings constantly. Appointment requests, cancellations, questions about office hours, insurance inquiries — and behind each call is a real person who wants a fast, accurate answer without navigating a maze.</p><p>For decades, the industry’s answer was the <strong>Interactive Voice Response (IVR)</strong> system. Press 1 for appointments. Press 2 for billing. Press 0 to speak to an agent. Simple, predictable, cheap to run. But also:</p><ul><li>Rigid. Changing a single menu option means a developer ticket, a deployment, and a prayer nothing breaks.</li><li>Frustrating. Callers who don’t fit the predefined paths hit dead ends.</li><li>Dumb. IVR has no understanding of context, no ability to adapt, and no memory of the caller.</li></ul><p>The natural evolution — replacing IVR with a <strong>pure large language model (LLM) voice agent</strong> — solves the flexibility problem but introduces a new one: unpredictability. An LLM can handle nuanced conversation beautifully, but in a production telephony system you need guarantees:</p><ul><li>The greeting message must play <em>before</em> the caller can speak.</li><li>The call must not transfer to a human agent unless specific conditions are met.</li><li>A DTMF keypress of “1” must <em>always</em> route to bookings, never somewhere else.</li><li>The call flow must be auditable and changeable by non-engineers.</li></ul><p>A freeform LLM agent, by nature, can’t make those guarantees. Every response is a generation, and generations vary.</p><h3>The Middle Ground</h3><p>What we needed was something in between: a system that uses AI agents for the parts that require intelligence (understanding a patient’s request, looking up available appointment slots, answering complex questions) but uses <strong>deterministic, declarative configuration</strong> to control the overall call flow.</p><p>The result is a JSON-based flow_config that acts as a call flow blueprint, interpreted at runtime by a SupervisorAgent — a state machine that traverses the flow graph node by node, delegating to AI agents only at the right moments.</p><p>This post walks through how it works, why we designed it this way, and what we learned building it for a real hospital call center system.</p><blockquote><strong><em>TL;DR</em></strong></blockquote><ul><li><strong>The problem:</strong> IVR is too rigid; pure LLM agents are too unpredictable for production telephony.</li><li><strong>The solution:</strong> A flow_config JSON blueprint + SupervisorAgent runtime that handles deterministic routing, while delegating open-ended conversation to specialized LLM agents.</li><li><strong>Three core components:</strong> FlowNode (5 node types), SupervisorAgent (graph traversal engine), and AI agents (BookingAgent, InfoAgent, TriageCoordinator).</li><li><strong>Two interaction modes:</strong> DTMF keypress routing (deterministic, auditable) and free voice routing (natural, LLM-driven).</li><li><strong>Best fit for:</strong> Healthcare, support, and scheduling systems with multiple routing branches, mixed deterministic + AI steps, and audit trail requirements.</li></ul><h3>2. Architecture Overview</h3><p>The system is organized around three concern areas, each with a distinct responsibility:</p><pre>┌─────────────────────────────────────────────────────────────────┐<br>│  CONCERN AREA 1: CALL INITIATION                                │<br>│                                                                 │<br>│   dial_info (JSON payload)                                      │<br>│        │                                                        │<br>│        ▼                                                        │<br>│   CallSessionData.from_dial_info()                              │<br>│        │                                                        │<br>│        ├── business_data    hospital info, operating hours      │<br>│        ├── recipient_data   caller&#39;s name, phone, chart no.     │<br>│        ├── call_config_data language, transfer settings         │<br>│        ├── flow_config      ◄── the call flow blueprint         │<br>│        └── agents_data      refs to all available AI agents     │<br>└──────────────────────────┬──────────────────────────────────────┘<br>                           │<br>                           ▼<br>┌─────────────────────────────────────────────────────────────────┐<br>│  CONCERN AREA 2: FLOW CONTROL  (SupervisorAgent)                │<br>│                                                                 │<br>│   on_enter()                                                    │<br>│       └──► _process_node(entry_node_id)                         │<br>│                   │                                             │<br>│           ┌───────▼────────┐                                    │<br>│           │  get_node(id)  │  ◄── looks up FlowConfig           │<br>│           └───────┬────────┘                                    │<br>│                   │                                             │<br>│       ┌───────────▼──────────────────────────────────────────┐ │<br>│       │              Node Type Dispatch                      │ │<br>│       ├──────────────────────────────────────────────────────┤ │<br>│       │ condition → evaluate field, pick branch             │ │<br>│       │ greeting  → play TTS announcement;                  │ │<br>│       │             optionally wait for DTMF keypress       │ │<br>│       │ action    → warm/cold transfer to human, or log     │ │<br>│       │ exit      → play closing message, shutdown          │ │<br>│       │ agent     → delegate to AI agent ───────────────────┼─┼──►<br>│       └──────────────────────────────────────────────────────┘ │<br>└─────────────────────────────────────────────────────────────────┘<br>                                                                   │<br>┌──────────────────────────────────────────────────────────────────┘<br>│  CONCERN AREA 3: AI AGENTS  (specialized, conversational)<br>│<br>│  These are the three specialized agents in this system:<br>│<br>│   ┌──────────────────────┐   ┌──────────────────────┐<br>│   │  TriageCoordinator   │   │    BookingAgent       │<br>│   │  interprets caller&#39;s │   │  creates, modifies,   │<br>│   │  free-speech intent  │   │  cancels appointments │<br>│   │  and routes to the   │   └──────────────────────┘<br>│   │  right specialist    │<br>│   └──────────────────────┘   ┌──────────────────────┐<br>│                               │      InfoAgent        │<br>│                               │  answers questions    │<br>│                               │  about the hospital   │<br>│                               └──────────────────────┘<br>└──────────────────────────────────────────────────────────────────</pre><blockquote><strong><em>Note on telephony actions:</em></strong><em> Warm/cold transfers are not a separate architectural layer — they are execution details handled </em>inside<em> action nodes by the </em><em>SupervisorAgent. They appear in the diagram above under &quot;FLOW CONTROL.&quot;</em></blockquote><h3>The Key Insight</h3><p>Notice the separation of responsibilities:</p><p>Concern AreaResponsibilityWho controls itflow_config JSON<em>What</em> happens, in <em>what order</em>Product / ops teamSupervisorAgent<em>How</em> each node is executedEngineeringAI Agents<em>What to say</em> in open conversationLLM</p><p>This separation means the call flow can be changed — add a menu option, adjust routing by business hours — without touching agent code. In practice, a management UI or template layer often sits above the raw JSON, but the interface contract remains this config structure. When an AI agent does take over, it operates within a guardrail: the SupervisorAgent has already made all the sensitive routing decisions before delegating.</p><h3>What Does dial_info Look Like?</h3><p>Every call session starts with a JSON payload — dial_info — delivered when the call is accepted. Here&#39;s an abbreviated example:</p><pre>{<br>  &quot;call_config_data&quot;: {<br>    &quot;language&quot;: &quot;ko-KR&quot;,<br>    &quot;voice&quot;: &quot;marin&quot;,<br>    &quot;transfer_to&quot;: &quot;01000000000&quot;,<br>    &quot;transfer_mode&quot;: &quot;warm_transfer&quot;<br>  },<br>  &quot;business_data&quot;: {<br>    &quot;site_id&quot;: &quot;example-clinic&quot;,<br>    &quot;client_name&quot;: &quot;Example Hospital&quot;,<br>    &quot;is_work_time&quot;: true<br>  },<br>  &quot;recipient_data&quot;: {<br>    &quot;phone&quot;: &quot;01012345678&quot;,<br>    &quot;user_name&quot;: &quot;John Doe&quot;,<br>    &quot;birth_date&quot;: &quot;1990-01-01&quot;,<br>    &quot;chart_no&quot;: &quot;000001&quot;<br>  },<br>  &quot;flow_config&quot;: {<br>    &quot;entry_node_id&quot;: &quot;greeting&quot;,<br>    &quot;nodes&quot;: [ ... ]<br>  },<br>  &quot;agents_config&quot;: { ... }<br>}</pre><p>CallSessionData.from_dial_info() parses this into typed dataclasses. The flow_config field — the call flow blueprint — is what SupervisorAgent reads at runtime. We&#39;ll see the full flow_config in Section 5.</p><h3>3. The FlowNode: Five Building Blocks of a Call</h3><p>A flow_config is a directed graph of <strong>nodes</strong>. Each node has a type that determines what happens when the SupervisorAgent visits it. There are five types, and together they cover every scenario a call flow needs.</p><pre>FlowNode<br>├── id          unique identifier (also used as routing target)<br>├── type        condition | greeting | action | agent | exit<br>├── name        human-readable label<br>└── ...         type-specific fields</pre><h3>1. condition — Branching on Data</h3><p>A condition node reads a field from the session data and picks the next node based on its value. No audio, no LLM — pure deterministic branching.</p><pre>{<br>  &quot;id&quot;: &quot;check_work_hours&quot;,<br>  &quot;type&quot;: &quot;condition&quot;,<br>  &quot;name&quot;: &quot;Check operating hours&quot;,<br>  &quot;field&quot;: &quot;business_data.is_work_time&quot;,<br>  &quot;branches&quot;: {<br>    &quot;true&quot;:  &quot;greeting_open&quot;,<br>    &quot;false&quot;: &quot;greeting_closed&quot;<br>  }<br>}</pre><p><strong>Pseudocode:</strong></p><pre>value = get_field(&quot;business_data.is_work_time&quot;)  // → &quot;true&quot;<br>next  = branches[value] ?? branches[&quot;any&quot;] ?? node.next<br>go to next</pre><p>Fields are resolved by prefix: business_data.*, recipient_data.*, or call_config_data.*. Values are coerced to lowercase strings before lookup, so True and &quot;true&quot; both match &quot;true&quot;.</p><h3>2. greeting — Announcement + Optional DTMF</h3><p>A greeting node plays a TTS message. It can then wait for a DTMF keypress and route based on which key was pressed — or simply move on to the next node if no input is needed.</p><pre>{<br>  &quot;id&quot;: &quot;main_menu&quot;,<br>  &quot;type&quot;: &quot;greeting&quot;,<br>  &quot;name&quot;: &quot;Main menu&quot;,<br>  &quot;input_method&quot;: &quot;dtmf&quot;,<br>  &quot;message&quot;: &quot;Press 1 for appointments. Press 2 for hospital information.&quot;,<br>  &quot;dtmf_options&quot;: {<br>    &quot;1&quot;: { &quot;next&quot;: &quot;booking_agent&quot;, &quot;user_request&quot;: &quot;Book appointment&quot; },<br>    &quot;2&quot;: { &quot;next&quot;: &quot;info_agent&quot;,    &quot;user_request&quot;: &quot;Hospital info&quot; },<br>    &quot;*&quot;: { &quot;next&quot;: &quot;main_menu&quot; }<br>  },<br>  &quot;next&quot;: &quot;main_menu&quot;<br>}</pre><p><strong>Pseudocode:</strong></p><pre>play TTS(message)<br>if input_method == &quot;dtmf&quot;:<br>    // GreetingDtmfTask handles internal retries (up to max_invalid_attempts=2)<br>    // and replays the message on each invalid input.<br>    // SupervisorAgent only sees the final outcome:<br>    result = GreetingDtmfTask.run(timeout=5s, max_invalid=2)<br><br>    if result.selected_key in dtmf_options:<br>            // Valid key confirmed after internal retry loop<br>            save user_request to session (if present)<br>            go to dtmf_options[result.selected_key].next<br>        elif result.timed_out:<br>            // All retry attempts exhausted, or silence throughout<br>            say &quot;No valid input received. Ending call.&quot;<br>            shutdown()<br>        else:<br>            // Key pressed but not in dtmf_options (edge case); use fallback<br>            go to node.next<br>    else:<br>        go to node.next // voice mode: just play message, move on</pre><p>The user_request field is particularly useful: it pre-seeds the AI agent with what the caller selected, so the agent doesn&#39;t need to ask &quot;How can I help you?&quot; from scratch.</p><h3>3. action — Telephony Side Effects</h3><p>An action node performs an operation with a real-world side effect. Depending on the action_type, it either continues to the next node (e.g. log) or terminates the flow entirely (e.g. transfer, transfer_direct).</p><pre>{<br>  &quot;id&quot;: &quot;transfer_to_staff&quot;,<br>  &quot;type&quot;: &quot;action&quot;,<br>  &quot;name&quot;: &quot;Connect to human agent&quot;,<br>  &quot;action_type&quot;: &quot;transfer_direct&quot;,<br>  &quot;action_config&quot;: {<br>    &quot;phone_number&quot;: &quot;01000000000&quot;,<br>    &quot;transfer_mode&quot;: &quot;warm_transfer&quot;<br>  }<br>}</pre><p>action_typeWhat it doestransferUses the global call_config_data.transfer_to numbertransfer_directUses action_config.phone_number directlylogRecords a message to the session log, continues to next</p><p>For transfer_direct, the transfer_mode determines behavior:</p><pre>warm_transfer → brief the human agent first, then connect caller<br>cold_transfer → connect caller directly, no briefing</pre><p>After a transfer action completes, the flow ends (return None). There is no &quot;next node&quot; — the call is now in human hands.</p><h3>4. agent — Delegate to an AI Agent</h3><p>An agent node hands control from the SupervisorAgent to one of the specialized conversational AI agents. Within the flow-config runtime, this is a one-way transition: once delegated, the SupervisorAgent exits and the specialist agent drives the conversation. The flow graph is not revisited — though the underlying session infrastructure does retain a prev_agent reference and a shared transfer helper, neither is used to return to the graph in the current design.</p><pre>{<br>  &quot;id&quot;: &quot;booking_agent&quot;,<br>  &quot;type&quot;: &quot;agent&quot;,<br>  &quot;name&quot;: &quot;Booking agent&quot;<br>}</pre><p><strong>Pseudocode:</strong></p><pre>next_agent = agents_data.agents[node.id]   // look up by node id<br>session.update_agent(next_agent)           // swap the active agent for the session<br>return                                     // SupervisorAgent exits</pre><p>The node.id must match exactly a key registered in agents_data.agents at session startup. This is the coupling point between the flow config and the agent registry — adding a new agent type requires both a new agent implementation <em>and</em> registering it in agents_data.agents under the same key as node.id.</p><h3>5. exit — Graceful Termination</h3><p>An exit node plays a closing message and shuts down the session. It’s the clean end state — used when the caller explicitly wants to hang up, or when a flow path has no useful continuation.</p><pre>{<br>  &quot;id&quot;: &quot;end_call&quot;,<br>  &quot;type&quot;: &quot;exit&quot;,<br>  &quot;name&quot;: &quot;End call&quot;,<br>  &quot;message&quot;: &quot;Thank you for calling. Have a great day.&quot;<br>}</pre><p><strong>Pseudocode:</strong></p><pre>if message:<br>    play TTS(message)<br>    wait for playout<br>log &quot;[CALL_TERMINATION: ACTOR=USER, REASON=&lt;exit_reason&gt;]&quot;  // e.g. EXPLICIT_REQUEST<br>session.shutdown()</pre><h3>How Nodes Connect</h3><p>Each node declares its next field — the default node to visit after it completes. Condition nodes override this with their branches map; greeting nodes with DTMF override with dtmf_options. Agent and exit nodes never continue — they are terminal.</p><pre>entry_node_id<br>      │<br>      ▼<br>  [condition] ──true──►  [greeting] ──&quot;1&quot;──►  [agent]   (terminal)<br>       │                     │<br>     false                  &quot;*&quot;<br>       │                     │<br>       ▼                     └──► (replay same greeting)<br>  [greeting] ──► [exit]    (terminal)</pre><h3>4. SupervisorAgent: The Runtime Graph Traversal Engine</h3><p>The SupervisorAgent is the interpreter that brings a flow_config to life. Its job is simple to state: read a node, execute it, find the next node, repeat. But the implementation has a few design decisions worth understanding.</p><h3>Async Recursive Traversal</h3><p>The traversal is implemented as an async recursive function — not a loop. Each node handler returns the ID of the next node (or None to stop), and _process_node calls itself with that ID.</p><pre>_process_node(node_id):<br>    node = flow_config.get_node(node_id)<br>    if not node:<br>        handle_missing_node(); return<br><br>    next_node_id = dispatch(node)   // condition / greeting / action / agent / exit<br>        if next_node_id:<br>            await _process_node(next_node_id)   // recurse</pre><p><strong>Why recursion instead of a loop?</strong></p><p>Each node handler is async and may await real I/O — TTS playout, DTMF input, a transfer call. A recursive call makes it natural for each handler to return cleanly after its async work completes, without needing explicit loop state or coroutine management. The depth is bounded by the flow graph itself (typically 3–10 nodes), so stack overflow is not a concern.</p><h3>Audio Input Control</h3><p>One of the trickier aspects of a live voice system is controlling <em>when</em> the caller’s audio is actually processed. If the caller speaks while the greeting TTS is still playing, it can interrupt the announcement and trigger unintended agent behavior.</p><p>The SupervisorAgent manages this with explicit audio gating:</p><pre>on_enter():<br>    session.input.set_audio_enabled(False)   // disable mic while Supervisor runs<br>    ...<br>    _process_node(entry_node_id)             // traverse the flow<br><br>_handle_agent_node():<br>    session.update_agent(next_agent)         // hand off to AI agent<br>    // AI agent&#39;s on_enter() re-enables audio after its opening TTS completes</pre><pre>Timeline:<br><br>call starts<br>      │<br>      ▼<br>  [audio INPUT: OFF] ──► greeting TTS plays ──► DTMF captured<br>                                                     │<br>                                                     ▼<br>                                             agent node reached<br>                                                     │<br>                                                     ▼<br>                                         [audio INPUT: ON] ◄── AI agent takes over</pre><p>This means the SupervisorAgent phase is entirely one-directional: the system speaks, the caller presses keys or waits. Free speech only becomes possible once an AI agent is active.</p><h3>Session State Through the Traversal</h3><p>All nodes in the graph share the same CallSessionData object. This is how context built up early in the call — caller identity, selected DTMF option, operating hours — is available to AI agents later without any explicit passing.</p><pre>CallSessionData (shared across all nodes and agents)<br>    │<br>    ├── business_data       read by condition nodes<br>    ├── recipient_data      read by condition nodes, logged at session start<br>    ├── call_config_data    read by action nodes (transfer settings)<br>    ├── flow_config         read by SupervisorAgent only<br>    └── agents_data<br>            ├── agents      { &quot;booking_agent&quot;: &lt;BookingAgent&gt;, ... }<br>            ├── prev_agent  set when SupervisorAgent hands off<br>            └── user_request  ◄── set by greeting node (DTMF selection)</pre><p>The user_request field is a notable example: when a caller presses &quot;1&quot; for <em>Book appointment</em>, the greeting node writes &quot;Book appointment&quot; into agents_data.user_request. The BookingAgent reads this on entry and skips the &quot;How can I help you?&quot; opener — it already knows.</p><h3>Observability: Structured Session Log</h3><p>Throughout the traversal, the SupervisorAgent writes structured tags into the session&#39;s developer history. These are not spoken aloud — they&#39;re internal markers that make the call auditable after the fact.</p><pre>[RECIPIENT_DATA: USER_NAME=John Doe, PHONE=01012345678, ...]<br>[GREETING: STATUS=STARTED]<br>[GREETING: STATUS=COMPLETED]<br>[GREETING_DTMF_TASK: SELECTED_KEY=1]<br>[CALL_TERMINATION: ACTOR=USER, REASON=EXPLICIT_REQUEST]</pre><p>This log is invaluable for debugging. When a call goes wrong — a transfer that didn’t fire, a greeting that cut off — you can reconstruct exactly which node was active and what state the session was in at that moment.</p><h3>5. A Real-World Example: Hospital Appointment Line</h3><p>This section traces a complete, production-like call flow for a hospital appointment line. This is the DTMF variant — callers navigate using keypresses.</p><h3>The Full flow_config</h3><pre>{<br>  &quot;entry_node_id&quot;: &quot;greeting_main&quot;,<br>  &quot;nodes&quot;: [<br>    {<br>      &quot;id&quot;: &quot;greeting_main&quot;,<br>      &quot;type&quot;: &quot;greeting&quot;,<br>      &quot;name&quot;: &quot;Main menu&quot;,<br>      &quot;input_method&quot;: &quot;dtmf&quot;,<br>      &quot;message&quot;: &quot;Hello! Press 1 to book an appointment, 2 to check an existing booking, 3 to cancel, 4 to modify, 5 for hospital information, 6 to speak with a staff member, or press * to hear this again.&quot;,<br>      &quot;dtmf_options&quot;: {<br>        &quot;1&quot;: { &quot;next&quot;: &quot;booking_agent&quot;,   &quot;user_request&quot;: &quot;Book appointment&quot; },<br>        &quot;2&quot;: { &quot;next&quot;: &quot;booking_agent&quot;,   &quot;user_request&quot;: &quot;Check booking&quot; },<br>        &quot;3&quot;: { &quot;next&quot;: &quot;booking_agent&quot;,   &quot;user_request&quot;: &quot;Cancel appointment&quot; },<br>        &quot;4&quot;: { &quot;next&quot;: &quot;booking_agent&quot;,   &quot;user_request&quot;: &quot;Modify appointment&quot; },<br>        &quot;5&quot;: { &quot;next&quot;: &quot;greeting_info&quot; },<br>        &quot;6&quot;: { &quot;next&quot;: &quot;transfer_staff&quot; },<br>        &quot;*&quot;: { &quot;next&quot;: &quot;greeting_main&quot; }<br>      },<br>      &quot;next&quot;: &quot;greeting_main&quot;<br>    },<br>    {<br>      &quot;id&quot;: &quot;greeting_info&quot;,<br>      &quot;type&quot;: &quot;greeting&quot;,<br>      &quot;name&quot;: &quot;Hospital information submenu&quot;,<br>      &quot;input_method&quot;: &quot;dtmf&quot;,<br>      &quot;message&quot;: &quot;Press 1 for opening hours, press 2 for directions, press 3 to end the call, or press * to go back.&quot;,<br>      &quot;dtmf_options&quot;: {<br>        &quot;1&quot;: { &quot;next&quot;: &quot;info_agent&quot;,  &quot;user_request&quot;: &quot;Opening hours&quot; },<br>        &quot;2&quot;: { &quot;next&quot;: &quot;info_agent&quot;,  &quot;user_request&quot;: &quot;Directions to hospital&quot; },<br>        &quot;3&quot;: { &quot;next&quot;: &quot;end_call&quot; },<br>        &quot;*&quot;: { &quot;next&quot;: &quot;greeting_main&quot; }<br>      },<br>      &quot;next&quot;: &quot;greeting_info&quot;<br>    },<br>    { &quot;id&quot;: &quot;booking_agent&quot;,   &quot;type&quot;: &quot;agent&quot;,  &quot;name&quot;: &quot;Booking agent&quot; },<br>    { &quot;id&quot;: &quot;info_agent&quot;,      &quot;type&quot;: &quot;agent&quot;,  &quot;name&quot;: &quot;Info agent&quot; },<br>    {<br>      &quot;id&quot;: &quot;transfer_staff&quot;,<br>      &quot;type&quot;: &quot;action&quot;,<br>      &quot;name&quot;: &quot;Transfer to human staff&quot;,<br>      &quot;action_type&quot;: &quot;transfer&quot;,<br>      &quot;action_config&quot;: { &quot;phone_number&quot;: &quot;01000000000&quot; }<br>    },<br>    {<br>      &quot;id&quot;: &quot;end_call&quot;,<br>      &quot;type&quot;: &quot;exit&quot;,<br>      &quot;name&quot;: &quot;End call&quot;,<br>      &quot;message&quot;: &quot;Thank you for calling. Have a great day.&quot;<br>    }<br>  ]<br>}</pre><h3>The Flow Graph</h3><pre>┌────────────────┐<br>       ┌──────────► │ greeting_main  │ ◄─────────────────┐<br>       │ (*)        └───────┬────────┘                   │<br>       │                    │                             │ (*)<br>       │         1,2,3,4 ───┤─── 5 ─────────► ┌──────────────────┐<br>       │                    │                   │  greeting_info   │<br>       │                    │ 6                 └──┬───────────────┘<br>       │                    │                      │ 1,2     │ 3<br>       │                    ▼                      ▼         ▼<br>       │           ┌─────────────────┐    ┌──────────────┐  ┌──────────┐<br>       │           │ transfer_staff  │    │  info_agent  │  │ end_call │<br>       │           │  (action: warm  │    │  (AI agent)  │  │  (exit)  │<br>       │           │   transfer)     │    └──────────────┘  └──────────┘<br>       │           └─────────────────┘<br>       │<br>       │    1,2,3,4 ──►  ┌────────────────┐<br>       │                  │ booking_agent  │<br>       └──────────────────│  (AI agent)   │<br>                          └────────────────┘</pre><h3>Three Caller Journeys</h3><h4>Journey A: Book an appointment (press 1)</h4><pre>[call starts]<br>  SupervisorAgent.on_enter()<br>    → audio input disabled<br>    → _process_node(&quot;greeting_main&quot;)<br>        → play TTS: &quot;Hello! Press 1 to book...&quot;<br>        → wait for DTMF keypress<br>        → caller presses 1<br>        → save user_request = &quot;Book appointment&quot;<br>        → _process_node(&quot;booking_agent&quot;)<br>            → session.update_agent(BookingAgent)<br>            → SupervisorAgent exits</pre><pre>  BookingAgent.on_enter()<br>    → audio input re-enabled<br>    → reads user_request = &quot;Book appointment&quot;<br>    → greets caller: &quot;I can help you with booking. What date works for you?&quot;<br>    → conversation continues...</pre><p>Session log at this point:</p><pre>[RECIPIENT_DATA: USER_NAME=John Doe, PHONE=01012345678, ...]<br>[GREETING: STATUS=STARTED]<br>[GREETING: STATUS=COMPLETED]<br>[GREETING_DTMF_TASK: SELECTED_KEY=1]</pre><h4>Journey B: Speak to a human (press 6)</h4><pre>[call starts]<br>  SupervisorAgent.on_enter()<br>    → _process_node(&quot;greeting_main&quot;)<br>        → play TTS: &quot;Hello! Press 1 to book...&quot;<br>        → caller presses 6<br>        → _process_node(&quot;transfer_staff&quot;)<br>            → action_type = &quot;transfer&quot;<br>            → _handle_warm_transfer_call(transfer_to=&quot;01000000000&quot;)<br>                → brief the human staff member first<br>                → connect caller<br>            → return None  ← flow ends here</pre><p>The SupervisorAgent never reaches another node after a transfer. The call is in human hands.</p><h4>Journey C: Check hospital info, then end call (press 5 → 3)</h4><pre>[call starts]<br>  _process_node(&quot;greeting_main&quot;)<br>    → caller presses 5<br>    → _process_node(&quot;greeting_info&quot;)<br>        → play TTS: &quot;Press 1 for opening hours...&quot;<br>        → caller presses 3<br>        → _process_node(&quot;end_call&quot;)<br>            → play TTS: &quot;Thank you for calling. Have a great day.&quot;<br>            → session.shutdown()</pre><p>Three nodes, zero AI agents involved. The entire interaction is deterministic and config-driven.</p><h3>6. Two Flavors: DTMF vs. Free Voice</h3><p>The same SupervisorAgent and flow_config engine supports two fundamentally different caller interaction modes. The choice is made per greeting node via input_method.</p><h3>DTMF Mode</h3><p>The caller navigates by pressing keys. The SupervisorAgent waits for a keypress after playing the TTS announcement and routes accordingly. Routing decisions are driven by keypress — the underlying GreetingDtmfTask also handles spoken digit input as a fallback, but no LLM reasoning is involved in the routing itself.</p><p><strong>flow_config shape:</strong></p><pre>entry: greeting_main (dtmf)<br>           │<br>    key 1 ─┼─ key 2 ─┼─ key * (replay)<br>           │          │<br>     booking_agent  booking_agent<br>     (AI agent)     (AI agent)</pre><p><strong>When no valid key is received:</strong> After max_invalid_attempts (default: 2) are exhausted or the timeout expires, the SupervisorAgent plays an error message and terminates the call — it does not silently fall back to node.next. This is intentional: an unresponsive caller is better handled by ending the call cleanly than by looping indefinitely.</p><p><strong>Best suited for:</strong></p><ul><li>Environments where audio quality is unpredictable (mobile, VoIP with packet loss)</li><li>High call volumes requiring fast, unambiguous routing</li><li>Regulated industries where routing decisions must be auditable and deterministic</li><li>Callers who are less comfortable with voice-activated systems</li></ul><h3>Free Voice Mode</h3><p>The caller speaks naturally. The greeting plays a short welcome message, then immediately hands off to a TriageCoordinator AI agent. The coordinator interprets the caller&#39;s free-form intent and delegates to the appropriate specialist.</p><p><strong>flow_config shape</strong> <em>(illustrative — a minimal deployment may use just the greeting node)</em>:</p><pre>{<br>  &quot;entry_node_id&quot;: &quot;greeting&quot;,<br>  &quot;nodes&quot;: [<br>    {<br>      &quot;id&quot;: &quot;greeting&quot;,<br>      &quot;type&quot;: &quot;greeting&quot;,<br>      &quot;input_method&quot;: &quot;voice&quot;,<br>      &quot;message&quot;: &quot;Hello, how can I help you today?&quot;,<br>      &quot;next&quot;: &quot;triage_coordinator&quot;<br>    },<br>    { &quot;id&quot;: &quot;triage_coordinator&quot;, &quot;type&quot;: &quot;agent&quot;, &quot;name&quot;: &quot;Triage coordinator&quot; }<br>  ]<br>}</pre><p><strong>What the flow looks like at runtime:</strong></p><pre>greeting (voice)<br>    │<br>    └──► play TTS: &quot;Hello, how can I help you today?&quot;<br>              │<br>              ▼<br>         triage_coordinator (AI agent)<br>              │<br>    ┌─────────┴──────────┐<br>    ▼                    ▼<br>booking_agent       info_agent<br>(if intent is       (if intent is<br> appointment)        information)</pre><p>The TriageCoordinator has no fixed menu — it interprets whatever the caller says and routes dynamically. This means a caller who says &quot;I need to cancel my appointment for next Tuesday&quot; goes directly to BookingAgent with context intact, without pressing any keys.</p><p><strong>Best suited for:</strong></p><ul><li>Callers who are unfamiliar with or frustrated by key-press menus</li><li>Use cases where the caller’s intent is varied and hard to enumerate up front</li><li>High-quality audio environments (office phones, good mobile signal)</li></ul><h3>Side-by-Side Comparison</h3><p>DTMFFree VoiceRouting mechanismKeypress → dtmf_options lookupLLM intent classificationDeterminismFully deterministicProbabilistic (depends on STT + LLM)Audio quality sensitivityLow — no speech recognition neededHigh — poor audio degrades intent accuracyCaller experienceFamiliar, fast for known menusNatural, no memorization requiredConfig complexityMore nodes, explicit branchingFewer nodes, routing delegated to AIAuditabilitySELECTED_KEY=N in session logLLM routing decision (less explicit than key-based routing)</p><h3>Mixing Both</h3><p>The two modes are not mutually exclusive. A single flow_config can use DTMF for top-level routing (clear, auditable) and free voice for deeper interactions once the caller is connected to a specialist agent. This is often the right default: use deterministic routing where the stakes are high, and LLM flexibility where nuance matters.</p><h3>7. Lessons Learned &amp; Trade-offs</h3><p>Building and operating this system in a real hospital environment taught us a few things that don’t show up in architecture diagrams.</p><h3>What Worked Well</h3><p><strong>Declarative config separated concerns cleanly.</strong> The biggest win was that product changes — new menu options, rerouting during holidays, adding a transfer number — became config edits, not code changes. When the config is injected externally (e.g., via call metadata or an API), this also means those changes can be deployed without a code release. The engineering team was out of the loop for most operational adjustments. This was the original goal, and it delivered.</p><p><strong>Node isolation made individual behaviors easy to reason about.</strong> Each node type has one job. A condition node never plays audio. A greeting node never makes routing decisions on its own. An exit node never transfers calls. This made testing and debugging straightforward: when something went wrong in a greeting, the search space was limited to exactly one handler.</p><p><strong>user_request pre-seeding eliminated friction at the AI handoff.</strong> Without it, every caller who pressed &quot;1 for appointments&quot; would still hear &quot;How can I help you?&quot; from the BookingAgent. With it, the agent opens with &quot;I can help you book an appointment — what date works for you?&quot; The caller never feels like they started over.</p><p><strong>Agent reuse across modes.</strong> The same agent implementation can be reused across both DTMF and free-voice modes, because both paths converge at the same agent node. The agent doesn’t know or care how the caller got there.</p><h3>What Was Tricky</h3><p><strong>Audio timing is surprisingly hard to get right.</strong> The sequence — disable mic → play TTS → enable DTMF listener → wait for keypress → re-enable mic for AI agent — has to be choreographed carefully. If audio input is re-enabled too early, a caller’s voice can interrupt the greeting and trigger the LLM before the DTMF phase even starts. If it’s re-enabled too late, the agent’s opening line plays into silence. We spent significant time tuning the handoff between SupervisorAgent.on_enter() and the AI agent&#39;s own on_enter().</p><p><strong>DTMF keypresses can arrive mid-TTS.</strong> A caller who already knows the menu will press “1” before the announcement finishes. The GreetingDtmfTask handles this by listening for SIP DTMF events in parallel with TTS playback and calling session.interrupt() immediately on a valid keypress. Getting this right required careful event ordering and completion state tracking.</p><p><strong>The node.id / agent registry coupling is a silent failure mode.</strong> If a flow_config references &quot;booking_agent&quot; as an agent node but the session starts with the key registered as &quot;BookingAgent&quot;, the SupervisorAgent logs a warning and returns — the flow stalls with only a warning in logs. This is a runtime error that no static validation catches, and it remains a sharp edge worth guarding against with consistent naming conventions.</p><p><strong>The one-way agent transition required clear ownership rules.</strong> Once the SupervisorAgent hands off, it&#39;s done. If a BookingAgent completes its task and the caller then asks about hospital hours, the BookingAgent has to handle that itself or transfer to InfoAgent through its own mechanism — there&#39;s no &quot;return to menu&quot; path. This is a deliberate constraint, but it means each AI agent needs to handle a broader range of follow-up requests than you might initially expect.</p><h3>Trade-offs We’d Make Again</h3><p>DecisionWhy we kept itAsync recursion over a loopEach node handler is naturally async with real I/O awaits — recursion keeps the code clean without explicit state machinesShared CallSessionDataPassing context through a shared object is simpler than explicit parameter threading across every node; the tradeoff is that any node can mutate shared stateAudio gating in SupervisorAgentSimple, explicit, and auditable — even if it requires careful coordination with each AI agent&#39;s on_enter()JSON flow config over codeConfig is reviewable by non-engineers, deployable without a code release, and diff-able in version control</p><h3>8. When to Use This Pattern</h3><p>The config-driven SupervisorAgent architecture is not the right fit for every voice AI system. Here&#39;s a practical guide.</p><h3>Good Fit ✓</h3><p><strong>You have multiple distinct routing branches.</strong> If callers need to reach different specialists (booking, billing, info, transfers), and the routing logic depends on known data (business hours, caller type, keypress), the flow-config graph makes that structure explicit and manageable. Flat single-agent systems don’t need it.</p><p><strong>Some steps must be deterministic and some require AI.</strong> The pattern shines when the two are interleaved: play a fixed greeting, route by keypress (deterministic), then hand off to an LLM agent for the nuanced part. If every step is either fully deterministic or fully LLM-driven, simpler approaches work.</p><p><strong>Non-engineers need to change the flow.</strong> If your product or operations team needs to add a menu option, swap a transfer number, or adjust routing during holidays — without a code deployment — this pattern gives them a config interface. This only holds if your deployment model injects config externally (e.g., via API or job metadata).</p><p><strong>You need an audit trail for routing decisions.</strong> Regulated industries, quality assurance, or customer dispute resolution all benefit from knowing exactly which node was visited and what the caller selected. The structured session log provides this out of the box.</p><p><strong>Your system is telephony or voice-first.</strong> The design assumptions — TTS playout, DTMF events, audio input gating, SIP transfers — are telephony-specific. The pattern applies naturally to inbound call systems; it’s less relevant for text chat or non-realtime pipelines.</p><h3>Poor Fit ✗</h3><p><strong>A single AI agent handles everything.</strong> If one LLM agent can handle the full range of caller intents without branching, the SupervisorAgent and flow graph add complexity for no benefit. Just start with the agent directly.</p><p><strong>The flow changes so frequently that JSON configs are still too rigid.</strong> If routing logic requires conditional expressions, loops, or programmatic generation, a config-driven approach eventually hits its ceiling. In that case, a fully code-driven state machine may be more appropriate.</p><p><strong>Your team has no operational process for managing configs.</strong> Config-as-data is only an advantage if there’s a system for reviewing, versioning, and deploying it. Without that, you get the complexity of two systems (code + config) without the operational benefit.</p><h3>Quick Checklist</h3><p>QuestionIf yes →If no →Multiple routing branches?Fits wellMay be overkillMix of deterministic + AI steps?Fits wellSingle-mode is simplerNon-engineers need to edit flow?Strong fitLess relevantAudit trail required?Strong fitLess relevantTelephony / voice-first?Designed for thisAdapt with careSingle agent, no branching?OverkillUse directly</p><h3>9. The Pattern in Production</h3><p>The core tension in production voice AI is simple: LLMs are flexible but unpredictable; rule-based systems are predictable but rigid. The flow_config + SupervisorAgent pattern is one answer to that tension — not by picking a side, but by giving each approach the parts of the problem it&#39;s actually suited for.</p><p>The SupervisorAgent handles what needs to be deterministic: the order of operations, the routing branches, the audio gate, the handoff to the right specialist. The AI agents handle what needs intelligence: understanding what the caller wants, responding naturally, looking up data, taking action. Neither side does the other&#39;s job.</p><p>The result is a system where:</p><ul><li>A product manager can add a menu option in a JSON file</li><li>An engineer can add a new specialist agent without touching the call flow</li><li>An ops team can reconstruct exactly what happened in any call from the session log</li><li>A caller gets the right agent immediately, without being asked twice what they need</li></ul><p>This isn’t a new idea — separating flow control from conversational logic has parallels in dialogue systems research going back decades. What’s new is the context: real-time voice, LLM-powered agents, and the expectation that it all works reliably in a production environment where a dropped call or misrouted patient is a real cost.</p><p>If you’re building voice AI for anything with meaningful routing complexity — healthcare, support, scheduling, finance — this pattern is worth considering before defaulting to a single all-purpose agent. The configuration overhead is real, but so is the operational clarity you get in return.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e89f57d18d01" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a Voice AI Call Analysis Pipeline]]></title>
            <link>https://medium.com/@kofsitho/building-a-voice-ai-call-analysis-pipeline-b2c6f1245be5?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/b2c6f1245be5</guid>
            <category><![CDATA[text-to-speech]]></category>
            <category><![CDATA[voice-ai]]></category>
            <category><![CDATA[ai-voice-agent]]></category>
            <category><![CDATA[conversation-analysis]]></category>
            <category><![CDATA[conversational-ai]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Fri, 13 Feb 2026 06:10:48 GMT</pubDate>
            <atom:updated>2026-02-13T06:32:02.502Z</atom:updated>
            <content:encoded><![CDATA[<h4>Sharing our experience developing a post-call conversation analysis system</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VkaCypXaaz4EQOY5pBgaJg.png" /></figure><h3><strong>Table of Contents</strong></h3><p>1. [Introduction]</p><p>- Connection to Previous Post<br>- Why Call Analysis is Needed<br>- What This Post Covers</p><p>2. [System Architecture]</p><p>- Overall Pipeline Structure<br>- Asynchronous Processing<br>- Core Components</p><p>3. [Speech Transcription Correction (Step 0)]</p><p>- Limitations of Real-time STT<br>- Gemini-based Correction System<br>- Ghost Message Handling<br>- Prompt Design</p><p>4. [Conversation Analysis (Step 1)]</p><p>- Metadata Extraction Goals<br>- Structured Output with trustcall<br>- Applying Hard Rules<br>- Challenges in Prompt Design</p><p>5. [Conversation Summary (Step 2)]</p><p>- Summary Format Design<br>- Patient-Centric Summaries</p><p>6. [Real-World Challenges]</p><p>- Audio File Availability<br>- STT Hallucination<br>- DTMF Message Handling<br>- Business Hours Distinction</p><p>7. [Conclusion]</p><ul><li>Lessons Learned<br>- Future Improvements</li></ul><h3>1. Introduction</h3><h3>1.1 Connection to Previous Post</h3><p>In our <a href="https://medium.com/@kofsitho/building-a-call-voice-ai-assistant-with-livekit-agents-ee6234aa07ef">previous post</a>, we shared our experience building a hospital Voice AI system using LiveKit Agents. We covered multi-agent architecture, appointment handling, and information retrieval.</p><p>This post discusses what happens <strong>after a call ends</strong>. Once a call concludes, we need to answer the question: “What happened during this call?” We need to determine whether an appointment was completed, if the patient responded positively, whether agent transfer was needed, and how to summarize the conversation.</p><h3>1.2 Why Call Analysis is Needed</h3><p>After a Voice AI call ends, various post-processing tasks are required.</p><p><strong>Problem 1: Real-time STT Errors</strong></p><p>Processing in real-time means speech recognition quality isn’t perfect. For example, when a patient says “I’d like to book for tomorrow at 10 AM,” the STT might produce mixed-language errors like “I’d like to book for tomorrow at ten AM” with inconsistent formatting.</p><p><strong>Problem 2: Understanding Call Outcomes</strong></p><p>When hundreds of calls occur, it’s difficult to manually review what happened in each one.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/570/1*TeDHGWTu975NRTDwZ3nxgw.png" /></figure><p><strong>Problem 3: Need for Summaries</strong></p><p>For agents to take follow-up actions, they need to quickly understand the call content.</p><h3>1.3 What This Post Covers</h3><p>This post covers:</p><ul><li><strong>Speech transcription correction</strong>: Correcting STT errors with Gemini</li><li><strong>Conversation analysis</strong>: Extracting metadata with LLM</li><li><strong>Conversation summary</strong>: Automatic patient-centric summaries</li><li><strong>Pipeline implementation</strong>: RabbitMQ-based asynchronous processing</li></ul><p>What we won’t cover:</p><ul><li>RabbitMQ installation and configuration (refer to official docs)</li><li>Basic LLM API usage</li><li>Frontend dashboard implementation</li></ul><p>Note: specific internal resource names (queues, service names, and log event keys) are anonymized in this post.</p><h3>2. System Architecture</h3><h3>2.1 Overall Pipeline Structure</h3><p>The entire system is divided into two parts: Voice Agent System and Conversation Analysis Pipeline.</p><p><strong>Voice Agent System</strong> handles calls through LiveKit Agent Sessions and records conversations. When a session ends, it publishes a message to a call-analysis start queue (e.g., call-analysis-start) via RabbitMQ.</p><p><strong>Conversation Analysis Pipeline</strong> receives messages and performs 3-step processing:</p><ol><li><strong>Step 0 — Transcriber</strong>: Speech transcription correction using Gemini 2.5 pro</li><li><strong>Step 1 — Analyzer</strong>: Conversation metadata extraction using Claude Sonnet 4.5 or GPT-4.1</li><li><strong>Step 2 — Summarizer</strong>: Conversation summary generation using GPT-4.1</li></ol><p>Once processing is complete, results are published to a backend API (DB storage) and an event bus (real-time event propagation).</p><h3>2.2 Asynchronous Processing</h3><p>Call analysis is processed <strong>asynchronously</strong>.</p><p>With synchronous processing, you would need to wait about 30 seconds after a call ends for analysis to complete before processing the next call, which is inefficient. With asynchronous processing, a message is published to MQ immediately after the call ends, and the next call can be processed right away. Analysis is handled by a separate service.</p><p><strong>Benefits of asynchronous processing:</strong></p><ul><li>Voice Agent focuses only on call handling</li><li>Analysis service can scale independently</li><li>Analysis failures don’t affect call service</li></ul><h3>2.3 Core Components</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/787/1*SoSLYzKWHqsZDxgnX-vd2w.png" /></figure><h3>3. Speech Transcription Correction (Step 0)</h3><h3>3.1 Limitations of Real-time STT</h3><p>Real-time speech processing using OpenAI Realtime API is fast but not perfect.</p><p><strong>Common issues:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/650/1*qas-Iqjkge6Ec4SF-DrS9A.png" /></figure><p><strong>What is a Ghost Message?</strong></p><p>A fake message that STT recognized even though the patient didn’t actually speak. For example, the actual audio contains patient silence or just background noise, but the STT result records a non-existent utterance like “Yes, I understand.”</p><h3>3.2 Gemini-based Correction System</h3><p>The solution is to <strong>re-listen to the original audio</strong>.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/635/1*YWo9vzxgvKG-hWvKiqYRqg.png" /></figure><p><strong>Why Gemini?</strong></p><p>Gemini 2.5 Pro is a multimodal model that can directly understand audio files. It can review audio and text together for correction.</p><p><strong>Processing steps:</strong></p><ol><li>Download audio file (wait until available from CDN)</li><li>Encode audio as Base64</li><li>Load prompt (different prompts for different models)</li><li>Send to Gemini with audio</li><li>Receive results as structured output</li></ol><h3>3.3 Ghost Message Handling</h3><p>Criteria for identifying Ghost Messages:</p><p><strong>Ghost Message deletion conditions:</strong></p><ul><li>The utterance is not audible in the audio</li><li>Only silence or noise exists</li><li>Contextually unnecessary utterance</li></ul><p><strong>Ghost Message retention conditions (exceptions):</strong></p><ul><li>DTMF messages (keypad input, no audio is normal)</li><li>Uncertain cases (hard to hear but might exist)</li><li>Assistant/Developer messages (Ground Truth)</li></ul><p><strong>Why DTMF handling is important:</strong></p><p>DTMF (Dual-Tone Multi-Frequency) is a telephone keypad input signal. For example, when a patient enters the last digits of their ID number, it’s recorded as “DTMF: 000102”.</p><p>DTMF is not voice, so it’s normal for it not to be in the audio file. It should not be mistaken for a Ghost Message and deleted.</p><h3>3.4 Prompt Design</h3><p>Key directives for transcription correction prompts:</p><p><strong>1. Message Filtering &amp; Reordering</strong></p><ul><li>Remove Ghost Messages: Delete if not in audio</li><li>Keep ALL DTMF Messages: Never delete DTMF</li><li>Reorder Sequences: Reorder according to actual audio sequence</li></ul><p><strong>2. Editing Scope</strong></p><ul><li>Modifiable: Only user message content can be modified</li><li>Immutable: Assistant, developer messages must never be modified</li></ul><p><strong>3. Metadata Handling</strong></p><ul><li>role: Preserve original</li><li>interrupted: Preserve original</li><li>start_time: Measure only for user, null for others</li></ul><p><strong>start_time measurement guide:</strong></p><ul><li><strong>Definition</strong>: Exact moment when the first syllable of user utterance begins (in seconds)</li><li><strong>Exclusions</strong>: Silence, breathing, background noise</li><li><strong>Procedure</strong>: Check previous assistant utterance end time → Measure gap between assistant end and user start → Compare with previous timestamp to verify order</li><li><strong>Format</strong>: Float (e.g., 21.5, 37.8)</li><li><strong>Constraint</strong>: Later messages must have larger start_time</li></ul><h3>4. Conversation Analysis (Step 1)</h3><h3>4.1 Metadata Extraction Goals</h3><p>The following information is automatically extracted from conversations:</p><p><strong>Agent transfer related:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*N9sc21AhvIO02wb0tY2gfg.png" /></figure><p><strong>Call termination related:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/989/1*Cth4GcFO7A-L3IpAMnxQEg.png" /></figure><h3>4.2 Structured Output with trustcall</h3><h4>What is trustcall?</h4><p><a href="https://github.com/hinthornw/trustcall">trustcall</a> is a library developed by William Hinthorn from the LangChain team, created to extract <strong>reliable structured output</strong> from LLMs.</p><p>When asking LLMs to generate or modify complex JSON schemas, they often fail or produce unexpected results. trustcall solves this problem through <strong>JSON Patch operations</strong>. Instead of regenerating the entire JSON, it asks the LLM to patch only the parts that need modification, achieving more stable and cost-effective results.</p><h4>Core Benefits of trustcall</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/938/1*CouFiOUc2jkky1bwuLRSNA.png" /></figure><h4>Basic Usage</h4><p>To use trustcall, first install it via pip: pip install trustcall</p><p>The usage process is divided into three main steps:</p><p><strong>Step 1: Define Schema</strong></p><p>Define the data structure you want to extract by inheriting from Pydantic’s BaseModel. Each field includes a type along with a detailed description using Field’s description parameter. This description plays a crucial role in helping the LLM understand what information to extract.</p><p>For example, to extract a user profile, add a description “User’s name” to the user_name field and &quot;List of user&#39;s interests&quot; to the interests field.</p><p><strong>Step 2: Create Extractor</strong></p><p>Use the create_extractor function to connect the LLM with the schema. Key parameters include:</p><ul><li>llm: LLM instance to use (e.g., ChatOpenAI, ChatAnthropic)</li><li>tools: List of Pydantic models to use for extraction</li><li>tool_choice: Tool name to use (same as model class name)</li><li>enable_inserts: When set to True, supports both new record creation and existing record updates</li></ul><p><strong>Step 3: Execute Extraction</strong></p><p>Pass messages to the created extractor’s invoke method to receive structured results. Input is a dictionary with conversation content in the messages key. Results are returned as a list of Pydantic model instances in the responses key.</p><h4>Application in Our Project</h4><p>For conversation analysis, we defined a Pydantic model called ConversationMetadataForLLM to define the metadata schema to extract from calls. Each field (e.g., positive_response, reservation_creation_complete) has a detailed description to guide the LLM in making accurate judgments.</p><p>For example, the agent_consultation_request field represents &quot;A state where agent consultation is still needed because AI couldn&#39;t resolve the issue,&quot; with True conditions including failed/incomplete agent transfer attempts in developer logs (e.g., [TRANSFER_OPERATION: RESULT=REQUESTED/FAILED/ERROR]) or when the assistant promises follow-up actions like &quot;I&#39;ll pass this to an agent.&quot;</p><h4>trustcall vs with_structured_output</h4><p>Differences between trustcall and LangChain’s basic with_structured_output method:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/720/1*QbBEIoILYWfqqC1zaCPDlg.png" /></figure><p>Especially for schemas like ours with 15+ boolean fields and complex conditions, trustcall provides much more stable results.</p><h4>References</h4><ul><li><a href="https://github.com/hinthornw/trustcall">trustcall GitHub Repository</a></li><li><a href="https://x.com/LangChainAI/status/1905663204593992096">LangChain Official Twitter Introduction</a></li><li><a href="https://dragonforest.in/trustcall-for-data-extraction-langgraph-tutorial/">trustcall Tutorial (Dragon Forest)</a></li></ul><h3>4.3 Applying Hard Rules</h3><p>When LLM judgment alone is insufficient, <strong>rule-based corrections</strong> are applied.</p><p><strong>Hard Rule 1: information_inquiry</strong></p><p>Set to True only when information lookup success logs exist. Even if the LLM judges True based only on conversation content, if a corresponding success log (e.g., [INFO_LOOKUP: RESULT=SUCCESS]) doesn&#39;t exist in actual logs, it&#39;s corrected to False.</p><p><strong>Hard Rule 2: transfer_call_request</strong></p><p>Set to True only when transfer success logs exist. Even if “Please connect me to an agent” was said in the conversation, the actual connection success must be determined by logs.</p><p><strong>Hard Rule 3: Enforce Mutual Exclusivity</strong></p><p>If transfer_call_request=True, set agent_consultation_request=False. If successfully connected to an agent, then &quot;agent transfer needed&quot; status is not applicable.</p><p><strong>Why are Hard Rules needed?</strong></p><p>Problems occur when using only LLM. For example, if the conversation content is “Please connect me to an agent” → AI: “I’ll connect you,” the LLM might judge transfer_call_request = True. But in reality, it only attempted connection, and success must be verified through logs.</p><p>If logs only show a transfer request (e.g., [TRANSFER_OPERATION: RESULT=REQUESTED]) without success, Hard Rules correct it to transfer_call_request = False, agent_consultation_request = True.</p><h3>4.4 Challenges in Prompt Design</h3><p>The most difficult part of analysis prompts is <strong>interpretation accounting for STT errors</strong>.</p><p><strong>Basic principle:</strong></p><p>Due to audio quality and STT limitations, user messages may contain content that doesn’t fit the conversation context or is unclear. When user messages don’t fit the context, prioritize analyzing the assistant message’s response patterns.</p><p><strong>AI response pattern analysis criteria:</strong></p><ul><li>When AI interprets positively with “Thank you for confirming”</li><li>When AI proceeds to next steps like appointment confirmation or change completion</li><li>When call termination reason is normal completion</li></ul><p><strong>Exception situations (AI response pattern analysis not applied):</strong></p><ul><li>When AI requests re-confirmation with “Could you say that again?”</li><li>When AI executes error handling protocol</li></ul><p><strong>Application example:</strong></p><p>Even if the user responded unclearly with “What?” but the assistant interpreted positively and proceeded with “Thank you for confirming. Here’s your appointment for December 17th at 10 AM,” judge positive_response = True (AI response pattern-based judgment).</p><h3>5. Conversation Summary (Step 2)</h3><h3>5.1 Summary Format Design</h3><p>Summaries consist of two fields:</p><ul><li><strong>title</strong>: One-line summary title</li><li><strong>content</strong>: Concise summary body</li></ul><p>Example output has title as “Appointment Confirmation — Patient Attendance Confirmed” and content as “- December 17th 10 AM Orthopedics appointment notification / — Patient attendance confirmed / — Parking information provided.”</p><h3>5.2 Patient-Centric Summaries</h3><p>The key to summaries is focusing on <strong>patient’s actions/reactions</strong>.</p><p><strong>Requirements:</strong></p><ul><li>title: Summarize outbound purpose + patient’s final status/requests in one line</li><li>content: Describe only key points concisely. Exclude unnecessary small talk, include only content needed for follow-up actions (rebooking, consultation needed, etc.)</li></ul><p><strong>Good summary vs bad summary:</strong></p><p>A bad summary lists the process: “AI greeted. Patient responded. AI confirmed again. Patient confirmed. Call ended.”</p><p>A good summary is result-focused: title is “Appointment Reminder — Attendance Confirmed” and content is “December 17th 10 AM Orthopedics appointment confirmed / Patient clearly confirmed attendance / Normal termination without additional inquiries.”</p><h3>6. Real-World Challenges</h3><h3>6.1 Audio File Availability</h3><p>When starting analysis immediately after a call ends, the recording file may not yet be uploaded to CDN.</p><p>After call termination, the recording file is uploaded to S3 (1–2 seconds) and CloudFront cache propagates (2–5 seconds) before the file becomes accessible. However, since MQ messages are published immediately, a 404 Error can occur when the analysis service receives the message but the file doesn’t exist yet.</p><p><strong>Solution: Polling with Retry</strong></p><p>We implemented logic to wait until the audio file is available on CDN. It checks file existence with HEAD requests and retries after a set time if not found.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/674/1*sfro8LPU-dk9xStzQ5AFTg.png" /></figure><h3>6.2 STT Hallucination</h3><p>The problem of STT recognizing speech that doesn’t exist.</p><p>In real situations, while a patient is silent for 3 seconds, STT might recognize “Yes yes yes I understand.” This is because background noise is mistaken for voice, or the model overfits to frequently occurring patterns and expects them.</p><p><strong>Solution: Audio-based verification</strong></p><p>Prompt instructions direct to “delete if the utterance is not heard in the audio.” However, in uncertain cases (might exist but hard to hear), the original is preserved.</p><h3>6.3 DTMF Message Handling</h3><p>DTMF is a keypad input signal, not voice.</p><p>When a patient enters the last digits of their ID as 0–0–0–1–0–2, the conversation log records 6 messages like “DTMF: 0”, “DTMF: 0”, “DTMF: 0”, “DTMF: 1”, “DTMF: 0”, “DTMF: 2”.</p><p><strong>Problem: Mistaken for Ghost Message</strong></p><p>The “DTMF: 0” utterance isn’t heard in the audio (of course, it’s keypad input). If judged as Ghost Message and deleted, important information is lost.</p><p><strong>Solution: DTMF Exception Handling</strong></p><p>We explicitly added instructions to the prompt: “DTMF messages are keypad input signals, NOT voice. No audio exists for DTMF — do NOT treat as ghost messages. Preserve EVERY DTMF message exactly as-is. Do NOT deduplicate, merge, or delete any DTMF messages. Set start_time to null for DTMF messages.”</p><h3>7. Conclusion</h3><h3>7.1 Lessons Learned</h3><p><strong>1. STT Quality Can Be Improved Through Post-processing</strong></p><p>Accepting the limitations of real-time STT and taking an approach of re-listening to audio afterward for correction was effective. Real-time processing is fast but can be inaccurate, and post-correction is accurate but takes time. Both are needed. Process calls in real-time, correct afterward.</p><p><strong>2. LLM + Hard Rules Combination</strong></p><p>LLM alone cannot accurately handle all cases. When clear criteria exist (log-based judgment), rule-based correction is more stable.</p><p>LLM’s strengths are context understanding and flexible judgment; weaknesses are occasional errors and inconsistency. Hard Rules’ strengths are 100% consistency and predictability; weakness is lack of flexibility. The combination is best.</p><p><strong>3. Benefits of Asynchronous Pipeline</strong></p><p>Operating the analysis service independently means analysis failures don’t affect call service, analysis logic changes can be deployed separately, and independent scaling is possible based on load.</p><h3>7.2 Future Improvements</h3><p><strong>1. Real-time Analysis</strong></p><p>What if we provided insights <strong>during the call</strong> rather than after it ends? We could provide patient sentiment analysis (suggest agent transfer if negative), intent prediction (seems to want to change appointment), real-time guidance (this patient has previous cancellation history).</p><p><strong>2. Multilingual Transcription Quality Improvement</strong></p><p>Currently Korean-focused, but transcription quality improvement is needed when handling foreign language patients.</p><p><strong>3. Feedback Loop</strong></p><p>A loop is needed to verify if analysis results were correct and improve models/prompts when wrong. The cycle: Analysis result → Agent verification → Feedback collection → Prompt improvement → Better analysis.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b2c6f1245be5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building a Call Voice AI Assistant with LiveKit Agents]]></title>
            <link>https://medium.com/@kofsitho/building-a-call-voice-ai-assistant-with-livekit-agents-ee6234aa07ef?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/ee6234aa07ef</guid>
            <category><![CDATA[livekit]]></category>
            <category><![CDATA[ai-voice-agent]]></category>
            <category><![CDATA[voice-assistant]]></category>
            <category><![CDATA[customer-service-agent]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Wed, 14 Jan 2026 09:57:33 GMT</pubDate>
            <atom:updated>2026-01-26T11:01:28.562Z</atom:updated>
            <content:encoded><![CDATA[<p>Sharing Our Experience Developing AI Call Agent</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aWC2cV4gRps3Nq_RxDbzmw.png" /></figure><h3>Table of Contents</h3><ol><li><a href="#1-introduction">Introduction</a></li></ol><ul><li>The Reality of Hospital Phone Operations</li><li>Problems We’re Solving with Voice AI</li><li>What This Article Covers</li></ul><p><a href="#2-tech-stack-and-architecture">2. Tech Stack and Architecture</a></p><ul><li>Why LiveKit Agents?</li><li>Overall System Architecture</li><li>Core Components</li><li>Call Lifecycle</li><li>Multi-language Support</li></ul><p><a href="#3-multi-agent-design-philosophy">3. Multi-Agent Design Philosophy</a></p><ul><li>Limitations of a Single Agent</li><li>Role-Based Agent Separation Strategy</li><li>Agent Role Definitions</li><li>BaseAgent Common Functionality</li></ul><p><a href="#4-implementing-infoagent">4. Implementing InfoAgent</a></p><ul><li>Hospital Information Search Requirements</li><li>Leveraging Qdrant Vector DB</li><li>Information Search Tool Design</li></ul><p><a href="#5-implementing-bookingagent">5. Implementing BookingAgent</a></p><ul><li>Booking Flow Design</li><li>Booking Tools Overview</li><li>Multi-turn Conversation Handling: Using AgentTask</li></ul><p><a href="#6-agent-routing-transitions">6. Agent Routing (Transitions)</a></p><ul><li>Role of TriageCoordinator</li><li>Context Passing Methods</li><li>Audio Input Control</li></ul><p><a href="#7-real-world-challenges">7. Real-World Challenges</a></p><ul><li>Natural Language Date/Time Parsing</li><li>Handling User Silence</li><li>Counselor Connection Fallback</li><li>Answering Machine (ARS) Detection</li><li>Prompt System Structure</li></ul><p><a href="#8-call-termination-and-post-processing">8. Call Termination and Post-Processing</a></p><ul><li>Handling Different Termination Scenarios</li><li>Post-Session Processing</li></ul><p><a href="#9-conclusion">9. Conclusion</a></p><ul><li>Lessons Learned</li><li>Areas for Improvement</li><li>Next Article Preview</li></ul><h3>1. Introduction</h3><h3>1.1 The Reality of Hospital Phone Operations</h3><p>Have you ever called a hospital?</p><pre>&quot;I&#39;ve been on hold for 10 minutes just to confirm an appointment...&quot;<br>&quot;They don&#39;t answer during lunch break...&quot;<br>&quot;I just wanted to ask about office hours but it took forever to reach someone&quot;</pre><p>Hospitals face the same challenge. They receive hundreds of calls daily, but many are repetitive questions.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/650/1*k9s0RSCCvHtLoyHkfKD96g.png" /></figure><p>We noticed that <strong>85% of calls are simple tasks that AI can handle</strong>.</p><h3>1.2 Problems We’re Solving with Voice AI</h3><p>Our goal was to build a <strong>24/7 AI phone assistant for hospitals</strong>.</p><p><strong>Objectives:</strong></p><ul><li>AI directly handles appointment queries, creation, and changes</li><li>Instant hospital information (hours, location, doctors)</li><li>Complex inquiries routed to human agents</li><li>Natural voice conversation in multiple languages</li></ul><p><strong>Expected Benefits:</strong></p><ul><li>Patients: Immediate response without waiting</li><li>Hospitals: Staff can focus on complex tasks</li><li>24/7: Basic inquiries handled even nights/weekends</li></ul><h3>1.3 What This Article Covers</h3><p>This article shares our experience building a hospital voice AI using the LiveKit Agents framework.</p><p><strong>Topics Covered:</strong></p><ul><li>Multi-Agent architecture design (InfoAgent + BookingAgent)</li><li>Hospital information search using Qdrant Vector DB</li><li>Multi-turn booking conversations (AgentTask)</li><li>Real-world problems and solutions</li></ul><p><strong>Not Covered:</strong></p><ul><li>LiveKit server installation/setup (see official docs)</li><li>SIP trunk detailed configuration</li><li>Frontend implementation</li></ul><p>Let’s get started.</p><h3>2. Tech Stack and Architecture</h3><h3>2.1 Why LiveKit Agents?</h3><p>There are several options for building voice AI: Twilio, Vonage, direct WebRTC implementation, etc. Here’s why we chose LiveKit Agents:</p><p><strong>LiveKit Agents Advantages:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/765/1*MHTwW6X3dVGzfLxDpoHPjQ.png" /></figure><p>The built-in <strong>Multi-Agent transition</strong> capability was decisive. Separating and dynamically switching between Booking Agent and Info Agent was seamlessly possible.</p><h3>2.2 Overall System Architecture</h3><pre>┌─────────────────────────────────────────────────────────────────────┐<br>│                         Outbound Trigger                             │<br>│                      (RabbitMQ Message)                              │<br>└─────────────────────────────┬───────────────────────────────────────┘<br>                              │<br>                              ▼<br>┌─────────────────────────────────────────────────────────────────────┐<br>│                       Agent Server                                   │<br>│  ┌─────────────────────────────────────────────────────────────┐   │<br>│  │                    LiveKit Room Creation                     │   │<br>│  │                 SIP Outbound Call Initiation                 │   │<br>│  └─────────────────────────────────────────────────────────────┘   │<br>└─────────────────────────────┬───────────────────────────────────────┘<br>                              │<br>                              ▼<br>┌─────────────────────────────────────────────────────────────────────┐<br>│                      Multi-Agent System                              │<br>│                                                                      │<br>│   ┌─────────────────┐                                               │<br>│   │TriageCoordinator│ ◄─── Entry Point                              │<br>│   │ (Intent Routing) │      Routes based on user intent             │<br>│   └────────┬────────┘                                               │<br>│            │                                                         │<br>│    ┌───────┴───────┐                                                │<br>│    ▼               ▼                                                │<br>│ ┌──────────┐  ┌──────────┐                                          │<br>│ │ Booking  │  │   Info   │                                          │<br>│ │  Agent   │  │  Agent   │                                          │<br>│ │(Booking) │  │  (Info)  │                                          │<br>│ └────┬─────┘  └────┬─────┘                                          │<br>│      │             │                                                 │<br>└──────┼─────────────┼────────────────────────────────────────────────┘<br>       │             │<br>       ▼             ▼<br>┌────────────┐  ┌────────────┐<br>│ Booking    │  │  Qdrant    │<br>│   API      │  │ Vector DB  │<br>│(Appt CRUD) │  │(Hosp Info) │<br>└────────────┘  └────────────┘</pre><h3>2.3 Core Components</h3><h4>LiveKit Agents Framework</h4><p>LiveKit Agents are implemented by inheriting the Agent class. System prompts go in instructions, and functions are registered in tools.</p><h4>OpenAI Realtime API</h4><p>The traditional approach was a Speech → STT → LLM → TTS → Speech pipeline. OpenAI Realtime API handles this in a single call, significantly reducing latency.</p><pre>Traditional: Speech → [STT] → Text → [LLM] → Text → [TTS] → Speech<br>                     (200ms)        (500ms)        (200ms)</pre><pre>Realtime: Speech → [OpenAI Realtime] → Speech<br>                       (300ms~)</pre><h4>Qdrant Vector DB</h4><p>Hospital information (doctors, departments, events) is stored in Qdrant Vector DB for semantic search. Topic-based metadata structure enables filtering by hospital and category.</p><h4>LiveKit SIP</h4><p>SIP trunks are used for actual phone network integration. LiveKit acts as a SIP gateway, enabling calls to/from regular phones.</p><h3>2.4 Call Lifecycle</h3><p>The complete lifecycle of an outbound call follows these state transitions:</p><pre>IDLE → DIALING → RINGING → CONNECTED → ACTIVE → TERMINATED<br>  │       │         │          │         │          │<br>  │       │         │          │         │          └─→ ANALYZED<br>  │       │         │          │         │<br>  │       │         │          │         └─→ TRANSFERRED → TERMINATED<br>  │       │         │          │<br>  │       │         │          └─→ RECORDING_STARTED<br>  │       │         │<br>  │       │         └─→ NO_ANSWER → TERMINATED<br>  │       │<br>  │       └─→ BUSY → TERMINATED<br>  │<br>  └─→ ERROR → TERMINATED</pre><p><strong>Key Stages:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/587/1*HHbfQEyq_6PczeSlSFohgQ.png" /></figure><h3>2.5 Multi-language Support</h3><p>Multi-language support in voice AI isn’t just text translation. Both Speech Recognition (STT) and Text-to-Speech (TTS) must support the target language.</p><p><strong>Implementation:</strong></p><ul><li>Language code set in CallConfigData (e.g., &quot;ko-KR&quot;)</li><li>Language passed to LLM model parameters</li><li>Prompt includes “use only this language” constraint</li></ul><h3>3. Multi-Agent Design Philosophy</h3><h3>3.1 Limitations of a Single Agent</h3><p>Initially, we tried handling all functions with a single Agent.</p><p><strong>Problems:</strong></p><ul><li>Prompts exceeded 200 lines, causing the model to miss instructions</li><li>With 14 tools, wrong tool calls became frequent</li><li>Modifying booking logic risked affecting information responses, making maintenance difficult</li></ul><h3>3.2 Role-Based Agent Separation Strategy</h3><p>The solution was <strong>separating Agents by role</strong>.</p><pre>Before (Single Agent):<br>┌─────────────────────────────────┐<br>│         HospitalAgent           │<br>│  Prompt: 200 lines | Tools: 14  │<br>│  Role: Booking + Info + ...     │<br>└─────────────────────────────────┘</pre><pre>After (Multi-Agent):<br>┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐<br>│TriageCoordinator│  │  BookingAgent   │  │    InfoAgent    │<br>│ Prompt: 40 lines│  │ Prompt: 50 lines│  │ Prompt: 40 lines│<br>│ Tools: 3        │  │ Tools: 5        │  │ Tools: 6        │<br>│ Role: Routing   │  │ Role: Booking   │  │ Role: Info      │<br>└─────────────────┘  └─────────────────┘  └─────────────────┘</pre><p><strong>Improvements After Separation:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/585/1*WWdl57H3B6asrOTUFNFTqw.png" /></figure><h3>3.3 Agent Role Definitions</h3><h4>TriageCoordinator (Intent Classification)</h4><p>Listens to the user’s first utterance and routes to the appropriate Agent.</p><ul><li>Booking-related → Transfer to BookingAgent</li><li>Information inquiry → Transfer to InfoAgent</li><li>Agent request → Handle human agent connection</li></ul><h4>BookingAgent (Booking Processing)</h4><p>Handles appointment queries, creation, and modifications.</p><ul><li>Department selection</li><li>Date/time selection</li><li>Appointment creation</li></ul><h4>InfoAgent (Information Provision)</h4><p>Handles hospital information search and guidance.</p><ul><li>Hospital introduction, hours</li><li>Directions, parking</li><li>Doctors, services, events</li></ul><h3>3.4 BaseAgent Common Functionality</h3><p>Common functions needed by all three Agents were extracted into BaseAgent.</p><p><strong>Common Functions:</strong></p><ul><li>on_enter(): Context handling on Agent entry</li><li>transfer_to_agent(): Inter-Agent transition</li><li>transfer_call(): Human agent connection</li><li>end_call_by_user_request(): Call termination</li><li>hangup(): Room deletion</li></ul><p>By consolidating common functions in BaseAgent, each Agent can focus solely on its role.</p><h3>4. Implementing InfoAgent</h3><h3>4.1 Hospital Information Search Requirements</h3><p>Here are the information types InfoAgent must handle:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/698/1*o0qxf0to_BjS-_cObltWQg.png" /></figure><p><strong>Key Requirements:</strong></p><ol><li><strong>Semantic Search</strong>: “Dr. Kim” → “Dr. Chulsu Kim” matching</li><li><strong>Filtering</strong>: Separate data by topic and hospital</li><li><strong>Dynamic Data</strong>: Event period checking</li></ol><h3>4.2 Leveraging Qdrant Vector DB</h3><h4>Topic-Based Data Structuring</h4><p>All hospital information is stored in a single collection, classified by metadata.</p><p><strong>Topic Classification System:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/843/1*5HNiDyiASUowY263AY9XVg.png" /></figure><h4>Metadata Filtering Strategy</h4><p>Searches always filter by client.id and topic to return only accurate data.</p><h3>4.3 Information Search Tool Design</h3><p>Key tools used by InfoAgent:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/787/1*TagNND1BhhnWgYuDbdr3uQ.png" /></figure><h3>4.4 Key Design Points</h3><p><strong>Important considerations for InfoAgent design:</strong></p><ol><li><strong>Clear Role Definition</strong>: Limited scope as “information guide”</li><li><strong>No Guessing</strong>: Emphasize using only tool search results</li><li><strong>Transition Rules</strong>: Transfer to BookingAgent for booking inquiries</li><li><strong>Response Examples</strong>: Provide expected behavior patterns</li></ol><h3>5. Implementing BookingAgent</h3><h3>5.1 Booking Flow Design</h3><p>Hospital booking seems simple but requires multiple steps.</p><pre>User: &quot;I&#39;d like to make an appointment&quot;<br>          │<br>          ▼<br>    ┌─────────────┐<br>    │ Select Dept │ ← get_medical_departments()<br>    └──────┬──────┘<br>           │<br>           ▼<br>    ┌─────────────┐<br>    │ Confirm Date│ ← &quot;next Tuesday&quot; → &quot;2024-12-17&quot;<br>    └──────┬──────┘<br>           │<br>           ▼<br>    ┌─────────────┐<br>    │ Select Time │ ← select_available_schedules()<br>    └──────┬──────┘<br>           │<br>           ▼<br>    ┌─────────────┐<br>    │Create Appt  │ ← add_new_appointment()<br>    └──────┬──────┘<br>           │<br>           ▼<br>    &quot;Your appointment has been scheduled&quot;</pre><p><strong>Key Challenges:</strong></p><ul><li>Natural language date (“next Tuesday”) → ISO date conversion</li><li>Multi-turn conversation for information gathering (date → time → confirmation)</li><li>Handle mid-flow exits or change requests</li></ul><h3>5.2 Booking Tools Overview</h3><p>Key tools used by BookingAgent:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/863/1*tR_bWZJOHR4FUknoFfQoqQ.png" /></figure><h3>5.3 Multi-turn Conversation Handling: Using AgentTask</h3><p>Appointment time selection requires multiple conversation turns. We implemented this using LiveKit’s AgentTask.</p><h4>What is AgentTask?</h4><p>A regular function_tool executes once and ends, but AgentTask can have <strong>its own conversation loop</strong>.</p><h4>ScheduleSelectionTask State Flow</h4><pre>collect_date → confirm_date → select_time → complete</pre><ol><li><strong>collect_date</strong>: Ask for desired date</li><li><strong>confirm_date</strong>: Confirm interpreted date (“Is December 17th correct?”)</li><li><strong>select_time</strong>: Present available times and get selection</li><li><strong>complete</strong>: Selection complete, Task ends</li></ol><h3>5.4 Booking Flow Summary</h3><ul><li>StepToolDescription1get_medical_departmentsDepartment</li><li>selection2select_available_schedulesDate/time selection (multi-turn Task)</li><li>create_new_appointmentCreate appointment</li></ul><h3>6. Agent Routing (Transitions)</h3><h3>6.1 Role of TriageCoordinator</h3><p>TriageCoordinator acts as a <strong>switchboard operator</strong>. It receives the call, understands the purpose, and connects to the appropriate handler (Agent).</p><pre>┌─────────────────────────────────────────────────────────┐<br>│                   TriageCoordinator                      │<br>│                                                          │<br>│  User: &quot;I&#39;d like to make an appointment&quot;                │<br>│                │                                         │<br>│                ▼                                         │<br>│  ┌─────────────────────────┐                            │<br>│  │ Intent Classification    │                            │<br>│  │ - Booking keyword detect │                            │<br>│  │ - Call route_to_booking  │                            │<br>│  └───────────┬─────────────┘                            │<br>│              │                                           │<br>│              ▼                                           │<br>│  ┌─────────────────────────┐                            │<br>│  │ Transfer to BookingAgent│                            │<br>│  │ + Pass user utterance   │                            │<br>│  └─────────────────────────┘                            │<br>└─────────────────────────────────────────────────────────┘</pre><p><strong>TriageCoordinator Routing Branches:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/830/1*PaotpsplziSRM1rhVN6dSw.png" /></figure><h3>6.2 Context Passing Methods</h3><p>When transitioning Agents, <strong>the user’s original utterance</strong> must be passed to the next Agent. Otherwise, the next Agent has to ask from the beginning.</p><pre># Wrong: No context passing<br>User: &quot;I&#39;d like to book internal medicine&quot;<br>Triage → Booking transition<br>Booking: &quot;Which department would you like?&quot; ← Asks again (bad UX)</pre><pre># Correct: Context passing<br>User: &quot;I&#39;d like to book internal medicine&quot;<br>Triage → Booking transition (user_request=&quot;I&#39;d like to book internal medicine&quot;)<br>Booking: &quot;I&#39;ll help with internal medicine. What date works for you?&quot; ← Natural</pre><h3>6.3 Audio Input Control (set_audio_enabled)</h3><p>If users keep talking during Agent transitions, confusion occurs. To prevent this, <strong>audio input is temporarily blocked during transitions</strong>.</p><p><strong>Why is this needed?</strong></p><pre>Without audio control:<br>User: &quot;I want to book internal medicine next week&quot;<br>       ├── Triage hears &quot;book&quot; and starts transition<br>       ├── &quot;internal medicine next week&quot; stays with Triage<br>       └── Booking doesn&#39;t receive it → Has to ask again</pre><pre>With audio control:<br>User: &quot;I want to book&quot;<br>       ├── Triage: calls route_to_booking<br>       ├── set_audio_enabled(False) → Block input<br>       ├── Agent transition complete<br>       ├── set_audio_enabled(True) → Resume input<br>       └── User: &quot;internal medicine&quot; → Booking receives normally</pre><h3>7. Real-World Challenges</h3><h3>7.1 Natural Language Date/Time Parsing</h3><p>Users don’t say dates like “2024–12–20”.</p><p><strong>Actual User Utterances:</strong></p><ul><li>“Next Tuesday”</li><li>“End of this month”</li><li>“Day before Christmas”</li><li>“Tomorrow morning”</li><li>“The 12th” (month omitted)</li></ul><h4>Solution Strategy</h4><p>Rule-based parsing has limitations, so we <strong>use LLM to convert natural language to ISO dates</strong>.</p><p>Passing today’s date along with the user’s expression allows the LLM to convert “next Tuesday” to “2024–12–17” format.</p><p>Korean time expressions (“9 AM”, “3:30 PM”) are also handled with separate parsing logic.</p><h3>7.2 Handling User Silence</h3><p>Surprisingly many cases where people answer but say nothing.</p><p><strong>Silence Scenarios:</strong></p><ul><li>Answered but surroundings too noisy to hear</li><li>Answered but doing something else</li><li>Answering machine picked up</li></ul><h4>Solution Strategy: Using user_state_changed Event</h4><p>LiveKit notifies user state changes via events.</p><ul><li>Start confirmation task when away state detected</li><li>Cancel task if user speaks</li><li>End call after 2 silent attempts</li></ul><h3>7.3 Counselor Connection Fallback</h3><p>AI can’t handle everything. Cases requiring human agent connection:</p><ul><li>User explicitly requests (“Connect me to a representative”)</li><li>Complex inquiries AI can’t handle</li><li>Emergency situations</li></ul><h4>Solution Strategy</h4><p>Behavior varies based on configuration:</p><ul><li><strong>AI Booking Mode</strong>: BookingAgent directly handles booking</li><li><strong>Agent Connection Mode</strong>: Attempt SIP transfer</li><li><strong>No Transfer Number Set</strong>: Collect message only and end</li></ul><h3>7.4 Answering Machine (ARS) Detection</h3><p>Outbound calls sometimes connect to answering machines. The AI shouldn’t keep trying to converse.</p><p><strong>Detection Conditions (all 3 must be met):</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/825/1*ir_uJahulT5sasbUa1zxOQ.png" /></figure><p><strong>Why all 3 conditions required?</strong></p><pre>Checking only 1 condition → High false positives<br>  e.g., &quot;Hello&quot; auto-greeting ≠ Answering machine</pre><pre>Checking all 3 conditions → High accuracy<br>  e.g., Auto greeting + Button prompt + Repetition = Definite answering machine</pre><p>Detection triggers call termination and logs the detection event to history.</p><h3>7.5 Prompt System Structure</h3><p>Voice AI quality heavily depends on prompt design. We use YAML-formatted structured prompts.</p><p><strong>Prompt Sections:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/825/1*ir_uJahulT5sasbUa1zxOQ.png" /></figure><p><strong>Conversation Flow Rules:</strong></p><pre>1. Greeting (max 2 attempts)<br>   └─ Turn 1: Initial greeting<br>   └─ Turn 2: Hospital name + purpose (brief)<br>   └─ Turn 2+: No more greeting attempts</pre><pre>2. Main Conversation<br>   └─ Handle user requests<br>   └─ Tool calls</pre><pre>3. Closing<br>   └─ Summary + Farewell</pre><p><strong>Safety &amp; Escalation Rules:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/647/1*iJbuqSVW-sFMQwmEa6CwPQ.png" /></figure><h3>8. Call Termination and Post-Processing</h3><h3>8.1 Handling Different Termination Scenarios</h3><p>Call termination occurs through various paths. Each scenario needs appropriate handling.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/676/1*wQe-ZmhNk-NkHn4VuSVsGw.png" /></figure><h3>8.2 Post-Session Processing</h3><p>Several post-processing tasks are needed after call termination.</p><p><strong>Post-Processing Tasks:</strong></p><ol><li><strong>Stop Recording</strong>: Stop Egress and save file</li><li><strong>Call Complete Notification</strong>: Publish MQ message</li><li><strong>Conversation Analysis Request</strong>: Publish MQ message</li><li><strong>Transcript Save</strong>: Save locally for debugging in local environment</li></ol><p><strong>Data Sent to Analysis Service:</strong></p><ul><li>Call session info (room_name, recipient, business, time info)</li><li>Full conversation history (role, content)</li></ul><h3>9. Conclusion</h3><h3>9.1 Lessons Learned</h3><h4>The Power of Multi-Agent</h4><p>After experiencing chaos with a single Agent handling everything — 200-line prompts, 14 tools — we truly felt the <strong>importance of role separation</strong>.</p><pre>Before: One all-purpose Agent → Complex, unstable, hard to maintain<br>After: Role-specific Agents → Simple, stable, independent modifications possible</pre><h4>Importance of Framework Selection</h4><p>LiveKit Agents provided framework-level support for Multi-Agent transitions, voice processing, and SIP integration, speeding up development. Direct WebRTC handling or implementing Agent transition logic ourselves would have taken much longer.</p><h4>Real Users Behave Unexpectedly</h4><ul><li>Natural language date expressions like “next Tuesday”</li><li>Cases of silence after answering</li><li>Suddenly switching to different questions mid-conversation</li></ul><p>Rule-based approaches have limits, making LLM utilization essential.</p><h3>9.2 Areas for Improvement</h3><h4>Conversation Flow Enhancement</h4><p>Currently using step-by-step questions, but want better handling when users provide lots of information at once.</p><pre>Current: &quot;Date?&quot; → &quot;December 17th&quot; → &quot;Time?&quot; → &quot;10 AM&quot;<br>Goal: &quot;Book for December 17th at 10 AM please&quot; → Process at once</pre><h4>Monitoring Dashboard</h4><p>Need a real-time dashboard showing call success rate, average processing time, frequently asked questions, etc.</p><h3>9.3 Next Article Preview</h3><p>The next article will cover more advanced topics:</p><ul><li><strong>AgentTask Deep Dive</strong>: Implementing complex multi-turn conversation patterns</li><li><strong>Performance Optimization</strong>: Reducing latency, prompt tuning</li><li><strong>Call Analysis Pipeline</strong>: Conversation analysis and insight extraction</li></ul><h3>Final Thoughts</h3><p>Building this hospital voice AI taught us that <strong>“a single phone call” is more complex than it seems</strong>.</p><p>Beyond simply answering questions:</p><ul><li>Understanding user intent</li><li>Multi-turn information gathering</li><li>Exception handling (silence, answering machines)</li><li>Human agent connection fallback</li><li>Post-call processing</li></ul><p>Handling all of this naturally is what makes a true “AI assistant.”</p><p>Thanks to LiveKit Agents, we could implement these complex requirements relatively quickly. We hope this helps those considering voice AI.</p><p>Questions and feedback are always welcome!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ee6234aa07ef" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Part 2: Architecting a Medical AI Assistant: A Deep Dive into Our LangGraph-Powered Architecture]]></title>
            <link>https://medium.com/@kofsitho/part-2-architecting-a-medical-ai-assistant-a-deep-dive-into-our-langgraph-powered-architecture-f17b51f8883d?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/f17b51f8883d</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[langgraph]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Fri, 20 Jun 2025 04:41:52 GMT</pubDate>
            <atom:updated>2025-06-20T04:41:52.789Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>This article details the technical decisions and architectural design behind our medical AI counseling system. We explore why LangGraph became our framework of choice over other popular options like LangChain, CrewAI, and AutoGen, and how its unique features helped us build a robust, production-ready agent.</blockquote><h3>The Framework Dilemma: Choosing the Right Engine for Our AI Agent</h3><p>The first major challenge in building our medical AI assistant was a critical one: which AI agent framework should we use? In early 2024, the AI agent ecosystem was exploding with options, each with its own philosophy and strengths.</p><p>Our main contenders were:</p><ul><li><strong>LangChain</strong>: The most popular and mature framework in the ecosystem.</li><li><strong>LangGraph</strong>: A newer, graph-based addition to the LangChain family.</li><li><strong>CrewAI</strong>: A framework focused on role-based multi-agent systems.</li><li><strong>AutoGen</strong>: Microsoft’s framework for conversational multi-agent systems.</li><li><strong>OpenAI Swarm</strong>: A lightweight framework designed for educational purposes.</li></ul><p>To make an informed decision, we tested each framework and evaluated them based on the criteria that mattered most for our production-level medical AI agent.</p><h4>Our Framework Comparison</h4><p>Here’s a summary of our findings:</p><figure><img alt="A summary of our comparative analysis, scoring each framework on its ability to meet our project’s core requirements." src="https://cdn-images-1.medium.com/max/1024/1*0_LbVBMJiWN4PBwnc88aOg.png" /><figcaption><em>A summary of our comparative analysis, scoring each framework on its ability to meet our project’s core requirements.</em></figcaption></figure><h3>The Decisive Reasons for Choosing LangGraph</h3><p>While the table gave a high-level overview, four key features of LangGraph sealed the deal. They directly addressed the core challenges of building a reliable, context-aware AI assistant.</p><h4>1. Powerful State Management with StateGraph</h4><p>For a medical AI assistant, maintaining conversational context is non-negotiable. If a user asks, “Where is the parking lot for that clinic?” the system must remember which clinic was previously discussed. LangGraph’s StateGraph provides a simple yet powerful way to manage this.</p><p>We defined a State for our graph, which acts as the central memory for the entire conversation.</p><pre># A simplified example of our actual implementation<br>from typing import TypedDict, Annotated, Sequence<br>from langchain_core.messages import BaseMessage<br><br>class State(TypedDict):<br>    # A sequence of messages, with new ones added at each step<br>    messages: Annotated[Sequence[BaseMessage], add_messages]<br>    # More complex context is managed through a separate Configuration</pre><p>This explicit, persistent state model was a game-changer compared to other frameworks:</p><ul><li>LangChain: While it allows information to be passed between chains, managing a continuous, evolving state across a full conversation is cumbersome.</li><li>CrewAI: Offers automated state management, which is convenient but offers limited customization for our specific domain needs.</li><li>AutoGen: Supports state management but requires more complex configuration.</li></ul><h4>2. Intelligent Tool Selection with a ReAct Agent Pattern</h4><p>In a medical context, user queries can span a wide range of topics, from clinic hours to treatment details. Instead of writing complex, rigid routing logic, we needed the LLM to autonomously select the right tool for the job. LangGraph’s native support for the ReAct (Reason and Act) agent pattern made this incredibly straightforward.</p><p>Our implementation is simple but effective: the agent assesses the user’s input, decides if a tool is needed, and selects one from a predefined set of six tools.</p><p>The ReAct Agent Flow in LangGraph:</p><pre># React Agent Pattern<br>def route_primary_assistant(state: State):<br>    route = tools_condition(state)<br>    if route == END:<br>        return END<br>    tool_calls = state[&quot;messages&quot;][-1].tool_calls<br>    if tool_calls:<br>        return &quot;primary_assistant_tools&quot;<br>    raise ValueError(&quot;Invalid route&quot;)</pre><ol><li>User Input: The agent receives the user’s question.</li><li>Primary Assistant (LLM): The LLM analyzes the message.</li><li>Tool Check: The LLM decides if it needs to use a tool to answer the question.</li></ol><ul><li>If Yes: It calls the appropriate tool (e.g., get_visit_guide, get_medical_staffs). The tool’s output is fed back to the assistant.</li><li>If No: It generates a direct response to the user.</li></ul><p>4. Response/End: The final answer is delivered, or the conversation ends.</p><p>This pattern allows the LLM to dynamically route the conversation, making the system flexible and intelligent without needing a complex web of if/else statements.</p><h4>3. Stability and Reliability for Production Environments</h4><p>Since this system would be used by real healthcare providers, stability and robust error handling were paramount. LangGraph provided several advantages for building a production-grade service:</p><ul><li>Explicit State Definition: The graph’s behavior is predictable because its state is clearly defined, making it easier to debug and maintain.</li><li>Robust Error Handling: We could implement exception handling at each node, isolating failures without crashing the entire system.</li><li>Easy Debugging: The graph structure allows us to visualize the execution flow, making it simple to trace the conversation’s path and identify issues.</li><li>Seamless LangSmith Integration: Out-of-the-box integration with LangSmith gave us real-time monitoring and debugging, which proved invaluable during development and testing.</li></ul><h4>4. Scalability and Modularity by Design</h4><p>Our system needed to support six different domains (e.g., clinic introductions, visitor guides, medical staff info). LangGraph’s modular design made it easy to build and manage these as separate, independent tools.</p><p>All our tools are managed within a single ToolNode. This design follows the Single Responsibility Principle, where each tool is responsible for one specific domain.</p><pre># Our toolset is a simple list of functions<br>primary_assistant_tools = [<br>    get_introduction,<br>    get_visit_guide, <br>    get_medical_staffs,<br>    get_medical_services,<br>    get_certificate,<br>    get_events<br>]<br><br># The graph uses a dedicated node to execute these tools<br>builder.add_node(&quot;primary_assistant_tools&quot;, create_tool_node_with_fallback(primary_assistant_tools))</pre><p>Adding a new capability is incredibly simple. For example, if we wanted to add a tool for insurance information, we would:</p><ol><li>Create a new tool function, get_insurance_info.</li><li>Add it to the primary_assistant_tools list.</li></ol><p>That’s it. The agent would automatically be able to use the new tool without requiring any changes to the core graph logic. This modularity ensures our system is both scalable and easy to maintain.</p><h3>Why Other Frameworks Didn’t Make the Cut</h3><p>While other frameworks are powerful in their own right, they presented challenges that would have complicated our development process and final architecture.</p><h4>Why Not LangChain?</h4><p>LangChain’s biggest drawback for us was its inherently linear structure. Chains are designed as a sequence of steps, which is perfect for straightforward tasks but becomes cumbersome for dynamic, multi-turn conversations.</p><pre># The linear nature of LangChain&#39;s LCEL<br>chain = (<br>    prompt_template <br>    | llm <br>    | output_parser <br>    | next_step<br>)</pre><p>This approach created three main issues for our use case:</p><ol><li><strong>Complex Branching</strong>: Implementing the conditional logic our agent required (e.g., “if the user asks X, use tool Y, otherwise do Z”) was not as intuitive.</li><li><strong>State Management</strong>: While possible, maintaining context across a long and branching conversation felt less natural than LangGraph’s explicit state.</li><li><strong>Scalability</strong>: Adding new tools or capabilities often meant rethinking or rebuilding significant parts of the chain.</li></ol><h4>Why Not CrewAI?</h4><p>CrewAI is excellent for orchestrating multiple agents with distinct roles. However, it was too high-level for our needs.</p><pre># CrewAI&#39;s role-based agent structure<br>crew = Crew(<br>    agents=[doctor_agent, receptionist_agent, manager_agent],<br>    tasks=[task1, task2, task3],<br>    process=Process.hierarchical<br>)</pre><p>The main limitations were:</p><ol><li>Limited Customization: We needed fine-grained control over the agent’s internal logic to handle specific medical domain queries, which was difficult with CrewAI’s abstractions.</li><li>“Black Box” Behavior: The automated processes, while convenient, made it harder to control and debug the exact flow of the conversation.</li><li>Complex Workflow Limits: Connecting our six distinct domains in a flexible way proved challenging within its role-based structure.</li></ol><h4>Why Not AutoGen?</h4><p>AutoGen is a powerful framework from Microsoft, but it was ultimately not the right choice for two key reasons:</p><ol><li>High Learning Curve: Given our tight 3-month timeline, the steep learning curve was a significant risk.</li><li>Over-engineered for Our Needs: For our specific goal — a single, highly reliable counseling agent — AutoGen’s multi-agent conversational capabilities felt like over-engineering.</li></ol><h3>Designing Our System: A High-Level Look at the Architecture</h3><p>With our framework chosen, the next step was to design a system architecture that was robust, scalable, and maintainable. We built our system around five core principles:</p><ol><li>Separation of Concerns: Each component should handle a distinct responsibility.</li><li>Single Responsibility Principle: Each module or service should have one, and only one, reason to change.</li><li>Scalability: The system must handle growing loads without a complete redesign.</li><li>Fault Isolation: A failure in one component should not cascade and take down the entire system.</li><li>Observability: We need clear visibility into the system’s health and performance at all times.</li></ol><h4>Our System Architecture Diagram</h4><p>This diagram illustrates the high-level architecture, showing how different layers and services interact, from the user-facing frontend to the backend infrastructure.</p><figure><img alt="A high-level view of our microservices architecture, from user interaction to backend services and infrastructure." src="https://cdn-images-1.medium.com/max/790/1*jpCniVyzTqecGj1X-Rq96g.png" /><figcaption><em>A high-level view of our microservices architecture, from user interaction to backend services and infrastructure.</em></figcaption></figure><h4>Mapping the Data Flow</h4><p>To understand how the system works in practice, let’s look at two critical data flows: how a user’s question gets answered and how we extract information from websites to feed our agent.</p><h4>1. The User Request Flow</h4><p>This flow shows the life cycle of a user’s question, from the moment they ask it to the moment they receive an AI-generated response.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/836/1*hD4RIwf8k4-TWeIQUxuM1g.png" /><figcaption><em>The journey of a user request through our system, from the initial query to the final, AI-powered answer.</em></figcaption></figure><h4>2. The Information Extraction Flow</h4><p>This automated flow is how we populate our knowledge base. An administrator provides a website URL, and the system automatically crawls, analyzes, and stores the relevant information in our database.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/782/1*ayZVMeoGdIRQmWSI6CdmcA.png" /><figcaption><em>Our automated pipeline for extracting, classifying, and storing information from a website into our knowledge base.</em></figcaption></figure><h4>A Closer Look at the Core Components</h4><p>While high-level diagrams are useful, the real magic happens inside the services. Here’s a more detailed look at how we designed our LangGraph agent and its tool system.</p><h4>1. The LangGraph Agent Architecture</h4><p>Our agent’s architecture is surprisingly simple, built around the ReAct pattern. The entire graph consists of just two core nodes: one for the main assistant (the LLM) and one for executing tools.</p><p>This code snippet from our implementation shows how the graph is constructed.</p><pre># The core State definition (from our actual implementation)<br>class State(TypedDict):<br>    messages: Annotated[Sequence[BaseMessage], add_messages]<br>    # A simple but effective structure.<br>    # Client-specific information is passed via the Configuration.<br><br># The graph is built using the ReAct agent pattern<br>def create_agent_graph():<br>    builder = StateGraph(State, config_schema=Configuration)<br>    <br>    # We use just two core nodes: the assistant and the tools<br>    builder.add_node(&quot;primary_assistant&quot;, primary_assistant_node)<br>    builder.add_node(&quot;primary_assistant_tools&quot;, create_tool_node_with_fallback(primary_assistant_tools))<br>    <br>    # Conditional routing defines the ReAct loop<br>    builder.add_conditional_edges(<br>        &quot;primary_assistant&quot;,<br>        route_primary_assistant,<br>        {<br>            &quot;primary_assistant_tools&quot;: &quot;primary_assistant_tools&quot;,<br>            END: END,<br>        },<br>    )<br>    # After a tool is called, the flow returns to the assistant<br>    builder.add_edge(&quot;primary_assistant_tools&quot;, &quot;primary_assistant&quot;)<br>    builder.set_entry_point(&quot;primary_assistant&quot;)<br>    <br>    return builder.compile()</pre><p>The logic is straightforward:</p><ol><li>The flow starts at the primary_assistant node.</li><li>The assistant decides whether to call a tool or respond directly.</li><li>If a tool is needed, the flow moves to the primary_assistant_tools node.</li><li>After the tool runs, the flow returns to the primary_assistant node with the new information.</li></ol><p>This simple, cyclical design is what makes the agent so powerful and easy to extend.</p><h4>2. The Tool System Design</h4><p>To keep our code organized and maintainable, we designed each tool as an independent, modular function. This approach adheres to the Single Responsibility Principle, where each tool is an expert in one specific domain.</p><p>Here is a look at our get_introduction tool, which provides basic information about a medical facility.</p><pre># An example tool from our implementation<br>from langchain_core.tools import tool<br>from typing import Literal, Optional<br><br>@tool<br>def get_introduction(<br>    state: State,<br>    config: RunnableConfig,<br>    sub_topic: Literal[<br>        &quot;INFO&quot;, &quot;ESTABLISHMENT_HISTORY&quot;, &quot;FACILITIES&quot;, <br>        &quot;CERTIFICATIONS&quot;, &quot;OPENING_HOURS&quot;, &quot;PROCEDURE&quot;<br>    ]<br>) -&gt; Optional[str]:<br>    &quot;&quot;&quot;<br>    Provides basic information about the medical institution.<br>    <br>    Args:<br>        state: The current conversation state.<br>        config: The runnable config, which includes the client_id.<br>        sub_topic: The specific type of information requested.<br>    <br>    Returns:<br>        The requested information about the institution, or None if not found.<br>    &quot;&quot;&quot;<br>    # Extract client_id from the config to query the right data<br>    configuration = Configuration.from_runnable_config(config)<br>    client_id = configuration.client_id<br>    <br>    # Search Qdrant for the relevant information<br>    query_filter = models.Filter(<br>        must=[<br>            models.FieldCondition(<br>                key=&quot;metadata.client.id&quot;, <br>                match=models.MatchValue(value=int(client_id))<br>            ),<br>            models.FieldCondition(<br>                key=&quot;metadata.topic&quot;, <br>                match=models.MatchValue(value=&quot;INTRODUCTION&quot;)<br>            ),<br>            models.FieldCondition(<br>                key=&quot;metadata.sub_topic&quot;, <br>                match=models.MatchText(text=sub_topic)<br>            ),<br>        ],<br>    )<br>    <br>    # Perform a similarity search with the filter<br>    response = vector_store.similarity_search(query=&quot;&quot;, filter=query_filter, k=1)<br>    <br>    # Return the content if a result is found<br>    return response[0].page_content if response else None</pre><p>Each tool follows this pattern: it receives the current state and configuration, queries our Qdrant vector database for specific, pre-filtered information, and returns the result.</p><p>This design makes our tools highly efficient and ensures that the LLM’s tool-use requests are precise and targeted.</p><h4>Key Technical Design Decisions</h4><p>Beyond the high-level architecture, several specific technical choices were crucial for building a responsive and resilient system.</p><h4>1. Asynchronous by Default for a Better User Experience</h4><p>To ensure our server could handle multiple concurrent users without blocking, we embraced asynchronous processing from the start.</p><p>Our FastAPI server uses astream to stream the LangGraph agent’s response back to the client. This means the user starts receiving the answer token by token, almost instantly, instead of waiting for the full response to be generated.</p><pre># Streaming responses from our FastAPI endpoint<br>@app.post(&quot;/api/chat/stream&quot;)<br>async def chat_stream(request: ChatRequest):<br>    async def generate():<br>        # The &#39;astream&#39; method streams the agent&#39;s output<br>        async for chunk in langgraph_app.astream(<br>            {&quot;messages&quot;: request.messages},<br>            config={&quot;configurable&quot;: {&quot;thread_id&quot;: request.thread_id}}<br>        ):<br>            # Each chunk is immediately sent to the client<br>            yield f&quot;data: {json.dumps(chunk)}\n\n&quot;<br>    <br>    return StreamingResponse(generate(), media_type=&quot;text/event-stream&quot;)</pre><h4>2. Built-in LLM Fallbacks for High Availability</h4><p>Relying on a single LLM provider is a significant risk in a production system. An API outage could render our service useless. To build a more resilient agent, we leveraged LangChain’s native .with_fallbacks() method, which provides a clean and declarative way to ensure high availability.</p><p>Instead of writing manual try…except blocks, we define a fallback model directly when initializing our primary chat model. Our system is configured to use an OpenAI model (like GPT-4o) as the primary choice, with Anthropic’s Claude 3.5 Sonnet designated as the automatic fallback.</p><p>Here’s how it’s implemented in our <strong><em>load_chat_model</em></strong> function:</p><pre># Our implementation using LangChain&#39;s .with_fallbacks()<br>from langchain_anthropic import ChatAnthropic<br>from langchain_core.language_models import BaseChatModel<br><br>def load_chat_model(fully_specified_name: str, temperature: float) -&gt; BaseChatModel:<br>    &quot;&quot;&quot;Loads a chat model with an integrated fallback.&quot;&quot;&quot;<br>    provider, model = fully_specified_name.split(&quot;/&quot;, maxsplit=1)<br>    <br>    # 1. Define our fallback model (Claude 3.5 Sonnet)<br>    anthropic_llm = ChatAnthropic(model=&quot;claude-3-5-sonnet-20240620&quot;)<br><br>    # 2. Initialize the primary model (e.g., OpenAI&#39;s GPT-4o)<br>    primary_llm = init_chat_model(<br>        model,<br>        model_provider=provider,<br>        temperature=temperature,<br>    )<br>    <br>    # 3. Attach the fallback model to the primary one<br>    return primary_llm.with_fallbacks([anthropic_llm])</pre><p>If a call to our primary model fails for any reason — be it an API error, server issue, or a rate limit — LangChain automatically and seamlessly retries the request with the fallback model.</p><p>This ensures that our service remains operational and can continue to serve user requests even during a partial provider outage. This declarative approach is far cleaner and more robust than manual error handling.</p><h4>Our Service-Oriented Architecture</h4><p>To ensure our system was both scalable and easy to maintain, we split it into three distinct services, each with a clear and specific role. This separation of concerns allows us to develop, deploy, and scale each part of the system independently.</p><h4>Our Three Core Services</h4><ol><li>FastAPI Gateway Service</li></ol><ul><li>Role: The public-facing front door to our system.</li><li>Responsibilities:</li><li>Handling all incoming HTTP requests and sending responses.</li><li>Validating and sanitizing user input.</li><li>Enforcing rate limiting to prevent abuse.</li><li>Centralized logging and monitoring for all incoming traffic.</li></ul><p>2. LangGraph Agent Service</p><ul><li>Role: The brain of the operation, containing all the core AI logic.</li><li>Responsibilities:</li><li>Managing the entire conversational flow using our StateGraph.</li><li>Executing tools and orchestrating their results.</li><li>Maintaining the conversation state.</li><li>Calling external LLMs (OpenAI, Anthropic) to generate responses.</li></ul><p>3. Extractor Service</p><ul><li>Role: The automated data pipeline for our knowledge base.</li><li>Responsibilities:</li><li>Crawling and chunking text from websites.</li><li>Classifying text into relevant topics.</li><li>Extracting structured information from the classified text.</li><li>Saving the structured data to our database.</li></ul><p>This division of labor keeps our codebase clean and allows different teams to work on different services without conflict.</p><h4>How Our Services Communicate</h4><p>The diagram below illustrates the communication paths between our services. The FastAPI Gateway acts as an orchestrator, routing requests to either the LangGraph Agent for real-time chat or the Extractor Service for data processing.</p><p>All services interact with a shared data layer that includes Qdrant, PostgreSQL, and Redis.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/821/1*2dplS8BlvKzI9O_rOD5ZDA.png" /><figcaption><em>A detailed look at the internal communication flows between the FastAPI Gateway, LangGraph Agent, Extractor Service, and our shared data layer.</em></figcaption></figure><h3>Putting Our Architecture to the Test</h3><p>After three months of intensive development, how did our architectural designs hold up in practice? Here’s an honest look at what succeeded and where we see opportunities for improvement.</p><h4>✅ What Went Right: Our Winning Decisions</h4><ol><li>The LangGraph ReAct Agent Pattern: This proved to be a simple yet incredibly powerful mechanism for tool selection. It gave us the flexibility we needed without introducing unnecessary complexity.</li><li>Asynchronous Processing: Building our services with async support from the ground up dramatically improved our ability to handle concurrent user requests.</li><li>Simple State Design: We kept our core State object lean and managed complexity through a separate Configuration. This decision made the agent far easier to maintain and debug.</li></ol><h4>🔄 What We’re Improving: Lessons Learned</h4><ol><li>Inter-Service Latency: While our services were decoupled, the HTTP calls between them introduced some latency. We are currently exploring gRPC as a more efficient communication protocol.</li><li>Information Sharing Between Tools: We are still refining the best way to pass context and share information between tool calls via the central State.</li><li>Monitoring Complexity: With three separate services, our monitoring became fragmented. We are now developing a unified dashboard to provide a single pane of glass for observability.</li></ol><h3>Final Thoughts and What’s Next</h3><p>The biggest lesson from this phase of the project was that practical, maintainable solutions are more valuable than technically complex ones. LangGraph’s ReAct agent pattern seemed almost too simple at first, but it gave us a robust and scalable foundation to build upon. It’s a powerful reminder that sometimes, simplicity is the ultimate sophistication.</p><p>In the next part of this series, we’ll get our hands dirty and dive into the first month of development. We’ll cover the practical implementation of the LangGraph agent, the development of our six core tools, and the challenges we faced integrating with the Qdrant vector database. Stay tuned!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f17b51f8883d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Part 1: From Idea to MVP in 90 Days: The Vision for Our Medical AI Agent]]></title>
            <link>https://medium.com/@kofsitho/part-1-from-idea-to-mvp-in-90-days-the-vision-for-our-medical-ai-agent-6c77aa2b8c78?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/6c77aa2b8c78</guid>
            <category><![CDATA[langgraph]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[ai-development]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Thu, 12 Jun 2025 09:43:45 GMT</pubDate>
            <atom:updated>2025-06-12T09:46:51.639Z</atom:updated>
            <content:encoded><![CDATA[<p><em>*This is the first installment of a multi-part series detailing our 3-month journey of building, deploying, and operating a specialized AI agent for medical clinics. We’ll cover everything from the initial concept and tech stack choices to development sprints, cloud deployment, and the lessons we learned along the way.*</em></p><h3><strong>1. The Problem: Why Medical Clinics Are Drowning in Repetitive Call</strong></h3><h4><strong>🏥 The Reality on the Ground</strong></h4><p>Every successful project starts with a real-world problem. Ours began with a simple observation: medical institutions, especially specialized clinics like dental offices, are overwhelmed by the sheer volume of repetitive customer inquiries.</p><p>During meetings with one of our clients, a dental clinic, we heard firsthand accounts of their daily struggles:</p><blockquote>“We receive about 50–60 phone calls a day, and most of them are the same questions over and over again. ‘What are your hours?’ ‘What treatments do you offer?’ ‘Where can I park?’ One of our staff members is practically tied to the phone all day.”</blockquote><blockquote>“All this information is on our website, but people still call to ask. It’s especially frustrating during evenings or weekends when we can’t answer, which I know hurts our patient satisfaction.”</blockquote><h4><strong>📊 The Problem in Numbers</strong></h4><p>We analyzed the inquiry patterns of several medical clinics and found a clear, consistent trend:</p><ul><li><strong>~70% of all inquiries are for basic, repetitive information:</strong></li><li>Operating hours and holidays</li><li>Location and parking information</li><li>Doctor specialties and staff information</li><li>Appointment booking procedures</li><li><strong>Inquiries peak during specific times:</strong> 80% of calls were concentrated during lunch hours (12–2 PM) and after work (5–7 PM).</li><li><strong>Opportunity cost from response delays:</strong> Nearly 30% of callers who didn’t get an immediate answer moved on to search for another clinic.</li></ul><h4><strong>💡 The Clear Need for Automation</strong></h4><p>In this context, introducing an <strong>AI-powered automated consultation system</strong> was more than a convenience — it was a critical business need. The goals were clear:</p><ol><li><strong>Maximize Staff Efficiency:</strong> Automate repetitive tasks so staff can focus on higher-value patient care.</li><li><strong>Provide 24/7 Service:</strong> Offer instant information outside of clinic hours.</li><li><strong>Enhance Patient Satisfaction:</strong> Deliver fast, accurate answers anytime.</li><li><strong>Reduce Operational Costs:</strong> Improve service quality without hiring additional staff.</li></ol><h3>2. Our Mission: Project Goals and Scope</h3><h4>🎯 The Core Objective</h4><p>Our mission was to <strong>build a specialized AI consultation agent for medical institutions</strong>. This wasn’t about creating just another chatbot. The goal was to develop a <strong>practical, scalable, and ready-to-use solution</strong> that clinics could immediately benefit from.</p><h4>Key Performance Indicators (KPIs)</h4><ul><li><strong>Response Accuracy:</strong> &gt;95%</li><li><strong>Response Speed:</strong> &lt;2 seconds on average</li><li><strong>System Availability:</strong> &gt;99.9%</li><li><strong>Scalability:</strong> Universally applicable to various clinics with minimal setup.</li></ul><h4>🔍 Defining the Boundaries: Project Scope</h4><h4>In Scope</h4><ol><li><strong>Support for 6 Core Domains:</strong></li></ol><ul><li>Clinic Introduction (hospital info, facilities, certifications)</li><li>Visit Guidance (location, parking, transport)</li><li>Medical Staff Information (specialties, careers)</li><li>Medical Services (treatments, procedures)</li><li>Certificate Issuance (types, procedures, costs)</li><li>Event Information (promotions, discounts)</li></ul><ol><li><strong>Automated Information Extraction:</strong> Automatically parse and structure information from a clinic’s website.</li><li><strong>Real-time Conversational Interface:</strong> Support natural language queries while maintaining context.</li><li><strong>Operations &amp; Management System:</strong> A real-time monitoring dashboard with conversation logs and analytics.</li></ol><h4>Out of Scope</h4><ul><li>Direct integration with appointment booking systems (we only provide guidance).</li><li>Medical diagnoses or treatment advice.</li><li>Handling of personal health information (PHI).</li><li>Payment system integration.</li></ul><h4>🏗️ Technical &amp; Operational Goals</h4><p>To ensure we built a robust system, we set clear technical and operational targets.</p><p><strong>Architecture Goals</strong></p><ul><li><strong>Modularity:</strong> Design independent components for each function.</li><li><strong>Scalability:</strong> Easily onboard new clinics with minimal configuration.</li><li><strong>Stability:</strong> Maintain core services even during partial failures.</li><li><strong>Performance:</strong> Support over 100 concurrent users.</li></ul><p><strong>Operational Goals</strong></p><ul><li><strong>Automated Deployment:</strong> Zero-downtime deployments via a CI/CD pipeline.</li><li><strong>Monitoring:</strong> Real-time performance tracking and alerts.</li><li><strong>Auto-scaling:</strong> Cloud-native, automatic scaling based on demand.</li><li><strong>Security:</strong> Adherence to medical information protection standards.</li></ul><h3>3. The Roadmap: A 3-Month Plan to MVP</h3><h4>📅 The Big Picture</h4><p>We set an ambitious 3-month timeline. This was driven by a strategy of <strong>rapid MVP validation and iterative improvement</strong>. We established clear monthly goals, aiming to have a tangible, usable product at the end of each month.</p><h4>🗓️ Month 1: Core AI Agent Development (Weeks 1–4)</h4><p><strong>Goal:</strong> Complete the core AI Agent logic using LangGraph.</p><ul><li><strong>Week 1:</strong> Set up the LangGraph environment and design the basic StateGraph.</li><li><strong>Week 2:</strong> Develop and test the 6 core tools.</li><li><strong>Week 3:</strong> Integrate Qdrant vector DB for retrieval.</li><li><strong>Week 4:</strong> Complete the first demo and conduct internal testing.</li></ul><p><strong>Success Criteria:</strong> Basic Q&amp;A works, all 6 domains are covered, context is maintained, and response accuracy exceeds 80%.</p><h4>🗓️ Month 2: Building the Automation Engine (Weeks 5–8)</h4><p><strong>Goal:</strong> Develop the automatic website information extractor and the FastAPI server.</p><ul><li><strong>Week 5:</strong> Design the information extraction workflow.</li><li><strong>Week 6:</strong> Optimize large-scale text chunking and topic classification.</li><li><strong>Week 7:</strong> Develop the FastAPI server with asynchronous processing.</li><li><strong>Week 8:</strong> Optimize performance and complete the second demo.</li></ul><p><strong>Success Criteria:</strong> Automated extraction is complete, extraction accuracy is over 90%, API response is under 3 seconds, and real-time streaming is implemented.</p><h4>🗓️ Month 3: Infrastructure and Deployment (Weeks 9–12)</h4><p><strong>Goal:</strong> Deploy to the AWS cloud and finalize the operational system.</p><ul><li><strong>Week 9:</strong> Design and build the AWS ECS Fargate infrastructure.</li><li><strong>Week 10:</strong> Establish a CI/CD pipeline with a Blue/Green deployment strategy.</li><li><strong>Week 11:</strong> Develop the monitoring system and Next.js dashboard.</li><li><strong>Week 12:</strong> Final testing and stabilization of the production environment.</li></ul><p><strong>Success Criteria:</strong> Achieve 99.9% availability, automated deployment is functional, the real-time dashboard is complete, and the system passes a load test of 100 concurrent users.</p><h3>🚀 Ready for Liftoff</h3><p>With a clear vision, a defined scope, and a detailed plan, we were ready to begin. Of course, no project goes exactly as planned. The journey was filled with unexpected challenges, technical hurdles, and valuable discoveries.</p><p>In the next part of this series, we’ll dive deep into our technology choices. <strong>Why did we choose LangGraph over more established frameworks like LangChain?</strong> And what did our final system architecture look like? Stay tuned.</p><blockquote><em>💡 </em><strong><em>Key Takeaway:</em></strong><em> The foundation of a successful AI project isn’t just cutting-edge technology; it’s a clear definition of the problem and a realistic, actionable plan to solve it. Always start with the user’s needs, not the technical hype.</em></blockquote><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6c77aa2b8c78" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Ruff: Python 개발자를 위한 차세대 린터]]></title>
            <link>https://medium.com/@kofsitho/ruff-python-%EA%B0%9C%EB%B0%9C%EC%9E%90%EB%A5%BC-%EC%9C%84%ED%95%9C-%EC%B0%A8%EC%84%B8%EB%8C%80-%EB%A6%B0%ED%84%B0-7a96acc8a302?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/7a96acc8a302</guid>
            <category><![CDATA[python]]></category>
            <category><![CDATA[development]]></category>
            <category><![CDATA[linter]]></category>
            <category><![CDATA[ruff]]></category>
            <category><![CDATA[developer]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Fri, 10 Jan 2025 06:26:29 GMT</pubDate>
            <atom:updated>2025-01-10T06:26:29.147Z</atom:updated>
            <content:encoded><![CDATA[<h3>Overview</h3><p>파이썬 개발자라면 누구나 코드 품질과 일관성 유지를 위해 <strong>린터(Linter)</strong>와 <strong>포맷터(Formatter)</strong>를 사용합니다. 그동안 우리는 Flake8, Black, isort 등 다양한 도구들을 조합해서 사용해왔습니다. 하지만 이러한 도구들을 개별적으로 관리하고 실행하는 것은 번거롭고, 특히 대규모 프로젝트에서는 성능 저하가 큰 문제가 되어왔습니다.</p><p>이러한 문제를 해결하기 위해 등장한 것이 바로 <strong>Ruff</strong>입니다. <strong>Rust</strong>로 작성된 Ruff는 기존 파이썬 도구들의 기능을 통합하면서도, 놀라운 속도 향상을 제공합니다. 실제로 기존 도구들과 비교했을 때 10–100배 더 빠른 성능을 보여주고 있습니다.</p><p>FastAPI의 제작자 Sebastián Ramírez가 말했듯이, “Ruff는 너무 빨라서 가끔은 실제로 작동하는지 확인하기 위해 일부러 버그를 넣어볼 정도”입니다. 이는 단순한 과장이 아닌, 실제 개발 현장에서 체감되는 변화입니다.</p><p>이 가이드에서는 다음 <strong><em>[ToC]</em></strong> 에 제시된 내용을 다룰 예정입니다.</p><p>특히 주목할 만한 점은 <strong>Ruff</strong>가 단순한 린터를 넘어서, 800개 이상의 내장 규칙을 제공하고 자동 수정 기능까지 갖추고 있다는 것입니다. 이는 코드 품질 관리에 들이는 시간과 노력을 대폭 줄여주며, 개발자가 실제 비즈니스 로직 구현에 더 집중할 수 있게 해줍니다.</p><p>이제 파이썬 개발의 새로운 표준이 되어가고 있는 <strong>Ruff</strong>에 대해 자세히 알아보겠습니다. 이 가이드를 통해 여러분의 파이썬 개발 경험이 한층 더 효율적이고 즐거워지기를 바랍니다.</p><h3>Table of Contents</h3><ul><li>Ruff 소개</li><li>Ruff 설치 및 기본 사용법</li><li>Ruff의 고급 기능</li><li>Ruff와 개발 환경 통합</li><li>Ruff 커스터마이징</li><li>Ruff 모범 사례 및 팁</li><li>Ruff의 미래와 전망</li><li>마무리</li></ul><h3>References</h3><ul><li><a href="https://docs.astral.sh/ruff/">Ruff 공식 홈페이지</a></li></ul><h3>Ruff 소개</h3><h4>Ruff란 무엇인가?</h4><p>개발자로서 코드 품질과 일관성을 유지하는 것은 항상 중요한 과제였습니다. 저는 오랫동안 Javascript와 Typescript를 사용해왔고, 이 과정에서 ESLint, Prettier와 같은 다양한 코드 품질 관리 도구들을 활용해왔습니다. 최근에는 Rust로 작성되어 뛰어난 성능을 자랑하는 <a href="https://biomejs.dev/guides/getting-started/">Biome</a>으로 전환하여 사용하고 있습니다.</p><p>이러한 경험을 통해 깨달은 것은, 효과적인 코드 품질 관리 도구가 개발 생산성과 코드 유지보수성에 얼마나 큰 영향을 미치는지입니다. 특히 팀 프로젝트에서는 일관된 코드 스타일과 품질 기준을 유지하는 것이 더욱 중요해집니다.</p><p>최근 Python 개발을 시작하면서, JavaScript/TypeScript 생태계에서 경험했던 것과 같은 효율적인 코드 품질 관리 도구를 찾게 되었습니다. 그 과정에서 발견한 것이 바로 Ruff입니다. JavaScript 생태계의 Biome과 마찬가지로, Rust로 작성되어 놀라운 성능을 보여주는 Ruff는 Python 개발자들에게 새로운 가능성을 제시하고 있습니다.</p><p>이 가이드를 통해 제가 경험한 Ruff의 장점과 실제 활용 방법을 공유하고자 합니다.</p><p>Ruff는 파이썬 개발 생태계에 혁신적인 변화를 가져온 차세대 린터 및 코드 포맷터입니다. 기존의 파이썬 도구들과 달리 <strong>Rust</strong> 프로그래밍 언어로 작성되어, 놀라운 성능 향상을 실현했습니다. 단순한 린터를 넘어서서, 코드 품질 관리를 위한 올인원 솔루션을 제공하는 것이 Ruff의 핵심 철학입니다.</p><p>다음 내용은 <a href="https://docs.astral.sh/ruff/">ruff 공식 홈페이지</a>에서 제공하는 내용입니다.</p><ul><li>⚡️ 기존 린터(Flake8)와 포맷터(Black) 대비 10–100배 빠른 속도</li><li>🐍 pip를 통한 간편한 설치</li><li>🛠️ pyproject.toml 설정 파일 지원</li><li>🤝 Python 3.13 버전까지 호환성 보장</li><li>⚖️ Flake8, isort, Black과 동일한 기능 제공</li><li>📦 변경되지 않은 파일의 재분석을 방지하는 내장 캐싱 기능</li><li>🔧 자동 오류 수정 지원 (예: 사용하지 않는 import 자동 제거)</li><li>📏 flake8-bugbear와 같은 인기 있는 Flake8 플러그인의 네이티브 재구현을 포함한 800개 이상의 내장 규칙</li><li>⌨️ VS Code 등을 위한 자체 에디터 통합 기능</li><li>🌎 계층적이고 연속적인 설정이 가능한 모노레포 친화적 구조</li></ul><h4>Ruff의 주요 특징</h4><p><strong>1. 압도적인 성능</strong></p><ul><li>기존 도구 대비 <strong>10–100</strong> 배 빠른 실행 속도</li><li>대규모 코드베이스에서도 즉각적인 피드백 제공</li><li>내장된 <strong>캐싱 시스템</strong>으로 변경된 파일만 선택적 분석</li></ul><p><strong>2. 통합된 기능성</strong></p><ul><li>Flake8의 린팅 기능</li><li>Black의 코드 포맷팅</li><li>isort의 임포트 정렬</li><li>pyupgrade의 자동 업그레이드</li><li>autoflake의 미사용 임포트 제거</li><li>pydocstyle의 문서화 검사</li></ul><p><strong>3. 현대적인 개발 경험</strong></p><ul><li>pyproject.toml을 통한 직관적인 설정</li><li>VS Code 등 주요 IDE와의 원활한 통합</li><li>pre-commit 훅 지원으로 자동화된 코드 품질 관리</li><li>CI/CD 파이프라인 통합 용이성</li></ul><h4>기존 파이썬 린터와의 차이점</h4><p><strong>1. 아키텍처적 차이</strong></p><ul><li><strong>Rust</strong> 기반 구현으로 인한 탁월한 성능</li><li>단일 바이너리로 배포되어 의존성 관리 간소화</li><li>멀티스레딩 지원으로 병렬 처리 최적화</li></ul><p><strong>2. 기능적 차이</strong></p><ul><li>800개 이상의 내장 규칙 제공</li><li>자동 수정 기능의 광범위한 지원</li><li>계층적 설정 시스템으로 유연한 규칙 관리</li><li>실시간 린팅으로 즉각적인 피드백</li></ul><p><strong>3. 사용자 경험 차이</strong></p><ul><li>단일 도구로 여러 기능 통합</li><li>간소화된 설정과 관리</li><li>빠른 실행 속도로 인한 개발 생산성 향상</li><li>적은 시스템 리소스 사용</li></ul><p>Ruff는 단순히 기존 도구들을 대체하는 것을 넘어서, 파이썬 개발자들의 코드 품질 관리 방식을 근본적으로 변화시키고 있습니다. 특히 대규모 프로젝트에서 그 진가를 발휘하며, Apache Airflow, FastAPI, Pandas 등 유명 오픈소스 프로젝트들이 이미 Ruff를 도입하여 사용하고 있습니다.</p><h3>Ruff 설치 및 기본 사용법</h3><p>Ruff는 다양한 방법으로 설치할 수 있습니다. 프로젝트의 요구사항과 개발 환경에 따라 적절한 설치 방법을 선택할 수 있습니다.</p><pre># pip를 통한 설치<br>pip install ruff</pre><pre># 프로젝트 개발 의존성으로 설치<br>pip install --dev ruff</pre><pre># conda를 통한 설치<br>conda install ruff -c conda-forge</pre><pre># Homebrew를 통한 설치 (macOS)<br>brew install ruff</pre><pre># 특정 버전 설치<br>pip install ruff==0.1.8</pre><h4>가상 환경에서의 설치</h4><p>프로젝트별로 독립된 환경을 유지하기 위해 가상 환경 사용을 권장합니다:</p><pre># 가상 환경 생성 및 활성화<br>python -m venv .venv<br>source .venv/bin/activate  # Linux/macOS<br>.venv\Scripts\activate     # Windows</pre><h4>기본 명령어</h4><p>Ruff는 크게 두 가지 주요 기능을 제공합니다: 린팅(check)과 포맷팅(format)</p><h4>1. 린팅 (ruff check)</h4><pre># 현재 디렉토리의 모든 파이썬 파일 검사<br>ruff check .<br><br># 특정 파일이나 디렉토리 검사<br>ruff check path/to/code/<br>ruff check path/to/code/*.py<br>ruff check path/to/code/to/file.py<br><br># 자동 수정 옵션 적용<br>ruff check --fix .</pre><h4>2. 포맷팅 (ruff format)</h4><pre># 현재 디렉토리의 모든 파이썬 파일 포맷팅<br>ruff format .<br><br># 특정 파일이나 디렉토리 포맷팅<br>ruff format path/to/code/<br>ruff format path/to/code/*.py<br>ruff format path/to/code/to/file.py</pre><h4>설정 파일 (pyproject.toml) 작성 방법</h4><p>Ruff는 pyproject.toml 파일을 통해 설정할 수 있습니다. 다음은 실용적인 설정 예시입니다:</p><pre>[tool.ruff]<br># 파이썬 버전 지정<br>target-version = &quot;py37&quot;<br><br># 자주 사용되는 규칙 조합<br>select = [<br>    &quot;E&quot;,     # pycodestyle errors<br>    &quot;W&quot;,     # pycodestyle warnings<br>    &quot;F&quot;,     # pyflakes<br>    &quot;I&quot;,     # isort<br>    &quot;C&quot;,     # flake8-comprehensions<br>    &quot;B&quot;,     # flake8-bugbear<br>    &quot;UP&quot;,    # pyupgrade<br>    &quot;N&quot;,     # pep8-naming<br>    &quot;YTT&quot;,   # flake8-2020<br>    &quot;S&quot;,     # flake8-bandit<br>]<br># 무시할 규칙<br>ignore = [<br>    &quot;E501&quot;,  # line length violations<br>]<br># 라인 길이 제한<br>line-length = 88<br># 자동 수정 활성화<br>fix = true<br># 캐시 사용<br>cache-dir = &quot;.ruff_cache&quot;<br># 파일 제외 패턴<br>exclude = [<br>    &quot;.git&quot;,<br>    &quot;.ruff_cache&quot;,<br>    &quot;.venv&quot;,<br>    &quot;venv&quot;,<br>    &quot;__pycache__&quot;,<br>]<br># 특정 파일/디렉토리에 대한 규칙 제외<br>[tool.ruff.per-file-ignores]<br>&quot;__init__.py&quot; = [&quot;F401&quot;]  # unused imports<br>&quot;tests/*&quot; = [&quot;S101&quot;]      # assert statements<br>&quot;**/tests/*&quot; = [&quot;S101&quot;]   # assert statements in nested test directories<br># 프로젝트별 설정 상속<br>extend = [&quot;../pyproject.toml&quot;]<br># 타입 관련 설정<br>typing-modules = [&quot;typing&quot;, &quot;typing_extensions&quot;]<br># 포맷팅 설정<br>[tool.ruff.format]<br>quote-style = &quot;double&quot;<br>indent-style = &quot;space&quot;<br>skip-magic-trailing-comma = false<br>line-ending = &quot;auto&quot;</pre><h4>주요 설정 옵션 설명</h4><ol><li><strong>target-version</strong>: 대상 파이썬 버전을 지정합니다.</li><li><strong>select/ignore</strong>: 적용하거나 무시할 린트 규칙을 지정합니다.</li><li><strong>line-length</strong>: 최대 줄 길이를 설정합니다.</li><li><strong>fix</strong>: 자동 수정 기능의 활성화 여부를 설정합니다.</li><li><strong>exclude</strong>: 검사에서 제외할 파일/디렉토리를 지정합니다.</li><li><strong>per-file-ignores</strong>: 특정 파일이나 디렉토리에 대해 다른 규칙을 적용합니다.</li><li><strong>extend</strong>: 다른 설정 파일로부터 설정을 상속받습니다.</li></ol><h3>Ruff의 고급 기능</h3><p>Ruff는 기본적인 린팅과 포맷팅 외에도 다양한 고급 기능을 제공합니다. 이러한 기능들을 활용하면 더욱 효율적인 코드 품질 관리가 가능합니다.</p><h4>자동 수정 ( — fix 옵션)</h4><p>Ruff의 가장 강력한 기능 중 하나는 자동 수정 기능입니다. --fix 옵션을 사용하면 많은 린트 오류를 자동으로 수정할 수 있습니다.</p><pre># 기본 자동 수정<br>ruff check --fix .<br><br># 안전한 수정만 적용<br>ruff check --fix-only .<br><br># 특정 규칙에 대해서만 수정 적용<br>ruff check --fix --select E501,F401 .</pre><p>주요 자동 수정 가능 항목:</p><ul><li>사용하지 않는 import 제거</li><li>import 순서 정렬</li><li>코드 포맷팅 (공백, 들여쓰기 등)</li><li>간단한 코드 최적화</li><li>타입 힌트 업그레이드</li></ul><h4>안전하지 않은 수정 적용 방법</h4><p>일부 수정은 코드의 동작을 변경할 수 있어 기본적으로 비 활성화되어 있습니다. 이러한 수정을 적용하려면 특별한 옵션을 사용해야 합니다.</p><pre># 모든 수정 적용 (안전하지 않은 수정 포함)<br>ruff check --unsafe-fixes .<br><br># 특정 규칙에 대해서만 안전하지 않은 수정 적용<br>ruff check --unsafe-fixes --select RUF100 .</pre><p>주의해야 할 안전하지 않은 수정:</p><ul><li>변수 이름 변경</li><li>코드 재구성</li><li>타입 관련 변경</li><li>복잡한 리팩토링</li></ul><h4>캐싱 시스템을 통한 성능 최적화</h4><p>Ruff는 강력한 캐싱 시스템을 내장하고 있어, 변경되지 않은 파일의 재분석을 방지합니다.</p><p><strong>1. 캐시 설정</strong></p><pre>[tool.ruff]<br># 캐시 디렉토리 설정<br>cache-dir = &quot;.ruff_cache&quot;<br><br># 캐시 사용 여부<br>cache = true</pre><p><strong>2. 캐시 관리 명령어</strong></p><pre># 캐시 정보 확인<br>ruff check --show-cache-info .<br><br># 캐시 초기화<br>ruff check --clear-cache .<br><br># 캐시 비활성화하고 실행<br>ruff check --no-cache .</pre><h4>고급 설정 옵션</h4><p><strong>1. 파일별 규칙 적용</strong></p><pre>[tool.ruff.per-file-ignores]<br>&quot;__init__.py&quot; = [&quot;F401&quot;, &quot;F403&quot;]<br>&quot;tests/*.py&quot; = [&quot;S101&quot;, &quot;PLR0913&quot;]<br>&quot;examples/*.py&quot; = [&quot;E402&quot;]</pre><p><strong>2. 외부 설정 파일 확장</strong></p><pre>[tool.ruff]<br># 기본 설정 파일 확장<br>extend = [&quot;../base.toml&quot;, &quot;./team.toml&quot;]<br><br># 특정 규칙 확장<br>extend-select = [&quot;RUF&quot;]<br>extend-ignore = [&quot;E501&quot;]</pre><p><strong>3. 매직 주석 사용</strong></p><pre># ruff: noqa<br># 이 파일의 모든 린트 검사 무시<br><br># ruff: noqa: F401<br># 특정 줄의 특정 규칙 무시<br><br># fmt: off<br># 포맷팅 무시 시작<br>code_here = &quot;포맷팅이 적용되지 않음&quot;<br># fmt: on</pre><h4>성능 최적화 팁</h4><ol><li><strong>병렬 처리 활용</strong></li></ol><pre># 워커 수 지정<br>ruff check --workers 4 .<br><br># 자동으로 최적의 워커 수 사용<br>ruff check --workers auto .</pre><p>2. <strong>파일 필터링 최적화</strong></p><pre>[tool.ruff]<br># 검사 제외 패턴 최적화<br>exclude = [<br>    &quot;.git&quot;,<br>    &quot;.venv&quot;,<br>    &quot;__pycache__&quot;,<br>    &quot;build&quot;,<br>    &quot;dist&quot;<br>]<br><br># 특정 파일 패턴만 검사<br>include = [&quot;*.py&quot;, &quot;*.pyi&quot;]</pre><p>3. <strong>규칙 선택 최적화</strong></p><pre>[tool.ruff]<br># 필요한 규칙만 선택하여 성능 향상<br>select = [<br> &quot;E&quot;,  # pycodestyle<br> &quot;F&quot;,  # pyflakes<br> &quot;I&quot;,  # isort<br>]</pre><h3>Ruff와 개발 환경 통합</h3><p><strong>Ruff</strong>의 강력한 기능을 최대한 활용하기 위해서는 <strong>개발 환경</strong>과의 <strong>통합</strong>이 필수적입니다. 여기서는 가장 일반적인 통합 방법들을 살펴보겠습니다.</p><h4>VS Code 확장 프로그램 사용법</h4><p><strong>VS Code</strong>는 Ruff를 위한 <a href="https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff">공식 확장 프로그램</a>을 제공합니다.</p><p><strong>1. 설치 및 기본 설정</strong></p><pre>// VS Code에서 Ruff 확장 프로그램 설치<br>// 1. Ctrl/Cmd + P를 눌러 명령 팔레트 열기<br>// 2. 다음 명령어 입력:<br>ext install charliermarsh.ruff</pre><pre>// settings.json 설정<br>{<br>    // Ruff를 기본 포맷터로 설정<br>    &quot;editor.defaultFormatter&quot;: &quot;charliermarsh.ruff&quot;,<br>    // Python 파일에 대해 Ruff 사용<br>    &quot;[python]&quot;: {<br>        &quot;editor.formatOnSave&quot;: true,<br>        &quot;editor.codeActionsOnSave&quot;: {<br>            &quot;source.fixAll.ruff&quot;: true,<br>            &quot;source.organizeImports.ruff&quot;: true<br>        }<br>    },<br>    // Ruff 확장 설정<br>    &quot;ruff.lint.run&quot;: &quot;onSave&quot;,<br>    &quot;ruff.format.args&quot;: [&quot;--line-length&quot;, &quot;88&quot;],<br>    &quot;ruff.lint.args&quot;: [&quot;--fix&quot;]<br>}</pre><p><strong>2. 주요 기능</strong></p><ul><li>실시간 린팅 피드백</li><li>저장 시 자동 포맷팅</li><li>코드 액션을 통한 빠른 수정</li><li>문제 목록에서 린트 오류 확인</li><li>호버를 통한 규칙 설명 확인</li></ul><h4>pre-commit 훅 설정</h4><p>pre-commit을 사용하여 커밋 전 자동으로 Ruff 검사를 실행할 수 있습니다.</p><p><strong>1. pre-commit 설치 및 설정</strong></p><pre># pre-commit 설치<br>pip install pre-commit<br><br># pre-commit 설정 파일 생성<br>touch .pre-commit-config.yaml</pre><p><strong>2. .pre-commit-config.yaml 설정</strong></p><pre>repos:<br>  - repo: https://github.com/astral-sh/ruff-pre-commit<br>    rev: v0.1.8<br>    hooks:<br>      # 린팅 실행<br>      - id: ruff<br>        args: [--fix]<br>      # 포맷팅 실행<br>      - id: ruff-format<br><br># 추가적인 훅 설정<br>  - repo: local<br>    hooks:<br>      - id: pytest<br>        name: Run pytest<br>        entry: pytest<br>        language: system<br>        types: [python]<br>        pass_filenames: false</pre><h4>3. pre-commit 활성화</h4><pre># pre-commit 설치 및 활성화<br>pre-commit install<br><br># 모든 파일에 대해 수동으로 실행<br>pre-commit run --all-files</pre><h4>CI/CD 파이프라인에 Ruff 통합하기</h4><p><strong>1. GitHub Actions 예시</strong></p><pre>name: Ruff<br>on: [push, pull_request]<br><br>jobs:<br>  ruff:<br>    runs-on: ubuntu-latest<br>    steps:<br>      - uses: actions/checkout@v4<br>      - uses: actions/setup-python@v4<br>        with:<br>          python-version: &#39;3.x&#39;<br>      # Ruff 린팅<br>      - uses: chartboost/ruff-action@v1<br>        with:<br>          version: 0.1.8<br>          args: --fix<br>      # 변경사항이 있으면 커밋<br>      - uses: stefanzweifel/git-auto-commit-action@v5<br>        with:<br>          commit_message: &quot;style: Format Python code with Ruff&quot;<br>          file_pattern: &quot;*.py&quot;</pre><h4>2. GitLab CI/CD 예시</h4><pre>ruff:<br>  image: python:3.11<br>  before_script:<br>    - pip install ruff<br>  script:<br>    - ruff check .<br>    - ruff format --check .<br>  rules:<br>    - if: $CI_PIPELINE_SOURCE == &quot;merge_request_event&quot;<br>    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH</pre><h4>통합 시 고려사항</h4><ol><li><strong>성능 최적화</strong></li></ol><ul><li>캐시 활용으로 CI/CD 실행 시간 단축</li><li>필요한 규칙만 선택적으로 활성화</li><li>대규모 프로젝트의 경우 병렬 처리 활용</li></ul><p><strong>2. 팀 협업</strong></p><ul><li>공통된 설정 파일 사용</li><li>코드 리뷰 프로세스에 Ruff 검사 포함</li><li>문서화를 통한 팀 규칙 공유</li></ul><p><strong>3. 문제 해결</strong></p><ul><li>특정 상황에서 규칙 무시 방법 숙지</li><li>CI/CD 파이프라인 실패 시 디버깅 전략</li><li>팀원 간 설정 동기화 유지</li></ul><h3>Ruff 커스터마이징</h3><p>Ruff는 매우 유연한 설정 시스템을 제공하여 프로젝트의 요구사항에 맞게 다양한 커스터마이징이 가능합니다.</p><h4>린팅 규칙 선택 및 무시하기</h4><p><strong>1. 규칙 선택 방법</strong></p><pre>[tool.ruff]<br># 기본 규칙 선택<br>select = [<br>    &quot;E&quot;,    # pycodestyle 에러<br>    &quot;W&quot;,    # pycodestyle 경고<br>    &quot;F&quot;,    # pyflakes<br>    &quot;B&quot;,    # flake8-bugbear<br>    &quot;I&quot;,    # isort<br>    &quot;N&quot;,    # pep8-naming<br>    &quot;UP&quot;,   # pyupgrade<br>    &quot;PL&quot;,   # pylint<br>    &quot;RUF&quot;,  # ruff-specific rules<br>]<br><br># 규칙 확장<br>extend-select = [<br>    &quot;C&quot;,    # mccabe complexity<br>    &quot;T&quot;,    # mypy type checks<br>]<br># 특정 규칙 무시<br>ignore = [&quot;E501&quot;]  # 라인 길이 제한 무시<br># 무시 규칙 확장<br>extend-ignore = [&quot;B904&quot;, &quot;B905&quot;]</pre><p><strong>2. 파일별 규칙 관리</strong></p><pre>[tool.ruff.per-file-ignores]<br># 특정 파일에 대한 규칙 무시<br>&quot;__init__.py&quot; = [&quot;F401&quot;]           # unused imports<br>&quot;tests/*&quot; = [<br>    &quot;S101&quot;,                        # assert statements<br>    &quot;PLR2004&quot;,                     # magic numbers<br>]<br>&quot;examples/*.py&quot; = [&quot;E402&quot;]         # module level imports not at top<br>&quot;**/generated/*.py&quot; = [&quot;ALL&quot;]      # 모든 규칙 무시<br><br># 정규식을 사용한 파일 매칭<br>&quot;**/tests/test_*.py&quot; = [&quot;S101&quot;]    # 모든 테스트 파일</pre><h4>프로젝트별 설정 관리</h4><p><strong>1. 기본 설정 상속</strong></p><pre># base.toml (기본 설정 파일)<br>[tool.ruff]<br>line-length = 88<br>target-version = &quot;py37&quot;<br>select = [&quot;E&quot;, &quot;F&quot;, &quot;I&quot;]<br><br># project/pyproject.toml (프로젝트별 설정)<br>[tool.ruff]<br>extend = [&quot;../base.toml&quot;]          # 기본 설정 상속<br>extend-select = [&quot;B&quot;, &quot;C&quot;]         # 추가 규칙</pre><p><strong>2. 환경별 설정 분리</strong></p><pre># 개발 환경 설정<br>[tool.ruff]<br>select = [&quot;ALL&quot;]<br>ignore = []<br>fix = true<br><br># 프로덕션 환경 설정<br>[tool.ruff]<br>select = [&quot;E&quot;, &quot;F&quot;, &quot;I&quot;]<br>fix = false<br>unsafe-fixes = false</pre><p><strong>3. 모노레포 설정</strong></p><pre># root/pyproject.toml (루트 설정)<br>[tool.ruff]<br>line-length = 88<br>select = [&quot;E&quot;, &quot;F&quot;]<br><br># root/service-a/pyproject.toml (서비스별 설정)<br>[tool.ruff]<br>extend = [&quot;../pyproject.toml&quot;]<br>select = [&quot;E&quot;, &quot;F&quot;, &quot;I&quot;]<br><br># root/service-b/pyproject.toml (다른 서비스 설정)<br>[tool.ruff]<br>extend = [&quot;../pyproject.toml&quot;]<br>select = [&quot;E&quot;, &quot;F&quot;, &quot;B&quot;]</pre><h4>사용자 정의 플러그인 개발 가이드</h4><p>Ruff는 현재 사용자 정의 플러그인을 직접적으로 지원하지 않지만, 다음과 같은 대안을 사용할 수 있습니다:</p><p><strong>1. 매직 주석을 활용한 규칙 관리</strong></p><pre># ruff: noqa<br># 파일 전체 린트 검사 무시<br><br># ruff: noqa: F401, E501<br># 특정 규칙만 무시<br>def some_function():  # noqa: CCR001<br>    # 특정 줄에 대한 규칙 무시<br>    pass</pre><p><strong>2. 프로젝트 수준의 규칙 정의</strong></p><pre>[tool.ruff]<br># 프로젝트 특화 규칙 설정<br>extend-select = [&quot;RUF&quot;]<br>line-length = 88<br><br>[tool.ruff.flake8-quotes]<br>docstring-quotes = &quot;double&quot;<br>inline-quotes = &quot;single&quot;<br><br>[tool.ruff.mccabe]<br>max-complexity = 10<br><br>[tool.ruff.pep8-naming]<br>classmethod-decorators = [&quot;classmethod&quot;, &quot;validator&quot;]</pre><p><strong>3. 외부 도구와의 통합</strong></p><pre>[tool.ruff]<br># 외부 도구 설정 통합<br>extend-select = [<br>    &quot;UP&quot;,   # pyupgrade<br>    &quot;PT&quot;,   # pytest style<br>    &quot;RET&quot;,  # return value checks<br>]<br><br># pytest 스타일 규칙 설정<br>[tool.ruff.pytest]<br>fixture-parentheses = false<br>mark-parentheses = false<br><br># 반환값 검사 설정<br>[tool.ruff.return-statements]<br>allow-implicit-returns = true</pre><h4>고급 커스터마이징 팁</h4><ol><li><strong>성능 최적화를 위한 설정</strong></li></ol><pre>[tool.ruff]<br># 캐시 설정<br>cache-dir = &quot;.ruff_cache&quot;<br>target-version = &quot;py37&quot;<br><br># 파일 필터링<br>exclude = [<br>    &quot;.git&quot;,<br>    &quot;.venv&quot;,<br>    &quot;build&quot;,<br>    &quot;dist&quot;,<br>]<br>respect-gitignore = true<br><br># 성능 설정<br>workers = 4</pre><ol><li><strong>팀 협업을 위한 설정</strong></li></ol><pre>[tool.ruff]<br># 팀 표준 설정<br>line-length = 88<br>indent-width = 4<br>respect-gitignore = true<br><br># 문서화 규칙<br>[tool.ruff.pydocstyle]<br>convention = &quot;google&quot;<br><br># 임포트 정렬<br>[tool.ruff.isort]<br>known-first-party = [&quot;myproject&quot;, &quot;tests&quot;]<br>section-order = [&quot;future&quot;, &quot;standard-library&quot;, &quot;third-party&quot;, &quot;first-party&quot;, &quot;local-folder&quot;]</pre><h3>Ruff 모범 사례 및 팁</h3><p>Ruff를 효과적으로 활용하기 위한 모범 사례와 실용적인 팁들을 알아보겠습니다.</p><p><strong>FastAPI의 Ruff 도입 사례</strong></p><ul><li>프로젝트 크기: 50,000+ 라인의 Python 코드</li><li>도입 결과: 린팅 시간 90% 감소 (45초 → 4초)</li><li>주요 전략:</li><li>점진적 규칙 적용</li><li>자동 수정 기능 적극 활용</li><li>CI/CD 파이프라인 최적화</li></ul><p><strong>Apache Airflow의 활용 사례</strong></p><ul><li>100만 라인 이상의 코드베이스</li><li>복잡한 의존성 관리</li><li>다중 Python 버전 지원</li></ul><p><strong>점진적 도입 전략</strong></p><pre># 1단계: 기본적인 규칙만 적용<br>[tool.ruff]<br>select = [&quot;E&quot;, &quot;F&quot;]  # pycodestyle 에러와 pyflakes만 적용<br><br># 2단계: 중요 규칙 추가<br>[tool.ruff]<br>select = [<br>    &quot;E&quot;, &quot;F&quot;,  # 기본 규칙<br>    &quot;B&quot;,       # bugbear<br>    &quot;I&quot;,       # isort<br>]<br># 3단계: 전체 규칙 적용<br>[tool.ruff]<br>select = [&quot;ALL&quot;]<br>ignore = []  # 필요한 예외만 추가</pre><p><strong>모듈별 설정 관리</strong></p><pre>[tool.ruff.per-file-ignores]<br># 레거시 코드에 대한 예외 처리<br>&quot;legacy/*.py&quot; = [&quot;ALL&quot;]<br><br># 단계적 적용<br>&quot;module_a/*.py&quot; = [&quot;E&quot;, &quot;F&quot;]           # 기본 규칙만 적용<br>&quot;module_b/*.py&quot; = [&quot;E&quot;, &quot;F&quot;, &quot;B&quot;, &quot;I&quot;] # 추가 규칙 적용<br>&quot;module_c/*.py&quot; = [&quot;ALL&quot;]              # 모든 규칙 적용</pre><h4>성능 최적화 및 벤치마크</h4><p><strong>1. 성능 벤치마크 데이터</strong></p><ul><li>Flake8 대비: 10–50배 빠름</li><li>Black 대비: 20–100배 빠름</li><li>isort 대비: 15–90배 빠름</li></ul><p><strong>2. 메모리 사용량 최적화</strong></p><ul><li>기본 설정: 100–200MB</li><li>최적화 후: 50–100MB</li><li>최적화 전략:</li><li>워커 수 조정</li><li>캐시 크기 제한</li><li>필요한 규칙만 선택</li></ul><p><strong>3. 성능 최적화 설정</strong></p><pre>[tool.ruff]<br># 캐시 설정 최적화<br>cache-dir = &quot;.ruff_cache&quot;<br>target-version = &quot;py37&quot;<br><br># 병렬 처리 설정<br>workers = &quot;auto&quot;<br><br># 파일 필터링 최적화<br>exclude = [<br>    &quot;.git&quot;,<br>    &quot;.venv&quot;,<br>    &quot;__pycache__&quot;,<br>    &quot;build&quot;,<br>    &quot;dist&quot;,<br>    &quot;migrations&quot;,<br>]</pre><h4>팀 내 Ruff 도입 프로세스</h4><ol><li><strong>단계별 도입 가이드</strong></li></ol><p><strong>분석 단계</strong> (1–2주)</p><ul><li>현재 코드베이스 분석</li><li>기존 린터와의 충돌 검토</li><li>팀 멤버 의견 수렴</li></ul><p><strong>파일럿 단계</strong> (2–4주)</p><ul><li>작은 모듈에 시범 적용</li><li>설정 최적화</li><li>팀 피드백 수집</li></ul><p><strong>전체 적용 단계</strong> (1–2개월)</p><ul><li>점진적 규칙 확대</li><li>자동화 도구 통합</li><li>문서화 및 가이드라인 작성</li></ul><p><strong>유지보수 단계</strong></p><ul><li>정기적인 설정 리뷰</li><li>새로운 규칙 평가</li><li>팀 교육 및 지원</li></ul><p><strong>2. 표준화된 설정 관리</strong></p><pre># team-standards.toml<br>[tool.ruff]<br># 팀 표준 린트 규칙<br>select = [<br>    &quot;E&quot;,   # 코드 스타일<br>    &quot;F&quot;,   # 논리적 오류<br>    &quot;B&quot;,   # 잠재적 버그<br>    &quot;S&quot;,   # 보안 이슈<br>    &quot;I&quot;,   # 임포트 순서<br>]<br><br># 문서화 규칙<br>[tool.ruff.pydocstyle]<br>convention = &quot;google&quot;</pre><p><strong>3. CI/CD 통합</strong></p><pre># .github/workflows/ruff-review.yml<br>name: Ruff Code Review<br>on: [pull_request]<br><br>jobs:<br>  ruff-check:<br>    runs-on: ubuntu-latest<br>    steps:<br>      - uses: actions/checkout@v4<br>      - uses: chartboost/ruff-action@v1<br>        with:<br>          version: 0.1.8<br>          args: check --output-format=github</pre><h4>문제 해결 가이드</h4><ol><li><strong>일반적인 이슈와 해결책</strong></li></ol><p><strong>성능 저하</strong></p><ul><li>원인: 과도한 규칙 적용</li><li>해결: 필수 규칙만 선택적 적용</li><li>모니터링: 실행 시간 추적</li></ul><p><strong>잘못된 수정</strong></p><ul><li>원인: 안전하지 않은 자동 수정</li><li>해결: --unsafe-fixes 옵션 제한적 사용</li><li>검증: 테스트 자동화</li></ul><p><strong>2. 실용적인 팁과 트릭</strong></p><ol><li><strong>VS Code 통합 최적화</strong></li></ol><pre>{<br> &quot;editor.formatOnSave&quot;: true,<br> &quot;editor.quickSuggestions&quot;: {<br>     &quot;other&quot;: true,<br>     &quot;comments&quot;: false,<br>     &quot;strings&quot;: false<br> }<br>}</pre><p><strong>2. Git 훅 최적화</strong></p><pre># .pre-commit-config.yaml<br>repos:<br>- repo: https://github.com/astral-sh/ruff-pre-commit<br> rev: v0.1.8<br> hooks:<br>   - id: ruff<br>     args: [--fix, --exit-non-zero-on-fix]<br>   - id: ruff-format</pre><p><strong>3. CI/CD 파이프라인 최적화</strong></p><pre># 병렬 처리로 CI 시간 단축<br>ruff:<br>parallel: true<br>matrix:<br> python-version: [&#39;3.7&#39;, &#39;3.8&#39;, &#39;3.9&#39;, &#39;3.10&#39;]</pre><h3>Ruff의 미래와 전망</h3><p>Ruff는 파이썬 생태계에서 빠르게 성장하고 있는 도구입니다. 2024년 3월 기준 1.3.0 버전까지 출시되었으며, 지속적인 발전을 이어가고 있습니다. 여기서는 Ruff의 현재 상황과 미래 전망을 객관적으로 살펴보겠습니다.</p><h4>최신 개발 현황 (2024년 3월 기준)</h4><ul><li>새로운 자동 수정 규칙 추가</li><li>향상된 포맷터 기능</li><li>LSP(Language Server Protocol) 지원 강화</li><li>대규모 코드베이스 처리 시 30% 성능 향상</li><li>메모리 사용량 최적화</li></ul><h4>실제 도입 사례 및 영향</h4><h4>1. 대규모 프로젝트 도입 사례</h4><p><strong>FastAPI</strong></p><ul><li>코드베이스: 50,000+ 라인</li><li>린팅 시간: 45초 → 4초 (91% 감소)</li><li>메모리 사용: 500MB → 150MB</li><li>도입 과정 문제점:</li><li>기존 설정 마이그레이션 어려움</li><li>일부 커스텀 규칙 호환성 이슈</li></ul><p><strong>Apache Airflow</strong></p><ul><li>코드베이스: 1,000,000+ 라인</li><li>빌드 파이프라인 시간: 15분 → 3분</li><li>주요 해결 과제:</li><li>다중 Python 버전 지원</li><li>복잡한 의존성 관리</li><li>점진적 도입 전략 필요</li></ul><h4>현재 한계점 및 과제</h4><h4>1. 기술적 한계</h4><ul><li>현재 제한적 지원</li><li>플러그인 시스템 부재</li><li>2024년 말 지원 계획</li><li>오래된 Python 버전 지원 제한</li><li>복잡한 코드베이스 처리 시 이슈</li><li>일부 자동 수정 불안정성</li></ul><h4>2. 생태계 도전 과제</h4><ul><li><strong>기존 도구와의 경쟁/협력</strong></li><li>Pylint: 더 풍부한 정적 분석 기능</li><li>Black: 확립된 포맷팅 표준</li><li>mypy: 더 강력한 타입 체크</li></ul><h4>향후 전망</h4><ul><li>버그 수정 및 성능 최적화</li><li>IDE 통합 완성도 개선</li><li>사용자 피드백 기반 개선</li><li>더 많은 자동 수정 규칙</li><li>새로운 분석 기능</li><li>설정 시스템 개선</li><li>주요 IDE/도구 완벽 지원</li><li>CI/CD 파이프라인 표준화</li><li>커스텀 규칙 시스템 도입</li></ul><p><strong>Ruff</strong>는 파이썬 개발 도구로서 큰 잠재력을 보여주고 있습니다. 특히 성능과 사용자 경험 측면에서 혁신적인 발전을 이루었으나, 여전히 해결해야 할 과제들이 있습니다.</p><p>성공적인 도입 사례들이 증가하고 있지만, 실제 도입을 고려하는 팀들은 다음 사항을 고려해야 합니다:</p><ul><li>팀의 기술적 성숙도</li><li>기존 도구와의 마이그레이션 계획</li><li>필요한 커스터마이징 수준</li><li>장기적인 유지보수 전략</li></ul><p><strong>Ruff</strong>는 계속해서 발전하고 있으며, 파이썬 생태계의 중요한 도구로 자리잡아가고 있습니다. 그러나 이는 기존 도구들의 완전한 대체가 아닌, 상호 보완적인 관계로 발전할 것으로 전망됩니다.</p><h3>마무리</h3><p><strong>Ruff</strong>는 단순한 린터를 넘어 파이썬 개발 워크플로우를 혁신하는 도구로 자리잡았습니다. 특히 성능, 사용자 경험, 그리고 확장성 측면에서 기존 도구들과 차별화된 가치를 제공합니다.</p><p>이 튜토리얼에서 다룬 내용을 바탕으로, 여러분의 프로젝트에 <strong>Ruff</strong>를 도입하시면서 다음 사항을 기억해주세요:</p><ol><li><strong>점진적 도입</strong>: 한 번에 모든 것을 바꾸려 하지 마세요. 단계적인 접근이 성공의 열쇠입니다.</li><li><strong>팀 참여</strong>: 설정과 규칙에 대한 팀의 합의를 구하고, 지속적인 피드백을 수집하세요.</li><li><strong>유연한 적용</strong>: 프로젝트의 특성과 팀의 상황에 맞게 유연하게 적용하세요.</li></ol><p><strong>Ruff</strong>의 여정은 아직 진행 중이며, 파이썬 개발 생태계는 계속해서 발전하고 있습니다. 이 도구를 통해 여러분의 개발 경험이 한층 더 효율적이고 즐거워지기를 바랍니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7a96acc8a302" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Effective Prompt Engineering for Data Extraction with Large Language Models]]></title>
            <link>https://medium.com/@kofsitho/effective-prompt-engineering-for-data-extraction-with-large-language-models-331ee454cbae?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/331ee454cbae</guid>
            <category><![CDATA[kor]]></category>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[extraction]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Mon, 22 Jul 2024 02:38:42 GMT</pubDate>
            <atom:updated>2024-07-22T02:38:42.297Z</atom:updated>
            <content:encoded><![CDATA[<p>In the era of big data, efficiently extracting structured information from vast amounts of unstructured text has become a critical task. Large Language Models (LLMs) like GPT-3 and GPT-4 have demonstrated impressive capabilities in natural language understanding and generation, but their performance heavily relies on well-crafted prompts. This blog will explore methods for effective prompt engineering to optimize data extraction using LLMs.</p><h3>Table of Contents</h3><p>1. Introduction</p><p>2. Importance of Prompt Engineering</p><p>3. Key Strategies for Effective Prompt Engineering</p><p>• Providing Clear Instructions</p><p>• Supplying Reference Examples</p><p>• Utilizing Extraction Schema</p><p>4. Example Prompt</p><p>5. Conclusion</p><p>6. References</p><p>7. Introduction</p><p>The advent of Large Language Models (LLMs) such as GPT-3 and GPT-4 has revolutionized natural language processing. These models are capable of performing a wide range of tasks, from generating human-like text to extracting meaningful data from unstructured inputs. However, their effectiveness significantly depends on how we engineer the prompts. Prompt engineering is the process of designing and refining the inputs given to LLMs to achieve the desired output.</p><h3>2. Importance of Prompt Engineering</h3><p>Prompt engineering is crucial because it directly impacts the quality and accuracy of the data extracted by LLMs. A well-crafted prompt can guide the model to produce precise and relevant information, while a poorly designed prompt can lead to ambiguous or incorrect results. Effective prompt engineering involves providing clear instructions, relevant examples, and well-defined schemas that the model can follow.</p><h3>3. Key Strategies for Effective Prompt Engineering</h3><p>Providing Clear Instructions</p><p>Clear and specific instructions are essential for guiding LLMs to extract the correct data. Ambiguity in instructions can cause the model to misinterpret the task, leading to errors.</p><p>Example:</p><p>Your goal is to extract structured information from the user’s input that matches the form described below. When extracting information please make sure it matches the type information exactly. Do not add any attributes that do not appear in the schema shown below.</p><p>Supplying Reference Examples</p><p>Providing input-output examples helps the model understand the type of data to extract and ensures consistency. These examples act as a template for the model to follow.</p><p>Example:</p><pre>Input: Songs by Paul Simon<br>Output: {&quot;musicrequest&quot;: {&quot;artist&quot;: [&quot;Paul Simon&quot;]}}<br>Input: Please stop the music<br>Output: {&quot;musicrequest&quot;: {&quot;action&quot;: &quot;stop&quot;}}<br>Input: play something<br>Output: {&quot;musicrequest&quot;: {&quot;action&quot;: &quot;play&quot;}}</pre><p>Utilizing Extraction Schema</p><p>Defining the structure of the data to be extracted clearly ensures the model understands the format in which to extract the data. This step is crucial for maintaining consistency and accuracy.</p><p>Example:</p><pre>musicrequest: {<br>song: Array // The song(s) that the user would like to be played.<br>album: Array // The album(s) that the user would like to be played.<br>artist: Array // The artist(s) whose music the user would like to hear.<br>action: &quot;play&quot; | &quot;stop&quot; | &quot;previous&quot; | &quot;next&quot; // The action that should be taken; one of play, stop, next, previous<br>}</pre><h3>4. Example Prompt</h3><p>Combining the strategies discussed, an example prompt for extracting music-related requests could look like this:</p><pre>Your goal is to extract structured information from the user&#39;s input that matches the form described below. <br>When extracting information please make sure it matches the type information exactly. Do not add any attributes that do not appear in the schema shown below.<br><br>musicrequest: {<br>song: Array // The song(s) that the user would like to be played.<br>album: Array // The album(s) that the user would like to be played.<br>artist: Array // The artist(s) whose music the user would like to hear.<br>action: &quot;play&quot; | &quot;stop&quot; | &quot;previous&quot; | &quot;next&quot; // The action that should be taken; one of play, stop, next, previous<br>}<br><br>Please output the extracted information in JSON format. <br>Do not output anything except for the extracted information. Do not add any clarifying information. Do not add any fields that are not in the schema. If the text contains attributes that do not appear in the schema, please ignore them. All output must be in JSON format and follow the schema specified above. Wrap the JSON in tags.<br><br><br>Input: Songs by Paul Simon<br>Output: {&quot;musicrequest&quot;: {&quot;artist&quot;: [&quot;Paul Simon&quot;]}}<br>Input: Please stop the music<br>Output: {&quot;musicrequest&quot;: {&quot;action&quot;: &quot;stop&quot;}}<br>Input: play something<br>Output: {&quot;musicrequest&quot;: {&quot;action&quot;: &quot;play&quot;}}<br>Input: play a song<br>Output: {&quot;musicrequest&quot;: {&quot;action&quot;: &quot;play&quot;}}<br>Input: next song<br>Output: {&quot;musicrequest&quot;: {&quot;action&quot;: &quot;next&quot;}}<br>Input: [user input]<br>Output:</pre><h3>5. Conclusion</h3><p>Effective prompt engineering is vital for harnessing the full potential of LLMs in data extraction tasks. By providing clear instructions, relevant examples, and well-defined schemas, we can significantly improve the accuracy and consistency of the extracted data. Implementing these strategies will lead to better project outcomes and more efficient data processing.</p><h3>6. References</h3><p>The content of this post is referenced from the Kor documentation available on GitHub.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=331ee454cbae" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[EP3: jobs.csv → Neo4J로 데이터로드]]></title>
            <link>https://medium.com/@kofsitho/ep3-jobs-csv-neo4j%EB%A1%9C-%EB%8D%B0%EC%9D%B4%ED%84%B0%EB%A1%9C%EB%93%9C-16760d756efe?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/16760d756efe</guid>
            <category><![CDATA[graph-database]]></category>
            <category><![CDATA[data-analysis]]></category>
            <category><![CDATA[neo4j]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Tue, 30 Apr 2024 06:50:51 GMT</pubDate>
            <atom:updated>2024-04-30T06:50:51.605Z</atom:updated>
            <content:encoded><![CDATA[<p>이 시리즈의 시작은 크롤링한 직업 데이터를 효과적으로 전처리하고 분석하는 방법을 소개하는것으로 시작했습니다. <br>이번 에피소드에서는 이전에 작업한 전 처리한 jobs 데이터를 Neo4j 그래프 데이터베이스에 로드하고 쿼리를 실행해보도록 하겠습니다.</p><h3>목차</h3><ul><li>준비물 챙기기(파이썬, Vscode or Jupyter, <a href="https://www.notion.so/EP3-jobs-csv-Neo4J-182518055b52485698c8d629e4e19e1a?pvs=21">jobs.csv 파일</a>)</li><li><strong>모델링:</strong> Node와 Edge(Relationship)에 대한 계획세우기</li><li>Neo4j에 데이터로드</li><li>간단한 EDA(탐색적 데이터 분석)를 통해 데이터 알아보기</li><li>FULLTEXT INDEX 만들고 실행(검색)해보기</li></ul><h3>준비물 챙기기(파이썬, Vscode or Jupyter, jobs.csv 파일)</h3><p>이번 블로그 포스트에서는 크롤링한 직업 데이터를 그래프 데이터베이스인 Neo4J에 로드하는 과정을 소개합니다. 이 작업을 성공적으로 수행하려면 몇 가지 필수 도구가 필요합니다. 이를 위해 아래의 준비물을 챙겨주세요:</p><ol><li><strong>Python</strong></li><li><strong>Vscode 또는 Jupyter Notebook</strong>: 데이터 전처리 및 그래프 데이터베이스 로드 작업은 코드 작성과 실행이 필수입니다. 코드 에디터(VSCode)나 Jupyter Notebook을 사용해 작업을 진행하도록 하겠습니다. Jupyter Notebook은 단계별로 작업을 실행하고 결과를 시각적으로 확인하기에 유용합니다.</li><li><strong>jobs.csv 파일</strong>: 이전 세션에서 전처리한 직업 데이터가 담긴 <a href="https://raw.githubusercontent.com/kofsitho87/RAG/main/Neo4j%20vector%20%EA%B2%80%EC%83%89%EC%9D%84%20%ED%86%B5%ED%95%B4%20%EC%9E%A1%EA%B2%80%EC%83%89%ED%95%98%EA%B8%B0/data/pre_processed_jobs_worknet.csv"><strong>jobs.csv</strong></a> 파일이 필요합니다. 이 파일에는 직업의 제목, 회사, 위치, 요구 사항 등 각종 직업 정보가 담겨 있습니다. 이 데이터를 Neo4J에 로드 할 것 입니다.<br>jobs.csv file url: <a href="https://raw.githubusercontent.com/kofsitho87/RAG/main/Neo4j%20vector%20%EA%B2%80%EC%83%89%EC%9D%84%20%ED%86%B5%ED%95%B4%20%EC%9E%A1%EA%B2%80%EC%83%89%ED%95%98%EA%B8%B0/data/pre_processed_jobs_worknet.csv">https://raw.githubusercontent.com/kofsitho87/RAG/main/Neo4j%20vector%20%EA%B2%80%EC%83%89%EC%9D%84%20%ED%86%B5%ED%95%B4%20%EC%9E%A1%EA%B2%80%EC%83%89%ED%95%98%EA%B8%B0/data/pre_processed_jobs_worknet.csv</a></li><li><strong>Neo4J 데이터베이스 준비</strong>: 이번 세션에서는 <a href="https://console.neo4j.io/?product=aura-db">Neo4J Sandbox</a> 를 활용할 예정입니다. Neo4J Sandbox의 시작방법에 대해서는 <a href="https://medium.com/@kofsitho/ep-2-graphdb-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0-feat-neo4j-1504bf3bdf57">이 블로그</a>의 Neo4j시작 부분을 참고해주세요.</li></ol><h3>모델링: Node와 Edge(Relationship)에 대한 계획세우기</h3><p>Neo4j의 그래프 모델링은 흡사 마인드맵과 비슷하거나 유사해 보입니다.</p><p>이러한 유사점은 둘 다 데이터를 시각적으로 표현하는 방식이라는 점입니다. 마인드맵은 중심 아이디어를 시작으로 다양한 노드와 가지를 통해 세부 정보를 나타내는데, 이는 그래프 모델링에서 <strong>노드(객체)</strong>와 <strong>에지(선)</strong>로 데이터를 표현하는 방식과 유사합니다.</p><p>이렇게 데이터를 시각화하고 구조화하는 것은 다양한 장점을 제공합니다.</p><ol><li><strong>데이터 이해</strong>: 복잡한 데이터를 한눈에 파악할 수 있게 해줍니다.</li><li><strong>정보 탐색과 분석</strong>: 이러한 시각적 구성을 통해 복잡한 정보를 쉽게 탐색할 수 있게 합니다.</li><li><strong>의사결정: </strong>결국 시각화는 데이터를 효과적으로 분석하여 의사결정 과정에서 활용할 수 있도록 도와줍니다.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_l3knjljkr8Fnp94bpR4rA.png" /><figcaption><strong>노드(객체)</strong>와 <strong>에지(선)</strong>에<strong> </strong>대한 Describe</figcaption></figure><p>이제 우리는 jobs.csv 데이터를 활용해서 위 이미지와 같은 그래프로 데이터를 로드 할 예정입니다.</p><ul><li>Job 노드는 직업에 대한 노드를 의미합니다.</li><li>Company 노드는 Job 노드와 HAS_JOB_OPENNIG 이란 관계로 연결되어 있습니다.</li><li>Benefit 노드는 “주택자금지원”, “식사제공” 등 회사의 복지와 관련된 노드이며, Job 노드와PROVIDES_BENEFIT 관계로 연결되어 있습니다.</li><li>VolunteerEducation 노드는 해당 Job에 대한 지원자의 교육적 요구사항에 대한 노드이며 Job 노드와REQUIRES_VOLUNTEER_EDUCATION 관계로 연결되어 있습니다.</li><li>WeeklyWorkdays 노드는 주간 근무일을 나타내며, Job 노드와HAS_WEEKLY_WORKDAYS 관계로 연결되어 있습니다.</li><li>ContractType 노드는 계약기간을 나타내며, Job 노드와USES_CONTRACT_TYPE 관계로 연결되어 있습니다.</li></ul><p>그래프 데이터에 대한 더 자세한 모델링 디자인에 대해서는 다음 글을 참고해보세요. <br><a href="https://neo4j.com/docs/getting-started/data-modeling/modeling-designs/">https://neo4j.com/docs/getting-started/data-modeling/modeling-designs</a></p><h3>Neo4j에 데이터로드</h3><p>이제 본격적으로 csv 데이터를 Neo4j 그래프데이터베이스에 로드하는 코드를 작성해 보겠습니다.</p><p>이제부터 코드는 주피터 노트북이나 vscode 노트북을 활용해 작성하시면 됩니다.</p><h4>1. Neo4j 라이브러리 설치</h4><pre># neo4j 라이브러리 설치<br>%pip install neo4j</pre><h4>2. 데이터베이스 연결 설정</h4><pre>username=&quot;neo4j&quot;<br>password=&quot;your db password&quot;<br>url=&quot;your db connection url&quot;<br>database=&quot;neo4j&quot; # default neo4j<br><br>from neo4j import GraphDatabase<br>with  GraphDatabase.driver(uri=url, auth=(username, password)) as driver:<br>    driver.verify_connectivity()<br>    session = driver.session(database=database)</pre><p>다음으로, Neo4j 데이터베이스에 연결하기 위한 설정을 진행합니다. 이 설정에서는 데이터베이스에 접속하기 위한 사용자 이름, 비밀번호, URL 등을 정의합니다.</p><pre>csv_file_path = &quot;https://raw.githubusercontent.com/kofsitho87/RAG/main/Neo4j%20vector%20%EA%B2%80%EC%83%89%EC%9D%84%20%ED%86%B5%ED%95%B4%20%EC%9E%A1%EA%B2%80%EC%83%89%ED%95%98%EA%B8%B0/data/pre_processed_jobs_worknet.csv&quot;  <br>session.run(f&quot;&quot;&quot; LOAD CSV WITH HEADERS FROM &#39;{csv_file_path}&#39; AS row WITH row.JobTitle as title RETURN title LIMIT 3 &quot;&quot;&quot;).to_df()</pre><pre>title<br>0	단순 포장반직원 모집합니다<br>1	단순포장 및 락크작업<br>2	육류 가공 식당납품</pre><p>위 코드를 통해서 csv파일이 잘 로드가 되었는지 확인해 볼 수 있습니다.</p><h4>3. Cypher 쿼리를 통해 데이터 로드하기</h4><pre>query = f&quot;&quot;&quot;<br>LOAD CSV WITH HEADERS FROM &#39;{csv_file_path}&#39; AS row<br><br>WITH row<br>// Job<br>MERGE (j:Job {name: trim(row.JobTitle)})<br>    SET j.required_experience_months = COALESCE(toInteger(row.RequiredExperienceMonths), null)<br>    SET j.preferred_experience_months = COALESCE(toInteger(row.PreferredExperienceMonths), null)<br>    SET j.payment = trim(row.JobPayment)<br>    SET j.min_monthly_payment = COALESCE(toInteger(row.MinMonthlyPayment), null)<br>    SET j.max_monthly_payment = COALESCE(toInteger(row.MaxMonthlyPayment), null)<br>    <br>// WeeklyWorkdays<br>WITH row, j<br>WHERE row.Workdays IS NOT NULL<br>MERGE (wd:WeeklyWorkdays {value: toInteger(row.Workdays)})<br>MERGE (j)-[:HAS_WEEKLY_WORKDAYS]-&gt;(wd)<br>// ContractType<br>WITH row, j<br>WHERE row.JobContractType IS NOT NULL<br>MERGE (ct:ContractType {name: trim(row.JobContractType)})<br>MERGE (j)-[:USES_CONTRACT_TYPE]-&gt;(ct)<br>// VolunteerEducation<br>WITH row, j<br>WHERE row.JobVolunteerEducation IS NOT NULL<br>MERGE (ve:VolunteerEducation {name: trim(row.JobVolunteerEducation)})<br>MERGE (j)-[:REQUIRES_VOLUNTEER_EDUCATION]-&gt;(ve)<br>// Benefit<br>WITH row, j<br>WHERE row.JobBenefits IS NOT NULL<br>FOREACH (<br>    item in split(row.JobBenefits, &#39; &#39;) | <br>    MERGE (b:Benefit {name: trim(item)})<br>    MERGE (j)-[:PROVIDES_BENEFIT]-&gt;(b)<br>)<br>// Company<br>WITH row, j<br>WHERE row.CompanyName IS NOT NULL<br>MERGE (c: Company {name: trim(row.CompanyName)})<br> SET c.industry = COALESCE(trim(row.CompanyIndustry), null)<br> SET c.size = COALESCE(trim(row.CompanySize), null)<br>    SET c.address = COALESCE(trim(row.CompanyLocation), null)<br>MERGE (c)-[:HAS_JOB_OPENING]-&gt;(j)<br>&quot;&quot;&quot;<br>result = session.run(query)</pre><p>위 쿼리의 각 부분을 살펴보겠습니다.</p><pre>query = f&quot;&quot;&quot;<br>LOAD CSV WITH HEADERS FROM &#39;{csv_file_path}&#39; AS row<br>&quot;&quot;&quot;</pre><p>이 부분은 주어진 URL에서 CSV 파일을 가져와 각 행을 row로 불러옵니다. <strong>HEADERS</strong> 키워드는 첫 번째 줄을 헤더로 간주하고, 이를 통해 행의 필드에 접근할 수 있게 합니다.</p><pre>MERGE (j:Job {name: trim(row.JobTitle)})<br>    SET j.required_experience_months = COALESCE(toInteger(row.RequiredExperienceMonths), null)<br>    SET j.preferred_experience_months = COALESCE(toInteger(row.PreferredExperienceMonths), null)<br>    SET j.payment = trim(row.JobPayment)<br>    SET j.min_monthly_payment = COALESCE(toInteger(row.MinMonthlyPayment), null)<br>    SET j.max_monthly_payment = COALESCE(toInteger(row.MaxMonthlyPayment), null)</pre><p>이 부분은 <strong>Job</strong> 노드를 생성하거나 (기존에 동일한 노드가 있다면) 해당 노드에 데이터를 업데이트합니다. <strong>MERGE</strong> 키워드는 노드가 존재하지 않으면 생성하고, 존재하면 그대로 유지합니다. 추가로, 여러 <strong>SET</strong> 구문을 통해 노드의 다양한 속성을 설정합니다.</p><pre>WITH row, j<br>WHERE row.Workdays IS NOT NULL<br>MERGE (wd:WeeklyWorkdays {value: toInteger(row.Workdays)})<br>MERGE (j)-[:HAS_WEEKLY_WORKDAYS]-&gt;(wd)</pre><p>이 부분은 <strong>WeeklyWorkdays</strong> 노드를 생성하고 <strong>Job</strong> 노드와 관계를 맺습니다. WITH row, j는 <strong>Job</strong> 노드를 유지한 채 다음 단계로 넘어가도록 해주고, WHERE는 <strong>Workdays</strong> 필드가 NULL이 아닐 때만 작업을 수행합니다.</p><pre>WITH row, j<br>WHERE row.JobContractType IS NOT NULL<br>MERGE (ct:ContractType {name: trim(row.JobContractType)})<br>MERGE (j)-[:USES_CONTRACT_TYPE]-&gt;(ct)<br><br>WITH row, j<br>WHERE row.JobVolunteerEducation IS NOT NULL<br>MERGE (ve:VolunteerEducation {name: trim(row.JobVolunteerEducation)})<br>MERGE (j)-[:REQUIRES_VOLUNTEER_EDUCATION]-&gt;(ve)<br>WITH row, j<br>WHERE row.JobBenefits IS NOT NULL<br>FOREACH (<br>    item in split(row.JobBenefits, &#39; &#39;) |<br>    MERGE (b:Benefit {name: trim(item)})<br>    MERGE (j)-[:PROVIDES_BENEFIT]-&gt;(b)<br>)<br>WITH row, j<br>WHERE row.CompanyName IS NOT NULL<br>MERGE (c: Company {name: trim(row.CompanyName)})<br>    SET c.industry = COALESCE(trim(row.CompanyIndustry), null)<br>    SET c.size = COALESCE(trim(row.CompanySize), null)<br>    SET c.address = COALESCE(trim(row.CompanyLocation), null)<br>MERGE (c)-[:HAS_JOB_OPENING]-&gt;(j)</pre><p>각 단계에서 노드를 생성하고 관계를 설정하는 작업이 수행됩니다. 특히 <strong>FOREACH</strong> 구문은 <strong>JobBenefits</strong> 필드를 공백 기준으로 분리하여 각 항목을 개별적으로 처리합니다.</p><pre>CALL db.schema.visualization()</pre><p>위 쿼리를 실행한 후 아래 코드를 통해 노드와 관계를 시각화 하면 아래 그림과 같습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/959/1*NJVbdh8re9mH4l-pVmHTtQ.png" /></figure><pre>MATCH (n:Benefit) RETURN n</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/982/1*3x18Ljx8E5h5hN8RXY9K6g.png" /></figure><p>이 SQL 쿼리는 <strong>Benefit</strong> 노드에 해당하는 모든 노드를 검색하여 반환합니다. 이 결과에는 다음과 같은 노드들이 포함되어 있습니다:</p><ul><li>“식사제공(1식)”</li><li>“식사제공(2식)”</li><li>“식사제공(3식)”</li><li>“식사제공(중식비지급)”</li></ul><p>이러한 <strong>Benefit</strong> 노드들의 이름에서 알 수 있듯이, 이들은 모두 식사 제공과 관련된 혜택을 나타냅니다. 그러나 노드 이름이 세분화되어 있어 복잡해 보일 수 있습니다. 따라서 이를 개선하기 위해 &quot;식사제공&quot;이라는 하나의 노드로 통합하려고 합니다.</p><p>통합 후에도 각 노드의 식사 제공 혜택의 세부 내용은 유지되어야 합니다. 이를 위해 각 노드와 <strong>Job</strong> 노드 간의 <strong>PROVIDES_BENEFIT</strong> 관계에 세부 정보를 추가하려고 합니다. 예를 들어, &quot;1식&quot;, &quot;2식&quot;, &quot;3식&quot; 등의 세부 정보를 관계에 포함시켜서, 어떤 식사 제공 혜택이 있는지 파악할 수 있습니다.</p><p>이렇게 통합된 구조에서는 “식사제공” 노드가 여러 <strong>Job</strong> 노드와 연결되며, 각각의 <strong>PROVIDES_BENEFIT</strong> 관계는 식사 제공의 종류에 대한 상세 정보를 포함합니다. 이를 통해 데이터 구조를 간소화하면서도 필요한 정보를 모두 유지할 수 있습니다.</p><p>다음의 “식사제공”이라는 하나의 노드로 통합을 하는 쿼리 입니다.</p><pre>session.run(&quot;&quot;&quot;<br>// &quot;식사제공&quot; Benefit 노드 생성<br>MERGE (unified:Benefit {name: &quot;식사제공&quot;})<br><br>// &quot;식사제공&quot; Benefit 노드에 연결되어 있던 기존 관계와 노드를 처리<br>WITH unified<br>MATCH (j:Job)-[r:PROVIDES_BENEFIT]-&gt;(b:Benefit)<br>WHERE b.name IN [&quot;식사제공(1식)&quot;, &quot;식사제공(2식)&quot;, &quot;식사제공(3식)&quot;, &quot;식사제공(중식비지급)&quot;]<br>WITH j, b, unified, r,<br> CASE b.name<br>  WHEN &quot;식사제공(1식)&quot; THEN 1<br>  WHEN &quot;식사제공(중식비지급)&quot; THEN 1<br>  WHEN &quot;식사제공(2식)&quot; THEN 2<br>  WHEN &quot;식사제공(3식)&quot; THEN 3<br> END as meals<br>MERGE (j)-[new_r:PROVIDES_BENEFIT {meals: meals}]-&gt;(unified)<br>DELETE r // 기존 관계 삭제<br>DETACH DELETE b // 기존 노드 삭제<br>&quot;&quot;&quot;)</pre><pre>session.run(&quot;&quot;&quot;<br>MATCH (b:Benefit {name: &#39;식사제공&#39;})&lt;-[r:PROVIDES_BENEFIT]-(j:Job)<br>WHERE r.meals IN [1, 2, 3]<br>RETURN r.meals, count(j) AS count<br>ORDER BY r.meals<br>&quot;&quot;&quot;).to_df()</pre><pre>r.meals count<br>0	1	      449<br>1	2	      143<br>2	3	      85</pre><p>이 결과는 <strong>meals</strong> 값에 따라 &quot;식사제공&quot; 혜택을 제공하는 직업의 수를 보여줍니다:</p><ul><li><strong>Job</strong> 데이터 중 &quot;식사제공&quot; 혜택이 가장 많은 것은 1식 제공이며, 이는 전체 중 가장 큰 비중을 차지합니다.</li><li>2식과 3식을 제공하는 직업의 수는 상대적으로 적지만, 해당 혜택을 제공하는 직업들도 다 수 있습니다.</li></ul><h3>간단한 EDA(탐색적 데이터 분석)를 통해 데이터 알아보기</h3><h4><strong>1. 직업의 수와 평균 급여</strong>:</h4><pre>MATCH (j:Job)<br>RETURN <br>count(j) AS num_jobs, <br>avg(j.min_monthly_payment) AS avg_min_payment, <br>avg(j.max_monthly_payment) AS avg_max_payment</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VjRfyYkPKp5nFMnQAyh1Rg.png" /></figure><p>이 쿼리는 데이터베이스에 있는 직업의 수와 각 직업의 최소, 최대 월급의 평균을 계산하여 반환합니다.</p><ul><li>최소월급의 평균: 약 226만원</li><li>최대월급의 평균: 약 264만원</li></ul><h4><strong>2. 직업 유형별 평균 급여</strong>:</h4><pre>MATCH (j:Job)-[:USES_CONTRACT_TYPE]-&gt;(ct:ContractType)<br>RETURN ct.name AS contract_type, avg(j.min_monthly_payment) AS avg_min_payment, avg(j.max_monthly_payment) AS avg_max_payment<br>ORDER BY contract_type</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LxVzzbeXKbak9PyIluM_pQ.png" /></figure><p>이 쿼리는 각 직업의 계약 유형별로 그룹화하여, 각 그룹의 평균 최소 월급과 평균 최대 월급을 계산하고 이를 반환합니다.</p><h4>3. 회사별 직업과 제공 혜택 현황</h4><pre>MATCH (c:Company)--&gt;(j:Job)-[r:PROVIDES_BENEFIT]-&gt;(b:Benefit)<br>RETURN c.name AS company_name, j.name AS job_name, count(b) AS num_benefits<br>ORDER BY num_benefits DESC<br>LIMIT 10</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Znb4GhsYREYNxfwPyKCbRQ.png" /></figure><p>각 회사의 직업이 제공하는 혜택의 수를 집계하고 상위 10개 결과 출력</p><h4>4. Benefit별 직업 제공 현황: 가장 많이 제공되는 혜택 순위</h4><pre>MATCH (j:Job)-[r:PROVIDES_BENEFIT]-&gt;(b:Benefit)<br>RETURN b.name AS benefit_name, count(j) AS offered_count<br>ORDER BY offered_count DESC</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*312hxZy11Xoyc9H5VNq_xg.png" /></figure><p>이 쿼리는 각 <strong>Benefit</strong> 노드에 대해 해당 혜택을 제공하는 직업의 수를 집계합니다. <strong>PROVIDES_BENEFIT</strong> 관계를 통해 <strong>Job</strong> 노드와 <strong>Benefit</strong> 노드 간의 연결을 찾아, 각 혜택이 얼마나 자주 제공 되는지 파악합니다.</p><h4>5. 직업의 근무 일수 분포:</h4><pre>MATCH (j:Job)-[:HAS_WEEKLY_WORKDAYS]-&gt;(wd:WeeklyWorkdays)<br>RETURN wd.value AS workdays, count(j) AS num_jobs<br>ORDER BY workdays</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/750/1*bsmJ0W8z-PTuE-3dc8ZEeQ.png" /></figure><p>이 쿼리는 직업의 주간 근무 일수별로 그룹화하여 각 그룹에 속하는 직업의 수를 반환합니다. 이를 통해 근무 일수 분포를 파악할 수 있습니다.</p><h3>FULLTEXT INDEX 만들고 실행(검색)해보기</h3><h4>1. FULLTEXT INDEX란?</h4><p>FULLTEXT INDEX는 Neo4j 데이터베이스에 저장된 노드와 관계의 텍스트 속성을 빠르게 검색할 수 있도록 도와주는 인덱스입니다. 예를 들어, 직업 데이터베이스에서 <strong>Job</strong> 노드의 <strong>name</strong> 속성이나 <strong>Company</strong> 노드의 <strong>industry</strong> 속성에 대한 검색을 빠르게 수행할 수 있습니다.</p><ul><li><strong>인덱싱</strong>: FULLTEXT INDEX는 지정된 노드와 관계의 텍스트 속성을 미리 인덱싱합니다. 인덱싱은 데이터의 특정 부분을 미리 정리하여, 이후 검색 시 빠르게 찾아낼 수 있도록 하는 작업입니다. 예를 들어, 직업 제목이나 회사 이름 등의 텍스트 데이터를 미리 정리해 둡니다.</li><li><strong>검색 속도 향상</strong>: 인덱싱된 데이터는 검색 시에 빠르게 접근할 수 있습니다. 예를 들어, 직업 데이터베이스에서 특정 직업 제목을 찾을 때, FULLTEXT INDEX를 사용하면 텍스트 데이터를 직접 스캔하는 대신 인덱스에서 바로 찾아낼 수 있습니다.</li></ul><h4>2. Create Full-Text Index</h4><p>먼저 <strong>Job</strong> 노드의 <strong>name</strong> 속성에 대한 FULLTEXT INDEX를 생성합니다.</p><pre>from neo4j import GraphDatabase<br>with  GraphDatabase.driver(uri=url, auth=(username, password)) as driver:<br>    driver.verify_connectivity()<br>    session = driver.session(database=database)<br>session.run(&quot;&quot;&quot;<br>CREATE FULLTEXT INDEX job_name_fulltext <br>FOR (j:Job) ON EACH [j.name]<br>OPTIONS {<br>  indexConfig: {<br>    `fulltext.analyzer`: &#39;cjk&#39;,<br>    `fulltext.eventually_consistent`: true<br>  }<br>}<br>&quot;&quot;&quot;)</pre><ul><li><strong>인덱스 생성</strong>: CREATE FULLTEXT INDEX job_name_fulltext는 job_name_fulltext라는 이름의 FULLTEXT INDEX를 생성합니다. 이 인덱스는 Neo4j 데이터베이스에서 <strong>Job</strong> 노드의 <strong>name</strong> 속성에 대한 인덱싱을 수행합니다.</li><li><strong>대상 노드와 속성</strong>: FOR (j:Job) ON EACH [j.name]는 <strong>Job</strong> 노드의 <strong>name</strong> 속성을 인덱싱의 대상으로 지정합니다. 이를 통해 직업 이름에 대한 텍스트 검색을 효율적으로 수행할 수 있습니다.</li><li><strong>옵션 설정</strong>: <strong>OPTIONS</strong> 블록에서 인덱스의 다양한 설정을 지정합니다. 특히 indexConfig에 대해 자세히 살펴보겠습니다.</li></ul><p><strong>indexConfig</strong> 블록에서는 인덱스에 대한 다양한 설정을 지정할 수 있습니다.</p><ul><li><strong>fulltext.analyzer: &#39;cjk&#39;</strong>: 이 옵션은 인덱싱에 사용할 분석기(Analyzer)를 지정합니다. 여기서는 &#39;cjk&#39; 분석기를 사용하여, 중국어, 일본어, 한국어 등 CJK 문자에 적합한 분석을 수행하도록 합니다. 이를 통해 해당 언어의 문자를 정확하게 인덱싱하고 검색할 수 있습니다.</li><li><strong>fulltext.eventually_consistent: true</strong>: 이 옵션은 인덱스의 일관성을 어떻게 유지 할 지를 지정합니다. true로 설정되어 있으면, 데이터베이스에서 발생하는 변경 사항이 인덱스에 반영되는 데 시간이 조금 걸릴 수 있지만, 전체 시스템의 성능이 향상됩니다.</li></ul><p>위와 같은 방식으로 계속에서 Full-Text Index를 생성하겠습니다.</p><pre>#volunteer_education_fulltext<br>session.run(&quot;&quot;&quot;<br>CREATE FULLTEXT INDEX volunteer_education_fulltext <br>FOR (n:VolunteerEducation) ON EACH [n.name]<br>OPTIONS {<br>  indexConfig: {<br>    `fulltext.analyzer`: &#39;cjk&#39;,<br>    `fulltext.eventually_consistent`: true<br>  }<br>}<br>&quot;&quot;&quot;)<br><br>#benefit_fulltext<br>session.run(&quot;&quot;&quot;<br>CREATE FULLTEXT INDEX benefit_fulltext <br>FOR (b:Benefit) ON EACH [b.name]<br>OPTIONS {<br>  indexConfig: {<br>    `fulltext.analyzer`: &#39;cjk&#39;,<br>    `fulltext.eventually_consistent`: true<br>  }<br>}<br>&quot;&quot;&quot;)<br><br>#company_industry<br>session.run(&quot;&quot;&quot;<br>CREATE FULLTEXT INDEX company_industry_fulltext <br>FOR (c:Company) ON EACH [c.industry]<br>OPTIONS {<br>  indexConfig: {<br>    `fulltext.analyzer`: &#39;cjk&#39;,<br>    `fulltext.eventually_consistent`: true<br>  }<br>}<br>&quot;&quot;&quot;)</pre><p><strong>Job</strong> 노드의 이름에 대한 FULLTEXT INDEX를 사용하여, &quot;식당보조&quot;라는 키워드를 포함하는 직업을 검색</p><pre>session.run(&quot;&quot;&quot;<br>CALL db.index.fulltext.queryNodes(&quot;job_name_fulltext&quot;, &quot;식당보조&quot;) <br>YIELD node, score<br>RETURN score, node.name as job<br>ORDER BY score DESC<br>LIMIT 10<br>&quot;&quot;&quot;)</pre><pre># Result<br>[{&#39;score&#39;: 4.155252456665039, &#39;job&#39;: &#39;정육식당 보조 구인(내/외국인)&#39;},<br> {&#39;score&#39;: 2.9305131435394287, &#39;job&#39;: &#39;육류 가공 식당납품&#39;},<br> {&#39;score&#39;: 2.7983179092407227, &#39;job&#39;: &#39;구내식당 찬모님 급구.&#39;},<br> {&#39;score&#39;: 2.2833163738250732, &#39;job&#39;: &#39;청담동순도리 식당 주방 / 홀서빙 직원 모집&#39;},<br> {&#39;score&#39;: 2.2188167572021484, &#39;job&#39;: &#39;용접 보조 조공 제관 보조 구인&#39;},<br> {&#39;score&#39;: 2.126753807067871, &#39;job&#39;: &#39;내국인, 외국인 구분 없이 채용. 식당 홀 서빙. 초보자 환영&#39;},<br> {&#39;score&#39;: 2.00286865234375, &#39;job&#39;: &#39;주방보조&#39;},<br> {&#39;score&#39;: 1.990283489227295, &#39;job&#39;: &#39;새마을운동중앙회 연수원식당 조리직원 채용&#39;},<br> {&#39;score&#39;: 1.9386987686157227, &#39;job&#39;: &#39;보조교사 구함 (보조인력)/외국인환영&#39;},<br> {&#39;score&#39;: 1.903559923171997, &#39;job&#39;: &#39;떡 제조 보조원&#39;}]</pre><h3>Summary</h3><p>이번 세션에서는 크롤링한 직업 데이터를 Neo4j 그래프 데이터베이스에 로드하고, 이를 활용하여 탐색적 데이터 분석(EDA)과 검색 작업을 수행하는 과정을 다뤘습니다.</p><p>주요 내용은 다음과 같습니다:</p><ol><li><strong>준비물 준비</strong>: 파이썬, Vscode 또는 Jupyter Notebook</li><li><strong>모델링</strong>: 직업 데이터에 대한 노드와 관계를 정의하고, 이를 통해 그래프 모델링의 장점과 유사점을 설명했습니다. Job, Company, Benefit, VolunteerEducation, WeeklyWorkdays, ContractType 등 다양한 노드와 그들 간의 관계를 다루며, 그래프 데이터베이스의 구조를 설계했습니다.</li><li><strong>데이터 로드</strong>: Neo4j 라이브러리를 통해 jobs.csv 파일의 데이터를 데이터베이스에 로드하는 과정을 거쳤습니다. Cypher 쿼리를 통해 각 노드와 관계를 생성하고, 이를 데이터베이스에 삽입하여 구조화된 데이터를 구축했습니다.</li><li><strong>EDA와 검색</strong>: 데이터베이스에 로드된 데이터를 탐색하고 분석하는 작업을 수행했습니다. 직업 수와 평균 급여, 직업 유형별 평균 급여, 회사별 직업과 혜택 현황, 그리고 각 혜택이 얼마나 제공되는지 등의 정보를 분석하고 결과를 반환했습니다.</li><li><strong>FULLTEXT INDEX 활용</strong>: FULLTEXT INDEX를 생성하고, 이를 통해 텍스트 검색 작업을 수행했습니다. Job, VolunteerEducation, Benefit, Company 등의 속성에 대해 FULLTEXT INDEX를 생성하고, 이를 활용하여 특정 키워드를 포함하는 노드들을 빠르게 검색했습니다.</li></ol><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=16760d756efe" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[EP 2: GraphDB 사용하기 — Feat. Neo4J]]></title>
            <link>https://medium.com/@kofsitho/ep-2-graphdb-%EC%82%AC%EC%9A%A9%ED%95%98%EA%B8%B0-feat-neo4j-1504bf3bdf57?source=rss-14df520bbc24------2</link>
            <guid isPermaLink="false">https://medium.com/p/1504bf3bdf57</guid>
            <category><![CDATA[graph-database]]></category>
            <category><![CDATA[그래프-데이터베이스]]></category>
            <category><![CDATA[neo4j]]></category>
            <dc:creator><![CDATA[DanShw]]></dc:creator>
            <pubDate>Thu, 25 Apr 2024 07:23:41 GMT</pubDate>
            <atom:updated>2024-04-25T07:23:41.441Z</atom:updated>
            <content:encoded><![CDATA[<h3>EP 2: GraphDB 사용하기 — Feat. Neo4J</h3><h3>목차</h3><ul><li><strong>그래프 데이터베이스에 대해서</strong></li><li><strong>그래프 데이터베이스의 장점</strong></li><li><strong>그래프 분석의 원리</strong></li><li><strong>Neo4j 시작하는 방법</strong></li><li><strong>Cypher Query 사용해보기</strong></li></ul><p>크롤링한 직업데이터를 통해 Neo4j의 vector검색을 통해 직업(job) 검색하는 어플리케이션을 구축하기에 앞서 Neo4J GraphDB를 간단하게 사용해보는 내용을 준비했습니다.</p><h3>그래프 데이터베이스에 대해서</h3><p>그래프 데이터베이스는 그래프 데이터 모델에서 작동하는 CRUD(만들기, 읽기, 업데이트 및 삭제) 작업을 갖춘 온라인 데이터베이스 관리 시스템입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/920/1*jXoqPRlENtOP8Unsdyh1Vg.png" /></figure><p><strong>그래프 데이터베이스란 무엇입니까?</strong></p><p>그래프 데이터베이스는 노드, 엣지, 그리고 이들 사이의 관계를 이용하여 데이터를 저장하고 검색하는 데이터베이스 관리 시스템입니다. 이러한 시스템은 CRUD (생성, 읽기, 업데이트, 삭제) 작업을 지원하며, 복잡한 네트워크 형태의 데이터를 효율적으로 처리할 수 있도록 설계되었습니다.</p><p><strong>그래프 데이터베이스의 목적은 무엇인가요?</strong></p><p>그래프 데이터베이스는 관계를 중심으로 데이터를 모델링하고 저장합니다. 이는 관계형 데이터베이스에서 복잡한 조인 작업을 필요로 하는 다양한 쿼리를 간소화하고, 데이터 간의 연결성을 더 직관적으로 파악할 수 있게 해 줍니다. 또한, 그래프 데이터베이스는 사회 네트워크, 추천 시스템, 사기 감지, 경로 탐색 등 다양한 분야에서 중요한 의사결정을 지원하는 데 큰 역할을 합니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3-wu5JB5namWo3oPZOEW1A.png" /><figcaption>동료 및 이들의 관계 집합이 속성 그래프로 표시됩니다.</figcaption></figure><p><strong>그래프 데이터베이스는 주로 두 가지 유형으로 분류됩니다:</strong></p><ol><li><strong>속성 그래프(Property Graph)</strong>: 노드와 엣지 모두에 속성(키-밸류 쌍)을 가질 수 있는 구조로, 각 엣지는 방향성을 가질 수 있으며, 두 노드 간 다중 관계를 표현할 수 있습니다. 이 유형은 분석과 쿼리 작업에 적합하며, Neo4j와 같은 데이터베이스에서 널리 사용됩니다.</li><li><strong>RDF(Resource Description Framework) 그래프</strong>: 웹의 데이터를 기술하기 위해 사용되는 표준 모델로, 데이터 간의 의미론적 관계를 표현합니다. 이 유형은 데이터 통합, 지식 그래프 구축에 주로 사용되며, 복잡한 추론을 가능하게 합니다.</li></ol><p><strong>그래프 데이터베이스의 활용분야는 무엇인가요?</strong></p><ul><li><strong>속성 그래프</strong>: 금융 분석, 사기 탐지, 소셜 네트워크 분석, 복잡한 거래 네트워크의 관리 등 다양한 분야에서 활용됩니다. 이는 노드와 엣지의 속성을 통해 더 깊은 분석과 인사이트를 제공하기 때문입니다.</li><li><strong>RDF 그래프</strong>: 주로 데이터 통합, 세맨틱 웹, 기업 내 지식 관리 시스템에서 사용됩니다. RDF는 데이터 간의 의미론적 관계를 정의하고, 이를 통해 데이터의 상호 운용성을 향상시키며, 복잡한 쿼리와 추론을 지원합니다.</li></ul><p><strong>그래프 데이터베이스와 관계형 데이터베이스(RDBMS)의 차이점은 무엇인가요?</strong></p><ol><li><strong>데이터 모델:</strong></li></ol><ul><li><strong>그래프 DB:</strong> 데이터는 노드(엔티티)와 엣지(관계)로 구성됩니다. 노드와 엣지 모두 속성(특성)을 가질 수 있습니다.</li><li><strong>관계형 DB:</strong> 데이터는 행(레코드)과 열(필드)이 있는 테이블에 저장됩니다. 테이블들은 외래 키를 사용하여 서로 연결됩니다.</li></ul><p><strong>2. 쿼리언어:</strong></p><ul><li><strong>그래프 DB:</strong> Cypher와 같은 그래프 기반 쿼리 언어를 사용하여 연결된 데이터를 탐색하고 쿼리합니다. 쿼리는 패턴과 관계에 초점을 맞춥니다.</li><li><strong>관계형 DB:</strong> SQL을 사용하여 테이블에 저장된 데이터를 쿼리합니다. 쿼리는 종종 여러 테이블에 걸쳐 복잡한 조인을 요구합니다.</li></ul><p><strong>3. 유연성:</strong></p><ul><li><strong>그래프 DB:</strong> 유연한 스키마로 새로운 노드/엣지 유형 및 속성을 쉽게 추가할 수 있습니다.</li><li><strong>관계형 DB:</strong> 테이블과 열을 미리 정의해야 하는 엄격한 스키마를 요구합니다. 관계는 외래 키를 통해 암시적으로 표현됩니다.</li></ul><p><strong>4. 성능:</strong></p><ul><li><strong>그래프 DB:</strong> 매우 연결된 데이터의 탐색과 쿼리에 최적화되어 있습니다. 관련 데이터의 검색이 매우 빠릅니다.</li><li><strong>관계형 DB:</strong> 대량의 테이블 데이터를 집계하고 처리하는 데 최적화되어 있습니다. 매우 연결된 데이터를 쿼리할 때는 비싼 조인으로 인해 속도가 느려질 수 있습니다.</li></ul><p><strong>RDBMS와의 용어 비교:</strong></p><ul><li>데이터베이스 = 그래프</li><li>테이블 = 라벨</li><li>행 = 노드</li><li>열 = 속성</li><li>기본 키 = 속성 + 고유 제약 조건</li><li>외래 키 = 관계</li><li>조인 = 그래프 순회</li><li>검색 = 일치</li></ul><blockquote>그래프 데이터베이스는 복잡하고 상호 연결된 데이터를 탐색하고 분석하는 데 적합한 반면, 관계형 데이터베이스는 구조화된 테이블 데이터를 관리하고 사전에 정의된 관계로 작업하는 데 탁월합니다.</blockquote><h3><strong>그래프 데이터베이스의 장점</strong></h3><p>그래프 데이터베이스는 데이터를 관리하고 분석하는데 있어 여러 가지 독특한 이점을 제공합니다. 이들 이점은 특히 복잡한 관계와 상호 연결된 데이터 네트워크를 다룰 때 더욱 두드러집니다.</p><p><strong>1. 고성능</strong></p><p>그래프 데이터베이스는 데이터 간의 관계를 빠르게 탐색하여 연결된 데이터 포인트 간의 연결을 신속하게 찾아낼 수 있습니다. 이는 복잡한 쿼리를 실행할 때 관계형 데이터베이스보다 훨씬 빠른 성능을 제공합니다. 특히, 사기 탐지, 실시간 추천 시스템, 경로 찾기 등의 작업에서 그 효과가 크게 나타납니다.</p><p><strong>2. 직관적인 데이터 모델</strong></p><p>데이터는 노드(엔티티)와 엣지(관계)로 저장되어, 실제 세계에서 우리가 생각하는 방식을 반영합니다. 이 모델은 복잡한 관계를 자연스럽게 표현하고 이해하기 쉽게 해 주어, 사용자가 데이터 간의 상호 작용을 직관적으로 파악할 수 있게 돕습니다.</p><p><strong>3. 향상된 맥락 인식</strong></p><p>관계를 일급 시민으로 저장함으로써 그래프 데이터베이스는 데이터 상호작용의 미묘한 차이를 밝혀내는 데 있어 강력한 능력을 발휘합니다. 이는 다른 접근 방식에서는 명확히 드러나지 않는 데이터 간의 연결과 패턴을 강조합니다.</p><h3>그래프 분석의 원리</h3><p>그래프 데이터베이스는 복잡한 네트워크와 관계를 효과적으로 분석하고 시각화하는 데 사용됩니다. <br>이를 설명하기 위해, “케빈 베이컨”과 “미스 피기”라는 두 배우 사이의 연결 고리를 찾는 예제를 살펴보겠습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/386/1*iCHQ5Zr3MNeV4iUfp0E0vA.png" /><figcaption>영화배우인 “케빈베이컨”이 출연한 “미스 피기”라는 영화배우의 관계를 도식화</figcaption></figure><p>영화배우인 “케빈베이컨”이 출연한 “미스 피기”라는 영화배우와 어떤 관계가 있는지 도식화한 이미지 입니다.</p><blockquote><strong>노드(Node)</strong> ⇒ 배우(A), 영화(B)<br><strong>관계(Edge)</strong> ⇒ A배우가 B영화에 <strong>출연</strong>했다.</blockquote><p><strong>그래프를 통해 알 수 있는것:</strong></p><ol><li><strong>케빈 베이컨</strong>은 영화 ‘<strong>리버 와일드</strong>’에서 <strong>메릴 스트립</strong>과 함께 출연했습니다</li><li><strong>메릴 스트립</strong>은 영화 ‘<strong>레모니 스니켓의 위험한 대결</strong>’에서 <strong>빌리 코놀리</strong>와 함께 출연했습니다.</li><li><strong>빌리 코놀리</strong>는 영화 ‘<strong>머펫의 보물섬</strong>’에서 <strong>미스 피기</strong>와 함께 출연했습니다.</li></ol><p>이 관계들은 각 배우와 영화를 노드로, 출연 관계를 엣지로 나타내어 그래프로 표현할 수 있습니다. 그래프 데이터베이스에서는 이러한 노드와 엣지를 사용하여 데이터 간의 직접적이거나 간접적인 연결을 쉽게 추적할 수 있습니다.</p><p><strong>그래프 분석의 특징:</strong></p><ul><li><strong>경로 찾기:</strong> 케빈 베이컨에서 미스 피기까지의 경로를 찾는 과정에서, 그래프 데이터베이스는 각 노드(배우, 영화)를 순차적으로 탐색하여 연결된 엣지(출연)를 따라 이동합니다.</li><li><strong>패턴 매칭:</strong> 그래프 분석은 또한 특정 패턴을 식별하는 데 유용합니다. 예를 들어, 특정 배우가 공통적으로 출연한 영화를 찾거나, 여러 배우가 같은 영화에 출연한 패턴을 찾을 수 있습니다.</li><li><strong>연결 중심성 계산:</strong> 케빈 베이컨과 같은 배우의 중심성을 계산하여, 그래프 내에서 가장 영향력 있는 노드(배우나 영화)를 식별할 수 있습니다. 이는 네트워크 내에서 가장 중요한 또는 가장 연결된 노드를 파악하는 데 도움이 됩니다.</li></ul><p>이 예제를 통해 우리는 그래프 데이터베이스가 어떻게 복잡한 연결 네트워크를 분석하고, 실제 세계의 관계를 명확하게 표현하며, 정보를 쉽게 접근할 수 있게 하는지 이해할 수 있습니다.</p><h3>Neo4j 시작</h3><p>Neo4j를 시작하는 방법에는 여러 가지 옵션이 있습니다.</p><ol><li><strong>Neo4J 데스크탑 내 컴퓨터에 설치하기<br></strong><a href="https://neo4j.com/download/">neo4J 공식 홈페이지</a> 에서 데스크탑에 설치버전을 다운받아 내 컴퓨터에서 직접 실행시킬 수 있습니다.<br>리눅스, 맥OS, 윈도우 모두 지원됩니다.</li><li><a href="https://neo4j.com/docs/operations-manual/current/docker/"><strong>도커로 사용하기</strong></a></li><li><strong>Neo4J Sandbox 로 웹에서 무료로 사용하기<br></strong><a href="https://neo4j.com/cloud/platform/aura-graph-database/?ref=docs-nav-get-started">무료로 사용하기 링크</a>를 따라가서 무료로 사용해 볼 수 있습니다.</li></ol><p>회원가입 또는 로그인하면 아래와 같은 화면을 보실 수 있는데, 처음 계정을 생성하신 분 이라면 “New Instance” 버튼을 클릭하여 새로운 인스턴스를 만들 수 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pJ2JFCxivaogAPPe3nKlPg.png" /><figcaption><strong>Neo4J Sandbox 로그인 후 화면</strong></figcaption></figure><p>인스턴스를 생성후에는 “Open” 버튼을 눌러 아래와 같은 화면으로 진입하여 본격적으로 Neo4J를 사용해 볼 수 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*so780MX8zHjdg2ysSkadTw.png" /></figure><h3>Cypher Query 사용해보기</h3><h4><strong>Cypher Query란 무엇인가요?</strong></h4><p>Cypher는 Neo4j 그래프 데이터베이스를 위해 특별히 개발된 선언적 그래프 쿼리 언어입니다. SQL과 비슷하게, Cypher는 데이터를 쉽고 효율적으로 검색하고 조작할 수 있는 강력하고 사용자 친화적인 구문을 제공합니다.</p><h4>Cypher의 주요 특징들:</h4><ul><li><strong>패턴 매칭:</strong> Cypher는 노드와 관계 사이의 복잡한 패턴을 쉽게 찾을 수 있도록 설계되었습니다. 이를 통해 사용자는 데이터 간의 다양한 연결을 직관적으로 표현하고 탐색할 수 있습니다.</li><li><strong>선언적 언어:</strong> Cypher는 어떤 데이터를 찾고 싶은지 설명하면, 데이터베이스가 어떻게 그 데이터를 찾을지 결정합니다. 이 접근 방식은 쿼리 작성을 간단하게 만들고, 복잡한 로직을 데이터베이스에 맡깁니다.</li><li><strong>읽기 및 쓰기 작업:</strong> Cypher를 사용하여 데이터를 생성, 읽기, 업데이트, 삭제하는 작업을 수행할 수 있습니다. 이는 그래프 데이터의 관리와 유지 보수를 용이하게 합니다.</li></ul><h4>Cypher의 기본 구조:</h4><ul><li><strong>CREATE:</strong> 새로운 노드와 관계를 생성합니다.</li><li><strong>MATCH:</strong> 패턴을 기반으로 데이터를 찾습니다.</li><li><strong>RETURN:</strong> 결과를 반환합니다.</li><li><strong>WHERE:</strong> 특정 조건을 기반으로 검색 결과를 필터링합니다.</li><li><strong>DELETE:</strong> 노드나 관계를 삭제합니다.</li><li><strong>SET:</strong> 노드나 관계의 속성을 업데이트합니다.</li></ul><h4><strong>그래프데이터와 Cypher Query 용어</strong></h4><ul><li>점(Node)</li><li>속성(Property): Node의 속성값, Person 노드의 “name” 속성이 존재</li><li>성질이 비슷한 객체들의 묶음(Label)</li><li>객체들간의 관계(Edge, Relationship)</li></ul><h4>Cypher에서 노드 표현</h4><figure><img alt="Cypher에서 노드 표현" src="https://cdn-images-1.medium.com/max/1024/1*_gEixao5LSUUPt08i9gd6Q.png" /></figure><p>위 그래프를 언어로 작성하면:</p><blockquote>Sally는 그래프를 좋아합니다. <br>Sally는 John과 친구입니다. <br>Sally는 Neo4j에서 일합니다.</blockquote><pre>// 위 그래프를 쿼리로 작성 해보겠습니다.<br>// 1. Salley 라는 이름의 속성을 가진 Peson 노드 생성<br>CREATE (Salley:Person {name: &#39;Salley&#39;});<br><br>// 2. John 라는 이름의 속성을 가진 Peson 노드 생성<br>CREATE (John:Person {name: &#39;John&#39;});<br><br>// 3. John과 Salley의 친구관계(Relationship)를 생성<br>MATCH (Salley:Person {name: &#39;Salley&#39;}), (John:Person {name: &#39;John&#39;})<br>MERGE (Salley)-[:IS_FRIENDS_WITH]-&gt;(John);<br><br>// 4. Sally가 그래프를 좋아하는 관계 생성<br>MATCH (Salley:Person {name: &#39;Salley&#39;})<br>MERGE (Salley)-[:LIKES]-&gt;(:Technology {type: &#39;Graphs&#39;});<br><br>// 5. Sally가 Neo4j에서 일하는 관계 생성<br>MATCH (Salley:Person {name: &#39;Salley&#39;})<br>MERGE (Salley)-[:WORKS_FOR]-&gt;(:Company {name: &#39;Neo4j&#39;});</pre><blockquote>💡 <strong>노드 생성</strong> <br>CREATE 문을 사용해서 노드를 생성합니다.<br>CREATE 문에 {name: ‘Salley’} 이름이란 속성을 추가 할 수 있습니다.</blockquote><blockquote>💡 <strong>노드 간의 관계 생성<br>MATCH</strong> 문은 특정 노드를 찾기 위해 사용됩니다. <br>예를 들어, MATCH (Salley:Person {name: &#39;Salley&#39;}), (John:Person {name: &#39;John&#39;})는 데이터베이스에서 &#39;Salley&#39;와 &#39;John&#39;이라는 이름을 가진 <strong>Person</strong> 노드들을 찾습니다.</blockquote><blockquote><strong>MERGE</strong> 문은 두 노드 사이에 관계를 생성하거나, 이미 존재하는 관계를 찾습니다.<br>MERGE (Salley)-[:IS_FRIENDS_WITH]-&gt;(John)은 Salley와 John 사이에 &#39;IS_FRIENDS_WITH&#39;라는 관계를 생성합니다.</blockquote><h3>Summary</h3><p>이 블로그에서는 그래프 데이터베이스의 개념부터 시작하여 Cypher 쿼리 언어의 사용법에 이르기까지, 그래프 데이터베이스의 다양한 측면을 탐구했습니다.</p><p><strong>주요 내용 요약:</strong></p><ol><li><strong>그래프 데이터베이스에 대해서</strong> <br>노드와 엣지를 사용해 데이터 간의 관계를 저장하고 쿼리하는 관리 시스템입니다. 이는 복잡한 데이터 네트워크를 효과적으로 모델링하고 처리할 수 있게 해 줍니다.</li><li><strong>그래프 데이터베이스의 장점</strong> <br>뛰어난 성능, 유연한 스키마, 직관적인 데이터 모델링, 맥락 인식 강화, 그리고 확장성을 포함한 여러 이점을 제공합니다.</li><li><strong>Neo4j 시작하는 방법</strong> <br>Neo4j 데스크탑 설치, 도커사용, 웹에서 바로 사용 할 수 있는Neo4j Sandbox</li><li><strong>그래프 분석의 원리</strong> <br>“케빈 베이컨의 6단계 법칙”을 예로 들어, 그래프 데이터베이스가 어떻게 복잡한 연결성을 분석하고 이해하는 데 도움을 주는지 설명합니다.</li><li><strong>Cypher 쿼리 사용해보기</strong> <br>Cypher는 그래프 데이터를 쿼리하기 위해 특별히 설계된 언어로, 사용자 친화적인 구문과 패턴 매칭 능력을 갖추고 있습니다.</li></ol><blockquote>이러한 내용을 통해 그래프 데이터베이스와 Cypher 쿼리 언어의 기본적인 이해와 그 응용 가능성을 탐색할 수 있었습니다. <br>데이터가 점점 더 복잡하고 상호 연결되는 현대에서 그래프 데이터베이스는 중요한 데이터 관리 및 분석 도구로 여겨지고 있는것 같습니다.</blockquote><h3>Resource</h3><ul><li><a href="https://neo4j.com/">Neo4j 웹사이트</a></li><li><a href="https://neo4j.com/developer/get-started">Neo4j 개발자 가이드</a></li><li><a href="https://neo4j.com/sandbox-v2/">Neo4j 샌드박스</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1504bf3bdf57" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>