Skip to content

GenAI POC (LangChain & LangGraph)

8 runnable scripts: LLM calls, RAG, LangGraph agents, multi-agent.

Source folder: /home/runner/work/offerready/offerready/personal-docs/genai-poc

Overview

GenAI POC - LangChain & LangGraph Learning

Last reviewed: October 2026

Hands-on POC examples for learning LLM calls, LangChain, and LangGraph.

Pinned to 2024 library versions

requirements.txt pins LangChain 0.2 / LangGraph 0.2, so the scripts use APIs from that era (for example langgraph.prebuilt.create_react_agent). They still teach the concepts, but current LangChain 1.x code uses create_agent with middleware, and legacy chains/memory moved to langchain-classic. Install the pinned versions in a fresh virtual environment; don't mix them with 1.x.

Setup

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.venv\Scripts\activate

# Activate (macOS / Linux)
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Configuration

Copy .env.example to .env and fill in your API keys (never commit .env):

copy .env.example .env      # Windows
cp .env.example .env        # macOS / Linux

07_tool_calling_agent.py also reads SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER, SNOWFLAKE_PASSWORD, SNOWFLAKE_WAREHOUSE and SNOWFLAKE_DATABASE, which are not in .env.example; add them yourself. Use a read-only role, and note that Snowflake is phasing out password-only sign-in, so you may need key-pair auth or a programmatic access token instead of a password.

Phase 1 - Foundations

File Description
01_basic_llm_call.py Direct LLM calls with OpenAI and Azure OpenAI
02_langchain_chat.py Chat assistant with conversation memory
03_langchain_rag.py RAG (Retrieval Augmented Generation) basics
04_langgraph_agent.py Stateful agent with tools using LangGraph

Phase 2 - Advanced Patterns

File Description
05_streamlit_chat_ui.py Web-based chat UI with streaming
06_multi_agent_system.py Supervisor + workers, debate/critique patterns
07_tool_calling_agent.py Agent that queries Snowflake and calls APIs
08_document_qa.py Upload docs and ask questions (RAG app)

Running

# Phase 1
python 01_basic_llm_call.py
python 02_langchain_chat.py
python 03_langchain_rag.py
python 04_langgraph_agent.py

# Phase 2
streamlit run 05_streamlit_chat_ui.py
python 06_multi_agent_system.py
python 07_tool_calling_agent.py
python 08_document_qa.py

Source files

Each script below is shown inline — read it here or copy it with the button in the top-right of the block.

.env.example

.env.example
# Choose one: OpenAI or Azure OpenAI

# --- OpenAI ---
OPENAI_API_KEY=sk-your-key-here

# --- Azure OpenAI ---
AZURE_OPENAI_API_KEY=your-azure-key-here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
AZURE_OPENAI_API_VERSION=2024-06-01

01_basic_llm_call.py

01_basic_llm_call.py
"""
01 - Basic LLM Calls
====================
Learn how to make direct calls to OpenAI and Azure OpenAI models.
This is the foundation for everything else.
"""

import os
from dotenv import load_dotenv

load_dotenv()

# ============================================================
# Example 1: Basic OpenAI call using the openai library directly
# ============================================================

def basic_openai_call():
    """Direct call to OpenAI API - the simplest way to talk to an LLM."""
    from openai import OpenAI

    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "What is retrieval-augmented generation?"},
        ],
        temperature=0.7,
        max_tokens=200,
    )

    print("=== Basic OpenAI Call ===")
    print(response.choices[0].message.content)
    print(f"\nTokens used: {response.usage.total_tokens}")
    return response


# ============================================================
# Example 2: Azure OpenAI call
# ============================================================

def azure_openai_call():
    """Call Azure OpenAI - same interface, enterprise-grade hosting."""
    from openai import AzureOpenAI

    client = AzureOpenAI(
        api_key=os.getenv("AZURE_OPENAI_API_KEY"),
        api_version=os.getenv("AZURE_OPENAI_API_VERSION", "2024-06-01"),
        azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    )

    response = client.chat.completions.create(
        model=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME", "gpt-4o"),
        messages=[
            {"role": "system", "content": "You are a helpful energy industry assistant."},
            {"role": "user", "content": "Explain renewable energy certificates (RECs) in 2 sentences."},
        ],
        temperature=0.3,
    )

    print("\n=== Azure OpenAI Call ===")
    print(response.choices[0].message.content)
    return response


# ============================================================
# Example 3: Using LangChain's ChatOpenAI wrapper
# ============================================================

def langchain_llm_call():
    """
    LangChain wraps the OpenAI client with extra features:
    - Automatic retries
    - Streaming support
    - Prompt templates
    - Output parsing
    """
    from langchain_openai import ChatOpenAI
    from langchain_core.messages import HumanMessage, SystemMessage

    # Initialize the LLM
    llm = ChatOpenAI(
        model="gpt-4o",
        temperature=0.7,
        max_tokens=200,
    )

    # Simple invocation
    messages = [
        SystemMessage(content="You are a concise technical assistant."),
        HumanMessage(content="What is LangChain and why would I use it?"),
    ]

    response = llm.invoke(messages)

    print("\n=== LangChain LLM Call ===")
    print(response.content)
    print(f"\nMetadata: {response.response_metadata}")
    return response


# ============================================================
# Example 4: Prompt Templates - reusable prompt patterns
# ============================================================

def prompt_template_example():
    """Prompt templates let you parameterize prompts for reuse."""
    from langchain_openai import ChatOpenAI
    from langchain_core.prompts import ChatPromptTemplate

    llm = ChatOpenAI(model="gpt-4o", temperature=0.5)

    # Create a reusable template
    template = ChatPromptTemplate.from_messages([
        ("system", "You are an expert in {domain}. Be concise."),
        ("human", "{question}"),
    ])

    # Chain the template with the LLM (this is a "chain")
    chain = template | llm

    # Use it with different inputs
    response = chain.invoke({
        "domain": "electric utilities",
        "question": "What is demand response?",
    })

    print("\n=== Prompt Template Example ===")
    print(response.content)

    # Same template, different inputs
    response2 = chain.invoke({
        "domain": "data engineering",
        "question": "What is a slowly changing dimension?",
    })

    print("\n=== Same Template, Different Domain ===")
    print(response2.content)
    return response


# ============================================================
# Example 5: Streaming responses
# ============================================================

def streaming_example():
    """Stream tokens as they're generated - better UX for chat apps."""
    from langchain_openai import ChatOpenAI
    from langchain_core.messages import HumanMessage

    llm = ChatOpenAI(model="gpt-4o", temperature=0.7, streaming=True)

    print("\n=== Streaming Example ===")
    for chunk in llm.stream([HumanMessage(content="Write a haiku about electricity.")]):
        print(chunk.content, end="", flush=True)
    print()  # newline at end


# ============================================================
# Run all examples
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  BASIC LLM CALLS - Learning the Fundamentals")
    print("=" * 60)

    # Uncomment the examples you want to run:

    # Requires OPENAI_API_KEY
    # basic_openai_call()

    # Requires Azure OpenAI credentials
    # azure_openai_call()

    # Requires OPENAI_API_KEY (uses LangChain wrapper)
    langchain_llm_call()
    prompt_template_example()
    streaming_example()

02_langchain_chat.py

02_langchain_chat.py
"""
02 - LangChain Chat Assistant with Memory
==========================================
Build a conversational assistant that remembers context across messages.
This is the core pattern for any chatbot/assistant application.
"""

import os
from dotenv import load_dotenv

load_dotenv()

# ============================================================
# Example 1: Chat with in-memory conversation history
# ============================================================

