Initial Changes

.dockerignore

@@ -0,0 +1,29 @@
+# Git
+.git
+.gitignore
+
+# Local env — secrets never go into the image
+.env
+.env.*
+
+# Python cache
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info
+dist/
+build/
+
+# Tests
+tests/
+
+# Docker files (not needed inside image)
+Dockerfile
+Dockerfile.space
+docker-compose.yml
+
+# Local dev notes
+*.md
+!README.md

.env.example

@@ -0,0 +1,9 @@
+GROQ_API_KEY=your_groq_api_key_here
+HUGGINGFACEHUB_API_TOKEN=your_groq_api_key_here
+HF_TOKEN=your_groq_api_key_here
+WEATHER_API_KEY=your_weatherstack_api_key_here
+LLM_MODEL=llama-3.3-70b-versatile
+LLM_TEMPERATURE=0
+MAX_RETRIES=3
+EVAL_THRESHOLD=0.6
+HITL_ENABLED=true

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.env
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.DS_Store

Dockerfile

@@ -0,0 +1,51 @@
+# HuggingFace Spaces — Dockerfile
+# Docs: https://huggingface.co/docs/hub/spaces-sdks-docker
+#
+# Rules for HF Spaces:
+#   - Must expose port 7860
+#   - Must run as non-root user (uid 1000)
+#   - No BuildKit cache mounts (HF builder doesn't support --mount)
+#   - Secrets injected via Space Settings → Variables, not .env file
+
+FROM python:3.10-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_ROOT_USER_ACTION=ignore \
+    PYTHONPATH=/app \
+    GRADIO_MODE=true \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860
+
+WORKDIR /app
+
+# System deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install heavy ML packages first (longest layer)
+RUN pip install --upgrade pip && \
+    pip install \
+        --extra-index-url https://download.pytorch.org/whl/cpu \
+        torch \
+        sentence-transformers \
+        transformers \
+        faiss-cpu
+
+# Install remaining dependencies
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+# Copy source
+COPY . .
+
+# HuggingFace Spaces requires non-root user uid=1000
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 7860
+
+CMD ["python", "app/frontend/gradio_app_hf.py"]

README.md

@@ -8,3 +8,89 @@ pinned: false
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# LangGraph Agent — Modular Structure
+
+A production-ready LangGraph application with 8 agentic checkpoints,
+modular architecture, and Docker support.
+
+## Project Structure
+
+```
+langgraph_agent/
+├── app/
+│   ├── config.py              # All settings (env-driven)
+│   ├── state.py               # AgentState TypedDict
+│   ├── nodes/
+│   │   ├── router.py          # ✅ Checkpoint 3 — Conditional routing
+│   │   ├── rag.py             # ✅ Checkpoint 2 — RAG retrieval
+│   │   ├── llm_node.py        # ✅ Checkpoint 4 — Retries
+│   │   ├── tool_executor.py   # ✅ Checkpoint 1 — Tool execution
+│   │   ├── memory.py          # ✅ Checkpoint 5 — Memory
+│   │   ├── hitl.py            # ✅ Checkpoint 6 — Human-in-the-Loop
+│   │   ├── evaluation.py      # ✅ Checkpoint 7 — Evaluation
+│   │   ├── guardrails.py      # ✅ Checkpoint 8 — Guardrails
+│   │   └── output.py          # Final output node
+│   ├── tools/
+│   │   ├── calculator.py      # Math expression tool
+│   │   └── weather.py         # Weatherstack API tool
+│   ├── rag/
+│   │   └── store.py           # FAISS vector store + retrieval
+│   ├── graph/
+│   │   └── builder.py         # Graph topology assembly
+│   └── utils/
+│       └── llm.py             # LLM singleton factory
+├── tests/
+│   └── test_nodes.py          # Unit tests (no API key needed)
+├── main.py                    # CLI entry point
+├── requirements.txt
+├── Dockerfile
+├── docker-compose.yml
+└── .env.example
+```
+
+## Quickstart
+
+### Local
+
+```bash
+cp .env.example .env
+# Fill in GROQ_API_KEY and WEATHER_API_KEY
+
+pip install -r requirements.txt
+python main.py
+```
+
+### Docker
+
+```bash
+cp .env.example .env
+# Fill in your API keys in .env
+
+docker compose up --build
+```
+
+### Run tests (no API keys needed)
+
+```bash
+pip install pytest
+pytest tests/
+```
+
+## Adding a new tool
+
+1. Create `app/tools/my_tool.py` with a `@tool` function
+2. Import it in `app/tools/__init__.py` and add to `ALL_TOOLS`
+3. Done — the router and LLM binding pick it up automatically
+
+## Environment Variables
+
+| Variable         | Description                        | Default                     |
+|------------------|------------------------------------|-----------------------------|
+| GROQ_API_KEY     | Groq API key                       | required                    |
+| WEATHER_API_KEY  | Weatherstack API key               | required for weather tool   |
+| LLM_MODEL        | Groq model name                    | llama-3.3-70b-versatile     |
+| LLM_TEMPERATURE  | LLM temperature                    | 0                           |
+| MAX_RETRIES      | Max LLM retry attempts             | 3                           |
+| EVAL_THRESHOLD   | Min quality score before retry     | 0.6                         |
+| HITL_ENABLED     | Enable human approval gate         | true                        |

app/config.py

@@ -0,0 +1,40 @@
+"""
+app/config.py
+─────────────
+Central configuration — all env-driven settings live here.
+"""
+
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class Config:
+    # ── LLM ───────────────────────────────────────────────────────────────
+    GROQ_API_KEY: str       = os.getenv("GROQ_API_KEY", "")
+    LLM_MODEL: str          = os.getenv("LLM_MODEL", "llama-3.3-70b-versatile")
+    LLM_TEMPERATURE: float  = float(os.getenv("LLM_TEMPERATURE", "0"))
+
+    # ── External APIs ─────────────────────────────────────────────────────
+    WEATHER_API_KEY: str    = os.getenv("WEATHER_API_KEY", "")
+
+    # ── Agent behaviour ───────────────────────────────────────────────────
+    MAX_RETRIES: int        = int(os.getenv("MAX_RETRIES", "3"))
+    EVAL_THRESHOLD: float   = float(os.getenv("EVAL_THRESHOLD", "0.6"))
+    HITL_ENABLED: bool      = os.getenv("HITL_ENABLED", "true").lower() == "true"
+
+    # ── UI mode ───────────────────────────────────────────────────────────
+    # Set to true when running under Gradio — switches HITL from input()
+    # to the exception-based pause/resume mechanism
+    GRADIO_MODE: bool       = os.getenv("GRADIO_MODE", "false").lower() == "true"
+
+    # ── RAG ───────────────────────────────────────────────────────────────
+    EMBEDDING_MODEL: str    = "sentence-transformers/all-MiniLM-L6-v2"
+    RAG_TOP_K: int          = 2
+
+    # ── Guardrails ────────────────────────────────────────────────────────
+    BLOCKED_PHRASES: list   = ["harm", "illegal", "violence", "hate"]
+
+
+settings = Config()

app/frontend/css.py

