Forem: hamid zangiabadi

Turning Your Documentation into Smart Responses

hamid zangiabadi — Sun, 31 Aug 2025 07:45:59 +0000

The 2 a.m. Support Crisis

Picture this: it’s 2 a.m. on a Friday night, and your phone buzzes with an urgent Slack notification.

A high‑value customer is stuck with a critical issue that’s blocking their entire workflow.

Your support team won’t be online for another six hours, but somewhere in your sprawling, 500‑page documentation library lies the exact solution they need.

Sound familiar? You’re not alone. This plays out thousands of times daily across companies worldwide, highlighting a fundamental problem with traditional customer support: the right information exists, but finding it feels like searching for a needle in a digital haystack.

What if your documentation could be more than searchable—what if it were genuinely intelligent?

A system that understands customer questions in natural language and provides precise, contextual answers instantly?

Welcome to the world of Retrieval‑Augmented Generation (RAG) for customer support.

What Is RAG, and Why It’s Perfect for Customer Support

Retrieval‑Augmented Generation isn’t just another buzzword in the AI hype cycle—it’s a paradigm shift that transforms static documentation into dynamic, conversational knowledge bases. Think of RAG as giving your documentation both a brain and a voice.

Here’s how it works: when a customer asks “Why is my payment failing?”, traditional keyword search might return dozens of articles about payments, billing, errors, and troubleshooting—forcing the customer to play detective.

RAG, on the other hand, understands the semantic meaning of the question, retrieves the most relevant context from your knowledge base, and crafts a personalized answer that directly addresses their situation.

The beauty of RAG lies in its three‑step process: Retrieve relevant information from your documentation, Augment a large language model with that context, and Generate a natural, helpful response.

It’s like having your best support agent online 24/7, with perfect recall of every piece of documentation you’ve ever written.

Architecture Overview

The RAG pipeline consists of five key components:

Document Ingestion – Process your support docs into searchable chunks
Vector Database – Store document embeddings for semantic search
Query Processing – Understand customer questions in natural language
Response Generation – Craft helpful answers using retrieved context
Feedback Loop – Learn from interactions to improve future responses

Building Your RAG‑Powered Support System

Step 1: Document Preparation

Your system is only as good as the knowledge it can access.

import os
from langchain.document_loaders import UnstructuredFileLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter

def load_support_docs(docs_path):
    """Load customer support documentation from various file formats"""
    documents = []
    for filename in os.listdir(docs_path):
        if filename.endswith(('.md', '.txt', '.pdf', '.docx')):
            loader = UnstructuredFileLoader(f"{docs_path}/{filename}")
            documents.extend(loader.load())
    return documents

def chunk_documents(documents, chunk_size=1000, chunk_overlap=200):
    """Split documents into manageable, searchable chunks"""
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=chunk_size,
        chunk_overlap=chunk_overlap,
        separators=["\n\n", "\n", ".", " "]
    )
    return text_splitter.split_documents(documents)

Step 2: Create the Knowledge Vector Store

from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import Chroma

def create_vector_store(chunks):
    """Transform document chunks into searchable vector embeddings"""
    embeddings = OpenAIEmbeddings()
    vectorstore = Chroma.from_documents(
        documents=chunks,
        embedding=embeddings,
        persist_directory="./support_vectordb"
    )
    return vectorstore

Step 3: Build the Intelligence Layer

import os
from langchain_openai import OpenAI
from langchain.chains import RetrievalQA
from langchain.prompts import PromptTemplate

