Upload 16 files

src/agents/graph.py

@@ -0,0 +1,129 @@
+"""Graph builder module. Assembles the complete multi-agent LangGraph workflow."""
+
+import logging
+from langchain_openai import ChatOpenAI
+from langgraph.graph import StateGraph, START, END
+from langgraph.prebuilt import ToolNode, create_react_agent
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.store.memory import InMemoryStore
+
+from src.state import State
+from src.tools import music_tools, invoice_tools
+from src.agents.prompts import INVOICE_SUBAGENT_PROMPT, SUPERVISOR_PROMPT
+from src.agents.nodes import (
+    create_music_assistant_node,
+    should_continue,
+    should_interrupt,
+    create_verify_info_node,
+    human_input,
+    load_memory,
+    create_memory_node,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def build_graph(
+    model_name: str = "gpt-4o-mini",
+    temperature: float = 0,
+    openai_api_key: str = None,
+    openai_api_base: str = None,
+):
+    llm_kwargs = {
+        "model": model_name,
+        "temperature": temperature,
+    }
+    if openai_api_key:
+        llm_kwargs["api_key"] = openai_api_key
+    if openai_api_base:
+        llm_kwargs["base_url"] = openai_api_base
+
+    llm = ChatOpenAI(**llm_kwargs)
+    logger.info(f"LLM initialized: {model_name}, temperature={temperature}")
+
+    # NOTE: Both stores are in-memory only — all data is lost on restart.
+    # For production, replace with SqliteSaver / persistent store.
+    in_memory_store = InMemoryStore()
+    checkpointer = MemorySaver()
+
+    # Music Catalog Sub-Agent (hand-built ReAct)
+    music_assistant_fn = create_music_assistant_node(llm, music_tools)
+    music_tool_node = ToolNode(music_tools)
+
+    music_workflow = StateGraph(State)
+    music_workflow.add_node("music_assistant", music_assistant_fn)
+    music_workflow.add_node("music_tool_node", music_tool_node)
+    music_workflow.add_edge(START, "music_assistant")
+    music_workflow.add_conditional_edges(
+        "music_assistant",
+        should_continue,
+        {"continue": "music_tool_node", "end": END},
+    )
+    music_workflow.add_edge("music_tool_node", "music_assistant")
+
+    music_catalog_subagent = music_workflow.compile(
+        name="music_catalog_subagent",
+        checkpointer=checkpointer,
+        store=in_memory_store,
+    )
+    logger.info("Music catalog sub-agent compiled.")
+
+    # Invoice Information Sub-Agent (pre-built ReAct)
+    invoice_information_subagent = create_react_agent(
+        llm,
+        tools=invoice_tools,
+        name="invoice_information_subagent",
+        prompt=INVOICE_SUBAGENT_PROMPT,
+        state_schema=State,
+        checkpointer=checkpointer,
+        store=in_memory_store,
+    )
+    logger.info("Invoice information sub-agent compiled.")
+
+    # Supervisor
+    from langgraph_supervisor import create_supervisor
+
+    supervisor_workflow = create_supervisor(
+        agents=[invoice_information_subagent, music_catalog_subagent],
+        output_mode="last_message",
+        model=llm,
+        prompt=SUPERVISOR_PROMPT,
+        state_schema=State,
+    )
+    supervisor_prebuilt = supervisor_workflow.compile(
+        name="supervisor",
+        checkpointer=checkpointer,
+        store=in_memory_store,
+    )
+    logger.info("Supervisor compiled.")
+
+    # Final Multi-Agent Graph
+    verify_info_fn = create_verify_info_node(llm)
+    create_memory_fn = create_memory_node(llm)
+
+    multi_agent = StateGraph(State)
+    multi_agent.add_node("verify_info", verify_info_fn)
+    multi_agent.add_node("human_input", human_input)
+    multi_agent.add_node("load_memory", load_memory)
+    multi_agent.add_node("supervisor", supervisor_prebuilt)
+    multi_agent.add_node("create_memory", create_memory_fn)
+
+    multi_agent.add_edge(START, "verify_info")
+    multi_agent.add_conditional_edges(
+        "verify_info",
+        should_interrupt,
+        {"continue": "load_memory", "interrupt": "human_input"},
+    )
+    multi_agent.add_edge("human_input", "verify_info")
+    multi_agent.add_edge("load_memory", "supervisor")
+    multi_agent.add_edge("supervisor", "create_memory")
+    multi_agent.add_edge("create_memory", END)
+
+    compiled_graph = multi_agent.compile(
+        name="multi_agent_final",
+        checkpointer=checkpointer,
+        store=in_memory_store,
+    )
+    logger.info("Final multi-agent graph compiled successfully.")
+
+    return compiled_graph, checkpointer, in_memory_store

src/agents/nodes.py

@@ -0,0 +1,234 @@
+"""Node functions for the multi-agent graph."""
+
+import logging
+from typing import Optional
+
+from langchain_core.messages import SystemMessage, HumanMessage
+from langchain_core.runnables import RunnableConfig
+from langgraph.store.base import BaseStore
+from langgraph.types import interrupt
+
+from src.state import State
+from src.models import UserInput, UserProfile
+from src.agents.prompts import (
+    generate_music_assistant_prompt,
+    STRUCTURED_EXTRACTION_PROMPT,
+    VERIFICATION_PROMPT,
+    CREATE_MEMORY_PROMPT,
+)
+from src.db.database import get_engine, normalize_phone
+
+logger = logging.getLogger(__name__)
+
+
+def get_customer_id_from_identifier(identifier: str) -> Optional[int]:
+    if not identifier or not identifier.strip():
+        return None
+
+    identifier = identifier.strip()
+    engine = get_engine()
+
+    try:
+        from sqlalchemy import text
+
+        if "@" in identifier:
+            with engine.connect() as conn:
+                result = conn.execute(
+                    text("SELECT CustomerId FROM Customer WHERE LOWER(Email) = LOWER(:email)"),
+                    {"email": identifier},
+                )
+                row = result.fetchone()
+                if row:
+                    return int(row[0])
+
+        if identifier.isdigit():
+            with engine.connect() as conn:
+                result = conn.execute(
+                    text("SELECT CustomerId FROM Customer WHERE CustomerId = :cid"),
+                    {"cid": int(identifier)},
+                )
+                row = result.fetchone()
+                if row:
+                    return int(row[0])
+
+        normalized_input = normalize_phone(identifier)
+        if normalized_input and len(normalized_input) >= 5:
+            with engine.connect() as conn:
+                result = conn.execute(text("SELECT CustomerId, Phone FROM Customer WHERE Phone IS NOT NULL"))
+                for row in result:
+                    db_phone_normalized = normalize_phone(str(row[1]))
+                    if db_phone_normalized == normalized_input:
+                        return int(row[0])
+
+    except Exception as e:
+        logger.error(f"Error looking up customer by identifier '{identifier}': {e}")
+
+    return None
+
+
+def format_user_memory(user_data: dict) -> str:
+    try:
+        profile = user_data.get("memory")
+        if profile and hasattr(profile, "music_preferences") and profile.music_preferences:
+            return f"Music Preferences: {', '.join(profile.music_preferences)}"
+    except Exception as e:
+        logger.error(f"Error formatting user memory: {e}")
+    return ""
+
+
+def create_music_assistant_node(llm, music_tools):
+    llm_with_tools = llm.bind_tools(music_tools)
+
+    def music_assistant(state: State, config: RunnableConfig):
+        memory = state.get("loaded_memory", "None") or "None"
+        prompt = generate_music_assistant_prompt(memory)
+
+        messages = [SystemMessage(content=prompt)]
+        if state.get("customer_id"):
+            messages.append(
+                SystemMessage(content=f"The current verified customer ID is: {state['customer_id']}")
+            )
+        messages.extend(state["messages"])
+
+        logger.info(f"Music assistant invoked with {len(state['messages'])} conversation messages")
+        response = llm_with_tools.invoke(messages)
+        return {"messages": [response]}
+
+    return music_assistant
+
+
+def should_continue(state: State, config: RunnableConfig) -> str:
+    messages = state["messages"]
+    last_message = messages[-1]
+    if not last_message.tool_calls:
+        return "end"
+    return "continue"
+
+
+def should_interrupt(state: State, config: RunnableConfig) -> str:
+    if state.get("customer_id") is not None:
+        return "continue"
+    return "interrupt"
+
+
+def create_verify_info_node(llm):
+    structured_llm = llm.with_structured_output(schema=UserInput)
+
+    def verify_info(state: State, config: RunnableConfig):
+        if state.get("customer_id") is not None:
+            logger.info(f"Customer already verified: {state['customer_id']}")
+            return {}
+
+        user_input = state["messages"][-1]
+        logger.info(f"Verification attempt with message: {getattr(user_input, 'content', '')[:100]}")
+
+        try:
+            parsed_info = structured_llm.invoke(
+                [SystemMessage(content=STRUCTURED_EXTRACTION_PROMPT)] + [user_input]
+            )
+            identifier = parsed_info.identifier
+            logger.info(f"Extracted identifier: '{identifier}'")
+        except Exception as e:
+            logger.error(f"Error parsing user input for verification: {e}")
+            identifier = ""
+
+        customer_id = None
+        if identifier:
+            customer_id = get_customer_id_from_identifier(identifier)
+            logger.info(f"DB lookup result: customer_id={customer_id}")
+
+        if customer_id is not None:
+            intent_message = SystemMessage(
+                content=(
+                    f"Customer verified successfully. "
+                    f"The verified customer_id is {customer_id}. "
+                    f"Use this customer_id for all invoice and purchase lookups."
+                )
+            )
+            return {
+                "customer_id": str(customer_id),
+                "messages": [intent_message],
+            }
+        else:
+            response = llm.invoke(
+                [SystemMessage(content=VERIFICATION_PROMPT)] + state["messages"]
+            )
+            return {"messages": [response]}
+
+    return verify_info
+
+
+def human_input(state: State, config: RunnableConfig):
+    user_input = interrupt("Please provide input.")
+    return {"messages": [HumanMessage(content=user_input)]}
+
+
+def load_memory(state: State, config: RunnableConfig, store: BaseStore):
+    user_id = str(state.get("customer_id", ""))
+    if not user_id:
+        return {"loaded_memory": ""}
+
+    namespace = ("memory_profile", user_id)
+    try:
+        existing_memory = store.get(namespace, "user_memory")
+        if existing_memory and existing_memory.value:
+            formatted = format_user_memory(existing_memory.value)
+            logger.info(f"Loaded memory for customer {user_id}: {formatted}")
+            return {"loaded_memory": formatted}
+    except Exception as e:
+        logger.error(f"Error loading memory for user {user_id}: {e}")
+
+    return {"loaded_memory": ""}
+
+
+def create_memory_node(llm):
+    def create_memory(state: State, config: RunnableConfig, store: BaseStore):
+        user_id = str(state.get("customer_id", ""))
+        if not user_id:
+            return {}
+
+        namespace = ("memory_profile", user_id)
+
+        try:
+            existing_preferences = []
+            existing_memory = store.get(namespace, "user_memory")
+            formatted_memory = ""
+            if existing_memory and existing_memory.value:
+                mem_dict = existing_memory.value
+                profile = mem_dict.get("memory")
+                if profile and hasattr(profile, "music_preferences"):
+                    existing_preferences = list(profile.music_preferences or [])
+                    formatted_memory = f"Music Preferences: {', '.join(existing_preferences)}"
+
+            recent_messages = state["messages"][-10:]
+            conversation_summary = "\n".join(
+                f"{getattr(msg, 'type', 'unknown')}: {getattr(msg, 'content', '')}"
+                for msg in recent_messages
+                if getattr(msg, "content", "")
+            )
+
+            formatted_prompt = CREATE_MEMORY_PROMPT.format(
+                conversation=conversation_summary,
+                memory_profile=formatted_memory or "Empty, no existing profile",
+            )
+
+            updated_memory = llm.with_structured_output(UserProfile).invoke(
+                [SystemMessage(content=formatted_prompt)]
+            )
+
+            new_prefs = updated_memory.music_preferences or []
+            if not new_prefs and existing_preferences:
+                logger.info(f"Memory unchanged for customer {user_id} (preserving existing preferences)")
+                return {}
+
+            merged_prefs = list(set(existing_preferences + new_prefs))
+            updated_memory.music_preferences = merged_prefs
+            updated_memory.customer_id = user_id
+
+            store.put(namespace, "user_memory", {"memory": updated_memory})
+            logger.info(f"Memory updated for customer {user_id}: {merged_prefs}")
+
+        except Exception as e:
+            logger.error(f"Error creating/updating memory for user {user_id}: {e}")
+
+    return create_memory

src/agents/prompts.py

@@ -0,0 +1,156 @@
+"""System prompts for all agents in the multi-agent system."""
+
+
+def generate_music_assistant_prompt(memory: str = "None") -> str:
+    return f"""You are the Music Catalog Assistant for a digital music store.
+You help customers discover and learn about music in the catalog.
+
+=== GROUNDING RULES (CRITICAL) ===
+1. ONLY provide information that is returned by your tools. DO NOT infer, assume, or extrapolate.
+2. If a tool returns "No albums found", "No tracks found", or similar, tell the customer exactly that.
+   Say: "I could not find that in our catalog."
+3. NEVER fabricate or guess album names, track names, artist names, prices, durations, or any other data.
+4. If results are truncated (the tool shows a sample), mention the total count and that more tracks exist.
+5. If you are unsure, say so. Do not make up information.
+6. Always quote exact numbers from tool results — never round, estimate, or approximate.
+7. If the customer asks about data outside your tools' scope (playlists, employee info, billing), say:
+   "I specialize in music catalog queries. Let me pass this to the right team."
+
+=== TOOLS AVAILABLE ===
+1. get_albums_by_artist(artist): Search albums by artist name (fuzzy match). Returns AlbumId, AlbumTitle, ArtistName.
+2. get_tracks_by_artist(artist): Search tracks by artist (sample of up to 20 with full details).
+3. get_songs_by_genre(genre): Get one representative song per artist in a genre (up to 10, with total count).
+4. check_for_songs(song_title): Search for a specific song by title (up to 10 matches with full details).
+5. get_track_details(track_id): Get ALL details for a specific track by TrackId.
+
+All track tools return: TrackId, SongName, ArtistName, AlbumTitle, GenreName, Composer,
+Milliseconds, DurationMinutes, Bytes, UnitPrice, and MediaType.
+Present the relevant details to the customer. Never say information is "not available"
+when it is present in the tool results.
+
+=== SEARCH GUIDELINES ===
+1. Always call the appropriate tool before answering. Do not answer from memory.
+2. If exact matches are not found, try alternative spellings or partial names.
+3. When providing song lists, include the artist name and album for each song.
+
+=== RESPONSE FORMAT ===
+Keep responses concise and well organized. Use clear formatting for lists.
+Always be helpful and friendly.
+
+Prior saved user preferences: {memory}
+
+Message history is also attached."""
+
+
+INVOICE_SUBAGENT_PROMPT = """You are the Invoice Information Assistant for a digital music store.
+You retrieve and present invoice and purchase information for verified customers.
+
+=== GROUNDING RULES (CRITICAL) ===
+1. ONLY provide information returned by your tools. NEVER fabricate invoice data.
+2. If a tool returns an error or empty result, say: "I could not retrieve that invoice information."
+3. NEVER guess invoice amounts, dates, track lists, or employee names.
+4. Always quote exact numbers (totals, prices, dates) from tool results — never round or estimate.
+5. DO NOT infer, assume, or extrapolate beyond what tools return.
+
+=== CUSTOMER ID ===
+CRITICAL: The verified customer ID will be provided in a system message in the conversation.
+Look for the message that says "The verified customer_id is X".
+Use ONLY that customer_id for ALL tool calls. Do NOT extract or guess customer IDs from other parts of the conversation.
+
+=== TOOLS AVAILABLE ===
+1. get_invoices_by_customer_sorted_by_date(customer_id): All invoices for a customer, most recent first.
+   Returns: InvoiceId, InvoiceDate, BillingAddress, Total.
+2. get_invoice_line_items_sorted_by_price(customer_id): All purchased tracks across all invoices,
+   sorted by unit price (highest first). Each row is ONE purchased track (not a full invoice).
+   Returns: InvoiceId, InvoiceDate, InvoiceTotal, TrackName, UnitPrice, Quantity.
+3. get_employee_by_invoice_and_customer(invoice_id, customer_id): Support rep info for an invoice.
+4. get_invoice_line_items(invoice_id, customer_id): Detailed track info for a specific invoice.
+
+=== COMMON QUERIES ===
+- "What was my most recent purchase?" -> Use get_invoices_by_customer_sorted_by_date, then get_invoice_line_items for the first invoice.
+- "How much was my last invoice?" -> Use get_invoices_by_customer_sorted_by_date, report the Total from the first result.
+- "What's the most expensive track I bought?" -> Use get_invoice_line_items_sorted_by_price, report the first result.
+- "Who helped me?" -> Use get_invoices_by_customer_sorted_by_date to find the invoice, then get_employee_by_invoice_and_customer.
+
+=== SCOPE ===
+You handle ONLY invoice and purchase queries. If the query is about music catalog, respond:
+"I specialize in invoice queries. Let me pass this to the right team."
+
+You may have additional context below:"""
+
+
+SUPERVISOR_PROMPT = """You are the supervisor for a digital music store customer support team.
+Your job is to route customer queries to the right sub-agent and combine their responses.
+
+=== YOUR TEAM ===
+1. music_catalog_subagent: Handles music catalog queries (albums, tracks, songs, artists, genres).
+   Has access to the customer's saved music preferences.
+2. invoice_information_subagent: Handles invoice, purchase, and billing queries.
+   Needs the customer_id (already verified and available in conversation context).
+
+=== ROUTING RULES ===
+1. Music/catalog questions -> route to music_catalog_subagent
+2. Invoice/purchase/billing questions -> route to invoice_information_subagent
+3. Mixed questions (both music AND invoice) -> route to invoice_information_subagent FIRST, then music_catalog_subagent SECOND
+4. Off-topic questions (weather, general knowledge, unrelated topics) -> respond DIRECTLY:
+   "I can only help with music store inquiries such as looking up songs, albums, artists, or your purchase history."
+   Do NOT route off-topic queries to any sub-agent.
+
+=== RESPONSE RULES ===
+1. After all sub-agents have responded, combine ALL their answers into a single coherent response.
+2. Do NOT drop any sub-agent's answer. Both parts of a mixed query must appear in the final response.
+3. If a sub-agent reports that information was not found, include that in your response honestly.
+4. When routing to invoice_information_subagent, ensure the customer_id from the conversation is available in context.
+5. Keep your final combined response clear and well-organized.
+6. NEVER add information that was not in the sub-agents' responses."""
+
+
+STRUCTURED_EXTRACTION_PROMPT = """You are a customer service system that extracts customer identifiers from messages.
+
+Your task: Extract exactly ONE identifier from the user's message. The identifier can be:
+- A customer ID (a number, e.g., "1", "42")
+- An email address (contains @, e.g., "user@example.com")
+- A phone number (starts with + or contains formatted digits, e.g., "+55 (12) 3923-5555")
+
+Rules:
+1. Extract ONLY the identifier. Do not extract names, questions, or other content.
+2. If the message contains multiple possible identifiers, prefer: customer ID > email > phone.
+3. If no identifier is present in the message, return an empty string for the identifier field.
+4. Do not fabricate identifiers. Only extract what is explicitly stated."""
+
+
+VERIFICATION_PROMPT = """You are a music store support agent. Your current task is to verify the customer's identity before you can help them.
+
+To verify identity, the customer must provide ONE of:
+- Customer ID (a number)
+- Email address
+- Phone number
+
+Rules:
+1. If the customer has NOT provided any identifier, ask politely:
+   "To help you with your account, I'll need to verify your identity. Could you please provide your Customer ID, email address, or phone number?"
+2. If the customer provided an identifier but it was NOT found in our system, say:
+   "I wasn't able to find an account with that information. Could you please double-check and try again? You can provide your Customer ID, email, or phone number."
+3. Be friendly and concise. Do not ask for more than one identifier at a time.
+4. If the customer is asking a general music catalog question (about songs, albums, artists) without needing account access, you may note that they don't need to verify for music browsing questions."""
+
+
+CREATE_MEMORY_PROMPT = """You are analyzing a conversation to update a customer's music preference profile.
+
+=== RULES ===
+1. Only save preferences the customer EXPLICITLY stated they like or enjoy.
+   Examples of explicit preferences: "I love rock music", "I like AC/DC", "Jazz is my favorite"
+2. Do NOT save preferences from questions alone.
+   Examples that are NOT preferences: "Do you have rock music?", "What songs are in Jazz?"
+3. If no new preferences were expressed, keep the existing preferences UNCHANGED.
+   CRITICAL: Do not return an empty list if existing preferences exist. Preserve them.
+4. Include artists, genres, or specific albums the customer expressed interest in.
+5. Merge new preferences with existing ones. Never remove existing preferences.
+
+=== CONVERSATION ===
+{conversation}
+
+=== EXISTING MEMORY PROFILE ===
+{memory_profile}
+
+Respond with the updated profile object. If nothing new was expressed, return the existing profile as-is."""

src/config.py

@@ -0,0 +1,28 @@
+import os
+import logging
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(name)s | %(levelname)s | %(message)s",
+    handlers=[logging.StreamHandler()],
+)
+
+
+class Settings:
+    openai_api_key: str = os.getenv("OPENAI_API_KEY", "")
+    openai_api_base: str = os.getenv("OPENAI_API_BASE", "")
+    model_name: str = os.getenv("MODEL_NAME", "gpt-4o-mini")
+    temperature: float = float(os.getenv("TEMPERATURE", "0"))
+    port: int = int(os.getenv("PORT", "7860"))
+    app_title: str = "Music Store Assistant"
+    app_description: str = (
+        "Welcome! I can help you explore our music catalog, look up invoices, "
+        "and find your purchase history. To access your account, please provide "
+        "your Customer ID, email, or phone number."
+    )
+
+
+settings = Settings()