@@ -0,0 +1,93 @@
+CSS = """
+/* Claude's exact font stack */
+*, *::before, *::after {
+    font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI",
+                 Helvetica, Arial, sans-serif !important;
+    box-sizing: border-box;
+}
+
+footer { display: none !important; }
+
+/* Full-page warm dark background */
+.gradio-container {
+    max-width: 100% !important;
+    width: 100% !important;
+    padding: 12px !important;
+    margin: 0 !important;
+    min-height: 100vh;
+    background: #1c1917 !important;
+}
+
+/* Gradio theme token overrides — warm stone palette */
+.gradio-container, .wrap, .prose {
+    --body-background-fill:        #1c1917 !important;
+    --background-fill-primary:     #28211e !important;
+    --background-fill-secondary:   #1c1917 !important;
+    --border-color-primary:        #44403c !important;
+    --color-accent:                #a78bfa !important;
+    --button-primary-background-fill:       #7c3aed !important;
+    --button-primary-background-fill-hover: #6d28d9 !important;
+    --button-primary-text-color:   #ffffff !important;
+    --input-background-fill:       #28211e !important;
+    --block-background-fill:       #28211e !important;
+    --block-border-color:          #44403c !important;
+    --body-text-color:             #e7e5e4 !important;
+    --body-text-color-subdued:     #a8a29e !important;
+}
+
+/* ── Bordered section boxes ── */
+/* Every top-level gr.Group or gr.Column block */
+.section-box {
+    border: 1px solid #44403c !important;
+    border-radius: 12px !important;
+    background: #211e1b !important;
+    padding: 16px !important;
+    margin-bottom: 10px !important;
+}
+
+/* Override Gradio's own block borders to match our style */
+.block {
+    border-radius: 12px !important;
+    border: 1px solid #44403c !important;
+    background: #211e1b !important;
+}
+
+/* Don't double-border inner elements */
+.block .block { border: none !important; background: transparent !important; }
+
+/* Chatbot window itself */
+.chatbot-block { border: 1px solid #44403c !important; border-radius: 12px !important; overflow: hidden !important; }
+
+/* Chat bubbles */
+.message.user {
+    background: #3b1f6b !important;
+    border: 1px solid #5b21b6 !important;
+    color: #ede9fe !important;
+    border-radius: 18px 18px 4px 18px !important;
+    font-size: 15px !important;
+    line-height: 1.65 !important;
+}
+.message.bot, .message.assistant {
+    background: #2a2420 !important;
+    border: 1px solid #44403c !important;
+    color: #e7e5e4 !important;
+    border-radius: 4px 18px 18px 18px !important;
+    font-size: 15px !important;
+    line-height: 1.65 !important;
+}
+.avatar-container { display: none !important; }
+
+/* Input textarea */
+textarea {
+    font-size: 15px !important;
+    line-height: 1.5 !important;
+}
+
+/* HITL warning box */
+.hitl-box {
+    border: 1px solid #92400e !important;
+    border-radius: 12px !important;
+    background: #1c1007 !important;
+    padding: 14px 16px !important;
+}
+"""

app/frontend/gradio_app.py

@@ -0,0 +1,232 @@
+"""
+app/frontend/gradio_app.py — Full page warm gray UI
+"""
+import os
+import gradio as gr
+from langchain_core.messages import HumanMessage
+
+os.environ["GRADIO_MODE"] = "true"
+os.environ["HITL_ENABLED"] = os.getenv("HITL_ENABLED", "true")
+
+from app.graph.builder import build_graph
+from app.state import AgentState
+from app.nodes.hitl import HITLPauseException
+
+_graph = build_graph()
+_thread_config = {"configurable": {"thread_id": "gradio-session-001"}}
+_conversation_history = []
+_pending_hitl_state: AgentState | None = None
+
+
+def run_graph(query: str) -> AgentState:
+    global _conversation_history
+    _conversation_history.append(HumanMessage(content=query))
+    initial_state: AgentState = {
+        "messages": _conversation_history.copy(), "query": query,
+        "route": "", "rag_context": "", "tool_calls": [], "tool_results": [],
+        "response": "", "retry_count": 0, "hitl_approved": False,
+        "evaluation_score": 0.0, "guardrail_passed": True,
+        "memory_summary": "", "node_log": [],
+    }
+    return _graph.invoke(initial_state, config=_thread_config)
+
+
+def resume_graph_after_hitl(state: AgentState, approved: bool) -> AgentState:
+    global _conversation_history
+    from app.nodes.evaluation import evaluation_node, eval_route
+    from app.nodes.guardrails import guardrails_node
+    from app.nodes.output import output_node
+    if not approved:
+        return {**state, "response": "🚫 Response rejected by human reviewer."}
+    s = evaluation_node({**state, "hitl_approved": True})
+    if eval_route(s) == "retry":
+        from app.nodes.llm_node import llm_node
+        s = llm_node(s)
+    s = guardrails_node(s)
+    s = output_node(s)
+    _conversation_history = s["messages"]
+    return s
+
+
+def format_trace(node_log: list) -> str:
+    if not node_log:
+        return "*Waiting for a query...*"
+    lines = []
+    for node in node_log:
+        if any(x in node for x in ["✅", "auto-pass", "approved", "output", "passed"]):
+            icon = "✅"
+        elif any(x in node for x in ["BLOCKED", "rejected", "FAILED", "ERROR"]):
+            icon = "❌"
+        elif any(x in node for x in ["retry", "⏳", "⏸"]):
+            icon = "🔄"
+        else:
+            icon = "▸"
+        lines.append(f"{icon} `{node}`")
+    return "\n\n".join(lines)
+
+
+def user_msg(t): return {"role": "user",      "content": t}
+def bot_msg(t):  return {"role": "assistant",  "content": t}
+
+
+def handle_submit(user_message, chat_history):
+    global _pending_hitl_state
+    if not user_message.strip():
+        return chat_history, "", "*Waiting for a query...*", "", gr.update(visible=False), gr.update(value="")
+
+    chat_history = chat_history + [user_msg(user_message)]
+    try:
+        fs = run_graph(user_message)
+        route = fs.get("route", "")
+        score = fs.get("evaluation_score", 0.0)
+        g_ok  = fs.get("guardrail_passed", True)
+
+        # Guardrail blocked — remove this exchange from history so it
+        # doesn't poison the memory summary for future innocent queries
+        if not g_ok:
+            global _conversation_history
+            if _conversation_history:
+                _conversation_history.pop()
+
+        chat_history = chat_history + [bot_msg(fs.get("response", ""))]
+        meta  = f"**Route:** {route.upper() or '—'}  ·  **Eval:** {score:.2f}  ·  **Guardrail:** {'✅ Passed' if g_ok else '🚫 Blocked'}"
+        return (chat_history, "", format_trace(fs.get("node_log", [])),
+                meta, gr.update(visible=False), gr.update(value=""))
+
+    except HITLPauseException as e:
+        _pending_hitl_state = e.state
+        log  = e.state.get("node_log", []) + ["⏸ hitl — awaiting approval"]
+        chat_history = chat_history + [bot_msg("⏳ *Awaiting human approval...*")]
+        meta = f"**Route:** {e.state.get('route','').upper() or '—'}  ·  **Status:** ⏸ Pending HITL"
+        return (chat_history, "", format_trace(log),
+                meta, gr.update(visible=True),
+                gr.update(value=f"**Pending response:**\n\n{e.pending_response}"))
+
+    except Exception as e:
+        chat_history = chat_history + [bot_msg(f"❌ Error: {e}")]
+        return (chat_history, "", f"❌ `{e}`", "", gr.update(visible=False), gr.update(value=""))
+
+
+def handle_approve(chat_history):
+    global _pending_hitl_state
+    if not _pending_hitl_state:
+        return chat_history, "*No trace.*", "", gr.update(visible=False)
+    fs = resume_graph_after_hitl(_pending_hitl_state, True)
+    _pending_hitl_state = None
+    if chat_history and chat_history[-1]["role"] == "assistant":
+        chat_history = chat_history[:-1] + [bot_msg(fs.get("response", ""))]
+    score = fs.get("evaluation_score", 0.0)
+    g_ok  = fs.get("guardrail_passed", True)
+    meta  = f"**Route:** {fs.get('route','').upper() or '—'}  ·  **Eval:** {score:.2f}  ·  **Guardrail:** {'✅ Passed' if g_ok else '🚫 Blocked'}"
+    return chat_history, format_trace(fs.get("node_log", []) + ["✅ hitl approved → output"]), meta, gr.update(visible=False)
+
+
+def handle_reject(chat_history):
+    global _pending_hitl_state
+    _pending_hitl_state = None
+    if chat_history and chat_history[-1]["role"] == "assistant":
+        chat_history = chat_history[:-1] + [bot_msg("🚫 Rejected by reviewer.")]
+    return chat_history, "❌ `hitl rejected → END`", "", gr.update(visible=False)
+
+
+def handle_clear():
+    global _conversation_history, _pending_hitl_state
+    _conversation_history, _pending_hitl_state = [], None
+    return [], "", "*Waiting for a query...*", "", gr.update(visible=False)
+
+
+from app.frontend.css import CSS
+
+
+def build_ui():
+    with gr.Blocks(title="LangGraph Agent", css=CSS, theme=gr.themes.Soft()) as demo:
+
+        # ── Header ───────────────────────────────────────────────────
+        gr.Markdown("## 🤖 LangGraph Agent")
+
+        with gr.Row(equal_height=True):
+
+            # ══ Main chat column ══════════════════════════════════════
+            with gr.Column(scale=4):
+
+                # Chat box
+                with gr.Group(elem_classes="section-box"):
+                    chatbot = gr.Chatbot(
+                        type="messages",
+                        show_label=False,
+                        height=500,
+                        container=False,
+                        placeholder="Send a message to get started.",
+                        elem_classes="chatbot-block",
+                    )
+
+                # HITL box
+                with gr.Group(visible=False, elem_classes="hitl-box") as hitl_panel:
+                    hitl_content = gr.Markdown()
+                    gr.Markdown("🔐 **Human review required** — approve or reject before the response is sent.")
+                    with gr.Row():
+                        approve_btn = gr.Button("✅ Approve", variant="primary")
+                        reject_btn  = gr.Button("❌ Reject",  variant="stop")
+
+                # Input box
+                with gr.Group(elem_classes="section-box"):
+                    with gr.Row():
+                        user_input = gr.Textbox(
+                            placeholder="Message LangGraph Agent...",
+                            show_label=False, scale=7, lines=1, container=False,
+                        )
+                        send_btn  = gr.Button("Send", variant="primary", scale=1)
+                        clear_btn = gr.Button("🗑",    variant="secondary", scale=0, min_width=44)
+                    meta_display = gr.Markdown("")
+
+                # Examples box
+                with gr.Group(elem_classes="section-box"):
+                    gr.Examples(
+                        examples=[
+                            ["What is RAG?"], ["What is LangGraph?"],
+                            ["Calculate 25 * 48"], ["Weather in Mumbai?"],
+                            ["Tell me a joke"], ["Explain HITL"],
+                        ],
+                        inputs=user_input,
+                        label="Examples",
+                    )
+
+            # ══ Right sidebar ══════════════════════════════════════════
+            with gr.Column(scale=1):
+
+                # Trace box
+                with gr.Group(elem_classes="section-box"):
+                    gr.Markdown("**⚡ Execution Trace**")
+                    trace_display = gr.Markdown("*Waiting for a query...*")
+
+                # Topology box
+                with gr.Group(elem_classes="section-box"):
+                    gr.Markdown("""**🗺 Graph Topology**
+```
+START → router
+  ├─ rag → llm
+  └─ tool/general → llm
+       ├─ tool_executor
+       └─ memory → hitl
+            ├─ evaluation
+            │    ├─ retry → llm
+            │    └─ guardrails → output
+            └─ END
+```""")
+
+        # ── Events ───────────────────────────────────────────────────
+        submit_outs = [chatbot, user_input, trace_display, meta_display, hitl_panel, hitl_content]
+        send_btn.click(fn=handle_submit, inputs=[user_input, chatbot], outputs=submit_outs)
+        user_input.submit(fn=handle_submit, inputs=[user_input, chatbot], outputs=submit_outs)
+
+        hitl_outs = [chatbot, trace_display, meta_display, hitl_panel]
+        approve_btn.click(fn=handle_approve, inputs=[chatbot], outputs=hitl_outs)
+        reject_btn.click(fn=handle_reject,   inputs=[chatbot], outputs=hitl_outs)
+        clear_btn.click(fn=handle_clear, outputs=[chatbot, user_input, trace_display, meta_display, hitl_panel])
+
+    return demo
+
+
+if __name__ == "__main__":
+    demo = build_ui()
+    demo.launch(server_name="0.0.0.0", server_port=7860, show_error=True)

