Guides

Zero to chatbot

Build a working AI chatbot grounded in your own documents. One file. No frameworks.

This is the simplest possible Aether app: a single script that loads your documents, then answers questions about them using Claude. Copy, paste, run.

What you'll need

Setup

Install the two packages:

pip install aether-ai anthropic

Set your API keys. If you're not sure how environment variables work, see the concepts page.

Bash
export AETHER_API_KEY="your-aether-key"
export ANTHROPIC_API_KEY="your-anthropic-key"

The entire app

import os

from aether import AetherClient
import anthropic

# Connect to Aether and Claude
aether = AetherClient(api_key=os.environ["AETHER_API_KEY"])
claude = anthropic.Anthropic()

# Step 1: Load your knowledge base
# Replace these with your own content, or use aether.insert() for files
docs = [
    "Our return policy allows returns within 30 days of purchase with a receipt.",
    "Shipping is free on orders over $50. Standard delivery takes 3-5 business days.",
    "We accept Visa, Mastercard, and PayPal. We do not accept cryptocurrency.",
    "Store hours are Monday-Saturday 9am-9pm and Sunday 10am-6pm.",
    "Loyalty members earn 1 point per dollar spent. 100 points = $5 off.",
]

print("Loading documents...")
for doc in docs:
    aether.insert_text(doc)
print(f"Loaded {len(docs)} documents.\n")

# Step 2: Chat loop
while True:
    question = input("Ask a question (or 'quit'): ")
    if question.lower() in ("quit", "exit", "q"):
        break

    # Find relevant documents
    results = aether.retrieve(question, k=3)
    context = "\n\n".join(r.content for r in results)

    # Ask Claude, grounded in your documents
    response = claude.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=300,
        system=f"Answer based only on this context. If the answer isn't in the context, say so.\n\n{context}",
        messages=[{"role": "user", "content": question}],
    )

    print(f"\n{response.content[0].text}\n")

Run it

python chatbot.py

That's it. You now have a chatbot that answers questions using your documents instead of making things up.

Try asking

  • "What's your return policy?"
  • "Do you take crypto?"
  • "How do I earn loyalty points?"

Notice how the answers come from the documents you loaded, not from the AI's general knowledge. If you ask something that isn't in the documents, it tells you it doesn't know — that's the whole point.

Make it yours

Use your own documents. Replace the docs list with your actual content, or load files:

aether.insert(file_path="./handbook.pdf", content_type="application/pdf")
aether.insert(file_path="./faq.md", content_type="text/markdown")

Use a different LLM. Swap Claude for OpenAI, Grok, or any provider — see Integrations.

Add a web interface. Wrap the chat loop in a Streamlit app (Python) or an Express server (TypeScript) — see the Examples section for complete implementations.

What just happened?

If you're curious about how this works under the hood:

  1. Insert — Aether split your text into chunks, converted each chunk into a list of numbers (called an embedding) that captures its meaning, and stored everything.
  2. Retrieve — When you asked a question, Aether converted your question into the same kind of numbers and found the chunks with the most similar meaning.
  3. Generate — Claude received the matching chunks as context and wrote an answer based on that context, not its training data.

This three-step pattern — insert, retrieve, generate — is called RAG. Every example in these docs is a variation of it.

Next steps