src/db/__init__.py

@@ -0,0 +1,3 @@
+from src.db.database import get_engine, get_db, run_query_safe, normalize_phone, verify_database
+
+__all__ = ["get_engine", "get_db", "run_query_safe", "normalize_phone", "verify_database"]

src/db/database.py

@@ -0,0 +1,107 @@
+import json
+import os
+import re
+import sqlite3
+import requests
+import logging
+from langchain_community.utilities.sql_database import SQLDatabase
+from sqlalchemy import create_engine, text
+from sqlalchemy.pool import StaticPool
+
+logger = logging.getLogger(__name__)
+
+_engine = None
+_db = None
+
+CHINOOK_SQL_URL = (
+    "https://raw.githubusercontent.com/lerocha/chinook-database/"
+    "master/ChinookDatabase/DataSources/Chinook_Sqlite.sql"
+)
+
+# Use project root for the cached SQL file
+LOCAL_SQL_PATH = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "Chinook_Sqlite.sql")
+
+
+def _load_sql_script() -> str:
+    if os.path.isfile(LOCAL_SQL_PATH):
+        logger.info(f"Loading Chinook SQL from local file: {LOCAL_SQL_PATH}")
+        with open(LOCAL_SQL_PATH, "r", encoding="utf-8") as f:
+            return f.read()
+    logger.info("Local SQL file not found. Downloading from GitHub...")
+    response = requests.get(CHINOOK_SQL_URL, timeout=60)
+    response.raise_for_status()
+    sql_script = response.text
+    try:
+        with open(LOCAL_SQL_PATH, "w", encoding="utf-8") as f:
+            f.write(sql_script)
+        logger.info(f"Cached SQL script to {LOCAL_SQL_PATH}")
+    except Exception as e:
+        logger.warning(f"Could not cache SQL script locally: {e}")
+    return sql_script
+
+
+def _create_engine():
+    sql_script = _load_sql_script()
+    connection = sqlite3.connect(":memory:", check_same_thread=False)
+    connection.executescript(sql_script)
+    logger.info("Chinook database loaded successfully into memory.")
+    return create_engine(
+        "sqlite://",
+        creator=lambda: connection,
+        poolclass=StaticPool,
+        connect_args={"check_same_thread": False},
+    )
+
+
+def get_engine():
+    global _engine
+    if _engine is None:
+        _engine = _create_engine()
+    return _engine
+
+
+def get_db() -> SQLDatabase:
+    global _db
+    if _db is None:
+        _db = SQLDatabase(get_engine())
+    return _db
+
+
+def run_query_safe(query: str, params: dict = None) -> str:
+    engine = get_engine()
+    try:
+        with engine.connect() as conn:
+            if params:
+                result = conn.execute(text(query), params)
+            else:
+                result = conn.execute(text(query))
+            rows = result.fetchall()
+            columns = result.keys()
+            if not rows:
+                return "[]"
+            results_list = [dict(zip(columns, row)) for row in rows]
+            return json.dumps(results_list, default=str)
+    except Exception as e:
+        logger.error(f"Query error: {e} | query={query} | params={params}")
+        raise
+
+
+def normalize_phone(phone: str) -> str:
+    if not phone:
+        return ""
+    phone = phone.strip()
+    if phone.startswith("+"):
+        return "+" + re.sub(r"[^\d]", "", phone[1:])
+    return re.sub(r"[^\d]", "", phone)
+
+
+def verify_database() -> dict:
+    try:
+        db = get_db()
+        tables = db.get_usable_table_names()
+        result = db.run("SELECT COUNT(*) FROM Customer;")
+        logger.info(f"Database verification OK. Customer count query returned: {result}")
+        return {"status": "healthy", "tables": len(tables)}
+    except Exception as e:
+        logger.error(f"Database verification failed: {e}")
+        return {"status": "unhealthy", "error": str(e)}