def chat_with_memory():
    """
    A chat assistant that maintains conversation history.

    Key concepts:
    - ChatMessageHistory: stores messages in memory
    - RunnableWithMessageHistory: wraps a chain to auto-manage history
    """
    from langchain_openai import ChatOpenAI
    from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
    from langchain_core.chat_history import InMemoryChatMessageHistory
    from langchain_core.runnables.history import RunnableWithMessageHistory

    llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

    # Define the prompt with a placeholder for conversation history
    prompt = ChatPromptTemplate.from_messages([
        ("system", """You are a helpful assistant for enterprise employees. 
You help with questions about energy, data engineering, and general topics.
Be friendly and concise."""),
        MessagesPlaceholder(variable_name="history"),
        ("human", "{input}"),
    ])

    # Create the chain
    chain = prompt | llm

    # Store for session histories (in production, use Redis/DB)
    session_store = {}

    def get_session_history(session_id: str):
        if session_id not in session_store:
            session_store[session_id] = InMemoryChatMessageHistory()
        return session_store[session_id]

    # Wrap the chain with message history management
    chat_with_history = RunnableWithMessageHistory(
        chain,
        get_session_history,
        input_messages_key="input",
        history_messages_key="history",
    )

    # Simulate a conversation
    print("=== Chat with Memory ===")
    print("(The assistant remembers previous messages)\n")

    config = {"configurable": {"session_id": "user-123"}}

    # Turn 1
    response1 = chat_with_history.invoke(
        {"input": "Hi! My name is Alex and I work in the data engineering team."},
        config=config,
    )
    print(f"User: Hi! My name is Alex and I work in the data engineering team.")
    print(f"Assistant: {response1.content}\n")

    # Turn 2 - the assistant should remember the name
    response2 = chat_with_history.invoke(
        {"input": "What are some good Python libraries for ETL pipelines?"},
        config=config,
    )
    print(f"User: What are some good Python libraries for ETL pipelines?")
    print(f"Assistant: {response2.content}\n")

    # Turn 3 - the assistant should still know the context
    response3 = chat_with_history.invoke(
        {"input": "Which of those would you recommend for someone on my team?"},
        config=config,
    )
    print(f"User: Which of those would you recommend for someone on my team?")
    print(f"Assistant: {response3.content}\n")

    return chat_with_history


# ============================================================
# Example 2: Interactive chat loop
# ============================================================

def interactive_chat():
    """
    Run an interactive chat session in the terminal.
    Type 'quit' to exit.
    """
    from langchain_openai import ChatOpenAI
    from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
    from langchain_core.chat_history import InMemoryChatMessageHistory
    from langchain_core.runnables.history import RunnableWithMessageHistory

    llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

    prompt = ChatPromptTemplate.from_messages([
        ("system", """You are a knowledgeable assistant that helps with:
- Data engineering questions (Snowflake, Python, ETL)
- Cloud services (AWS, Azure)
- Energy industry concepts
- General programming help

Be concise but thorough. Ask clarifying questions when needed."""),
        MessagesPlaceholder(variable_name="history"),
        ("human", "{input}"),
    ])

    chain = prompt | llm
    history = InMemoryChatMessageHistory()

    chat = RunnableWithMessageHistory(
        chain,
        lambda _: history,
        input_messages_key="input",
        history_messages_key="history",
    )

    config = {"configurable": {"session_id": "interactive"}}

    print("\n" + "=" * 60)
    print("  Interactive Chat Assistant")
    print("  Type 'quit' to exit, 'clear' to reset history")
    print("=" * 60 + "\n")

    while True:
        user_input = input("You: ").strip()

        if user_input.lower() == "quit":
            print("Goodbye!")
            break
        elif user_input.lower() == "clear":
            history.clear()
            print("(History cleared)\n")
            continue
        elif not user_input:
            continue

        response = chat.invoke({"input": user_input}, config=config)
        print(f"Assistant: {response.content}\n")


# ============================================================
# Example 3: Chat with structured output
# ============================================================

def chat_with_structured_output():
    """
    Get structured (JSON) responses from the LLM.
    Useful for extracting data from conversations.
    """
    from langchain_openai import ChatOpenAI
    from langchain_core.prompts import ChatPromptTemplate
    from pydantic import BaseModel, Field

    llm = ChatOpenAI(model="gpt-4o", temperature=0)

    # Define the output structure
    class TaskExtraction(BaseModel):
        """Extract task details from a user message."""
        task_description: str = Field(description="What needs to be done")
        priority: str = Field(description="high, medium, or low")
        category: str = Field(description="Category: data, code, infrastructure, or other")
        estimated_hours: float = Field(description="Rough estimate in hours")

    # Bind the structure to the LLM
    structured_llm = llm.with_structured_output(TaskExtraction)

    prompt = ChatPromptTemplate.from_messages([
        ("system", "Extract task details from the user's message."),
        ("human", "{input}"),
    ])

    chain = prompt | structured_llm

    # Test it
    print("\n=== Structured Output Example ===")

    tasks = [
        "I need to build a new Snowflake pipeline for the billing data by Friday",
        "Can someone fix the typo in the README? It's not urgent.",
        "We need to migrate the Lambda functions to use Python 3.12 runtime ASAP",
    ]

    for task in tasks:
        result = chain.invoke({"input": task})
        print(f"\nInput: {task}")
        print(f"  Task: {result.task_description}")
        print(f"  Priority: {result.priority}")
        print(f"  Category: {result.category}")
        print(f"  Est. Hours: {result.estimated_hours}")


# ============================================================
# Run examples
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  LANGCHAIN CHAT ASSISTANT")
    print("=" * 60)

    # Run the memory demo
    chat_with_memory()

    # Run structured output demo
    chat_with_structured_output()

    # Uncomment for interactive mode:
    # interactive_chat()

03_langchain_rag.py

03_langchain_rag.py
"""
03 - RAG (Retrieval Augmented Generation)
==========================================
Ground LLM responses in your own documents/data.
This is how you build assistants that "know" about your internal docs.
"""

import os
from dotenv import load_dotenv

load_dotenv()

# ============================================================
# Example 1: Simple RAG with in-memory vector store
# ============================================================

