switchboard/core
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Releases 9 Wiki Activity

Update README with comprehensive project overview

Browse Source
This commit is contained in:
xcaliber
2026-02-03 23:12:51 +00:00
parent 20a96111ea
commit 51b0586160
1 changed files with 330 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

415
README.md
View File

@@ -1,115 +1,360 @@
# 🔀 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
- **Thinking Blocks**: Collapsible `<thinking>` tags with distinct styling
- **Streaming Responses**: Real-time token streaming with stop button
- **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
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?logo=go)](https://go.dev/)
[![Python Version](https://img.shields.io/badge/Python-3.9+-3776AB?logo=python)](https://python.org/)
## 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
# Build the single-file version
# Clone and build
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
cd chat-switchboard
./build.sh
# Open in browser
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
# Serve src/ directory for development
python3 -m http.server 8080 --directory src
```
# Clone repo
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
```
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
# Start with Docker
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 |
|-----|-------------|
| `chatSwitchboard_settings` | API endpoint, model, parameters |
| `chatSwitchboard_models` | Cached model list |
| `chatSwitchboard_chats` | Chat history |
## ✨ Core Features
## 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
- Anthropic (via proxy)
- Ollama (`http://localhost:11434/v1`)
- LM Studio
- LocalAI
- vLLM
- Together AI
- OpenRouter
- And more...
Multi-user chat rooms where you can @mention AI models:
## 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! 🚀**