src/models.py

@@ -0,0 +1,21 @@
+from typing import List
+from pydantic import BaseModel, Field
+
+
+class UserInput(BaseModel):
+    identifier: str = Field(
+        default="",
+        description=(
+            "Identifier: can be a customer ID (numeric), "
+            "email address (contains @), or phone number (starts with + or contains digits). "
+            "Return empty string if no identifier is found in the message."
+        ),
+    )
+
+
+class UserProfile(BaseModel):
+    customer_id: str = Field(description="The customer ID of the customer")
+    music_preferences: List[str] = Field(
+        default_factory=list,
+        description="The music preferences of the customer (artists, genres, albums they like)",
+    )

src/state.py

@@ -0,0 +1,11 @@
+from typing import Annotated, Optional
+from typing_extensions import TypedDict
+from langgraph.graph.message import AnyMessage, add_messages
+from langgraph.managed.is_last_step import RemainingSteps
+
+
+class State(TypedDict):
+    customer_id: Optional[str]
+    messages: Annotated[list[AnyMessage], add_messages]
+    loaded_memory: str
+    remaining_steps: RemainingSteps

src/tools/__init__.py

@@ -0,0 +1,4 @@
+from src.tools.music_catalog import music_tools
+from src.tools.invoice import invoice_tools
+
+__all__ = ["music_tools", "invoice_tools"]