def simple_rag():
    """
    Basic RAG pipeline:
    1. Load documents
    2. Split into chunks
    3. Create embeddings and store in vector DB
    4. Query: retrieve relevant chunks + send to LLM
    """
    from langchain_openai import ChatOpenAI, OpenAIEmbeddings
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_core.output_parsers import StrOutputParser
    from langchain_core.runnables import RunnablePassthrough
    from langchain_community.vectorstores import FAISS
    from langchain_text_splitters import RecursiveCharacterTextSplitter

    # --- Step 1: Prepare sample documents ---
    # In production, these would come from files, databases, APIs, etc.
    documents = [
        """An electric utility provides power to residential and commercial customers
        across a service territory. Utilities generate electricity from diverse sources
        including wind, solar, natural gas, and hydroelectric power.""",

        """A typical data engineering team uses Snowflake as their cloud data warehouse.
        They build ETL pipelines using AWS Lambda, Python, and various orchestration tools.
        Data flows from source systems through S3 into Snowflake for analytics.""",

        """Renewable Energy Certificates (RECs) represent the environmental attributes of
        one megawatt-hour of renewable electricity generation. Utilities use RECs
        to demonstrate compliance with Renewable Portfolio Standards (RPS).""",

        """AWS Lambda is a serverless compute service that runs code in response to events.
        Teams use Lambda functions for ETL processing, triggered by S3 events or scheduled
        via EventBridge. Functions are written in Python and deployed via CloudFormation.""",

        """LangChain is a framework for building applications with large language models.
        It provides tools for prompt management, memory, chains, and agents.
        LangGraph extends LangChain with graph-based workflow orchestration.""",

        """Snowflake best practices include: use appropriate warehouse sizes, implement
        clustering keys for large tables, use materialized views for complex queries,
        and leverage Snowpipe for real-time data ingestion.""",
    ]

    # --- Step 2: Split documents into chunks ---
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=300,
        chunk_overlap=50,
    )
    chunks = text_splitter.create_documents(documents)
    print(f"Split {len(documents)} documents into {len(chunks)} chunks")

    # --- Step 3: Create embeddings and vector store ---
    embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
    vectorstore = FAISS.from_documents(chunks, embeddings)

    # Create a retriever (returns top 3 most relevant chunks)
    retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

    # --- Step 4: Build the RAG chain ---
    llm = ChatOpenAI(model="gpt-4o", temperature=0.3)

    prompt = ChatPromptTemplate.from_messages([
        ("system", """Answer the question based on the provided context. 
If the context doesn't contain enough information, say so.
Be concise and specific.

Context:
{context}"""),
        ("human", "{question}"),
    ])

    def format_docs(docs):
        return "\n\n".join(doc.page_content for doc in docs)

    # The RAG chain: retrieve docs -> format -> prompt -> LLM -> parse
    rag_chain = (
        {"context": retriever | format_docs, "question": RunnablePassthrough()}
        | prompt
        | llm
        | StrOutputParser()
    )

    # --- Step 5: Ask questions ---
    print("\n=== RAG Q&A ===\n")

    questions = [
        "What data warehouse does the org use?",
        "How are Lambda functions deployed?",
        "What is a REC?",
        "What are Snowflake best practices?",
    ]

    for q in questions:
        answer = rag_chain.invoke(q)
        print(f"Q: {q}")
        print(f"A: {answer}\n")

    return rag_chain, vectorstore


# ============================================================
# Example 2: RAG with source citations
# ============================================================

def rag_with_citations():
    """
    Enhanced RAG that shows which documents were used to answer.
    Important for trust and verification.
    """
    from langchain_openai import ChatOpenAI, OpenAIEmbeddings
    from langchain_core.prompts import ChatPromptTemplate
    from langchain_community.vectorstores import FAISS
    from langchain_text_splitters import RecursiveCharacterTextSplitter
    from pydantic import BaseModel, Field

    # Sample docs with metadata (source tracking)
    from langchain_core.documents import Document

    docs_with_sources = [
        Document(
            page_content="The org uses Snowflake for data warehousing and analytics.",
            metadata={"source": "data-architecture.md", "section": "Infrastructure"},
        ),
        Document(
            page_content="ETL pipelines are built with Python Lambda functions on AWS.",
            metadata={"source": "etl-guide.md", "section": "Pipeline Design"},
        ),
        Document(
            page_content="LangGraph uses a graph-based state machine for agent workflows.",
            metadata={"source": "genai-notes.md", "section": "Frameworks"},
        ),
    ]

    embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
    vectorstore = FAISS.from_documents(docs_with_sources, embeddings)
    retriever = vectorstore.as_retriever(search_kwargs={"k": 2})

    # Structured output for citations
    class AnswerWithSources(BaseModel):
        answer: str = Field(description="The answer to the question")
        sources: list[str] = Field(description="List of source documents used")
        confidence: str = Field(description="high, medium, or low")

    llm = ChatOpenAI(model="gpt-4o", temperature=0).with_structured_output(AnswerWithSources)

    print("\n=== RAG with Citations ===\n")

    # Retrieve and answer
    question = "What tools does the org use for data pipelines?"
    docs = retriever.invoke(question)

    context = "\n".join(
        f"[Source: {d.metadata['source']}] {d.page_content}" for d in docs
    )

    prompt = ChatPromptTemplate.from_messages([
        ("system", "Answer based on the context. Cite your sources.\n\nContext:\n{context}"),
        ("human", "{question}"),
    ])

    chain = prompt | llm
    result = chain.invoke({"context": context, "question": question})

    print(f"Q: {question}")
    print(f"A: {result.answer}")
    print(f"Sources: {result.sources}")
    print(f"Confidence: {result.confidence}")


# ============================================================
# Run examples
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  RAG - Retrieval Augmented Generation")
    print("=" * 60)

    simple_rag()
    rag_with_citations()

04_langgraph_agent.py

04_langgraph_agent.py
"""
04 - LangGraph Agent
====================
Build a stateful agent with tools using LangGraph.
This is the most powerful pattern - an LLM that can reason, use tools, 
and maintain complex state across interactions.
"""

import os
from dotenv import load_dotenv

load_dotenv()

# ============================================================
# Example 1: Simple ReAct Agent with Tools
# ============================================================

def simple_agent():
    """
    A ReAct agent that can use tools to answer questions.

    ReAct pattern: Reason → Act → Observe → Repeat

    LangGraph models this as a graph:
    - Nodes: steps in the workflow (call LLM, execute tool)
    - Edges: transitions between steps
    - State: shared data that flows through the graph
    """
    from langchain_openai import ChatOpenAI
    from langchain_core.tools import tool
    from langgraph.prebuilt import create_react_agent

    # --- Define tools the agent can use ---

    @tool
    def get_weather(city: str) -> str:
        """Get the current weather for a city."""
        # Mock implementation - in production, call a real API
        weather_data = {
            "portland": "72°F, partly cloudy, wind 8mph NW",
            "seattle": "65°F, overcast, wind 12mph W",
            "san francisco": "68°F, foggy, wind 15mph W",
        }
        return weather_data.get(city.lower(), f"Weather data not available for {city}")

    @tool
    def calculate_energy_cost(kwh: float, rate: float = 0.12) -> str:
        """Calculate electricity cost given usage in kWh and rate per kWh."""
        cost = kwh * rate
        return f"{kwh} kWh at ${rate}/kWh = ${cost:.2f}"

    @tool
    def search_documentation(query: str) -> str:
        """Search internal documentation for relevant information."""
        # Mock - in production, this would search your actual docs
        docs = {
            "snowflake": "Snowflake is our cloud data warehouse. Connect via account: myorg.us-west-2",
            "lambda": "Lambda functions are deployed via CloudFormation. Runtime: Python 3.11",
            "etl": "ETL pipelines run on schedule via EventBridge. Logs in CloudWatch.",
            "langgraph": "LangGraph builds stateful agents with graph-based workflows.",
        }
        for key, value in docs.items():
            if key in query.lower():
                return value
        return "No documentation found for that query."

    # --- Create the agent ---
    llm = ChatOpenAI(model="gpt-4o", temperature=0)

    agent = create_react_agent(
        llm,
        tools=[get_weather, calculate_energy_cost, search_documentation],
        state_modifier="""You are a helpful assistant for enterprise employees.
You have access to tools for weather, energy calculations, and documentation search.
Always use tools when they can help answer a question.
Be concise in your final answers.""",
    )

    # --- Run the agent ---
    print("=== LangGraph ReAct Agent ===\n")

    queries = [
        "What's the weather like in Portland?",
        "How much would 500 kWh of electricity cost at the standard rate?",
        "What do we use for our data warehouse?",
        "What's the weather in Portland and how much would it cost to run AC for 8 hours at 2kW?",
    ]

    for query in queries:
        print(f"User: {query}")
        result = agent.invoke({"messages": [("human", query)]})
        # Get the last AI message
        final_message = result["messages"][-1]
        print(f"Agent: {final_message.content}\n")

    return agent


# ============================================================
# Example 2: Custom LangGraph workflow (multi-step agent)
# ============================================================