app/frontend/gradio_app_hf.py

@@ -0,0 +1,265 @@
+"""
+app/frontend/gradio_app_hf.py
+──────────────────────────────
+HuggingFace Spaces entry point.
+
+Key differences from local gradio_app.py:
+  - Reads all config from environment variables (HF injects secrets as env vars)
+  - No .env file available on HF Spaces — dotenv is silenced gracefully
+  - Runs on port 7860 (HF Spaces requirement)
+  - PYTHONPATH=/app must be set in Dockerfile so `from app.*` imports resolve
+"""
+
+import os
+
+# ── Set env flags before any app imports ──────────────────────────────────
+os.environ["GRADIO_MODE"]   = "true"
+os.environ["PYTHONPATH"]    = "/app"
+
+# HITL defaults to false on public spaces — override via HF Space Variables
+# All other secrets (GROQ_API_KEY, WEATHER_API_KEY, LLM_MODEL etc.)
+# are set in HuggingFace Space → Settings → Variables and Secrets
+
+# ── Silence dotenv — no .env file exists on HF Spaces ─────────────────────
+# app/config.py calls load_dotenv() which would print a warning if .env
+# is missing. We patch it to a no-op before config is imported.
+import sys
+from unittest.mock import MagicMock
+if "dotenv" not in sys.modules:
+    sys.modules["dotenv"] = MagicMock()
+
+# ── Import the full app (config, graph, nodes all load here) ───────────────
+import gradio as gr
+from langchain_core.messages import HumanMessage
+
+from app.graph.builder import build_graph
+from app.state import AgentState
+from app.nodes.hitl import HITLPauseException
+from app.frontend.css import CSS
+
+
+# ── Graph singleton ────────────────────────────────────────────────────────
+_graph = build_graph()
+_thread_config = {"configurable": {"thread_id": "hf-session-001"}}
+_conversation_history = []
+_pending_hitl_state: AgentState | None = None
+
+
+# ── Core runner ────────────────────────────────────────────────────────────
+
+def run_graph(query: str) -> AgentState:
+    global _conversation_history
+    _conversation_history.append(HumanMessage(content=query))
+    initial_state: AgentState = {
+        "messages":         _conversation_history.copy(),
+        "query":            query,
+        "route":            "",
+        "rag_context":      "",
+        "tool_calls":       [],
+        "tool_results":     [],
+        "response":         "",
+        "retry_count":      0,
+        "hitl_approved":    False,
+        "evaluation_score": 0.0,
+        "guardrail_passed": True,
+        "memory_summary":   "",
+        "node_log":         [],
+    }
+    return _graph.invoke(initial_state, config=_thread_config)
+
+
+def resume_graph_after_hitl(state: AgentState, approved: bool) -> AgentState:
+    global _conversation_history
+    from app.nodes.evaluation import evaluation_node, eval_route
+    from app.nodes.guardrails import guardrails_node
+    from app.nodes.output import output_node
+    if not approved:
+        return {**state, "response": "🚫 Response rejected by human reviewer."}
+    s = evaluation_node({**state, "hitl_approved": True})
+    if eval_route(s) == "retry":
+        from app.nodes.llm_node import llm_node
+        s = llm_node(s)
+    s = guardrails_node(s)
+    s = output_node(s)
+    _conversation_history = s["messages"]
+    return s
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────
+
+def format_trace(node_log: list) -> str:
+    if not node_log:
+        return "*Waiting for a query...*"
+    lines = []
+    for node in node_log:
+        if any(x in node for x in ["✅", "auto-pass", "approved", "output", "passed"]):
+            icon = "✅"
+        elif any(x in node for x in ["BLOCKED", "rejected", "FAILED", "ERROR"]):
+            icon = "❌"
+        elif any(x in node for x in ["retry", "⏳", "⏸"]):
+            icon = "🔄"
+        else:
+            icon = "▸"
+        lines.append(f"{icon} `{node}`")
+    return "\n\n".join(lines)
+
+
+def user_msg(t): return {"role": "user",      "content": t}
+def bot_msg(t):  return {"role": "assistant",  "content": t}
+
+
+# ── Event handlers ─────────────────────────────────────────────────────────
+
+def handle_submit(user_message, chat_history):
+    global _pending_hitl_state, _conversation_history
+    if not user_message.strip():
+        return chat_history, "", "*Waiting for a query...*", "", gr.update(visible=False), gr.update(value="")
+
+    chat_history = chat_history + [user_msg(user_message)]
+    try:
+        fs    = run_graph(user_message)
+        route = fs.get("route", "")
+        score = fs.get("evaluation_score", 0.0)
+        g_ok  = fs.get("guardrail_passed", True)
+
+        # Drop blocked exchange from history to prevent memory poisoning
+        if not g_ok and _conversation_history:
+            _conversation_history.pop()
+
+        chat_history = chat_history + [bot_msg(fs.get("response", ""))]
+        meta = f"**Route:** {route.upper() or '—'}  ·  **Eval:** {score:.2f}  ·  **Guardrail:** {'✅ Passed' if g_ok else '🚫 Blocked'}"
+        return (chat_history, "", format_trace(fs.get("node_log", [])),
+                meta, gr.update(visible=False), gr.update(value=""))
+
+    except HITLPauseException as e:
+        _pending_hitl_state = e.state
+        log  = e.state.get("node_log", []) + ["⏸ hitl — awaiting approval"]
+        chat_history = chat_history + [bot_msg("⏳ *Awaiting human approval...*")]
+        meta = f"**Route:** {e.state.get('route','').upper() or '—'}  ·  **Status:** ⏸ Pending HITL"
+        return (chat_history, "", format_trace(log),
+                meta, gr.update(visible=True),
+                gr.update(value=f"**Pending response:**\n\n{e.pending_response}"))
+
+    except Exception as e:
+        chat_history = chat_history + [bot_msg(f"❌ Error: {e}")]
+        return (chat_history, "", f"❌ `{e}`", "", gr.update(visible=False), gr.update(value=""))
+
+
+def handle_approve(chat_history):
+    global _pending_hitl_state
+    if not _pending_hitl_state:
+        return chat_history, "*No trace.*", "", gr.update(visible=False)
+    fs = resume_graph_after_hitl(_pending_hitl_state, True)
+    _pending_hitl_state = None
+    if chat_history and chat_history[-1]["role"] == "assistant":
+        chat_history = chat_history[:-1] + [bot_msg(fs.get("response", ""))]
+    score = fs.get("evaluation_score", 0.0)
+    g_ok  = fs.get("guardrail_passed", True)
+    meta  = f"**Route:** {fs.get('route','').upper() or '—'}  ·  **Eval:** {score:.2f}  ·  **Guardrail:** {'✅ Passed' if g_ok else '🚫 Blocked'}"
+    return chat_history, format_trace(fs.get("node_log", []) + ["✅ hitl approved → output"]), meta, gr.update(visible=False)
+
+
+def handle_reject(chat_history):
+    global _pending_hitl_state
+    _pending_hitl_state = None
+    if chat_history and chat_history[-1]["role"] == "assistant":
+        chat_history = chat_history[:-1] + [bot_msg("🚫 Rejected by reviewer.")]
+    return chat_history, "❌ `hitl rejected → END`", "", gr.update(visible=False)
+
+
+def handle_clear():
+    global _conversation_history, _pending_hitl_state
+    _conversation_history, _pending_hitl_state = [], None
+    return [], "", "*Waiting for a query...*", "", gr.update(visible=False)
+
+
+# ── UI ─────────────────────────────────────────────────────────────────────
+
+def build_ui():
+    with gr.Blocks(title="LangGraph Agent", css=CSS, theme=gr.themes.Soft()) as demo:
+
+        gr.Markdown("## 🤖 LangGraph Agent")
+
+        with gr.Row(equal_height=True):
+
+            # ══ Main chat ═════════════════════════════════════════════
+            with gr.Column(scale=4):
+
+                with gr.Group(elem_classes="section-box"):
+                    chatbot = gr.Chatbot(
+                        type="messages", show_label=False, height=500,
+                        container=False,
+                        placeholder="Send a message to get started.",
+                        elem_classes="chatbot-block",
+                    )
+
+                with gr.Group(visible=False, elem_classes="hitl-box") as hitl_panel:
+                    hitl_content = gr.Markdown()
+                    gr.Markdown("🔐 **Human review required** — approve or reject before the response is sent.")
+                    with gr.Row():
+                        approve_btn = gr.Button("✅ Approve", variant="primary")
+                        reject_btn  = gr.Button("❌ Reject",  variant="stop")
+
+                with gr.Group(elem_classes="section-box"):
+                    with gr.Row():
+                        user_input = gr.Textbox(
+                            placeholder="Message LangGraph Agent...",
+                            show_label=False, scale=7, lines=1, container=False,
+                        )
+                        send_btn  = gr.Button("Send", variant="primary", scale=1)
+                        clear_btn = gr.Button("🗑",    variant="secondary", scale=0, min_width=44)
+                    meta_display = gr.Markdown("")
+
+                with gr.Group(elem_classes="section-box"):
+                    gr.Examples(
+                        examples=[
+                            ["What is RAG?"], ["What is LangGraph?"],
+                            ["Calculate 25 * 48"], ["Weather in Mumbai?"],
+                            ["Tell me a joke"], ["Explain HITL"],
+                        ],
+                        inputs=user_input,
+                        label="Examples",
+                    )
+
+            # ══ Right sidebar ══════════════════════════════════════════
+            with gr.Column(scale=1):
+
+                with gr.Group(elem_classes="section-box"):
+                    gr.Markdown("**⚡ Execution Trace**")
+                    trace_display = gr.Markdown("*Waiting for a query...*")
+
+                with gr.Group(elem_classes="section-box"):
+                    gr.Markdown("""**🗺 Graph Topology**
+```
+START → router
+  ├─ rag → llm
+  └─ tool/general → llm
+       ├─ tool_executor
+       └─ memory → hitl
+            ├─ evaluation
+            │    ├─ retry → llm
+            │    └─ guardrails → output
+            └─ END
+```""")
+
+        submit_outs = [chatbot, user_input, trace_display, meta_display, hitl_panel, hitl_content]
+        send_btn.click(fn=handle_submit, inputs=[user_input, chatbot], outputs=submit_outs)
+        user_input.submit(fn=handle_submit, inputs=[user_input, chatbot], outputs=submit_outs)
+
+        hitl_outs = [chatbot, trace_display, meta_display, hitl_panel]
+        approve_btn.click(fn=handle_approve, inputs=[chatbot], outputs=hitl_outs)
+        reject_btn.click(fn=handle_reject,   inputs=[chatbot], outputs=hitl_outs)
+        clear_btn.click(fn=handle_clear, outputs=[chatbot, user_input, trace_display, meta_display, hitl_panel])
+
+    return demo
+
+
+# ── Launch ─────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    demo = build_ui()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.getenv("GRADIO_SERVER_PORT", "7860")),
+        show_error=True,
+    )