src/tools/invoice.py

@@ -0,0 +1,146 @@
+"""Invoice information tools for the multi-agent system."""
+
+import logging
+from langchain_core.tools import tool
+from src.db.database import run_query_safe
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_int(value: str, label: str = "value") -> int:
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        raise ValueError(f"Invalid {label}: '{value}'. Please provide a numeric value.")
+
+
+@tool
+def get_invoices_by_customer_sorted_by_date(customer_id: str) -> str:
+    """
+    Look up all invoices for a customer using their ID.
+    Returns invoices sorted by date (most recent first).
+    """
+    logger.info(f"TOOL_CALL: get_invoices_by_customer_sorted_by_date | customer_id={customer_id}")
+    try:
+        result = run_query_safe(
+            """
+            SELECT InvoiceId, CustomerId, InvoiceDate, BillingAddress, BillingCity,
+                   BillingState, BillingCountry, BillingPostalCode, Total
+            FROM Invoice
+            WHERE CustomerId = :customer_id
+            ORDER BY InvoiceDate DESC;
+            """,
+            {"customer_id": _safe_int(customer_id, "customer ID")},
+        )
+        logger.info(f"TOOL_RESULT: get_invoices_by_customer_sorted_by_date | result_length={len(result)}")
+        if result == "[]":
+            return f"No invoices found for customer {customer_id}."
+        return result
+    except Exception as e:
+        logger.error(f"Error in get_invoices_by_customer_sorted_by_date: {e}")
+        return f"Error retrieving invoices for customer {customer_id}. Please try again."
+
+
+@tool
+def get_invoice_line_items_sorted_by_price(customer_id: str) -> str:
+    """
+    Look up all purchased line items for a customer, sorted by unit price (highest first).
+    Each row is a single purchased track (NOT a full invoice). An invoice with 5 tracks
+    will appear as 5 separate rows, each showing the track name, unit price, and quantity.
+    """
+    logger.info(f"TOOL_CALL: get_invoice_line_items_sorted_by_price | customer_id={customer_id}")
+    try:
+        result = run_query_safe(
+            """
+            SELECT Invoice.InvoiceId, Invoice.InvoiceDate, Invoice.Total AS InvoiceTotal,
+                   Track.Name AS TrackName, InvoiceLine.UnitPrice, InvoiceLine.Quantity
+            FROM Invoice
+            JOIN InvoiceLine ON Invoice.InvoiceId = InvoiceLine.InvoiceId
+            JOIN Track ON InvoiceLine.TrackId = Track.TrackId
+            WHERE Invoice.CustomerId = :customer_id
+            ORDER BY InvoiceLine.UnitPrice DESC;
+            """,
+            {"customer_id": _safe_int(customer_id, "customer ID")},
+        )
+        logger.info(f"TOOL_RESULT: get_invoice_line_items_sorted_by_price | result_length={len(result)}")
+        if result == "[]":
+            return f"No purchase records found for customer {customer_id}."
+        return result
+    except Exception as e:
+        logger.error(f"Error in get_invoice_line_items_sorted_by_price: {e}")
+        return f"Error retrieving purchase records for customer {customer_id}. Please try again."
+
+
+@tool
+def get_employee_by_invoice_and_customer(invoice_id: str, customer_id: str) -> str:
+    """
+    Find the employee (support rep) associated with a specific invoice and customer.
+    Returns employee full name, title, and email.
+    """
+    logger.info(f"TOOL_CALL: get_employee_by_invoice_and_customer | invoice_id={invoice_id}, customer_id={customer_id}")
+    try:
+        result = run_query_safe(
+            """
+            SELECT Employee.FirstName, Employee.LastName, Employee.Title, Employee.Email
+            FROM Employee
+            JOIN Customer ON Customer.SupportRepId = Employee.EmployeeId
+            JOIN Invoice ON Invoice.CustomerId = Customer.CustomerId
+            WHERE Invoice.InvoiceId = :invoice_id AND Invoice.CustomerId = :customer_id;
+            """,
+            {"invoice_id": _safe_int(invoice_id, "invoice ID"), "customer_id": _safe_int(customer_id, "customer ID")},
+        )
+        logger.info(f"TOOL_RESULT: get_employee_by_invoice_and_customer | result_length={len(result)}")
+        if result == "[]":
+            return f"No employee found for invoice ID {invoice_id} and customer ID {customer_id}."
+        return result
+    except Exception as e:
+        logger.error(f"Error in get_employee_by_invoice_and_customer: {e}")
+        return f"Error finding employee for invoice {invoice_id}. Please try again."
+
+
+@tool
+def get_invoice_line_items(invoice_id: str, customer_id: str) -> str:
+    """
+    Get the detailed line items (tracks purchased) for a specific invoice.
+    Returns full track details for each purchased item.
+    """
+    logger.info(f"TOOL_CALL: get_invoice_line_items | invoice_id={invoice_id}, customer_id={customer_id}")
+    try:
+        result = run_query_safe(
+            """
+            SELECT Track.TrackId,
+                   Track.Name AS TrackName,
+                   Artist.Name AS ArtistName,
+                   Album.Title AS AlbumTitle,
+                   Genre.Name AS GenreName,
+                   Track.Composer,
+                   Track.Milliseconds,
+                   ROUND(Track.Milliseconds / 60000.0, 1) AS DurationMinutes,
+                   InvoiceLine.UnitPrice,
+                   InvoiceLine.Quantity
+            FROM InvoiceLine
+            JOIN Invoice ON InvoiceLine.InvoiceId = Invoice.InvoiceId
+            JOIN Track ON InvoiceLine.TrackId = Track.TrackId
+            LEFT JOIN Album ON Track.AlbumId = Album.AlbumId
+            LEFT JOIN Artist ON Album.ArtistId = Artist.ArtistId
+            LEFT JOIN Genre ON Track.GenreId = Genre.GenreId
+            WHERE Invoice.InvoiceId = :invoice_id AND Invoice.CustomerId = :customer_id
+            ORDER BY Track.Name;
+            """,
+            {"invoice_id": _safe_int(invoice_id, "invoice ID"), "customer_id": _safe_int(customer_id, "customer ID")},
+        )
+        logger.info(f"TOOL_RESULT: get_invoice_line_items | result_length={len(result)}")
+        if result == "[]":
+            return f"No line items found for invoice {invoice_id} (customer {customer_id})."
+        return result
+    except Exception as e:
+        logger.error(f"Error in get_invoice_line_items: {e}")
+        return f"Error retrieving line items for invoice {invoice_id}. Please try again."
+
+
+invoice_tools = [
+    get_invoices_by_customer_sorted_by_date,
+    get_invoice_line_items_sorted_by_price,
+    get_employee_by_invoice_and_customer,
+    get_invoice_line_items,
+]