def custom_graph_agent():
    """
    Build a custom graph for a multi-step workflow:
    1. Classify the user's intent
    2. Route to appropriate handler
    3. Generate response

    This shows the power of LangGraph for complex workflows.
    """
    from langchain_openai import ChatOpenAI
    from langchain_core.messages import HumanMessage, AIMessage
    from langgraph.graph import StateGraph, MessagesState, START, END

    llm = ChatOpenAI(model="gpt-4o", temperature=0)

    # --- Define the graph nodes ---

    def classify_intent(state: MessagesState):
        """Classify what the user wants."""
        messages = state["messages"]
        last_message = messages[-1].content

        classification_prompt = f"""Classify this message into one category:
- TECHNICAL: coding, data, infrastructure questions
- GENERAL: general knowledge, weather, small talk
- TASK: requests to do something specific

Message: {last_message}

Respond with just the category name."""

        response = llm.invoke([HumanMessage(content=classification_prompt)])
        category = response.content.strip().upper()

        # Store classification in state by adding a system-like message
        return {"messages": [AIMessage(content=f"[CLASSIFIED: {category}]")]}

    def handle_technical(state: MessagesState):
        """Handle technical questions with detailed responses."""
        messages = state["messages"]
        # Find the original user message (skip classification)
        user_msg = next(m for m in messages if isinstance(m, HumanMessage))

        response = llm.invoke([
            HumanMessage(content=f"""You are a senior data engineer. 
Answer this technical question thoroughly but concisely.
Include code examples if relevant.

Question: {user_msg.content}""")
        ])
        return {"messages": [response]}

    def handle_general(state: MessagesState):
        """Handle general questions casually."""
        messages = state["messages"]
        user_msg = next(m for m in messages if isinstance(m, HumanMessage))

        response = llm.invoke([
            HumanMessage(content=f"""Answer this casually and briefly: {user_msg.content}""")
        ])
        return {"messages": [response]}

    def handle_task(state: MessagesState):
        """Handle task requests with action items."""
        messages = state["messages"]
        user_msg = next(m for m in messages if isinstance(m, HumanMessage))

        response = llm.invoke([
            HumanMessage(content=f"""The user wants to do something. 
Break it into clear action items.

Request: {user_msg.content}""")
        ])
        return {"messages": [response]}

    # --- Define routing logic ---

    def route_by_intent(state: MessagesState):
        """Route to the right handler based on classification."""
        messages = state["messages"]
        # Find the classification message
        for msg in reversed(messages):
            if isinstance(msg, AIMessage) and "[CLASSIFIED:" in msg.content:
                if "TECHNICAL" in msg.content:
                    return "handle_technical"
                elif "TASK" in msg.content:
                    return "handle_task"
                else:
                    return "handle_general"
        return "handle_general"

    # --- Build the graph ---
    workflow = StateGraph(MessagesState)

    # Add nodes
    workflow.add_node("classify", classify_intent)
    workflow.add_node("handle_technical", handle_technical)
    workflow.add_node("handle_general", handle_general)
    workflow.add_node("handle_task", handle_task)

    # Add edges
    workflow.add_edge(START, "classify")
    workflow.add_conditional_edges("classify", route_by_intent)
    workflow.add_edge("handle_technical", END)
    workflow.add_edge("handle_general", END)
    workflow.add_edge("handle_task", END)

    # Compile
    app = workflow.compile()

    # --- Test the workflow ---
    print("\n=== Custom LangGraph Workflow ===\n")

    test_messages = [
        "How do I optimize a Snowflake query with clustering keys?",
        "What's a good restaurant in Portland?",
        "I need to set up a new ETL pipeline for billing data",
    ]

    for msg in test_messages:
        print(f"User: {msg}")
        result = app.invoke({"messages": [HumanMessage(content=msg)]})
        # Get the final response (last AI message that isn't classification)
        final = [m for m in result["messages"] if isinstance(m, AIMessage) and "[CLASSIFIED:" not in m.content]
        if final:
            print(f"Agent: {final[-1].content}\n")
        print("-" * 40 + "\n")

    return app


# ============================================================
# Example 3: Agent with persistent memory (conversation)
# ============================================================

def agent_with_memory():
    """
    LangGraph agent that maintains conversation history across invocations.
    Uses checkpointing for state persistence.
    """
    from langchain_openai import ChatOpenAI
    from langchain_core.tools import tool
    from langgraph.prebuilt import create_react_agent
    from langgraph.checkpoint.memory import MemorySaver

    @tool
    def note_taker(note: str) -> str:
        """Save a note for later reference."""
        return f"Note saved: {note}"

    llm = ChatOpenAI(model="gpt-4o", temperature=0.5)

    # MemorySaver keeps state in memory (use SqliteSaver for persistence)
    memory = MemorySaver()

    agent = create_react_agent(
        llm,
        tools=[note_taker],
        checkpointer=memory,
        state_modifier="You are a helpful assistant. Remember previous conversations.",
    )

    # Thread ID groups messages into a conversation
    config = {"configurable": {"thread_id": "session-1"}}

    print("\n=== Agent with Memory ===\n")

    # Multi-turn conversation
    conversations = [
        "Hi, I'm working on the NEMA project. Can you remember that?",
        "Save a note: need to review the CDC lambda handler this week",
        "What project am I working on?",
    ]

    for msg in conversations:
        print(f"User: {msg}")
        result = agent.invoke({"messages": [("human", msg)]}, config=config)
        print(f"Agent: {result['messages'][-1].content}\n")


# ============================================================
# Run examples
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  LANGGRAPH AGENTS")
    print("=" * 60)

    simple_agent()
    custom_graph_agent()
    agent_with_memory()

05_streamlit_chat_ui.py

05_streamlit_chat_ui.py
"""
05 - Streamlit Chat UI
======================
A web-based chat interface for your LangChain assistant.
Run with: streamlit run 05_streamlit_chat_ui.py
"""

import os
import streamlit as st
from dotenv import load_dotenv

load_dotenv()

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.messages import HumanMessage, AIMessage


# --- Page config ---
st.set_page_config(
    page_title="GenAI Assistant",
    page_icon="⚡",
    layout="centered",
)

st.title("⚡ GenAI Assistant")
st.caption("Powered by LangChain + OpenAI | Learning POC")


# --- Initialize session state ---
if "messages" not in st.session_state:
    st.session_state.messages = []

if "llm" not in st.session_state:
    st.session_state.llm = ChatOpenAI(
        model="gpt-4o",
        temperature=0.7,
        streaming=True,
    )


# --- Sidebar settings ---
with st.sidebar:
    st.header("⚙️ Settings")

    system_prompt = st.text_area(
        "System Prompt",
        value="""You are a helpful assistant for enterprise employees.
You help with:
- Data engineering (Snowflake, Python, ETL, AWS)
- Energy industry concepts
- General programming questions
- GenAI/LLM concepts

Be concise, friendly, and technical when needed.""",
        height=200,
    )

    temperature = st.slider("Temperature", 0.0, 1.0, 0.7, 0.1)
    max_tokens = st.slider("Max Tokens", 100, 4000, 1000, 100)

    if st.button("🗑️ Clear Chat"):
        st.session_state.messages = []
        st.rerun()

    st.divider()
    st.markdown("### Quick Prompts")
    quick_prompts = [
        "Explain RAG in simple terms",
        "How do LangGraph agents work?",
        "Snowflake optimization tips",
        "Compare LangChain vs LangGraph",
    ]
    for qp in quick_prompts:
        if st.button(qp, key=f"qp_{qp}"):
            st.session_state.pending_prompt = qp
            st.rerun()


# --- Display chat history ---
for msg in st.session_state.messages:
    with st.chat_message(msg["role"]):
        st.markdown(msg["content"])