app/graph/builder.py

@@ -0,0 +1,114 @@
+"""
+app/graph/builder.py
+─────────────────────
+Assembles the LangGraph StateGraph from all nodes and edges.
+This is the only file that knows about graph topology.
+
+Graph topology:
+                    ┌──────────┐
+              ┌────►│   rag    │────┐
+              │     └──────────┘    │
+ [START] ─► router                  ▼
+              │     ┌──────────────────────────────┐
+              └────►│     llm (tool / general)     │
+                    └──────────────────────────────┘
+                         │          │
+                  tool_calls?      none
+                         │          │
+                    tool_executor   │
+                         │          │
+                         ▼          ▼
+                        memory ◄────┘
+                          │
+                         hitl ──(rejected)──► END
+                          │
+                       evaluation ──(retry)──► llm
+                          │
+                       guardrails
+                          │
+                        output
+                          │
+                         END
+"""
+
+from langgraph.graph import StateGraph, END
+from langgraph.checkpoint.memory import MemorySaver
+from app.state import AgentState
+from app.nodes import (
+    router_node, route_selector,
+    rag_node,
+    llm_node,
+    tool_executor_node,
+    memory_node,
+    hitl_node, hitl_route,
+    evaluation_node, eval_route,
+    guardrails_node,
+    output_node,
+)
+
+
+def build_graph():
+    """Compile and return the full LangGraph agent."""
+    builder = StateGraph(AgentState)
+
+    # ── Register nodes ────────────────────────────────────────────────────
+    builder.add_node("router",        router_node)
+    builder.add_node("rag",           rag_node)
+    builder.add_node("llm",           llm_node)
+    builder.add_node("tool_executor", tool_executor_node)
+    builder.add_node("memory",        memory_node)
+    builder.add_node("hitl",          hitl_node)
+    builder.add_node("evaluation",    evaluation_node)
+    builder.add_node("guardrails",    guardrails_node)
+    builder.add_node("output",        output_node)
+
+    # ── Entry point ───────────────────────────────────────────────────────
+    builder.set_entry_point("router")
+
+    # ── Conditional routing (CHECKPOINT 3) ────────────────────────────────
+    builder.add_conditional_edges(
+        "router",
+        route_selector,
+        {
+            "rag":     "rag",   # Knowledge query → retrieve then answer
+            "tool":    "llm",   # Tool query → LLM decides which tool to call
+            "general": "llm",   # Chat query → straight to LLM
+        },
+    )
+
+    # RAG retrieval feeds into the LLM node
+    builder.add_edge("rag", "llm")
+
+    # After LLM: execute tools if requested, else go straight to memory
+    builder.add_conditional_edges(
+        "llm",
+        lambda s: "tool_executor" if s.get("tool_calls") else "memory",
+        {"tool_executor": "tool_executor", "memory": "memory"},
+    )
+
+    builder.add_edge("tool_executor", "memory")
+
+    # Memory → HITL review (CHECKPOINT 6)
+    builder.add_edge("memory", "hitl")
+
+    # HITL approval gate
+    builder.add_conditional_edges(
+        "hitl",
+        hitl_route,
+        {"evaluation": "evaluation", "end": END},
+    )
+
+    # Evaluation quality gate — may loop back to LLM (CHECKPOINT 7)
+    builder.add_conditional_edges(
+        "evaluation",
+        eval_route,
+        {"retry": "llm", "guardrails": "guardrails"},
+    )
+
+    # Safety filter → final output
+    builder.add_edge("guardrails", "output")
+    builder.add_edge("output", END)
+
+    # MemorySaver persists state across invocations (CHECKPOINT 5)
+    checkpointer = MemorySaver()
+    return builder.compile(checkpointer=checkpointer)

