Introducing the HubSpot RAG Assistant

It's 1 AM, coffee is cold, a deadline looms tomorrow morning, and I'm swimming through HubSpot's docs to figure out why my integration keeps throwing that weird response. It's good times. The truth is, we've all wasted hours digging through massive developer documentation. It's not that the docs are bad—they're actually pretty great—but they're HUGE. Finding that one specific answer you need? Total time-sink.

That frustration is exactly why I built the HubSpot RAG Assistant: I needed an easy way to address developer-centric questions for a Postman Flow I was building with HubSpot APIs. It's an open-source tool I've been working on that uses AI to cut through the documentation maze and give you straight answers fast.

The Power of RAG: Beyond Traditional Search

So, what is RAG, anyway? No, it’s not a piece of old cloth. It’s Retrieval-Augmented Generation, which might sound like tech jargon, but it's pretty straightforward.

Here's the deal: normal AI chatbots like ChatGPT just make stuff up based on what they've seen before. Sometimes, they're right, and sometimes hilariously wrong (we've all seen those screenshots). RAG flips the script by saying, "Hold up, let me check the actual documents first."

It's like the difference between:

• Asking your friend who thinks they know everything (standard AI)
• Asking someone who actually stops to look up the answer in a trusted manual (RAG)

RAG does two crucial things:

1. It actually understands what you're asking. The "semantic retrieval" part means it understands your question, even if you phrase it differently than the docs do.
2. It gives you real answers, not hallucinations. Once it finds relevant information, it crafts a helpful response based on actual documentation, with links to where it found it.

I like to think of it as giving my AI assistant a library card and teaching it how to use HubSpot's documentation before it answers me. It's a game-changer.

Why Traditional Documentation Search Falls Short (sometimes)

Look, HubSpot's docs are solid. Thorough. Comprehensive. Some of my favorite co-workers are our tech writers at HubSpot (you know who you are). But sometimes that's part of the problem.

I recently spent 45 minutes figuring out how to use HubSpot’s Calls API correctly. The information was there, but it was spread across different pages, and the examples didn't quite match my use case. Classic!

The problems with traditional doc search are real:

• Too. Much. Information. It's like drinking from a firehose when you just need a sip.
• Keyword nightmare: If you don't use the exact terminology in the documents, you may have trouble finding what you need.
• Context confusion: Understanding how snippets from different sections actually fit together? Now, we have a headache.

What makes the RAG Assistant different is that it actually understands the question behind your question. It's like having a senior developer who knows the docs inside and out sitting beside you, ready to point you to exactly what you need (sigh - the good ol’ days).

• Dramatically faster answers: Get direct responses in seconds instead of reading through multiple documentation pages.
• Higher accuracy: Receive information that's relevant to your specific intent and context.
• Verifiable sources: Every answer includes citations from the official documentation so that you can verify or explore further.

Behind the Scenes: How the HubSpot RAG Assistant Works

After one too many late nights lost in the documentation labyrinth, I cobbled together this open-source project to save my sanity (and hopefully yours too).

The magic happens through a combination of tech that works surprisingly well together:

Key Features

• Everything indexed: I've taken all of HubSpot's developer documentation and turned it into searchable chunks with Pinecone and LangChain.
• Smart question understanding: Uses OpenAI under the hood to figure out what you're really asking.
• Lightning-fast retrieval: Pinecone's vector search finds relevant info in milliseconds.
• Clean API: Built on FastAPI because, well, it's fast and I like Python.
• Simple UI option: Threw together a Streamlit interface for those who prefer clicking to coding.

Here is a helpful diagram to give you a better understanding of the architecture: 

Getting This Running On Your Machine

Want to try it yourself? I've open-sourced the whole thing. Here's how to get it up and running:

1. Grab the Code

2. Set Up Your Keys

You'll need API keys for this. Create a .env file with:

(Yes, there are costs associated with these services, but the usage for personal projects is pretty reasonable.) Here are the tools you can expense to your manager for later: 

• OpenAI
• Pinecone
• FastAPI
• LangChain
• Streamlit (optional)

3. Install the Goodies

4. Load Up the Docs

This script is doing several things:

• Taking that massive documentation file (llms-full.txt)
• Chopping it into bite-sized chunks
• Converting those chunks into vector embeddings via OpenAI
• Storing everything in Pinecone so you can search it

Fair warning: this step might take a few minutes and cost you a few cents in API calls (it cost me .30 cents). Coffee break time!

5. Fire Up the Server

Now you're ready to start asking questions! If you're an API kind of person, hit Postman with: POSThttp://localhost:8000/ask or use this premade Postman Collection.

Request body:

Response body:

6. For the GUI Folks

If you prefer buttons to API calls, I've got you covered:

This gives you a clean interface where you can just type questions and get answers. No JSON formatting required. Take a look at the example below to give you an idea of what this UI looks like:

The Tech Stack

Nothing fancy here, just reliable tools that get the job done:

• OpenAI: Does the heavy lifting for understanding text and generating coherent answers
• Pinecone: Handles the vector search so we can find relevant content crazy fast
• FastAPI: Because life's too short for slow APIs
• Streamlit: Makes creating a simple UI dead simple

What's Next on the Roadmap

This is just version 0.1. I've got plans:

• Making it secure: Adding proper auth and usage limits so you can use it with a team
• Cloud-ready versions: Deployment templates for AWS, GCP, etc.
• Auto-updating docs: So it stays current as HubSpot updates our documentation
• Expanding beyond dev docs: Adding knowledge bases, community forums, Stack Overflow answers...the world is our oyster!

Why This Matters for Your Sanity

I built this tool because I was tired of context-switching between coding and documentation hunting, and I really needed it for a project. It's saved me countless hours already, especially when onboarding new developers to our HubSpot projects.

The real value is simple:

• Get unstuck in seconds, not hours
• Have confidence that you're implementing things correctly
• Save brain cycles for actual problem-solving instead of documentation hunting

Jump In and Try It

Ready to reclaim those lost hours? Go to the GitHub repo, clone it, and give it a try.

And hey, if you find it useful or have ideas for improving it, I'd love to hear from you. This is a side project born from frustration—contributions are welcome! Just submit an issue.

P.S. Next time you find yourself stuck in documentation at 1 AM, remember: there's a better way. Your future sleep-deprived self will thank you.