src/tools/music_catalog.py

@@ -0,0 +1,246 @@
+"""Music catalog tools for the multi-agent system."""
+
+import logging
+from langchain_core.tools import tool
+from src.db.database import run_query_safe
+
+logger = logging.getLogger(__name__)
+
+
+def _safe_int(value: str, label: str = "value") -> int:
+    try:
+        return int(value)
+    except (ValueError, TypeError):
+        raise ValueError(f"Invalid {label}: '{value}'. Please provide a numeric value.")
+
+
+@tool
+def get_albums_by_artist(artist: str) -> str:
+    """Get albums by an artist from the music catalog. Uses fuzzy matching on artist name."""
+    logger.info(f"TOOL_CALL: get_albums_by_artist | artist={artist}")
+    try:
+        result = run_query_safe(
+            """
+            SELECT Album.AlbumId, Album.Title AS AlbumTitle, Artist.Name AS ArtistName
+            FROM Album
+            JOIN Artist ON Album.ArtistId = Artist.ArtistId
+            WHERE Artist.Name LIKE :pattern
+            ORDER BY Album.Title;
+            """,
+            {"pattern": f"%{artist}%"},
+        )
+        logger.info(f"TOOL_RESULT: get_albums_by_artist | result_length={len(result)}")
+        if result == "[]":
+            return f"No albums found for artist: {artist}"
+        return result
+    except Exception as e:
+        logger.error(f"Error in get_albums_by_artist: {e}")
+        return f"Error looking up albums for '{artist}'. Please try again."
+
+
+@tool
+def get_tracks_by_artist(artist: str) -> str:
+    """
+    Get songs/tracks by an artist from the catalog.
+    Returns total count and a sample of up to 20 tracks with full details.
+    """
+    logger.info(f"TOOL_CALL: get_tracks_by_artist | artist={artist}")
+    try:
+        count_result = run_query_safe(
+            """
+            SELECT COUNT(*) AS total_tracks
+            FROM Track
+            JOIN Album ON Track.AlbumId = Album.AlbumId
+            JOIN Artist ON Album.ArtistId = Artist.ArtistId
+            WHERE Artist.Name LIKE :pattern;
+            """,
+            {"pattern": f"%{artist}%"},
+        )
+
+        result = run_query_safe(
+            """
+            SELECT Track.TrackId,
+                   Track.Name AS SongName,
+                   Artist.Name AS ArtistName,
+                   Album.Title AS AlbumTitle,
+                   Genre.Name AS GenreName,
+                   Track.Composer,
+                   Track.Milliseconds,
+                   ROUND(Track.Milliseconds / 60000.0, 1) AS DurationMinutes,
+                   Track.Bytes,
+                   Track.UnitPrice,
+                   MediaType.Name AS MediaType
+            FROM Track
+            JOIN Album ON Track.AlbumId = Album.AlbumId
+            JOIN Artist ON Album.ArtistId = Artist.ArtistId
+            LEFT JOIN Genre ON Track.GenreId = Genre.GenreId
+            LEFT JOIN MediaType ON Track.MediaTypeId = MediaType.MediaTypeId
+            WHERE Artist.Name LIKE :pattern
+            ORDER BY Album.Title, Track.Name
+            LIMIT 20;
+            """,
+            {"pattern": f"%{artist}%"},
+        )
+        logger.info(f"TOOL_RESULT: get_tracks_by_artist | count={count_result} | sample_length={len(result)}")
+
+        if result == "[]":
+            return f"No tracks found for artist: {artist}"
+
+        return f"Total tracks found: {count_result}. Sample (up to 20): {result}"
+    except Exception as e:
+        logger.error(f"Error in get_tracks_by_artist: {e}")
+        return f"Error looking up tracks for '{artist}'. Please try again."
+
+
+@tool
+def get_songs_by_genre(genre: str) -> str:
+    """
+    Fetch a representative sample of songs from a specific genre.
+    Returns total count and one song per artist (up to 10), deterministically
+    picking each artist's first track by TrackId.
+    """
+    logger.info(f"TOOL_CALL: get_songs_by_genre | genre={genre}")
+    try:
+        count_result = run_query_safe(
+            """
+            SELECT COUNT(*) AS total_tracks
+            FROM Track
+            JOIN Genre ON Track.GenreId = Genre.GenreId
+            WHERE Genre.Name LIKE :pattern;
+            """,
+            {"pattern": f"%{genre}%"},
+        )
+
+        result = run_query_safe(
+            """
+            WITH ranked AS (
+                SELECT Track.TrackId,
+                       Track.Name AS SongName,
+                       Artist.Name AS ArtistName,
+                       Album.Title AS AlbumTitle,
+                       Genre.Name AS GenreName,
+                       Track.Composer,
+                       Track.Milliseconds,
+                       ROUND(Track.Milliseconds / 60000.0, 1) AS DurationMinutes,
+                       Track.Bytes,
+                       Track.UnitPrice,
+                       MediaType.Name AS MediaType,
+                       ROW_NUMBER() OVER (PARTITION BY Artist.ArtistId ORDER BY Track.TrackId) AS rn
+                FROM Track
+                JOIN Genre ON Track.GenreId = Genre.GenreId
+                JOIN Album ON Track.AlbumId = Album.AlbumId
+                JOIN Artist ON Album.ArtistId = Artist.ArtistId
+                LEFT JOIN MediaType ON Track.MediaTypeId = MediaType.MediaTypeId
+                WHERE Genre.Name LIKE :pattern
+            )
+            SELECT TrackId, SongName, ArtistName, AlbumTitle, GenreName,
+                   Composer, Milliseconds, DurationMinutes, Bytes, UnitPrice, MediaType
+            FROM ranked
+            WHERE rn = 1
+            ORDER BY ArtistName
+            LIMIT 10;
+            """,
+            {"pattern": f"%{genre}%"},
+        )
+        logger.info(f"TOOL_RESULT: get_songs_by_genre | count={count_result} | sample_length={len(result)}")
+
+        if result == "[]":
+            return f"No songs found for the genre: {genre}"
+
+        return (
+            f"Total {genre} tracks in catalog: {count_result}. "
+            f"Representative sample (one per artist, up to 10): {result}"
+        )
+    except Exception as e:
+        logger.error(f"Error in get_songs_by_genre: {e}")
+        return f"Error looking up songs for genre '{genre}'. Please try again."
+
+
+@tool
+def check_for_songs(song_title: str) -> str:
+    """
+    Check if a song exists in the catalog by its name. Uses fuzzy matching.
+    Returns up to 10 matches with full track details.
+    """
+    logger.info(f"TOOL_CALL: check_for_songs | song_title={song_title}")
+    try:
+        result = run_query_safe(
+            """
+            SELECT Track.TrackId,
+                   Track.Name AS SongName,
+                   Artist.Name AS ArtistName,
+                   Album.Title AS AlbumTitle,
+                   Genre.Name AS GenreName,
+                   Track.Composer,
+                   Track.Milliseconds,
+                   ROUND(Track.Milliseconds / 60000.0, 1) AS DurationMinutes,
+                   Track.Bytes,
+                   Track.UnitPrice,
+                   MediaType.Name AS MediaType
+            FROM Track
+            JOIN Album ON Track.AlbumId = Album.AlbumId
+            JOIN Artist ON Album.ArtistId = Artist.ArtistId
+            LEFT JOIN Genre ON Track.GenreId = Genre.GenreId
+            LEFT JOIN MediaType ON Track.MediaTypeId = MediaType.MediaTypeId
+            WHERE Track.Name LIKE :pattern
+            ORDER BY Track.Name
+            LIMIT 10;
+            """,
+            {"pattern": f"%{song_title}%"},
+        )
+        logger.info(f"TOOL_RESULT: check_for_songs | result_length={len(result)}")
+        if result == "[]":
+            return f"No songs found matching: {song_title}"
+        return result
+    except Exception as e:
+        logger.error(f"Error in check_for_songs: {e}")
+        return f"Error looking up song '{song_title}'. Please try again."
+
+
+@tool
+def get_track_details(track_id: str) -> str:
+    """
+    Get complete details for a specific track by its TrackId.
+    Use this when the customer needs detailed info about a specific known track.
+    """
+    logger.info(f"TOOL_CALL: get_track_details | track_id={track_id}")
+    try:
+        result = run_query_safe(
+            """
+            SELECT Track.TrackId,
+                   Track.Name AS SongName,
+                   Artist.Name AS ArtistName,
+                   Album.Title AS AlbumTitle,
+                   Genre.Name AS GenreName,
+                   Track.Composer,
+                   Track.Milliseconds,
+                   ROUND(Track.Milliseconds / 60000.0, 1) AS DurationMinutes,
+                   Track.Bytes,
+                   ROUND(Track.Bytes / 1048576.0, 1) AS SizeMB,
+                   Track.UnitPrice,
+                   MediaType.Name AS MediaType
+            FROM Track
+            LEFT JOIN Album ON Track.AlbumId = Album.AlbumId
+            LEFT JOIN Artist ON Album.ArtistId = Artist.ArtistId
+            LEFT JOIN Genre ON Track.GenreId = Genre.GenreId
+            LEFT JOIN MediaType ON Track.MediaTypeId = MediaType.MediaTypeId
+            WHERE Track.TrackId = :track_id;
+            """,
+            {"track_id": _safe_int(track_id, "track ID")},
+        )
+        logger.info(f"TOOL_RESULT: get_track_details | result_length={len(result)}")
+        if result == "[]":
+            return f"No track found with TrackId: {track_id}"
+        return result
+    except Exception as e:
+        logger.error(f"Error in get_track_details: {e}")
+        return f"Error looking up track {track_id}. Please try again."
+
+
+music_tools = [
+    get_albums_by_artist,
+    get_tracks_by_artist,
+    get_songs_by_genre,
+    check_for_songs,
+    get_track_details,
+]