# --- Handle input ---
# Check for pending quick prompt
user_input = None
if "pending_prompt" in st.session_state:
    user_input = st.session_state.pending_prompt
    del st.session_state.pending_prompt
else:
    user_input = st.chat_input("Ask me anything...")

if user_input:
    # Display user message
    st.session_state.messages.append({"role": "user", "content": user_input})
    with st.chat_message("user"):
        st.markdown(user_input)

    # Build the prompt with history
    prompt = ChatPromptTemplate.from_messages([
        ("system", system_prompt),
        MessagesPlaceholder(variable_name="history"),
        ("human", "{input}"),
    ])

    # Convert session messages to LangChain format
    history = []
    for msg in st.session_state.messages[:-1]:  # exclude current
        if msg["role"] == "user":
            history.append(HumanMessage(content=msg["content"]))
        else:
            history.append(AIMessage(content=msg["content"]))

    # Create chain with current settings
    llm = ChatOpenAI(
        model="gpt-4o",
        temperature=temperature,
        max_tokens=max_tokens,
        streaming=True,
    )
    chain = prompt | llm

    # Stream the response
    with st.chat_message("assistant"):
        response_placeholder = st.empty()
        full_response = ""

        for chunk in chain.stream({"input": user_input, "history": history}):
            full_response += chunk.content
            response_placeholder.markdown(full_response + "▌")

        response_placeholder.markdown(full_response)

    # Save assistant response
    st.session_state.messages.append({"role": "assistant", "content": full_response})

06_multi_agent_system.py

06_multi_agent_system.py
"""
06 - Multi-Agent System
=======================
Multiple specialized agents that collaborate to solve complex tasks.
Pattern: Supervisor routes work to specialized workers.
"""

import os
from dotenv import load_dotenv

load_dotenv()

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
from langchain_core.tools import tool
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import create_react_agent


# ============================================================
# Example 1: Supervisor + Workers Pattern
# ============================================================

def supervisor_agent_system():
    """
    Architecture:
    - Supervisor: decides which worker should handle the task
    - Researcher: finds information and context
    - Writer: produces polished output
    - Coder: writes code solutions

    The supervisor orchestrates the flow between workers.
    """
    from pydantic import BaseModel, Field
    from typing import Literal

    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    creative_llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

    # --- Define routing schema ---
    class RouteDecision(BaseModel):
        """Supervisor's routing decision."""
        next_worker: Literal["researcher", "writer", "coder", "FINISH"] = Field(
            description="Which worker should handle this next, or FINISH if done"
        )
        instructions: str = Field(
            description="Specific instructions for the next worker"
        )

    # --- Worker definitions ---
    def make_researcher_node():
        """Researcher gathers information and provides context."""

        @tool
        def search_knowledge_base(query: str) -> str:
            """Search the internal knowledge base for relevant information."""
            # Mock knowledge base
            kb = {
                "snowflake": "The org uses Snowflake Enterprise on AWS us-west-2. Key databases: RAW, STAGING, ANALYTICS. Warehouses: ETL_WH (XL), ANALYTICS_WH (L), DEV_WH (S).",
                "lambda": "ETL Lambdas use Python 3.11, deployed via CloudFormation. Timeout: 15min. Memory: 512MB-3GB. Layers: pandas, snowflake-connector.",
                "architecture": "Source → S3 Raw → Lambda ETL → Snowflake Staging → dbt → Analytics layer. CDC via DynamoDB streams.",
                "security": "All data encrypted at rest (AES-256) and in transit (TLS 1.2). IAM roles per service. Secrets in AWS Secrets Manager.",
            }
            results = []
            for key, value in kb.items():
                if key in query.lower():
                    results.append(value)
            return "\n".join(results) if results else "No specific info found. Use general knowledge."

        agent = create_react_agent(
            llm,
            tools=[search_knowledge_base],
            state_modifier="You are a research specialist. Find relevant information and summarize findings clearly. Always use your search tool.",
        )
        return agent

    def make_writer_node():
        """Writer produces polished, well-structured content."""

        @tool
        def format_as_markdown(content: str) -> str:
            """Format content as clean markdown."""
            return content  # The LLM handles formatting

        agent = create_react_agent(
            creative_llm,
            tools=[format_as_markdown],
            state_modifier="""You are a technical writer. Take research or rough notes 
and produce polished, well-organized documentation. Use markdown formatting.
Be concise but thorough.""",
        )
        return agent

    def make_coder_node():
        """Coder writes implementation code."""

        @tool
        def validate_python(code: str) -> str:
            """Validate Python code syntax."""
            try:
                compile(code, "<string>", "exec")
                return "✅ Code is syntactically valid"
            except SyntaxError as e:
                return f"❌ Syntax error: {e}"

        agent = create_react_agent(
            llm,
            tools=[validate_python],
            state_modifier="""You are a senior Python developer. Write clean, well-documented code.
Follow best practices: type hints, docstrings, error handling.
Always validate your code before submitting.""",
        )
        return agent

    # --- Build the supervisor graph ---
    researcher = make_researcher_node()
    writer = make_writer_node()
    coder = make_coder_node()

    def supervisor_node(state: MessagesState):
        """Supervisor decides what to do next."""
        structured_llm = llm.with_structured_output(RouteDecision)

        messages = state["messages"]
        # Build context for supervisor
        supervisor_prompt = f"""You are a project supervisor managing a team of:
- researcher: finds information, searches knowledge bases
- writer: produces polished documentation and explanations  
- coder: writes Python code solutions

Based on the conversation so far, decide:
1. Which worker should handle the next step
2. What specific instructions to give them
3. Or if the task is COMPLETE, route to FINISH

Look at the full conversation to understand what's been done and what remains."""

        decision = structured_llm.invoke(
            [SystemMessage(content=supervisor_prompt)] + messages
        )

        return {
            "messages": [
                AIMessage(content=f"[SUPERVISOR → {decision.next_worker}]: {decision.instructions}")
            ]
        }

    def route_supervisor(state: MessagesState):
        """Route based on supervisor's decision."""
        last_msg = state["messages"][-1].content
        if "FINISH" in last_msg:
            return END
        elif "researcher" in last_msg:
            return "researcher"
        elif "writer" in last_msg:
            return "writer"
        elif "coder" in last_msg:
            return "coder"
        return END

    def researcher_node(state: MessagesState):
        result = researcher.invoke(state)
        return {"messages": result["messages"][-1:]}

    def writer_node(state: MessagesState):
        result = writer.invoke(state)
        return {"messages": result["messages"][-1:]}

    def coder_node(state: MessagesState):
        result = coder.invoke(state)
        return {"messages": result["messages"][-1:]}

    # --- Assemble the graph ---
    workflow = StateGraph(MessagesState)

    workflow.add_node("supervisor", supervisor_node)
    workflow.add_node("researcher", researcher_node)
    workflow.add_node("writer", writer_node)
    workflow.add_node("coder", coder_node)

    workflow.add_edge(START, "supervisor")
    workflow.add_conditional_edges("supervisor", route_supervisor)
    workflow.add_edge("researcher", "supervisor")
    workflow.add_edge("writer", "supervisor")
    workflow.add_edge("coder", "supervisor")

    app = workflow.compile()

    # --- Test it ---
    print("=== Multi-Agent Supervisor System ===\n")

    tasks = [
        "Research our Snowflake setup and write a brief onboarding guide for new team members.",
        "Write a Python function that connects to Snowflake and runs a health check query.",
    ]

    for task in tasks:
        print(f"📋 Task: {task}")
        print("-" * 50)

        result = app.invoke(
            {"messages": [HumanMessage(content=task)]},
            {"recursion_limit": 15},
        )

        # Print the final outputs (skip supervisor routing messages)
        for msg in result["messages"]:
            if isinstance(msg, AIMessage) and "[SUPERVISOR" not in msg.content:
                print(f"\n{msg.content}")

        print("\n" + "=" * 60 + "\n")

    return app