app/nodes/__init__.py

@@ -0,0 +1,10 @@
+"""Re-export every node for clean imports in graph/builder.py."""
+from app.nodes.router import router_node, route_selector
+from app.nodes.rag import rag_node
+from app.nodes.llm_node import llm_node
+from app.nodes.tool_executor import tool_executor_node
+from app.nodes.memory import memory_node
+from app.nodes.hitl import hitl_node, hitl_route
+from app.nodes.evaluation import evaluation_node, eval_route
+from app.nodes.guardrails import guardrails_node
+from app.nodes.output import output_node

app/nodes/evaluation.py

@@ -0,0 +1,80 @@
+"""
+app/nodes/evaluation.py — CHECKPOINT 7: Evaluation
+
+Extra fix: detect LLM refusal responses and auto-pass them
+so we don't waste retries on intentional refusals.
+"""
+from langchain_core.messages import HumanMessage
+from app.state import AgentState
+from app.utils.llm import llm
+from app.config import settings
+
+# Phrases that indicate the LLM intentionally refused — don't retry these
+REFUSAL_PHRASES = [
+    "sensitive", "harmful", "hate", "threat", "negative", "i can't help with that."
+    "i cannot provide information on",
+    "i can't help", "i cannot help", "i'm unable", "i am unable",
+    "i won't", "i will not", "not able to assist", "can't assist",
+    "i'm sorry, i can't", "i'm not able", "as an ai, i cannot",
+    "i must decline", "i'm going to have to decline",
+]
+
+
+def evaluation_node(state: AgentState) -> AgentState:
+    log = state.get("node_log", [])
+    response_lower = state.get("response", "").lower()
+
+    # Tool responses are always valid — skip LLM scoring
+    if state.get("route") == "tool" or state.get("tool_results"):
+        print("[EVAL] Tool response — auto-passed.")
+        return {**state, "evaluation_score": 1.0, "node_log": log + ["evaluation (tool auto-pass ✅)"]}
+
+    # Refusal responses are intentional — don't retry, let guardrails handle
+    if any(phrase in response_lower for phrase in REFUSAL_PHRASES):
+        print("[EVAL] LLM refusal detected — auto-passed to guardrails.")
+        return {
+            **state,
+            "evaluation_score": 1.0,
+            "node_log": log + ["evaluation (refusal auto-pass → guardrails)"],
+        }
+
+    eval_prompt = f"""Rate the following AI response on a scale of 0.0 to 1.0
+    for relevance and quality relative to the query.
+    Return ONLY a float number between 0.0 and 1.0 — no other text.
+
+    Query: {state['query']}
+    Response: {state['response']}
+
+    Score:"""
+
+    try:
+        raw   = llm.invoke([HumanMessage(content=eval_prompt)]).content.strip()
+        score = max(0.0, min(1.0, float(raw)))
+    except Exception:
+        score = 0.8
+
+    current_retries = state.get("retry_count", 0)
+    below_threshold = score < settings.EVAL_THRESHOLD
+    new_retry_count = (current_retries + 1) if below_threshold else current_retries
+
+    print(f"[EVAL] Score: {score:.2f} (threshold: {settings.EVAL_THRESHOLD}, retries: {current_retries})")
+    return {
+        **state,
+        "evaluation_score": score,
+        "retry_count":      new_retry_count,
+        "node_log":         log + [f"evaluation (score={score:.2f}, retry={new_retry_count})"],
+    }
+
+
+def eval_route(state: AgentState) -> str:
+    score       = state["evaluation_score"]
+    retry_count = state.get("retry_count", 0)
+
+    if score < settings.EVAL_THRESHOLD and retry_count <= settings.MAX_RETRIES:
+        print(f"[EVAL] Score {score:.2f} below threshold — retry {retry_count}/{settings.MAX_RETRIES}")
+        return "retry"
+
+    if score < settings.EVAL_THRESHOLD:
+        print(f"[EVAL] Max retries ({settings.MAX_RETRIES}) reached — proceeding anyway.")
+
+    return "guardrails"

app/nodes/guardrails.py

@@ -0,0 +1,18 @@
+"""app/nodes/guardrails.py — CHECKPOINT 8: Guardrails"""
+from app.state import AgentState
+from app.config import settings
+
+SAFE_FALLBACK = "I'm sorry, I can't help with that request."
+
+
+def guardrails_node(state: AgentState) -> AgentState:
+    response_lower = state.get("response", "").lower()
+    triggered = [p for p in settings.BLOCKED_PHRASES if p in response_lower]
+    log = state.get("node_log", [])
+    if triggered:
+        print(f"[GUARDRAILS] ⚠️  Blocked — matched phrases: {triggered}")
+        log = log + [f"guardrails (BLOCKED: {triggered})"]
+        return {**state, "guardrail_passed": False, "response": SAFE_FALLBACK, "node_log": log}
+    print("[GUARDRAILS] ✅ Passed.")
+    log = log + ["guardrails ✅"]
+    return {**state, "guardrail_passed": True, "node_log": log}

app/nodes/hitl.py

