README.md

metadata

title: Simple Chatbot
emoji: 🤖
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

🤖 Simple Chatbot

A sleek, real-time AI chatbot built with FastAPI and vanilla HTML/CSS/JS, powered by OpenRouter for free access to various AI models.

---

✨ Features

Feature	Description
🔄 Streaming Responses	AI replies appear in real-time, token by token — no waiting for the full response
💬 Conversation Memory	Full chat history is maintained within a session so the AI remembers context
🎨 Premium Dark UI	Glassmorphism design with ambient gradient blobs and smooth animations
⚡ Quick Suggestions	Clickable prompt starters on the welcome screen to get started fast
📝 Markdown Rendering	Supports bold, italic, inline code, and code blocks in responses
📱 Responsive Design	Works beautifully on desktop and mobile screens
🔁 New Chat	One-click reset to clear history and start fresh

---

📁 Project Structure

Simple Chatbot/
├── main.py              # FastAPI backend — API routes & OpenRouter integration
├── static/
│   ├── index.html       # Frontend HTML — chat UI layout
│   ├── style.css        # Styling — dark theme, glassmorphism, animations
│   └── script.js        # Frontend logic — streaming, history, markdown
├── .env                 # Environment variables (API key)
├── pyproject.toml       # Python project config & dependencies
├── uv.lock              # Dependency lock file
└── README.md            # You are here!

---

🚀 Getting Started

Prerequisites

• Python 3.13+ installed
• uv package manager (recommended) or pip
• An OpenRouter API key — get one free at openrouter.ai/keys

1. Clone the Repository

git clone <your-repo-url>
cd "Simple Chatbot"

2. Set Up Environment Variables

Create a .env file in the project root:

OPENROUTER_API_KEY=sk-or-v1-your-api-key-here

⚠️ Never commit your .env file to version control. It's already in .gitignore.

3. Install Dependencies

Using uv (recommended):

uv sync

Using pip:

pip install fastapi uvicorn openai python-dotenv

4. Run the Server

uv run python -m uvicorn main:app --reload --port 8000

5. Open the Chatbot

Navigate to http://127.0.0.1:8000 in your browser. That's it! 🎉

---

🔧 How It Works

Architecture Overview

┌──────────────┐       POST /api/chat        ┌──────────────┐      Stream      ┌──────────────┐
│              │  ───────────────────────────► │              │ ───────────────► │              │
│   Browser    │   { messages: [...] }        │   FastAPI    │   completions    │  OpenRouter  │
│  (Frontend)  │  ◄─────────────────────────  │  (Backend)   │ ◄─────────────  │   (AI API)   │
│              │   Streaming text chunks      │              │   SSE chunks     │              │
└──────────────┘                              └──────────────┘                  └──────────────┘

Step-by-Step Flow

1. User types a message in the textarea and hits Enter (or clicks send)
2. Frontend appends the message to the local conversationHistory array
3. Frontend sends the full conversation history to POST /api/chat
4. Backend forwards the messages to OpenRouter's API with stream=True
5. Backend streams each text chunk back to the frontend as it arrives
6. Frontend renders each chunk in real-time with a blinking cursor animation
7. Assistant response is saved to conversationHistory for context in future messages

API Endpoint

POST /api/chat

Streams a chat completion from the AI model.

Request Body:

{
  "messages": [
    { "role": "user", "content": "Hello, who are you?" },
    { "role": "assistant", "content": "I'm an AI assistant..." },
    { "role": "user", "content": "Tell me a joke" }
  ]
}

Response: text/plain streamed response (chunked transfer encoding)

---

🧠 Memory & Context

The chatbot maintains in-session memory:

• ✅ Within a session — the AI remembers everything you've said
• ❌ Across page refreshes — memory is lost (stored in browser JS only)
• ❌ Across sessions — no database persistence

The full conversation history is sent with every request, so the AI model has complete context to generate relevant responses.

---

⚙️ Configuration

Changing the AI Model

In main.py, modify the model parameter:

stream = client.chat.completions.create(
    model="openrouter/free",  # ← Change this
    messages=[m.model_dump() for m in request.messages],
    stream=True,
)

Popular free models on OpenRouter:

Model	ID
Auto (free tier)	openrouter/free
Gemma 3	google/gemma-3-27b-it:free
Llama 4 Scout	meta-llama/llama-4-scout:free
Mistral Small	mistralai/mistral-small-3.1-24b-instruct:free

Browse all models at openrouter.ai/models.

Changing the Port

uv run python -m uvicorn main:app --reload --port 3000

---

📦 Dependencies

Package	Purpose
fastapi	Web framework for the API server
uvicorn	ASGI server to run FastAPI
openai	OpenAI-compatible client (works with OpenRouter)
python-dotenv	Loads .env variables into the environment

---

🛠️ Development

Hot Reload

The server runs with --reload, so any changes to Python files will auto-restart the server. For frontend changes (HTML/CSS/JS), just refresh the browser.

Project Dependencies

All dependencies are managed via pyproject.toml and locked in uv.lock. To add a new package:

uv add <package-name>

---

☁️ Deploying to Hugging Face Spaces

You can deploy this chatbot for free on Hugging Face Spaces using Docker.

1. Create a Hugging Face Account

Sign up at huggingface.co/join if you don't have an account.

2. Create a New Space

1. Go to huggingface.co/new-space
2. Fill in:
   • Space name: simple-chatbot
   • SDK: Select Docker
   • Visibility: Public or Private
3. Click Create Space

3. Set Your API Key as a Secret

⚠️ Do NOT push your .env file. Use Space Secrets instead.

1. In your Space, go to Settings → Variables and secrets
2. Click New secret
3. Set:
   • Name: OPENROUTER_API_KEY
   • Value: Your OpenRouter API key
4. Save — HF automatically injects secrets as environment variables

4. Push Your Code

Option A — Add HF as a remote (recommended if you already have a git repo):

git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/simple-chatbot
git push hf main

Option B — Clone and copy:

git clone https://huggingface.co/spaces/YOUR_USERNAME/simple-chatbot
# Copy your project files into the cloned repo
cd simple-chatbot
git add .
git commit -m "Initial deployment"
git push

💡 Replace YOUR_USERNAME with your Hugging Face username.

5. Wait for Build & Go Live

1. Visit https://huggingface.co/spaces/YOUR_USERNAME/simple-chatbot
2. Watch the build logs under the "Building" status badge
3. Once it shows "Running", your chatbot is live at:

https://YOUR_USERNAME-simple-chatbot.hf.space

Troubleshooting

Issue	Fix
Build fails on requirements.txt	Make sure the file is committed and not in .dockerignore
"API key not found" crash	Verify the secret name is exactly OPENROUTER_API_KEY in Space Settings
Port mismatch error	Ensure app_port: 7860 in README frontmatter matches EXPOSE 7860 in Dockerfile
Space is sleeping	Free Spaces sleep after inactivity — visit the URL to wake it, or upgrade for persistent uptime

---

📄 License

This project is open source and available under the MIT License.

---

🙏 Acknowledgments

• OpenRouter — Free AI model access
• FastAPI — Modern Python web framework
• Inter Font — Clean UI typography