def create_support_bot(vectorstore):
    api_key = os.getenv("OPENAI_API_KEY")
    if not api_key:
        raise ValueError("OPENAI_API_KEY not found in environment variables.")

    if not hasattr(vectorstore, "as_retriever"):
        raise ValueError("Provided vectorstore does not implement `.as_retriever()`")

    prompt_template = """
    You are a friendly and knowledgeable customer support assistant. 
    Use the provided documentation to answer the customer's question accurately and helpfully.

    If you cannot find a complete answer in the context, 
    say so honestly and suggest contacting human support.

    Context from documentation:
    {context}

    Customer question: {question}

    Your helpful response (include step-by-step instructions when applicable):
    """
    PROMPT = PromptTemplate(
        template=prompt_template.strip(),
        input_variables=["context", "question"]
    )

    llm = OpenAI(api_key=api_key, temperature=0.2)

    qa_chain = RetrievalQA.from_chain_type(
        llm=llm,
        chain_type="stuff",
        retriever=vectorstore.as_retriever(search_kwargs={"k": 4}),
        chain_type_kwargs={"prompt": PROMPT}
    )

    return qa_chain

The code you’ve just seen implements a basic Retrieval‑Augmented Generation (RAG) pipeline for customer support.

It follows a clear, modular structure so each step can be tested, improved, or swapped independently:

Document Preparation – Load your documentation from multiple formats, then split it into manageable, context‑preserving chunks.
Vector Store Creation – Convert each chunk into a semantic embedding and store it in a vector database for lightning‑fast, relevant retrieval.
Support Bot Assembly – Use LangChain’s RetrievalQA to:
- Retrieve – Find the most relevant chunks from the vector database using semantic search.
- Augment – Feed those chunks into a Large Language Model (LLM) as reference material.
- Generate – Produce a natural, helpful response that directly addresses the customer’s question.

Performance Optimization Tips

Smart Chunking – Split docs at natural boundaries for better context.
Domain‑Specific Embeddings – Fine‑tune to understand your terminology.
Intelligent Caching – Use Redis for common queries to cut latency and costs.
Hybrid Search – Combine semantic search with exact keyword matching.

Ready to Transform Your Support?

RAG shifts customer support from reactive to proactive. By making documentation conversational and instantly accessible, you aren’t just solving the 2 a.m. crisis—you’re creating an exceptional support experience.

TypeScript Generics: The Magic Wand for Reusable Type-Safe Code

hamid zangiabadi — Tue, 26 Aug 2025 08:06:35 +0000

Ever felt like you're writing the same function over and over, just with different types? Welcome to the world of TypeScript generics – where code reusability meets type safety in perfect harmony.

What Are Generics?

Imagine you're building a toolbox. Instead of having separate hammers for nails, screws, and pins, wouldn't it be amazing to have one universal hammer that adapts to whatever you're working with? That's exactly what generics do for your code.

Generics allow you to create reusable components that work with multiple types while maintaining type safety. Think of them as type variables – placeholders that get filled in when you actually use the function, class, or interface.

The Problem Generics Solve

Let's start. Say you want to create a function that returns the first item from an array:

function getFirstString(items: string[]): string {
  return items[0];
}

function getFirstNumber(items: number[]): number {
  return items[0];
}

function getFirstBoolean(items: boolean[]): boolean {
  return items[0];
}

This approach is like having a separate key for every door in your house. It works, but it's unnecessarily complicated.

Enter Generics: The Master Key 🗝️

Here's how generics solve this elegantly:

function getFirst<T>(items: T[]): T {
  return items[0];
}

// Now we can use it with any type!
const firstString = getFirst(['apple', 'banana', 'cherry']); // Type: string
const firstNumber = getFirst([1, 2, 3]); // Type: number
const firstUser = getFirst([{name: 'Alice'}, {name: 'Bob'}]); // Type: {name: string}

The <T> is our type parameter – a placeholder that TypeScript fills in based on how we use the function. It's like saying "Hey TypeScript, I'll tell you what type this is when I actually use it."

Generic Syntax: Breaking It Down

The basic syntax follows this pattern:

function functionName<TypeParameter>(param: TypeParameter): TypeParameter {
  // function body
}

You can name your type parameters anything, but common conventions include:

