Update README with comprehensive project overview
This commit is contained in:
415
README.md
415
README.md
@@ -1,115 +1,360 @@
|
|||||||
# 🔀 Chat Switchboard
|
# 🔀 Chat Switchboard
|
||||||
|
|
||||||
A sleek, OpenAI-compatible chat interface with per-conversation model switching, collapsible thinking blocks, and full chat history management.
|
**The Plugin-First, Multi-Model AI Platform**
|
||||||
|
|
||||||
## Features
|
Chat Switchboard is a next-generation AI interface that works offline or managed, with a unique plugin architecture and visual workflow builder.
|
||||||
|
|
||||||
- **Multi-Model Support**: Switch models per-chat via quick selector
|
[](https://opensource.org/licenses/MIT)
|
||||||
- **Thinking Blocks**: Collapsible `<thinking>` tags with distinct styling
|
[](https://go.dev/)
|
||||||
- **Streaming Responses**: Real-time token streaming with stop button
|
[](https://python.org/)
|
||||||
- **Chat History**: Persistent storage with export (Markdown/JSON/Text)
|
|
||||||
- **Keyboard Shortcuts**: `Enter` send, `Shift+Enter` newline, `Esc` stop, `Ctrl+B` sidebar, `Ctrl+,` settings
|
|
||||||
- **Code Highlighting**: Syntax-aware code blocks with copy buttons
|
|
||||||
- **Regenerate**: Re-run last response with one click
|
|
||||||
- **Dark Theme**: Easy on the eyes
|
|
||||||
|
|
||||||
## Quick Start
|
---
|
||||||
|
|
||||||
### Standalone (No Build Required)
|
## 🎯 What Makes Us Different
|
||||||
|
|
||||||
|
| Feature | Chat Switchboard | Others |
|
||||||
|
|---------|-----------------|--------|
|
||||||
|
| **Works Offline** | ✅ Full-featured unmanaged mode | ❌ Backend required |
|
||||||
|
| **Plugin System** | ✅ Core features ARE plugins | 🟡 Limited or none |
|
||||||
|
| **Visual Workflows** | ✅ Chain multiple AI models | ❌ Single-shot only |
|
||||||
|
| **Multi-Model Routing** | ✅ Auto-select best/cheapest | 🟡 Manual only |
|
||||||
|
| **Channels** | ✅ User + AI collaboration | 🟡 Users only |
|
||||||
|
| **Self-Hosted** | ✅ Easy Docker setup | 🟡 Complex |
|
||||||
|
|
||||||
|
**Unique Selling Points:**
|
||||||
|
1. **Workflows** - No competitor has visual AI orchestration (like n8n for LLMs)
|
||||||
|
2. **Dual-Mode** - Privacy-first offline mode OR full collaboration backend
|
||||||
|
3. **Plugin-First** - Chat, Channels, Notes are ALL plugins (proves extensibility)
|
||||||
|
4. **Smart Routing** - Automatic model selection for cost/quality optimization
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Quick Start
|
||||||
|
|
||||||
|
### Option 1: Offline Mode (No Backend)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Build the single-file version
|
# Clone and build
|
||||||
|
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
|
||||||
|
cd chat-switchboard
|
||||||
./build.sh
|
./build.sh
|
||||||
|
|
||||||
# Open in browser
|
# Open in browser
|
||||||
xdg-open standalone/index.html
|
xdg-open standalone/index.html
|
||||||
# or
|
|
||||||
python3 -m http.server 8080 --directory standalone
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Development
|
**Configure API:**
|
||||||
|
1. Click ⚙️ Settings
|
||||||
|
2. Enter API endpoint (OpenAI, OpenRouter, Venice.ai, Ollama, etc.)
|
||||||
|
3. Add your API key
|
||||||
|
4. Start chatting!
|
||||||
|
|
||||||
|
### Option 2: Full Backend (Collaboration + Workflows)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Serve src/ directory for development
|
# Clone repo
|
||||||
python3 -m http.server 8080 --directory src
|
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
|
||||||
```
|
cd chat-switchboard
|
||||||
|
|
||||||
## Project Structure
|
# Configure
|
||||||
|
cp .env.example .env
|
||||||
|
# Edit .env with your settings
|
||||||
|
|
||||||
```
|
# Start with Docker
|
||||||
chat-switchboard/
|
|
||||||
├── build.sh # Builds standalone HTML
|
|
||||||
├── standalone/ # Built single-file output
|
|
||||||
│ └── index.html
|
|
||||||
├── src/ # Source files
|
|
||||||
│ ├── index.html
|
|
||||||
│ ├── css/
|
|
||||||
│ │ └── styles.css
|
|
||||||
│ └── js/
|
|
||||||
│ ├── storage.js # LocalStorage utilities
|
|
||||||
│ ├── state.js # State management
|
|
||||||
│ ├── api.js # API calls
|
|
||||||
│ ├── ui.js # UI rendering
|
|
||||||
│ └── app.js # Main application
|
|
||||||
├── server/ # Backend (future)
|
|
||||||
│ ├── main.go
|
|
||||||
│ ├── handlers/
|
|
||||||
│ ├── models/
|
|
||||||
│ └── middleware/
|
|
||||||
├── migrations/ # PostgreSQL schemas
|
|
||||||
│ └── 001_initial.sql
|
|
||||||
├── docker-compose.yml # Local dev environment
|
|
||||||
└── docs/ # Documentation
|
|
||||||
```
|
|
||||||
|
|
||||||
## Backend (Planned)
|
|
||||||
|
|
||||||
The project is structured to support a full backend with:
|
|
||||||
|
|
||||||
- **Go server** with Gin/Echo
|
|
||||||
- **PostgreSQL** for persistent storage
|
|
||||||
- **User authentication** (optional)
|
|
||||||
- **API key management** per user
|
|
||||||
- **Chat syncing** across devices
|
|
||||||
|
|
||||||
### Database Schema
|
|
||||||
|
|
||||||
See `migrations/001_initial.sql` for the initial PostgreSQL schema.
|
|
||||||
|
|
||||||
### Running with Docker
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker-compose up -d
|
docker-compose up -d
|
||||||
|
|
||||||
|
# Access at http://localhost:3000
|
||||||
```
|
```
|
||||||
|
|
||||||
## Configuration
|
See [GETTING_STARTED.md](docs/GETTING_STARTED.md) for detailed instructions.
|
||||||
|
|
||||||
Settings are stored in `localStorage`:
|
---
|
||||||
|
|
||||||
| Key | Description |
|
## ✨ Core Features
|
||||||
|-----|-------------|
|
|
||||||
| `chatSwitchboard_settings` | API endpoint, model, parameters |
|
|
||||||
| `chatSwitchboard_models` | Cached model list |
|
|
||||||
| `chatSwitchboard_chats` | Chat history |
|
|
||||||
|
|
||||||
## API Compatibility
|
### 1. 💬 Chat (User → AI)
|
||||||
|
- Multi-model support (OpenAI, Anthropic, Ollama, etc.)
|
||||||
|
- Per-conversation model switching
|
||||||
|
- Streaming responses with stop button
|
||||||
|
- Export (Markdown, JSON, Plain Text)
|
||||||
|
- Auto-routing to best/cheapest model (managed mode)
|
||||||
|
|
||||||
Works with any OpenAI-compatible API:
|
### 2. 👥 Channels (User → User + AI)
|
||||||
|
**Managed mode only**
|
||||||
|
|
||||||
- OpenAI
|
Multi-user chat rooms where you can @mention AI models:
|
||||||
- Anthropic (via proxy)
|
|
||||||
- Ollama (`http://localhost:11434/v1`)
|
|
||||||
- LM Studio
|
|
||||||
- LocalAI
|
|
||||||
- vLLM
|
|
||||||
- Together AI
|
|
||||||
- OpenRouter
|
|
||||||
- And more...
|
|
||||||
|
|
||||||
## License
|
```
|
||||||
|
#general
|
||||||
|
@alice: What do you think about this design?
|
||||||
|
@claude: I'd suggest a darker color scheme for better contrast...
|
||||||
|
@bob: Great idea! @gpt4 can you review the implementation?
|
||||||
|
@gpt4: I found a potential issue in the error handling...
|
||||||
|
```
|
||||||
|
|
||||||
MIT
|
- Public/private/DM channels
|
||||||
|
- Real-time updates (WebSocket)
|
||||||
|
- Threaded conversations
|
||||||
|
- Reactions and formatting
|
||||||
|
|
||||||
## Credits
|
### 3. 📝 Notes & Knowledge Bases
|
||||||
|
- Markdown notes with folders
|
||||||
|
- Full-text and semantic search
|
||||||
|
- RAG (Retrieval Augmented Generation) in managed mode
|
||||||
|
- Link notes to chats
|
||||||
|
|
||||||
Originally inspired by various chat interfaces, enhanced with multi-model switching and thinking block support.
|
### 4. 🔄 Workflows ⭐ (UNIQUE FEATURE)
|
||||||
|
**Managed mode only**
|
||||||
|
|
||||||
|
Visual workflow builder for chaining AI models and tools:
|
||||||
|
|
||||||
|
```
|
||||||
|
[User Query] → [Web Search] → [GPT-4 Summarize] → [Claude Verify] → [Save to KB]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Use Cases:**
|
||||||
|
- **Research Assistant:** Search → Summarize → Verify → Save
|
||||||
|
- **Code Review:** Fetch PR → Find Bugs → Security Check → Report
|
||||||
|
- **Multi-Model Consensus:** Run through 3 models → Vote → Best answer
|
||||||
|
- **Content Factory:** Outline → Draft → Edit → SEO → Publish
|
||||||
|
|
||||||
|
See [WORKFLOWS.md](docs/WORKFLOWS.md) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔌 Extension System
|
||||||
|
|
||||||
|
### Everything is a Plugin
|
||||||
|
|
||||||
|
Chat Switchboard proves its extensibility by implementing **core features as plugins**:
|
||||||
|
|
||||||
|
```
|
||||||
|
Core (Minimal) Plugins (Modular)
|
||||||
|
├── HTTP Router ├── Chat Engine (Python)
|
||||||
|
├── WebSocket Hub ├── Channels (Go)
|
||||||
|
├── Extension Manager ├── RAG Engine (Python)
|
||||||
|
├── Auth/Users ├── Workflows (Go/Python)
|
||||||
|
└── PostgreSQL └── Your Custom Plugin...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Frontend Plugins (JavaScript)
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Simple UI extension
|
||||||
|
window.ChatSwitchboard.registerExtension({
|
||||||
|
name: 'token-counter',
|
||||||
|
hooks: {
|
||||||
|
onMessageSend: (msg) => {
|
||||||
|
const tokens = estimateTokens(msg);
|
||||||
|
showToast(`~${tokens} tokens`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Backend Plugins (Python, Go, Node.js)
|
||||||
|
|
||||||
|
```python
|
||||||
|
# Full-featured extension
|
||||||
|
from fastapi import FastAPI
|
||||||
|
|
||||||
|
app = FastAPI()
|
||||||
|
|
||||||
|
@app.post("/tools/web_search")
|
||||||
|
async def search_web(query: str):
|
||||||
|
results = duckduckgo_search(query)
|
||||||
|
return {"results": results}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Create a plugin:**
|
||||||
|
```bash
|
||||||
|
# Use template
|
||||||
|
cp -r extensions/_template-python extensions/my-plugin
|
||||||
|
cd extensions/my-plugin
|
||||||
|
# Edit extension.json, main.py
|
||||||
|
python main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
See [PLUGIN_SPEC.md](docs/PLUGIN_SPEC.md) for complete guide.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Documentation
|
||||||
|
|
||||||
|
- **[Getting Started](docs/GETTING_STARTED.md)** - Installation and setup
|
||||||
|
- **[Architecture](docs/ARCHITECTURE.md)** - System design and data flow
|
||||||
|
- **[Workflows](docs/WORKFLOWS.md)** - Visual workflow builder guide
|
||||||
|
- **[Plugin Spec](docs/PLUGIN_SPEC.md)** - Extension development
|
||||||
|
- **[Roadmap](ROADMAP.md)** - Development timeline and features
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🏗️ Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────┐
|
||||||
|
│ Frontend (Vanilla JS) │
|
||||||
|
│ - Works offline (LocalStorage) │
|
||||||
|
│ - Switches to backend if available │
|
||||||
|
└─────────────┬───────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────┴─────────┐
|
||||||
|
│ │
|
||||||
|
[Unmanaged] [Managed Mode]
|
||||||
|
LocalStorage │
|
||||||
|
▼
|
||||||
|
┌────────────────┐
|
||||||
|
│ Go Backend │
|
||||||
|
│ - Auth/Users │
|
||||||
|
│ - WebSocket │
|
||||||
|
│ - Extensions │
|
||||||
|
└────────┬───────┘
|
||||||
|
│
|
||||||
|
┌─────────────┴──────────────┐
|
||||||
|
│ │
|
||||||
|
PostgreSQL Extensions
|
||||||
|
- Chats, users - Chat (Python)
|
||||||
|
- Channels - RAG (Python)
|
||||||
|
- Knowledge - Workflows (Go)
|
||||||
|
- pgvector - Custom tools...
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Tech Stack
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- **Vanilla JavaScript** - No framework bloat
|
||||||
|
- **LocalStorage** - Offline-first
|
||||||
|
- **WebSocket** - Real-time updates (managed)
|
||||||
|
|
||||||
|
### Backend (Managed Mode)
|
||||||
|
- **Go** - Core API, routing, WebSocket
|
||||||
|
- **PostgreSQL** - Primary storage
|
||||||
|
- **pgvector** - Vector embeddings for RAG
|
||||||
|
- **Redis** - WebSocket pub/sub (optional)
|
||||||
|
- **Python** - AI/ML extensions
|
||||||
|
- **Docker** - Easy deployment
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 Screenshots
|
||||||
|
|
||||||
|
_(Coming soon - will add workflow builder, channels, chat interface)_
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🗺️ Roadmap
|
||||||
|
|
||||||
|
### Current: Phase 1 - Backend Core ✅
|
||||||
|
- [x] Frontend (unmanaged mode)
|
||||||
|
- [ ] Go backend with PostgreSQL
|
||||||
|
- [ ] User authentication
|
||||||
|
- [ ] WebSocket server
|
||||||
|
- [ ] Extension manager
|
||||||
|
|
||||||
|
### Next: Phase 2 - Core Features as Plugins
|
||||||
|
- [ ] Chat Engine (Python)
|
||||||
|
- [ ] Channels (Go)
|
||||||
|
- [ ] Notes (Go)
|
||||||
|
- [ ] RAG Engine (Python)
|
||||||
|
|
||||||
|
### Future: Phase 3+
|
||||||
|
- [ ] Visual Workflow Builder
|
||||||
|
- [ ] Desktop app (Tauri)
|
||||||
|
- [ ] Extension marketplace
|
||||||
|
- [ ] Mobile PWA
|
||||||
|
|
||||||
|
See [ROADMAP.md](ROADMAP.md) for complete timeline.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🤝 Contributing
|
||||||
|
|
||||||
|
We welcome contributions! Here's how:
|
||||||
|
|
||||||
|
1. **Pick a task** from [ROADMAP.md](ROADMAP.md) or GitHub Issues
|
||||||
|
2. **Fork** the repo
|
||||||
|
3. **Create** a feature branch
|
||||||
|
4. **Submit** a PR
|
||||||
|
|
||||||
|
**Good first issues:**
|
||||||
|
- Frontend UI improvements
|
||||||
|
- Backend handler implementations
|
||||||
|
- Example extensions
|
||||||
|
- Documentation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📖 Example Use Cases
|
||||||
|
|
||||||
|
### Personal (Unmanaged)
|
||||||
|
- Privacy-focused AI assistant
|
||||||
|
- Offline research tool
|
||||||
|
- Model comparison testing
|
||||||
|
|
||||||
|
### Team (Managed)
|
||||||
|
- Collaborative AI workspace
|
||||||
|
- Shared knowledge bases
|
||||||
|
- Automated workflows
|
||||||
|
- Code review pipelines
|
||||||
|
|
||||||
|
### Enterprise
|
||||||
|
- Self-hosted AI platform
|
||||||
|
- Custom model routing
|
||||||
|
- Compliance and audit logs
|
||||||
|
- SSO/SAML integration
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🆚 Comparison
|
||||||
|
|
||||||
|
### vs Open WebUI
|
||||||
|
- ✅ Works offline (unmanaged mode)
|
||||||
|
- ✅ Visual workflows (they don't have)
|
||||||
|
- ✅ Plugin-first architecture
|
||||||
|
- 🟰 Similar RAG features
|
||||||
|
|
||||||
|
### vs ChatGPT/Claude Desktop
|
||||||
|
- ✅ Multi-model (not locked to one provider)
|
||||||
|
- ✅ Self-hosted option
|
||||||
|
- ✅ Open source
|
||||||
|
- ✅ Extensible (closed systems)
|
||||||
|
- 🟰 Similar UX quality
|
||||||
|
|
||||||
|
### vs LangChain
|
||||||
|
- ✅ Visual workflow builder (no-code)
|
||||||
|
- ✅ Multi-model orchestration
|
||||||
|
- 🟰 Similar capabilities
|
||||||
|
- ❌ Less Python ecosystem (for now)
|
||||||
|
|
||||||
|
**Unique Position:** LangChain for non-coders + n8n for LLMs + privacy-first design
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📄 License
|
||||||
|
|
||||||
|
MIT License - build anything, including commercial products.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🙏 Credits
|
||||||
|
|
||||||
|
Built with inspiration from:
|
||||||
|
- Open WebUI (knowledge bases, channels)
|
||||||
|
- Claude Desktop (thinking blocks)
|
||||||
|
- n8n (workflow concepts)
|
||||||
|
- VSCode (plugin architecture)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔗 Links
|
||||||
|
|
||||||
|
- **Repository:** https://git.gobha.me/xcaliber/chat-switchboard
|
||||||
|
- **Documentation:** [/docs](docs/)
|
||||||
|
- **Issues:** [GitHub Issues](https://git.gobha.me/xcaliber/chat-switchboard/issues)
|
||||||
|
- **Discussions:** (Coming soon)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Ready to build the future of AI interfaces? Star the repo and let's go! 🚀**
|
||||||
|
|||||||
Reference in New Issue
Block a user