@@ -0,0 +1,58 @@
+"""
+app/nodes/hitl.py
+──────────────────
+CHECKPOINT 6 — HUMAN-IN-THE-LOOP (HITL)
+
+Two modes:
+  • CLI mode  (HITL_ENABLED=true,  GRADIO_MODE=false) → uses input()
+  • Gradio mode (GRADIO_MODE=true)                    → stores pending response
+    in state and raises HITLPauseException so Gradio can show
+    Approve / Reject buttons and resume the graph after user clicks.
+"""
+
+from app.state import AgentState
+from app.config import settings
+
+
+class HITLPauseException(Exception):
+    """
+    Raised by hitl_node when running under Gradio.
+    Carries the pending response so the UI can display it for approval.
+    """
+    def __init__(self, pending_response: str, state: AgentState):
+        self.pending_response = pending_response
+        self.state = state
+        super().__init__("HITL approval required")
+
+
+def hitl_node(state: AgentState) -> AgentState:
+    """Show the pending response to a human and record their approval."""
+
+    # Auto-approve when HITL is disabled (CI / tests)
+    if not settings.HITL_ENABLED:
+        print("[HITL] Auto-approved (HITL_ENABLED=false).")
+        return {**state, "hitl_approved": True}
+
+    # Gradio mode — pause graph execution and let the UI handle approval
+    if settings.GRADIO_MODE:
+        raise HITLPauseException(
+            pending_response=state.get("response", ""),
+            state=state,
+        )
+
+    # CLI mode — blocking console prompt
+    print("\n" + "=" * 55)
+    print("[HITL] Agent wants to send this response:")
+    print("-" * 55)
+    print(state.get("response", "(no response yet)"))
+    print("=" * 55)
+    raw = input("[HITL] Approve? (yes/no): ").strip().lower()
+    approved = raw in ("yes", "y")
+    if not approved:
+        print("[HITL] Response rejected — stopping this turn.")
+    return {**state, "hitl_approved": approved}
+
+
+def hitl_route(state: AgentState) -> str:
+    """Conditional edge: approved → evaluation, rejected → END."""
+    return "evaluation" if state["hitl_approved"] else "end"

app/nodes/llm_node.py

@@ -0,0 +1,67 @@
+"""
+app/nodes/llm_node.py — CHECKPOINT 4: RETRIES
+
+Fix: For tool routes, only send the current query to the LLM.
+     Full history causes the LLM to re-fire tools from previous turns.
+     For rag/general routes, full clean history is fine for context.
+"""
+import time
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage, ToolMessage
+from app.state import AgentState
+from app.tools import ALL_TOOLS
+from app.utils.llm import get_llm_with_tools, llm
+from app.config import settings
+
+_llm_with_tools = get_llm_with_tools(ALL_TOOLS)
+
+
+def llm_node(state: AgentState) -> AgentState:
+    for attempt in range(1, settings.MAX_RETRIES + 1):
+        try:
+            system_parts = ["You are a helpful AI assistant."]
+            if state.get("rag_context"):
+                system_parts.append(f"\nUse the following context to answer:\n{state['rag_context']}")
+            if state.get("memory_summary"):
+                system_parts.append(f"\nPrevious conversation summary:\n{state['memory_summary']}")
+
+            system_msg = SystemMessage(content="\n".join(system_parts))
+
+            if state["route"] == "tool":
+                # Tool route: only send current query — never include history.
+                # History contains previous HumanMessages which confuse the LLM
+                # into calling tools for old queries alongside the new one.
+                messages = [system_msg, HumanMessage(content=state["query"])]
+                ai_msg = _llm_with_tools.invoke(messages)
+            else:
+                # RAG / general: full clean history gives the LLM good context
+                clean_messages = [
+                    m for m in state["messages"]
+                    if not isinstance(m, ToolMessage)
+                    and not (isinstance(m, AIMessage) and getattr(m, "tool_calls", []))
+                ]
+                messages = [system_msg] + clean_messages
+                ai_msg = llm.invoke(messages)
+
+            tool_calls    = getattr(ai_msg, "tool_calls", []) or []
+            response_text = ai_msg.content or ""
+
+            print(f"[LLM] Attempt {attempt} succeeded. Tool calls: {len(tool_calls)}")
+            print(f"[LLM] Generated Output for Usery Query ({state['query']}) : {response_text[0:200]}")
+            log = state.get("node_log", []) + [f"llm (attempt={attempt}, route={state['route']})"]
+
+            return {
+                **state,
+                "tool_calls":   tool_calls,
+                "tool_results": [],
+                "response":     response_text,
+                "node_log":     log,
+            }
+
+        except Exception as e:
+            print(f"[LLM] Attempt {attempt}/{settings.MAX_RETRIES} failed: {e}")
+            if attempt == settings.MAX_RETRIES:
+                log = state.get("node_log", []) + [f"llm (FAILED after {attempt} attempts)"]
+                return {**state, "response": "Sorry, I encountered an error.", "node_log": log}
+            time.sleep(2 ** attempt)
+
+    return state

app/nodes/memory.py

@@ -0,0 +1,67 @@
+"""
+app/nodes/memory.py — CHECKPOINT 5: Memory
+
+Fix: Sanitize memory summary — if the summary contains refusal/harmful
+context from a previous blocked query, reset it so it doesn't poison
+future innocent queries.
+"""
+from langchain_core.messages import HumanMessage, AIMessage
+from app.state import AgentState
+from app.utils.llm import llm
+
+SUMMARY_THRESHOLD = 6   # increased so memory kicks in less aggressively
+
+# If the summary contains these, it's tainted — reset it
+TAINTED_PHRASES = [
+    "illegal", "harmful", "violence", "harm", "cannot help",
+    "can't help", "i'm unable", "i cannot provide",
+]
+
+
+def _is_tainted(summary: str) -> bool:
+    low = summary.lower()
+    return any(p in low for p in TAINTED_PHRASES)
+
+
+def memory_node(state: AgentState) -> AgentState:
+    log = state.get("node_log", []) + ["memory"]
+
+    # Reset tainted memory so it doesn't bleed into future turns
+    existing_summary = state.get("memory_summary", "")
+    if existing_summary and _is_tainted(existing_summary):
+        print("[MEMORY] Tainted summary detected — resetting.")
+        return {**state, "memory_summary": "", "node_log": log}
+
+    # Only summarise clean human/assistant turns — no tool messages
+    clean = [
+        m for m in state["messages"]
+        if isinstance(m, HumanMessage)
+        or (isinstance(m, AIMessage) and not getattr(m, "tool_calls", []))
+    ]
+
+    if len(clean) < SUMMARY_THRESHOLD:
+        return {**state, "node_log": log}
+
+    recent_text = "\n".join(
+        f"{'User' if isinstance(m, HumanMessage) else 'Assistant'}: {m.content}"
+        for m in clean[-SUMMARY_THRESHOLD:]
+    )
+    prompt = (
+        "Summarise the following conversation in 2-3 sentences, "
+        "focusing only on the topics discussed and useful context. "
+        "Do NOT include any harmful, violent, or illegal content in the summary.\n\n"
+        + recent_text
+    )
+    try:
+        summary = llm.invoke([HumanMessage(content=prompt)]).content
+
+        # Double-check the generated summary is not tainted
+        if _is_tainted(summary):
+            print("[MEMORY] Generated summary was tainted — discarding.")
+            return {**state, "memory_summary": "", "node_log": log}
+
+        print("[MEMORY] Summary updated.")
+        return {**state, "memory_summary": summary, "node_log": log}
+    except Exception as e:
+        print(f"[MEMORY] Summarisation failed: {e}")
+        return {**state, "node_log": log}

app/nodes/output.py

@@ -0,0 +1,11 @@
+"""app/nodes/output.py — Final output node"""
+from langchain_core.messages import AIMessage
+from app.state import AgentState
+
+
+def output_node(state: AgentState) -> AgentState:
+    ai_message = AIMessage(content=state["response"])
+    updated_messages = state["messages"] + [ai_message]
+    log = state.get("node_log", []) + ["output"]
+    print(f"\n🤖  {state['response']}\n")
+    return {**state, "messages": updated_messages, "node_log": log}

app/nodes/rag.py

@@ -0,0 +1,18 @@
+"""
+app/nodes/rag.py
+─────────────────
+CHECKPOINT 2 — RAG node
+
+Retrieves relevant document chunks and stores them in state so the
+LLM node can inject them into its prompt.
+"""
+
+from app.state import AgentState
+from app.rag.store import retrieve_context
+
+
+def rag_node(state: AgentState) -> AgentState:
+    context = retrieve_context(state["query"])
+    print(f"[RAG] Retrieved {len(context.splitlines())} chunk(s).")
+    log = state.get("node_log", []) + ["rag"]
+    return {**state, "rag_context": context, "node_log": log}