# ============================================================
# Example 2: Debate/Critique Pattern
# ============================================================

def debate_agents():
    """
    Two agents debate a topic, improving each other's arguments.
    Pattern: Proposer → Critic → Proposer (refined) → Final

    Useful for: code review, document review, decision analysis
    """
    llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

    from typing import TypedDict, Annotated
    from langgraph.graph import add_messages

    class DebateState(TypedDict):
        messages: Annotated[list, add_messages]
        topic: str
        rounds: int

    def proposer_node(state: DebateState):
        """Makes the initial proposal or refines based on critique."""
        messages = state["messages"]
        topic = state["topic"]

        if len(messages) == 0:
            # Initial proposal
            prompt = f"Make a clear, well-reasoned argument about: {topic}"
        else:
            # Refine based on critique
            prompt = f"""Based on the critique, improve your argument about: {topic}
Address the weak points raised. Keep it concise."""

        response = llm.invoke(
            [SystemMessage(content="You are a thoughtful proposer. Make clear arguments.")] + 
            messages + 
            [HumanMessage(content=prompt)]
        )
        return {"messages": [AIMessage(content=f"[PROPOSER]: {response.content}")]}

    def critic_node(state: DebateState):
        """Critiques the proposal, finds weaknesses."""
        messages = state["messages"]

        response = llm.invoke(
            [SystemMessage(content="You are a constructive critic. Find weaknesses and suggest improvements. Be specific.")] + 
            messages + 
            [HumanMessage(content="Critique the latest proposal. What are the weak points? What's missing?")]
        )
        return {
            "messages": [AIMessage(content=f"[CRITIC]: {response.content}")],
            "rounds": state["rounds"] + 1,
        }

    def should_continue(state: DebateState):
        """Stop after 2 rounds of debate."""
        if state["rounds"] >= 2:
            return "synthesize"
        return "proposer"

    def synthesize_node(state: DebateState):
        """Produce final synthesis incorporating all perspectives."""
        messages = state["messages"]

        response = llm.invoke(
            [SystemMessage(content="Synthesize the debate into a final, balanced conclusion.")] + 
            messages + 
            [HumanMessage(content="Produce a final synthesis that incorporates the best points from both sides. Be concise.")]
        )
        return {"messages": [AIMessage(content=f"[FINAL SYNTHESIS]: {response.content}")]}

    # Build graph
    workflow = StateGraph(DebateState)
    workflow.add_node("proposer", proposer_node)
    workflow.add_node("critic", critic_node)
    workflow.add_node("synthesize", synthesize_node)

    workflow.add_edge(START, "proposer")
    workflow.add_edge("proposer", "critic")
    workflow.add_conditional_edges("critic", should_continue)
    workflow.add_edge("synthesize", END)

    app = workflow.compile()

    # Test
    print("\n=== Debate Pattern ===\n")

    topic = "Should our team migrate from AWS Lambda to AWS Step Functions for ETL orchestration?"
    print(f"🎯 Topic: {topic}\n")

    result = app.invoke({"messages": [], "topic": topic, "rounds": 0})

    for msg in result["messages"]:
        if isinstance(msg, AIMessage):
            print(f"{msg.content}\n")
            print("-" * 40)

    return app


# ============================================================
# Run examples
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  MULTI-AGENT SYSTEMS")
    print("=" * 60)

    supervisor_agent_system()
    debate_agents()

07_tool_calling_agent.py

07_tool_calling_agent.py
"""
07 - Tool-Calling Agent (Snowflake + API Integration)
=====================================================
An agent that can query databases, call APIs, and take real actions.
This demonstrates how to give an LLM access to your actual systems.
"""

import os
from dotenv import load_dotenv

load_dotenv()

from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import MemorySaver


# ============================================================
# Tool Definitions
# ============================================================

@tool
def query_snowflake(sql: str) -> str:
    """
    Execute a SELECT query against Snowflake and return results.
    Only SELECT queries are allowed for safety.
    """
    # --- MOCK IMPLEMENTATION ---
    # In production, replace with actual Snowflake connector:
    #
    # import snowflake.connector
    # conn = snowflake.connector.connect(
    #     account=os.getenv("SNOWFLAKE_ACCOUNT"),
    #     user=os.getenv("SNOWFLAKE_USER"),
    #     password=os.getenv("SNOWFLAKE_PASSWORD"),
    #     warehouse=os.getenv("SNOWFLAKE_WAREHOUSE"),
    #     database=os.getenv("SNOWFLAKE_DATABASE"),
    # )
    # cursor = conn.cursor()
    # cursor.execute(sql)
    # results = cursor.fetchall()
    # columns = [desc[0] for desc in cursor.description]
    # return format_results(columns, results)

    if not sql.strip().upper().startswith("SELECT"):
        return "ERROR: Only SELECT queries are permitted."

    # Mock responses based on query content
    if "count" in sql.lower() and "customers" in sql.lower():
        return "| COUNT | \n|-------|\n| 892,451 |"
    elif "tables" in sql.lower() or "information_schema" in sql.lower():
        return """| TABLE_NAME | ROW_COUNT | LAST_MODIFIED |
|------------|-----------|---------------|
| CUSTOMERS | 892,451 | 2024-10-15 |
| BILLING | 12,340,000 | 2024-10-15 |
| METERS | 1,205,000 | 2024-10-14 |
| USAGE_HOURLY | 450,000,000 | 2024-10-15 |"""
    elif "billing" in sql.lower():
        return """| MONTH | TOTAL_REVENUE | AVG_BILL |
|-------|---------------|----------|
| 2024-08 | $145,230,000 | $162.73 |
| 2024-09 | $138,450,000 | $155.12 |
| 2024-10 | $152,100,000 | $170.42 |"""
    else:
        return f"Query executed: {sql}\n(Mock: 0 rows returned)"


@tool
def get_pipeline_status(pipeline_name: str) -> str:
    """Check the status of an ETL pipeline by name."""
    # Mock - in production, check CloudWatch/Step Functions/Airflow
    pipelines = {
        "billing_daily": {"status": "✅ SUCCESS", "last_run": "2024-10-15 06:00 UTC", "duration": "4m 32s", "records": "1.2M"},
        "customer_cdc": {"status": "✅ SUCCESS", "last_run": "2024-10-15 08:15 UTC", "duration": "2m 10s", "records": "3,421"},
        "meter_reads": {"status": "⚠️ WARNING", "last_run": "2024-10-15 05:00 UTC", "duration": "12m 45s", "records": "5.8M", "warning": "Slower than usual"},
        "nem_export": {"status": "❌ FAILED", "last_run": "2024-10-15 04:00 UTC", "error": "Timeout connecting to PowerClerk API"},
    }

    pipeline = pipelines.get(pipeline_name.lower().replace(" ", "_"))
    if not pipeline:
        available = ", ".join(pipelines.keys())
        return f"Pipeline '{pipeline_name}' not found. Available: {available}"

    result = f"Pipeline: {pipeline_name}\n"
    for key, value in pipeline.items():
        result += f"  {key}: {value}\n"
    return result


