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):
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¶
# 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 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 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 - 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
====================
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
======================
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
=======================
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 (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 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())