T for "Type" (most common)
K for "Key" and V for "Value" (in key-value scenarios)
U, V, W for additional type parameters

Real-World Examples

1. API Response Handler

interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

// Now we can handle different types of API responses
const userResponse: ApiResponse<User> = {
  data: { id: 1, name: 'Alice' },
  status: 200,
  message: 'Success'
};

const productsResponse: ApiResponse<Product[]> = {
  data: [{ id: 1, name: 'Laptop' }, { id: 2, name: 'Phone' }],
  status: 200,
  message: 'Success'
};

2. Generic Promise Wrapper

async function fetchData<T>(url: string): Promise<T> {
  const response = await fetch(url);
  return response.json();
}

// TypeScript knows exactly what type we're getting back
const user = await fetchData<User>('/api/users/1');
const posts = await fetchData<Post[]>('/api/posts');

3. Type-Safe Storage System

class Storage<T> {
  private items: T[] = [];

  add(item: T): void {
    this.items.push(item);
  }

  get(index: number): T | undefined {
    return this.items[index];
  }

  getAll(): T[] {
    return [...this.items];
  }
}

// Different storage instances for different types
const userStorage = new Storage<User>();
const productStorage = new Storage<Product>();

userStorage.add({ id: 1, name: 'Alice' }); // ✅ Works
userStorage.add('invalid'); // ❌ TypeScript error!

Advanced Generic Patterns

Generic Constraints: Setting Boundaries

Sometimes you want your generic to work with any type, but that type must have certain properties:

interface Identifiable {
  id: number;
}

function updateItem<T extends Identifiable>(item: T, updates: Partial<T>): T {
  return { ...item, ...updates };
}

// This works because User has an id property
interface User extends Identifiable {
  name: string;
  email: string;
}

const user: User = { id: 1, name: 'Alice', email: 'alice@example.com' };
const updatedUser = updateItem(user, { name: 'Alice Smith' });

Multiple Type Parameters

function merge<T, U>(obj1: T, obj2: U): T & U {
  return { ...obj1, ...obj2 };
}

const personalInfo = { name: 'Alice', age: 30 };
const workInfo = { company: 'TechCorp', position: 'Developer' };

const fullProfile = merge(personalInfo, workInfo);
// Type: { name: string; age: number; company: string; position: string; }

Conditional Types (The Mind-Bender)

type ApiResult<T> = T extends string 
  ? { message: T } 
  : T extends number 
  ? { count: T }
  : { data: T };

// TypeScript automatically infers the right shape
const stringResult: ApiResult<string> = { message: "Hello" };
const numberResult: ApiResult<number> = { count: 42 };
const objectResult: ApiResult<User> = { data: { id: 1, name: "Alice" } };

Utility Types: Generics in Action

TypeScript comes with powerful built-in generic utility types:

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
}

// Pick only specific properties
type PublicUser = Pick<User, 'id' | 'name'>;

// Make all properties optional
type PartialUser = Partial<User>;

// Exclude specific properties
type UserWithoutPassword = Omit<User, 'password'>;

// Create a record type
type UserRoles = Record<string, 'admin' | 'user' | 'guest'>;

Common Pitfalls and How to Avoid Them

1. The Generic Type Erasure Trap

// ❌ This won't work as expected
function createArray<T>(length: number, value: T): T[] {
  return new Array(length).fill(value);
}

// ✅ Better approach
function createArray<T>(length: number, factory: () => T): T[] {
  return Array.from({ length }, factory);
}

2. Forgetting About Type Inference

// ❌ Unnecessary explicit type
const numbers = identity<number[]>([1, 2, 3]);

// ✅ Let TypeScript infer
const numbers = identity([1, 2, 3]); // Type is automatically number[]

When NOT to Use Generics

Generics are powerful, but they're not always the answer:

Simple, one-off functions that will never need to handle multiple types
When the type is always the same – just use the specific type
Over-abstraction – if your generic has more than 3-4 type parameters, reconsider your design