@tool
def check_data_quality(table_name: str) -> str:
    """Run data quality checks on a Snowflake table."""
    # Mock
    checks = {
        "customers": {
            "null_check": "✅ No nulls in required fields",
            "duplicate_check": "✅ No duplicate customer IDs",
            "freshness": "✅ Data updated within last 24h",
            "row_count_trend": "✅ Within 5% of 7-day average",
        },
        "billing": {
            "null_check": "✅ No nulls in required fields",
            "duplicate_check": "⚠️ 3 duplicate invoice IDs found",
            "freshness": "✅ Data updated within last 24h",
            "row_count_trend": "✅ Within expected range",
            "value_range": "⚠️ 12 records with negative amounts",
        },
        "usage_hourly": {
            "null_check": "✅ No nulls in required fields",
            "duplicate_check": "✅ No duplicates",
            "freshness": "❌ Data is 36 hours stale",
            "row_count_trend": "⚠️ 15% below 7-day average",
        },
    }

    table = table_name.lower().replace(" ", "_")
    if table not in checks:
        return f"No quality checks configured for '{table_name}'. Available: {', '.join(checks.keys())}"

    result = f"Data Quality Report: {table_name}\n{'=' * 40}\n"
    for check, status in checks[table].items():
        result += f"  {check}: {status}\n"
    return result


@tool
def create_jira_ticket(title: str, description: str, priority: str = "medium") -> str:
    """Create a Jira ticket for tracking issues."""
    # Mock
    import random
    ticket_id = f"DATA-{random.randint(1000, 9999)}"
    return f"✅ Created ticket {ticket_id}: '{title}' (Priority: {priority})"


@tool
def send_slack_alert(channel: str, message: str) -> str:
    """Send an alert to a Slack channel."""
    # Mock
    return f"✅ Alert sent to #{channel}: {message}"


# ============================================================
# Agent Definition
# ============================================================

def create_data_ops_agent():
    """
    A Data Ops agent that can:
    - Query Snowflake
    - Check pipeline status
    - Run data quality checks
    - Create Jira tickets
    - Send Slack alerts
    """
    llm = ChatOpenAI(model="gpt-4o", temperature=0)
    memory = MemorySaver()

    tools = [
        query_snowflake,
        get_pipeline_status,
        check_data_quality,
        create_jira_ticket,
        send_slack_alert,
    ]

    agent = create_react_agent(
        llm,
        tools=tools,
        checkpointer=memory,
        state_modifier="""You are a Data Operations assistant for a data engineering team.

Your capabilities:
1. Query Snowflake (SELECT only) for data analysis
2. Check ETL pipeline status
3. Run data quality checks on tables
4. Create Jira tickets for issues
5. Send Slack alerts for urgent problems

Guidelines:
- Always check data quality when asked about table health
- If you find issues, offer to create a Jira ticket
- For critical failures, suggest sending a Slack alert
- Be concise and actionable in responses
- Use tables to format query results nicely""",
    )

    return agent


# ============================================================
# Demo: Interactive Data Ops Session
# ============================================================

def demo_data_ops():
    """Run a demo conversation with the Data Ops agent."""
    agent = create_data_ops_agent()
    config = {"configurable": {"thread_id": "demo-session"}}

    print("=== Data Operations Agent ===\n")

    conversations = [
        "What tables do we have in Snowflake and how big are they?",
        "Check the status of all our ETL pipelines",
        "The nem_export pipeline failed. Run data quality checks on the billing table and create a ticket if there are issues.",
        "Show me the billing revenue trend for the last 3 months",
    ]

    for msg in conversations:
        print(f"👤 User: {msg}")
        print("-" * 50)

        result = agent.invoke(
            {"messages": [("human", msg)]},
            config=config,
        )

        # Get the final AI response
        final_msg = result["messages"][-1]
        print(f"🤖 Agent: {final_msg.content}\n")
        print("=" * 60 + "\n")


# ============================================================
# Interactive mode
# ============================================================

def interactive_data_ops():
    """Run the Data Ops agent interactively."""
    agent = create_data_ops_agent()
    config = {"configurable": {"thread_id": "interactive-session"}}

    print("\n" + "=" * 60)
    print("  Data Operations Agent - Interactive Mode")
    print("  Type 'quit' to exit")
    print("=" * 60 + "\n")

    while True:
        user_input = input("You: ").strip()
        if user_input.lower() == "quit":
            break
        if not user_input:
            continue

        result = agent.invoke(
            {"messages": [("human", user_input)]},
            config=config,
        )

        print(f"\nAgent: {result['messages'][-1].content}\n")


# ============================================================
# Run
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  TOOL-CALLING AGENT (Data Ops)")
    print("=" * 60)

    demo_data_ops()

    # Uncomment for interactive mode:
    # interactive_data_ops()

08_document_qa.py

08_document_qa.py
"""
08 - Document Q&A App
=====================
Upload documents (PDF, TXT, MD) and ask questions about them.
Uses RAG with a local vector store for document understanding.
"""

import os
from pathlib import Path
from dotenv import load_dotenv

load_dotenv()

from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough
from langchain_community.vectorstores import FAISS
from langchain_text_splitters import RecursiveCharacterTextSplitter


# ============================================================
# Document Loading Utilities
# ============================================================

def load_text_file(file_path: str) -> str:
    """Load a plain text or markdown file."""
    with open(file_path, "r", encoding="utf-8") as f:
        return f.read()


def load_pdf_file(file_path: str) -> str:
    """Load a PDF file (requires pypdf)."""
    try:
        from pypdf import PdfReader
        reader = PdfReader(file_path)
        text = ""
        for page in reader.pages:
            text += page.extract_text() + "\n"
        return text
    except ImportError:
        return "ERROR: Install pypdf to load PDFs: pip install pypdf"


def load_document(file_path: str) -> str:
    """Load any supported document format."""
    path = Path(file_path)
    if path.suffix.lower() == ".pdf":
        return load_pdf_file(file_path)
    elif path.suffix.lower() in [".txt", ".md", ".py", ".sql", ".yaml", ".yml", ".json"]:
        return load_text_file(file_path)
    else:
        raise ValueError(f"Unsupported file format: {path.suffix}")


# ============================================================
# Document Q&A Engine
# ============================================================