app/nodes/router.py

@@ -0,0 +1,53 @@
+"""
+app/nodes/router.py — CHECKPOINT 3: CONDITIONAL ROUTING
+LLM-based semantic router that classifies query into rag / tool / general.
+"""
+
+import json
+from langchain_core.messages import HumanMessage
+from app.state import AgentState
+from app.tools import ALL_TOOLS
+from app.utils.llm import llm
+
+
+def router_node(state: AgentState) -> AgentState:
+    tool_descriptions = "\n".join(
+        f'- "{t.name}": {t.description}' for t in ALL_TOOLS
+    )
+    router_prompt = f"""You are a query router for an AI assistant.
+
+Available tools:
+{tool_descriptions}
+
+Knowledge base topics (for RAG):
+- LangGraph, RAG, Guardrails, HITL, Memory in AI agents, Tool calling, Conditional routing
+
+Given the user query below, decide the best route:
+  • "tool"    — if any available tool can directly answer or act on this query
+  • "rag"     — if the query asks for information that exists in the knowledge base
+  • "general" — for everything else (chit-chat, opinions, open-ended questions)
+
+Respond ONLY with valid JSON — no explanation, no markdown fences:
+{{"route": "<tool|rag|general>", "reason": "<one sentence why>"}}
+
+User query: {state["query"]}"""
+
+    try:
+        response = llm.invoke([HumanMessage(content=router_prompt)])
+        raw = response.content.strip().removeprefix("```json").removesuffix("```").strip()
+        parsed = json.loads(raw)
+        route = parsed.get("route", "general")
+        reason = parsed.get("reason", "")
+        if route not in ("rag", "tool", "general"):
+            route = "general"
+        print(f"[ROUTER] → '{route}' | {reason}")
+    except Exception as e:
+        print(f"[ROUTER] Failed ({e}), defaulting to 'general'.")
+        route = "general"
+
+    log = state.get("node_log", []) + [f"router → {route}"]
+    return {**state, "route": route, "node_log": log}
+
+
+def route_selector(state: AgentState) -> str:
+    return state["route"]

app/nodes/tool_executor.py

@@ -0,0 +1,34 @@
+"""
+app/nodes/tool_executor.py — CHECKPOINT 1: Tool execution
+
+Fix: Format tool results as natural language instead of raw key:value dump.
+"""
+from app.state import AgentState
+from app.tools import TOOL_MAP
+
+
+def tool_executor_node(state: AgentState) -> AgentState:
+    results = []
+
+    for tc in state.get("tool_calls", []):
+        tool_name = tc["name"]
+        tool_args = tc.get("args", {})
+        if tool_name in TOOL_MAP:
+            result = TOOL_MAP[tool_name].invoke(tool_args)
+            print(f"[TOOL] {tool_name}({tool_args}) → {result}")
+            results.append({"tool": tool_name, "result": result})
+        else:
+            results.append({"tool": tool_name, "result": "Tool not found."})
+
+    # Format as readable natural language instead of raw "tool: result" dump
+    if results:
+        if len(results) == 1:
+            response = str(results[0]["result"])
+        else:
+            lines = [f"- **{r['tool']}**: {r['result']}" for r in results]
+            response = "\n".join(lines)
+
+        log = state.get("node_log", []) + [f"tool_executor ({', '.join(r['tool'] for r in results)})"]
+        return {**state, "tool_results": results, "response": response, "node_log": log}
+
+    return state

app/rag/store.py

@@ -0,0 +1,55 @@
+"""
+app/rag/store.py
+─────────────────
+CHECKPOINT 2 — RAG (Retrieval-Augmented Generation)
+
+Builds a FAISS vector store from sample documents and exposes a single
+`retrieve_context(query)` function used by the RAG graph node.
+
+How RAG works:
+  1. Documents are split into chunks and embedded into vectors.
+  2. At query time the query is also embedded.
+  3. FAISS finds the chunks whose vectors are closest to the query vector.
+  4. Those chunks are injected into the LLM prompt as "context".
+"""
+
+from langchain_community.vectorstores import FAISS
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_core.documents import Document
+from app.config import settings
+
+
+# ── Sample knowledge base ─────────────────────────────────────────────────
+# Replace or extend this list with real documents / a document loader.
+SAMPLE_DOCS = [
+    Document(page_content="LangGraph is a library for building stateful, multi-actor LLM applications using graphs."),
+    Document(page_content="RAG stands for Retrieval-Augmented Generation. It combines a retriever with an LLM."),
+    Document(page_content="Guardrails are safety checks that prevent harmful or off-topic responses from AI systems."),
+    Document(page_content="Human-in-the-Loop (HITL) pauses automation so a human can review or approve an action."),
+    Document(page_content="Memory in AI agents allows them to remember past interactions within or across sessions."),
+    Document(page_content="Tool calling allows LLMs to invoke external functions like calculators or APIs."),
+    Document(page_content="Conditional routing directs a query to the most appropriate processing path."),
+]
+
+
+def build_vector_store(docs: list[Document] | None = None) -> FAISS:
+    """
+    Embed documents and load them into an in-memory FAISS index.
+    Pass custom `docs` to override the default knowledge base.
+    """
+    embeddings = HuggingFaceEmbeddings(model_name=settings.EMBEDDING_MODEL)
+    return FAISS.from_documents(docs or SAMPLE_DOCS, embeddings)
+
+
+# Build once at import time — reused across all requests
+_vector_store: FAISS = build_vector_store()
+
+
+def retrieve_context(query: str, k: int | None = None) -> str:
+    """
+    Return the top-k most relevant document chunks for `query` as plain text.
+    Each chunk is separated by a newline.
+    """
+    top_k = k or settings.RAG_TOP_K
+    results = _vector_store.similarity_search(query, k=top_k)
+    return "\n".join(doc.page_content for doc in results)

app/state.py

@@ -0,0 +1,24 @@
+"""
+app/state.py
+────────────
+AgentState is the single source of truth that flows through every graph node.
+Added `node_log` so the Gradio UI can display which nodes were visited.
+"""
+
+from typing import TypedDict, List
+
+
+class AgentState(TypedDict):
+    messages: List          # Full conversation history (HumanMessage / AIMessage)
+    query: str              # Current user query (raw string)
+    route: str              # Router decision: "rag" | "tool" | "general"
+    rag_context: str        # Retrieved document chunks (injected into LLM prompt)
+    tool_calls: list        # Tool-call objects returned by the LLM
+    tool_results: list      # Executed tool results {"tool": ..., "result": ...}
+    response: str           # Final text response to send to the user
+    retry_count: int        # How many LLM retries have happened this turn
+    hitl_approved: bool     # Did a human approve the response?
+    evaluation_score: float # LLM self-evaluation score 0.0 – 1.0
+    guardrail_passed: bool  # Did the safety filter pass?
+    memory_summary: str     # Compressed summary of older conversation turns
+    node_log: List[str]     # Ordered list of nodes visited — shown in Gradio UI

app/tools/__init__.py

@@ -0,0 +1,15 @@
+"""
+app/tools/__init__.py
+──────────────────────
+Aggregates all tools into one list.
+Add new tools here — the router and LLM binding pick them up automatically.
+"""
+
+from app.tools.calculator import calculator
+from app.tools.weather import get_weather_data
+
+# Master tool registry — every node that needs tools imports this list
+ALL_TOOLS = [calculator, get_weather_data]
+
+# Convenience map for the tool-executor node
+TOOL_MAP = {t.name: t for t in ALL_TOOLS}

app/tools/calculator.py

@@ -0,0 +1,24 @@
+"""
+app/tools/calculator.py
+────────────────────────
+CHECKPOINT 1 — TOOL CALLS (calculator)
+
+A @tool is a plain Python function decorated so the LLM can call it.
+The docstring becomes the tool description the LLM reads to decide when to use it.
+"""
+
+from langchain_core.tools import tool
+
+
+@tool
+def calculator(expression: str) -> str:
+    """
+    Evaluate a safe arithmetic expression and return the result as a string.
+    Examples: '2 + 2', '10 * 5', '(3 + 4) ** 2'
+    """
+    try:
+        # eval() with empty builtins prevents code injection
+        result = eval(expression, {"__builtins__": {}})
+        return str(result)
+    except Exception as e:
+        return f"Error evaluating expression: {e}"