Wrapping Up: Your Generic Journey Starts Here

Generics might seem intimidating at first, but they're one of TypeScript's most powerful features. They let you write flexible, reusable code without sacrificing type safety – like having your cake and eating it too! 🍰

Start small: convert a few of your existing functions to use generics. You'll quickly see how they can eliminate code duplication and make your APIs more flexible. Before you know it, you'll be thinking in generics and wondering how you ever lived without them.

Remember, the best way to learn generics is by using them. So fire up your editor, pick a function that handles multiple types, and give it the generic treatment. Your future self (and your teammates) will thank you!

Rasa, LLMs, and RAG — Powering a Solution for Conversational AI

hamid zangiabadi — Sun, 17 Aug 2025 06:14:36 +0000

Conversational AI hasn’t just evolved in the past few years — it’s quietly staged a revolution.

We’ve gone from basic intent classification and rigid, rule‑based scripts to Large Language Models (LLMs) that can hold conversations with fluency.

And yet — in real‑world production environments where accuracy, trustworthiness, and scalability matter — LLMs alone aren’t enough. The real magic happens when you blend their creativity with structured, reliable systems.

In this post, we’ll explore how Rasa, LLMs, and RAG (Retrieval‑Augmented Generation) can work together to build chatbots that are natural, reliable, and grounded.

Bridging the Gap: Why Mix Rasa, LLMs, and RAG?

LLMs are brilliant at generating smooth, coherent replies — but they can “hallucinate” when they don’t know the answer, especially in regulated or domain‑specific contexts. Rasa, on the other hand, excels at predictable control — intent classification, slot filling, business logic, and integrating with APIs. RAG acts as the glue, retrieving trusted documents, FAQs, or knowledge base entries, feeding them into the LLM so responses remain factual and grounded in the organization’s data.

This is where:

Rasa ⟶ gives you predictable control: intent classification, slot filling, API calls, and workflow logic.
RAG (Retrieval‑Augmented Generation) ⟶ injects facts by retrieving trusted answers from your documentation, FAQs, or knowledge base.
LLM ⟶ uses both user input and retrieved context to generate natural, grounded responses.

The Architecture at a Glance

You can think of this trio as a human‑like conversation team inside your chatbot:

Rasa is the executive planner — listening to the user, interpreting their intent, and deciding which pathway to follow.
RAG plays the research assistant — diving into the knowledge base and coming back with the most relevant facts.
LLM is the storyteller — presenting those facts in a friendly, human‑like tone.

A typical workflow looks like this:

The user asks a question.
Rasa analyses the intent and determines whether this is a standard flow (e.g., “Book me a meeting”) or a factual query (“What’s your refund policy?”).
For factual queries, Rasa triggers the RAG pipeline.
The query is converted into an embedding vector, similar content is fetched from a FAISS index or other vector storage.
Retrieved data is inserted into an LLM prompt so the answer is grounded in the right context.
The LLM generates a polished response, and Rasa sends it back to the user.

Production Benefits

By combining these components together, you create a balanced conversational system: Rasa provides structured, predictable dialogue control; RAG contributes accurate, context‑aware information; and the LLM adds natural, human‑like interaction. This blend minimizes misleading responses, handles complex queries with context retention, scales gracefully as your knowledge base grows, and allows new features to be introduced without disrupting existing behavior.

Minimal Working Example (Rasa + FAISS RAG Custom Action)

# Pseudo-code: Rasa + FAISS RAG Custom Action

load embedding_model("all-MiniLM-L6-v2")
load faiss_index("kb.index")  # Built from company knowledge base

class ActionRAGLookup:
    function name():
        return "action_rag_lookup"

    function run(dispatcher, tracker, domain):
        user_query = tracker.get_latest_message_text()
        query_vector = embedding_model.encode(user_query)

        distances, indices = faiss_index.search(query_vector, top_k=1)
        best_answer = read_from_file("kb_answers.txt")[indices[0]]

        dispatcher.send_message(best_answer)
        return no_events