src/ui/app.py

@@ -0,0 +1,262 @@
+"""Gradio application for the Music Store Multi-Agent System."""
+
+import uuid
+import time
+import logging
+
+import gradio as gr
+from langchain_core.messages import HumanMessage, AIMessage
+
+from src.config import settings
+from src.db.database import verify_database
+from src.agents.graph import build_graph
+from src.ui.styles import CUSTOM_CSS
+
+logger = logging.getLogger(__name__)
+
+# Module-level state
+_graph = None
+_checkpointer = None
+_store = None
+
+
+def initialize():
+    global _graph, _checkpointer, _store
+
+    logger.info("Initializing Music Store Agent...")
+
+    db_health = verify_database()
+    if db_health.get("status") != "healthy":
+        logger.error(f"Database unhealthy: {db_health}")
+    else:
+        logger.info(f"Database healthy: {db_health['tables']}")
+
+    try:
+        _graph, _checkpointer, _store = build_graph(
+            model_name=settings.model_name,
+            temperature=settings.temperature,
+            openai_api_key=settings.openai_api_key or None,
+            openai_api_base=settings.openai_api_base or None,
+        )
+        logger.info("Agent graph built successfully.")
+    except Exception as e:
+        logger.error(f"Failed to build agent graph: {e}")
+        raise
+
+
+def _status_html(status: str, message: str, tools_used: list = None) -> str:
+    colors = {
+        "success": "#10b981",
+        "error": "#ef4444",
+        "warning": "#f59e0b",
+        "waiting": "#6366f1",
+        "idle": "#6b7280",
+    }
+    icons = {
+        "success": "✓",
+        "error": "✗",
+        "warning": "⚠",
+        "waiting": "⏳",
+        "idle": "●",
+    }
+    color = colors.get(status, "#6b7280")
+    icon = icons.get(status, "●")
+
+    tools_text = ""
+    if tools_used:
+        tools_text = f" | Data sources: {', '.join(set(tools_used))}"
+
+    return (
+        f'<div style="display:flex;align-items:center;gap:6px;padding:6px 12px;'
+        f'border-radius:6px;background:{color}15;border:1px solid {color}30;'
+        f'font-size:13px;color:{color};">'
+        f'<span>{icon}</span>'
+        f'<span>{message}{tools_text}</span>'
+        f'</div>'
+    )
+
+
+def reset_conversation() -> tuple:
+    new_thread = str(uuid.uuid4())
+    logger.info(f"Conversation reset. New thread_id={new_thread}")
+    return [], new_thread, _status_html("idle", "New conversation started")
+
+
+def show_user_message(message, history, tid):
+    if not message.strip():
+        return history, "", tid, _status_html("idle", "Ready")
+    if not tid:
+        tid = str(uuid.uuid4())
+    history = history + [{"role": "user", "content": message}]
+    return history, "", tid, _status_html("waiting", "Processing...")
+
+
+def generate_response(history, tid):
+    if not history:
+        return history, tid, _status_html("idle", "Ready")
+
+    user_message = None
+    for msg in reversed(history):
+        if msg.get("role") == "user":
+            user_message = msg["content"]
+            break
+
+    if not user_message:
+        return history, tid, _status_html("idle", "Ready")
+
+    if not _graph:
+        history.append({"role": "assistant", "content": "System not initialized. Please refresh the page."})
+        return history, tid, _status_html("error", "System not initialized")
+
+    config = {"configurable": {"thread_id": tid}}
+
+    try:
+        start_time = time.time()
+        input_state = {"messages": [HumanMessage(content=user_message)]}
+
+        final_response = None
+        tools_used = []
+
+        for event in _graph.stream(input_state, config=config, stream_mode="updates"):
+            for node_name, node_output in event.items():
+                logger.info(f"Graph event: node={node_name}")
+
+                if node_name in ("music_tool_node",):
+                    tools_used.append("music_catalog")
+                elif node_name == "invoice_information_subagent":
+                    tools_used.append("invoice_lookup")
+
+                if isinstance(node_output, dict) and "messages" in node_output:
+                    for msg in node_output["messages"]:
+                        if isinstance(msg, AIMessage) and msg.content:
+                            final_response = msg.content
+
+        elapsed = time.time() - start_time
+
+        if final_response:
+            history.append({"role": "assistant", "content": final_response})
+            status_out = _status_html(
+                "success",
+                f"Responded in {elapsed:.1f}s",
+                tools_used=tools_used,
+            )
+        else:
+            snapshot = _graph.get_state(config)
+            if snapshot and hasattr(snapshot, "next") and snapshot.next:
+                state_messages = snapshot.values.get("messages", [])
+                for msg in reversed(state_messages):
+                    if isinstance(msg, AIMessage) and msg.content:
+                        final_response = msg.content
+                        break
+
+                if final_response and not any(
+                    h.get("content") == final_response for h in history if h.get("role") == "assistant"
+                ):
+                    history.append({"role": "assistant", "content": final_response})
+
+                status_out = _status_html("waiting", "Waiting for your input")
+            else:
+                history.append({
+                    "role": "assistant",
+                    "content": "I'm sorry, I wasn't able to generate a response. Please try rephrasing your question.",
+                })
+                status_out = _status_html("warning", "No response generated")
+
+        return history, tid, status_out
+
+    except Exception as e:
+        logger.error(f"Error processing message: {e}", exc_info=True)
+        history.append({"role": "assistant", "content": "I encountered an error. Please try again."})
+        return history, tid, _status_html("error", str(e)[:100])
+
+
+def create_app() -> gr.Blocks:
+    initialize()
+
+    with gr.Blocks(
+        title=settings.app_title,
+        css=CUSTOM_CSS,
+        theme=gr.themes.Soft(
+            primary_hue="blue",
+            secondary_hue="slate",
+            neutral_hue="slate",
+            font=gr.themes.GoogleFont("Inter"),
+        ),
+    ) as app:
+
+        thread_id = gr.State(value="")
+
+        gr.HTML(
+            f"""
+            <div class="app-header">
+                <h1>{settings.app_title}</h1>
+                <p>{settings.app_description}</p>
+            </div>
+            """
+        )
+
+        chatbot = gr.Chatbot(
+            value=[],
+            type="messages",
+            height=480,
+            show_label=False,
+            avatar_images=(None, "https://api.dicebear.com/7.x/bottts/svg?seed=music"),
+            elem_classes=["chatbot-container"],
+            placeholder=(
+                "**Welcome!** Type your message below to get started.\n\n"
+                "Try: *\"My customer ID is 5\"* or *\"What rock albums do you have?\"*"
+            ),
+        )
+
+        status = gr.HTML(
+            value=_status_html("idle", "Ready — type a message to begin"),
+            elem_classes=["status-bar"],
+        )
+
+        with gr.Row():
+            msg_input = gr.Textbox(
+                placeholder="Type your message here...",
+                show_label=False,
+                scale=6,
+                container=False,
+                autofocus=True,
+            )
+            send_btn = gr.Button("Send", variant="primary", scale=1, min_width=80)
+
+        with gr.Row():
+            reset_btn = gr.Button("New Conversation", size="sm", variant="secondary")
+
+        gr.HTML(
+            '<div class="app-footer">'
+            'Powered by LangGraph Multi-Agent Architecture · '
+            'Data from Chinook Sample Database'
+            '</div>'
+        )
+
+        send_btn.click(
+            fn=show_user_message,
+            inputs=[msg_input, chatbot, thread_id],
+            outputs=[chatbot, msg_input, thread_id, status],
+        ).then(
+            fn=generate_response,
+            inputs=[chatbot, thread_id],
+            outputs=[chatbot, thread_id, status],
+        )
+
+        msg_input.submit(
+            fn=show_user_message,
+            inputs=[msg_input, chatbot, thread_id],
+            outputs=[chatbot, msg_input, thread_id, status],
+        ).then(
+            fn=generate_response,
+            inputs=[chatbot, thread_id],
+            outputs=[chatbot, thread_id, status],
+        )
+
+        reset_btn.click(
+            fn=reset_conversation,
+            inputs=[],
+            outputs=[chatbot, thread_id, status],
+        )
+
+    return app

src/ui/styles.py

@@ -0,0 +1,46 @@
+"""CSS styles for the Gradio application."""
+
+CUSTOM_CSS = """
+.gradio-container {
+    max-width: 900px !important;
+    margin: 0 auto !important;
+    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif !important;
+}
+.app-header {
+    text-align: center;
+    padding: 24px 16px 16px;
+    border-bottom: 1px solid #e5e7eb;
+    margin-bottom: 16px;
+}
+.app-header h1 {
+    font-size: 28px;
+    font-weight: 700;
+    color: #1f2937;
+    margin: 0 0 8px;
+}
+.app-header p {
+    font-size: 14px;
+    color: #6b7280;
+    margin: 0;
+    line-height: 1.5;
+}
+.chatbot-container {
+    border: 1px solid #e5e7eb !important;
+    border-radius: 12px !important;
+    overflow: hidden;
+}
+.status-bar {
+    min-height: 36px;
+}
+.app-footer {
+    text-align: center;
+    padding: 12px;
+    font-size: 12px;
+    color: #9ca3af;
+    border-top: 1px solid #f3f4f6;
+    margin-top: 8px;
+}
+@media (max-width: 640px) {
+    .app-header h1 { font-size: 22px; }
+}
+"""