ragchatbot

Add a semantic search chatbot to any website in minutes. Drop in your docs, get a working API, no ML experience required.

pip install ragchatbot
ragchatbot setup

Your chatbot API is live at http://localhost:8000.

---

What It Does

ragchatbot reads your documents, understands their meaning, and answers questions grounded in your actual content, not hallucinated responses.

Ask:

"what is your refund policy?"

and it finds the answer from your docs.

---

Requirements

• Python 3.10 or higher
• One of:
  • A Gemini API key (free) — get one at aistudio.google.com
  • An OpenAI API key — get one at platform.openai.com
  • Ollama installed locally (no API key, no cost)

---

Quick Start

Step 1 — Install

pip install ragchatbot

Step 2 — Run guided setup

mkdir my-chatbot
cd my-chatbot
ragchatbot setup

Setup will:

• Ask which LLM you want (Gemini, OpenAI, or Ollama)
• Ask which model
• Ask for your API key
• Optionally protect your /ask endpoint with an API key
• Create all folders
• Scan and index your docs automatically

Step 3 — Add your docs

Put your .md, .txt, .pdf, or .docx files in the docs/ folder:

docs/
├── faq.md
├── refund-policy.pdf
├── shipping-policy.docx
└── terms.txt

Then press y when setup prompts you, it will index everything.

Step 4 — Ask a question

ragchatbot ask "what is your refund policy?"

Step 5 — Start the API server

ragchatbot start

API live at http://localhost:8000

Interactive API docs at http://localhost:8000/docs

---

Using the API

Browser-safe endpoint — /chat

If you're calling ragchatbot from a frontend (React, Vue, vanilla JS), use /chat instead of /ask. No API key needed in the browser.

const response = await fetch("http://localhost:8000/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ question: "What is your refund policy?" }),
});

Use /ask only from your own backend or CLI — it requires X-API-Key.

Once the server is running, your frontend can call it:

// Standard request
const response = await fetch("http://localhost:8000/ask", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key", // only if auth is enabled
  },
  body: JSON.stringify({
    question: "What is your refund policy?",
  }),
});

const data = await response.json();
console.log(data.answer); // answer from your docs
console.log(data.sources); // ["refund-policy.pdf"]

Streaming responses

// Streaming request — tokens arrive as they're generated
const response = await fetch("http://localhost:8000/ask", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your-api-key", // only if auth is enabled
  },
  body: JSON.stringify({
    question: "What is your refund policy?",
    stream: true,
  }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  if (chunk.startsWith("\n\n__sources__:")) {
    const sources = JSON.parse(chunk.replace("\n\n__sources__:", ""));
    console.log("Sources:", sources);
  } else {
    process.stdout.write(chunk); // print tokens as they arrive
  }
}

Works with React, Vue, vanilla JS, Next.js — any frontend.

---

CLI Commands

ragchatbot setup                        # guided setup — LLM, API key, index docs
ragchatbot ask "your question"          # ask a question from terminal (streams by default)
ragchatbot ask "question" --no-stream   # wait for full answer
ragchatbot ask "question" --llm ollama  # ask using a specific LLM
ragchatbot start                        # index docs + start API server
ragchatbot start --port 9000            # use a different port
ragchatbot start --llm ollama           # start with a specific LLM
ragchatbot llm                          # show current LLM setup and switch if needed
ragchatbot stats                        # show what's indexed in ChromaDB
ragchatbot verify                       # re-check everything is working
ragchatbot init                         # scaffold folders + .env manually (advanced)
ragchatbot --help                       # show all commands

Auth on /ask

To protect your endpoint so only your frontend can use it:

ragchatbot setup  # choose "y" when asked about auth

Or add manually to .env:

RAGCHATBOT_API_KEY=your-secret-key

Then pass it in every request:

headers: { "X-API-Key": "your-secret-key" }

Without the key, the server returns 401 Unauthorized.

---

Using Ollama (Local, No API Key)

Ollama runs fully locally — no API key, no internet, no cost.

brew install ollama
ollama serve
ollama pull llama3.2

Then run setup and choose Ollama, or set in .env:

ragchatbot_LLM=ollama
ragchatbot_MODEL=llama3.2

---

Using OpenAI

pip install ragchatbot[openai]

Run setup and choose OpenAI, or set in .env:

OPENAI_API_KEY=your-openai-api-key
ragchatbot_LLM=openai
ragchatbot_MODEL=gpt-4o-mini

---

Supported File Types

Type	Status
Markdown .md	✅ Supported
Plain text .txt	✅ Supported
PDF .pdf	✅ Supported
Word .docx	✅ Supported

---

Settings Reference

All settings live in .env (created automatically by ragchatbot setup):

Setting	Default	Description
GEMINI_API_KEY	—	Your Gemini API key
OPENAI_API_KEY	—	Your OpenAI API key
ragchatbot_DOCS	./docs	Folder containing your docs
ragchatbot_DB	./chroma_db	Where vectors are stored
ragchatbot_LLM	gemini	Which LLM: gemini, openai, or ollama
ragchatbot_MODEL	per LLM default	Model name — set automatically during setup
RAGCHATBOT_API_KEY	—	Protect /ask with this key (optional)
HF_HUB_OFFLINE	0	Set to 1 after first run to use cached embedding model

---

Links

• PyPI: https://pypi.org/project/ragchatbot
• Issues: https://github.com/yourusername/ragchatbot/issues
• Contributing: CONTRIBUTING.md

---

License

MIT