Minimal Working Example (Pseudo‑Code)

load embedding_model("all-MiniLM-L6-v2")
load faiss_index("kb.index")  # Built from company knowledge base

class ActionRAGLookup:
    function name():
        return "action_rag_lookup"

    function run(dispatcher, tracker, domain):
        user_query = tracker.get_latest_message_text()
        query_vector = embedding_model.encode(user_query)

        distances, indices = faiss_index.search(query_vector, top_k=1)
        best_answer = read_from_file("kb_answers.txt")[indices[0]]

        dispatcher.send_message(best_answer)
        return no_events

Step‑by‑Step Implementation

1. Set up Rasa

pip install rasa
rasa init

This creates a default bot with intents, domain, and sample actions.

2. Prepare your Knowledge Base

Gather Q&A pairs from your docs.
Generate embeddings (all-MiniLM-L6-v2).
Build and save FAISS index (kb.index) and answers file.

3. Create the Custom RAG Action

Add retrieval logic like in ActionRAGLookup.
Encode query, search index, return top match.

4. Update domain.yml

Add action_rag_lookup under actions.
Declare needed intents (e.g., ask_question).
Optional: add utter_fallback for low‑confidence cases.

5. Train and Run

rasa train
rasa run            # Terminal 1 — starts bot server
rasa run actions    # Terminal 2 — starts action server

6. Test

rasa shell

Type a query → Rasa processes it → RAG retrieves matching answer → LLM formats and sends it back.

Domain — The Blueprint of Your Bot

File: domain.yml

Think of the domain as your chatbot’s ID card + skill list.

It tells Rasa:

Who you are (list of possible responses the bot knows)
What you can do (custom actions, forms)
What you understand (intents & entities you’re trained to recognize)
What you remember (slots that hold values through a conversation)

A typical structure:

intents:
  - greet
  - ask_price

entities:
  - product_name

slots:
  product_name:
    type: text

responses:
  utter_greet:
    - text: "Hi there! How can I help you?"
  utter_ask_price:
    - text: "How much this product costs?"

actions:
  - action_rag_lookup

The domain is like the API surface of your bot. If your bot’s ability or response isn’t declared here, Rasa won’t touch it — even if it’s coded elsewhere.

Stories — Example Conversations Rasa Learns From

File: stories.yml

Stories are like training scripts for actors — they’re examples of how a conversation might go from start to finish.

They teach Rasa’s dialogue management how to react over multiple turns.
Based on these examples, Rasa learns patterns for fluid, non‑rigid conversations.

Example:

stories:
  - story: user asks a factual question
    steps:
      - intent: ask_question
      - action: action_rag_lookup

Here, we’re saying:

“If the user intent is ask_question, the next step in the conversation is to run our RAG retrieval action.”

The more varied but plausible your stories, the smarter Rasa becomes at guessing what to do when a new but similar situation happens.

Rules — Fixed Conversation Logic

File: rules.yml

Rules are if‑this‑then‑that triggers, for when you want absolute determinism.

Unlike stories, rules don’t let Rasa “improvise” — they always fire exactly as defined.

Example:

rules:
  - rule: Handle fallback
    steps:
      - intent: nlu_fallback
      - action: utter_fallback

Meaning:

“Every time my NLU confidence is low, trigger utter_fallback.”

You use rules for:

Mandatory flows (always confirm a user’s email before proceeding)
Hard fallbacks (don’t let the bot guess)
Compliance scripts (legal disclaimers, medical advice warnings)

What happens:

This launches an interactive CLI where you type messages as a user.
Rasa will process them through your NLU pipeline, then — if your logic routes to the RAG action — it will:
1. Embed your text
2. Retrieve the top match from FAISS
3. Send that as the bot’s reply.