class DocumentQA:
    """
    A document question-answering engine.

    Workflow:
    1. Load documents
    2. Split into chunks
    3. Create embeddings
    4. Store in vector DB
    5. Query: retrieve relevant chunks → LLM generates answer
    """

    def __init__(self, model: str = "gpt-4o", chunk_size: int = 500, chunk_overlap: int = 100):
        self.llm = ChatOpenAI(model=model, temperature=0.3)
        self.embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
        self.text_splitter = RecursiveCharacterTextSplitter(
            chunk_size=chunk_size,
            chunk_overlap=chunk_overlap,
            separators=["\n\n", "\n", ". ", " ", ""],
        )
        self.vectorstore = None
        self.retriever = None
        self.documents_loaded = []

    def add_document(self, file_path: str):
        """Load and index a document."""
        print(f"📄 Loading: {file_path}")
        content = load_document(file_path)
        filename = Path(file_path).name

        # Create document chunks with metadata
        from langchain_core.documents import Document
        chunks = self.text_splitter.create_documents(
            texts=[content],
            metadatas=[{"source": filename}],
        )
        print(f"   Split into {len(chunks)} chunks")

        # Add to vector store
        if self.vectorstore is None:
            self.vectorstore = FAISS.from_documents(chunks, self.embeddings)
        else:
            self.vectorstore.add_documents(chunks)

        self.retriever = self.vectorstore.as_retriever(search_kwargs={"k": 4})
        self.documents_loaded.append(filename)
        print(f"   ✅ Indexed successfully")

    def add_text(self, text: str, source_name: str = "direct_input"):
        """Index raw text content."""
        from langchain_core.documents import Document
        chunks = self.text_splitter.create_documents(
            texts=[text],
            metadatas=[{"source": source_name}],
        )

        if self.vectorstore is None:
            self.vectorstore = FAISS.from_documents(chunks, self.embeddings)
        else:
            self.vectorstore.add_documents(chunks)

        self.retriever = self.vectorstore.as_retriever(search_kwargs={"k": 4})
        self.documents_loaded.append(source_name)

    def ask(self, question: str) -> dict:
        """Ask a question about the loaded documents."""
        if self.retriever is None:
            return {"answer": "No documents loaded yet. Use add_document() first.", "sources": []}

        # Retrieve relevant chunks
        relevant_docs = self.retriever.invoke(question)

        # Format context
        context = "\n\n---\n\n".join(
            f"[Source: {doc.metadata.get('source', 'unknown')}]\n{doc.page_content}"
            for doc in relevant_docs
        )

        # Generate answer
        prompt = ChatPromptTemplate.from_messages([
            ("system", """Answer the question based on the provided document context.
If the context doesn't contain enough information, say so clearly.
Always cite which source document(s) you used.
Be precise and concise.

Context:
{context}"""),
            ("human", "{question}"),
        ])

        chain = prompt | self.llm | StrOutputParser()
        answer = chain.invoke({"context": context, "question": question})

        # Collect unique sources
        sources = list(set(doc.metadata.get("source", "unknown") for doc in relevant_docs))

        return {"answer": answer, "sources": sources}

    def ask_with_followup(self, question: str) -> str:
        """Ask and suggest follow-up questions."""
        result = self.ask(question)

        # Generate follow-up suggestions
        followup_prompt = ChatPromptTemplate.from_messages([
            ("system", "Based on this Q&A, suggest 3 natural follow-up questions the user might ask."),
            ("human", "Question: {question}\nAnswer: {answer}\n\nSuggest 3 follow-up questions:"),
        ])

        chain = followup_prompt | self.llm | StrOutputParser()
        followups = chain.invoke({"question": question, "answer": result["answer"]})

        output = f"📝 Answer: {result['answer']}\n"
        output += f"📚 Sources: {', '.join(result['sources'])}\n"
        output += f"\n💡 Follow-up questions:\n{followups}"
        return output


# ============================================================
# Demo with sample documents
# ============================================================

def demo_document_qa():
    """Demo with sample content (no file dependencies)."""
    print("=== Document Q&A Engine ===\n")

    qa = DocumentQA()

    # Add sample documents as text
    qa.add_text("""
    Data Architecture Overview
    ==============================

    Our data platform is built on three layers:

    1. Raw Layer (S3): Landing zone for all source data. Files arrive via API pulls,
       SFTP transfers, and streaming. Retention: 90 days.

    2. Staging Layer (Snowflake STAGING database): Cleaned and typed data.
       ETL Lambda functions transform raw files and load here. Schema-on-read
       with basic validation.

    3. Analytics Layer (Snowflake ANALYTICS database): Business-ready data models
       built with dbt. Star schema design. Used by Tableau dashboards and 
       data science notebooks.

    Key Technologies:
    - Storage: AWS S3, Snowflake
    - Compute: AWS Lambda, Snowflake Warehouses
    - Orchestration: AWS EventBridge, Step Functions
    - Transformation: Python, dbt
    - BI: Tableau, Jupyter
    """, "data-architecture.md")

    qa.add_text("""
    ETL Pipeline Standards
    ======================

    All ETL pipelines must follow these standards:

    Naming Convention:
    - Lambda functions: {team}_{source}_{process_type}
    - Example: intrcon_pwrclrk_etl_cdc

    Error Handling:
    - All errors must be caught and logged to CloudWatch
    - Critical failures trigger SNS alerts to #data-alerts Slack channel
    - Failed records written to error table for reprocessing

    Data Quality:
    - Null checks on required fields
    - Duplicate detection on primary keys
    - Row count validation (+/- 10% of rolling average)
    - Freshness monitoring (alert if >24h stale)

    Performance:
    - Lambda timeout: max 15 minutes
    - Batch size: 10,000 records per invoke
    - Use Snowflake COPY INTO for bulk loads
    - Avoid single-row inserts
    """, "etl-standards.md")

    qa.add_text("""
    Snowflake Access & Security
    ===========================

    Roles:
    - SYSADMIN: Full access (DBA team only)
    - DATA_ENGINEER: Create/modify tables in STAGING and ANALYTICS
    - ANALYST: Read-only access to ANALYTICS
    - SERVICE_ACCOUNT: Used by ETL pipelines, scoped to specific schemas

    Warehouses:
    - ETL_WH (X-Large): For ETL workloads, auto-suspend 60s
    - ANALYTICS_WH (Large): For dashboards and ad-hoc queries
    - DEV_WH (Small): For development and testing
    - ML_WH (Medium): For data science workloads

    Best Practices:
    - Never use ACCOUNTADMIN for routine work
    - All service accounts use key-pair authentication
    - Data masking policies on PII columns
    - Network policies restrict access to the corporate VPN
    """, "snowflake-security.md")

    # Ask questions
    print("\n" + "=" * 50)
    print("Asking questions about the documents...\n")

    questions = [
        "What are the three data layers and what technology does each use?",
        "What's the naming convention for Lambda functions?",
        "What Snowflake warehouse should I use for development?",
        "What happens when an ETL pipeline fails?",
        "How is PII data protected in Snowflake?",
    ]

    for q in questions:
        result = qa.ask(q)
        print(f"❓ {q}")
        print(f"📝 {result['answer']}")
        print(f"📚 Sources: {', '.join(result['sources'])}")
        print()

    return qa


# ============================================================
# Streamlit version (run with: streamlit run 08_document_qa.py)
# ============================================================

def streamlit_document_qa():
    """
    Streamlit UI for document Q&A.
    Uncomment the imports and run with: streamlit run 08_document_qa.py
    """
    import streamlit as st

    st.set_page_config(page_title="Document Q&A", page_icon="📚")
    st.title("📚 Document Q&A")

    # Initialize
    if "qa_engine" not in st.session_state:
        st.session_state.qa_engine = DocumentQA()

    # File upload
    with st.sidebar:
        st.header("📄 Upload Documents")
        uploaded_files = st.file_uploader(
            "Upload files",
            type=["txt", "md", "pdf", "py", "sql"],
            accept_multiple_files=True,
        )

        if uploaded_files:
            for file in uploaded_files:
                if file.name not in st.session_state.qa_engine.documents_loaded:
                    content = file.read().decode("utf-8")
                    st.session_state.qa_engine.add_text(content, file.name)
                    st.success(f"Loaded: {file.name}")

        st.divider()
        st.write(f"**Documents loaded:** {len(st.session_state.qa_engine.documents_loaded)}")
        for doc in st.session_state.qa_engine.documents_loaded:
            st.write(f"- {doc}")

    # Q&A interface
    question = st.text_input("Ask a question about your documents:")
    if question:
        with st.spinner("Searching documents..."):
            result = st.session_state.qa_engine.ask(question)

        st.markdown(f"**Answer:** {result['answer']}")
        st.caption(f"Sources: {', '.join(result['sources'])}")


# ============================================================
# Run
# ============================================================

if __name__ == "__main__":
    print("=" * 60)
    print("  DOCUMENT Q&A")
    print("=" * 60)

    demo_document_qa()

    # To run the Streamlit version:
    # streamlit run 08_document_qa.py
    # (It will detect Streamlit and use streamlit_document_qa())

requirements.txt

requirements.txt
langchain==0.2.16
langchain-openai==0.1.25
langchain-community==0.2.16
langgraph==0.2.28
openai==1.51.0
python-dotenv==1.0.1
faiss-cpu==1.8.0
tiktoken==0.7.0

# Phase 2
streamlit==1.38.0
pypdf==4.3.1
pydantic==2.9.2