Echo 🔊

Echo is an AI chat assistant application built with Chainlit and OpenRouter. It provides a beautiful, conversational interface for interacting with multiple AI models through a single platform — with OAuth authentication, streaming responses, and persistent chat history.

Features

• 🔐 OAuth Authentication — Sign in with GitHub or Google
• 🤖 Multiple AI Models — Access various AI models through OpenRouter API
• 💬 Chat History & Threads — Conversations are saved and resumable per user
• ⚙️ Live Settings — Switch model, temperature, and context window mid-chat
• 🐳 Docker Ready — Fully containerized for easy deployment
• 🎨 Modern UI — Clean, responsive interface built with Chainlit
• 🔄 Streaming Responses — Real-time AI responses with token-level streaming

Quick Start

Using Docker (Recommended)

1. Pull the image from Docker Hub:

   docker pull ragilhadi/echo:latest

2. Create a .env file:

   cp .env.example .env
   # Edit .env — fill in OPENROUTER_API_KEY, CHAINLIT_AUTH_SECRET,
   # and at least one OAuth provider (GitHub or Google)

   Generate the auth secret:

   chainlit create-secret

3. Run with Docker Compose:

   docker-compose up -d

4. Access the application: Open your browser and navigate to http://localhost:8000

Building from Source

1. Clone the repository:

   git clone <repository-url>
   cd chatbot-web

2. Create .env file:

   cp .env.example .env
   # Edit .env — add your keys and secrets

3. Build and run with Docker Compose:

   docker-compose up -d --build

Configuration

Environment Variables

Variable	Required	Description
OPENROUTER_API_KEY	✅	Your OpenRouter API key
CHAINLIT_AUTH_SECRET	✅	JWT signing secret (generate with chainlit create-secret)
OAUTH_GITHUB_CLIENT_ID	⬜	GitHub OAuth app client ID
OAUTH_GITHUB_CLIENT_SECRET	⬜	GitHub OAuth app client secret
OAUTH_GOOGLE_CLIENT_ID	⬜	Google OAuth app client ID
OAUTH_GOOGLE_CLIENT_SECRET	⬜	Google OAuth app client secret
CHAINLIT_URL	⬜	Public URL when behind a reverse proxy

At least one OAuth provider (GitHub or Google) must be configured.

Getting an OpenRouter API Key

1. Visit OpenRouter
2. Sign up for an account
3. Navigate to API Keys section
4. Generate a new API key
5. Add it to your .env file

Setting Up OAuth

GitHub

1. Go to GitHub Developer Settings → OAuth Apps
2. Create a new OAuth app
3. Set callback URL to http://localhost:8000/auth/oauth/github/callback
4. Copy Client ID and Client Secret to .env

Google

1. Go to Google Cloud Console → Credentials
2. Create a new OAuth 2.0 Client ID
3. Set authorized redirect URI to http://localhost:8000/auth/oauth/google/callback
4. Copy Client ID and Client Secret to .env

Project Structure

.
├── app.py                      # Main Chainlit application (lifecycle hooks)
├── constants.py                # Application constants & default system prompt
├── chainlit.md                 # Welcome screen content
├── .chainlit/
│   └── config.toml             # Chainlit UI & feature configuration
├── modules/
│   ├── __init__.py             # Module exports
│   ├── message_manager.py     # Message formatting, trimming, sanitization
│   └── client/                 # OpenRouter API client
│       ├── __init__.py
│       ├── base.py            # Abstract base chat client
│       ├── openrouter.py      # OpenRouter implementation
│       └── exception.py       # Custom exceptions
├── Dockerfile                 # Docker image definition
├── docker-compose.yml         # Docker Compose configuration
├── requirements.txt           # Python dependencies
└── README.md                  # This file

Usage

Starting a Conversation

1. Sign in via GitHub or Google on the login page
2. Type a message or pick a starter prompt
3. The AI responds with streaming tokens in real time

Changing Settings

Click the ⚙️ gear icon in the chat bar to open the settings panel:

• Model — Choose from available OpenRouter models
• Temperature — Control creativity (0 = focused, 2 = creative)
• Context Window — Number of conversation pairs sent to the model

Managing Threads

• Previous conversations appear in the sidebar
• Click a thread to resume it
• Start a new conversation with the ➕ button

Docker Commands

# Start the application
docker-compose up -d

# View logs
docker-compose logs -f echo

# Stop the application
docker-compose down

# Rebuild and restart
docker-compose up -d --build

# Remove everything including volumes
docker-compose down -v

Development

Local Development (without Docker)

1. Install Python 3.11+

2. Create virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set up environment variables:

   cp .env.example .env
   # Edit .env with your keys
   chainlit create-secret  # generate CHAINLIT_AUTH_SECRET

5. Run the application:

   chainlit run app.py -w

   The -w flag enables hot-reload during development.

Technology Stack

• UI Framework: Chainlit
• AI API: OpenRouter
• Authentication: OAuth 2.0 (GitHub, Google)
• Containerization: Docker & Docker Compose
• Language: Python 3.11

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Author

Ragil Prasetyo

• Email: ragilhprasetyo@gmail.com

Support

If you encounter any issues or have questions:

1. Check the logs: docker-compose logs -f echo
2. Ensure your .env file has a valid OpenRouter API key and Chainlit auth secret
3. Verify at least one OAuth provider is configured
4. Verify Docker and Docker Compose are properly installed

---

Enjoy chatting with Echo! 🔊