app/tools/weather.py

@@ -0,0 +1,36 @@
+"""
+app/tools/weather.py
+─────────────────────
+CHECKPOINT 1 — TOOL CALLS (weather)
+
+Calls the Weatherstack API and returns current conditions for a city.
+The API key is read from settings so it never lives in code.
+"""
+
+import requests
+from langchain_core.tools import tool
+from app.config import settings
+
+
+@tool
+def get_weather_data(city: str) -> str:
+    """
+    Fetch current weather for a given city name (e.g. 'Pune', 'London').
+    Returns a summary string with temperature and conditions.
+    """
+    url = (
+        f"https://api.weatherstack.com/current"
+        f"?access_key={settings.WEATHER_API_KEY}&query={city}"
+    )
+    try:
+        data = requests.get(url, timeout=10).json()
+        if "error" in data:
+            return f"Weather API error: {data['error'].get('info', 'unknown error')}"
+        current = data.get("current", {})
+        location = data.get("location", {})
+        return (
+            f"{location.get('name')}, {location.get('country')} — "
+            f"{current.get('temperature')}°C, {', '.join(current.get('weather_descriptions', []))}"
+        )
+    except Exception as e:
+        return f"Failed to fetch weather: {e}"

app/utils/llm.py

@@ -0,0 +1,27 @@
+"""
+app/utils/llm.py
+────────────────
+LLM singleton factory.
+Import `llm` and `llm_with_tools` from here — never instantiate ChatGroq elsewhere.
+"""
+
+from langchain_groq import ChatGroq
+from app.config import settings
+
+
+def _build_llm() -> ChatGroq:
+    return ChatGroq(
+        model=settings.LLM_MODEL,
+        temperature=settings.LLM_TEMPERATURE,
+        api_key=settings.GROQ_API_KEY,
+    )
+
+
+# Plain LLM — used by router, evaluator, memory summariser
+llm = _build_llm()
+
+# Lazy-bound version with tools (tools are registered after this module loads)
+# Call get_llm_with_tools() after tools are imported.
+def get_llm_with_tools(tools: list) -> ChatGroq:
+    """Return an LLM instance with the given tools bound."""
+    return llm.bind_tools(tools)

docker-compose.yml

@@ -0,0 +1,41 @@
+services:
+
+  # ── CLI mode ──────────────────────────────────────────────────────────
+  agent:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: langgraph-agent:local
+    container_name: langgraph_agent
+    env_file: .env
+    environment:
+      - PYTHONPATH=/app
+      - GRADIO_MODE=false
+    stdin_open: true
+    tty: true
+    volumes:
+      - .:/app
+      - huggingface_cache:/root/.cache/huggingface
+    command: python main.py
+    profiles: ["cli"]
+
+  # ── Gradio UI mode ────────────────────────────────────────────────────
+  gradio:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: langgraph-agent:local
+    container_name: langgraph_gradio
+    env_file: .env
+    environment:
+      - PYTHONPATH=/app
+      - GRADIO_MODE=true
+    ports:
+      - "7860:7860"
+    volumes:
+      - .:/app
+      - huggingface_cache:/root/.cache/huggingface
+    command: python app/frontend/gradio_app.py
+
+volumes:
+  huggingface_cache:

main.py

@@ -0,0 +1,57 @@
+"""
+main.py
+────────
+Entry point — runs the CLI chat loop.
+Gradio frontend will replace this file in the next phase.
+"""
+
+from langchain_core.messages import HumanMessage
+from app.graph.builder import build_graph
+from app.state import AgentState
+
+
+def main():
+    graph = build_graph()
+    thread_config = {"configurable": {"thread_id": "session-001"}}
+    conversation_history = []
+
+    print("\n🚀  LangGraph Agent ready. Type 'quit' to exit.")
+    print("─" * 50)
+    print("Try:")
+    print("  • 'What is RAG?'              → RAG route")
+    print("  • 'Calculate 15 * 8'          → Tool route")
+    print("  • 'Weather in Pune'           → Tool route")
+    print("  • 'Tell me a joke'            → General route")
+    print("─" * 50 + "\n")
+
+    while True:
+        user_input = input("You: ").strip()
+        if not user_input:
+            continue
+        if user_input.lower() in ("quit", "exit", "q"):
+            print("Goodbye! 👋")
+            break
+
+        conversation_history.append(HumanMessage(content=user_input))
+
+        initial_state: AgentState = {
+            "messages":         conversation_history.copy(),
+            "query":            user_input,
+            "route":            "",
+            "rag_context":      "",
+            "tool_calls":       [],
+            "tool_results":     [],
+            "response":         "",
+            "retry_count":      0,
+            "hitl_approved":    False,
+            "evaluation_score": 0.0,
+            "guardrail_passed": True,
+            "memory_summary":   "",
+        }
+
+        final_state = graph.invoke(initial_state, config=thread_config)
+        conversation_history = final_state["messages"]
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,14 @@
+langgraph>=0.2.0
+langchain>=0.3.0
+langchain-core>=0.3.0
+langchain-groq>=0.2.0
+langchain-community>=0.3.0
+langchain-huggingface>=0.1.0
+faiss-cpu>=1.7.4
+sentence-transformers>=3.0.0
+requests>=2.31.0
+python-dotenv>=1.0.0
+gradio==5.23.0
+# CPU-only torch
+--extra-index-url https://download.pytorch.org/whl/cpu
+torch

tests/test_nodes.py

@@ -0,0 +1,73 @@
+"""
+tests/test_nodes.py
+────────────────────
+Unit tests for individual nodes using a mock LLM so no API key is needed.
+Run with: pytest tests/
+"""
+
+import pytest
+from unittest.mock import patch, MagicMock
+from langchain_core.messages import HumanMessage, AIMessage
+
+from app.state import AgentState
+from app.nodes.guardrails import guardrails_node
+from app.nodes.output import output_node
+from app.tools.calculator import calculator
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────
+
+def make_state(**overrides) -> AgentState:
+    base: AgentState = {
+        "messages": [],
+        "query": "test query",
+        "route": "general",
+        "rag_context": "",
+        "tool_calls": [],
+        "tool_results": [],
+        "response": "Hello!",
+        "retry_count": 0,
+        "hitl_approved": True,
+        "evaluation_score": 0.8,
+        "guardrail_passed": True,
+        "memory_summary": "",
+    }
+    return {**base, **overrides}
+
+
+# ── Calculator tool ───────────────────────────────────────────────────────
+
+def test_calculator_basic():
+    assert calculator.invoke({"expression": "2 + 2"}) == "4"
+
+def test_calculator_complex():
+    assert calculator.invoke({"expression": "10 * 5 - 3"}) == "47"
+
+def test_calculator_bad_input():
+    result = calculator.invoke({"expression": "import os"})
+    assert "Error" in result
+
+
+# ── Guardrails node ───────────────────────────────────────────────────────
+
+def test_guardrails_passes_clean_response():
+    state = make_state(response="The weather in Pune is sunny today.")
+    result = guardrails_node(state)
+    assert result["guardrail_passed"] is True
+    assert result["response"] == "The weather in Pune is sunny today."
+
+def test_guardrails_blocks_harmful_response():
+    state = make_state(response="Here is how to cause harm to someone...")
+    result = guardrails_node(state)
+    assert result["guardrail_passed"] is False
+    assert "can't help" in result["response"]
+
+
+# ── Output node ───────────────────────────────────────────────────────────
+
+def test_output_node_appends_message():
+    state = make_state(messages=[HumanMessage(content="Hi")], response="Hello!")
+    result = output_node(state)
+    assert len(result["messages"]) == 2
+    assert isinstance(result["messages"][-1], AIMessage)
+    assert result["messages"][-1].content == "Hello!"