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

Changeset 0.5.0 (#35)

Browse Source
This commit is contained in:
xcaliber
2026-02-19 15:03:20 +00:00
parent a93a6b9635
commit 30d0c11219
65 changed files with 5345 additions and 8070 deletions
Download Patch File Download Diff File Expand all files Collapse all files

424
README.md
View File

@@ -1,360 +1,192 @@
# 🔀 Chat Switchboard
**The Plugin-First, Multi-Model AI Platform**
**Multi-Model AI Chat Platform — Self-Hosted, Extensible, Fast**
Chat Switchboard is a next-generation AI interface that works offline or managed, with a unique plugin architecture and visual workflow builder.
A self-hosted AI chat interface that routes conversations across multiple LLM providers. Built with a Go backend for performance and a clean vanilla JS frontend inspired by Open WebUI.
[![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/)
[![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8?logo=go)](https://go.dev/)
---
## 🎯 What Makes Us Different
## What It Does
| 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
- **Multi-provider routing** — Connect OpenAI, Anthropic, Venice.ai, Ollama, or any OpenAI-compatible API. Switch models per-conversation.
- **Streaming responses** — SSE-based streaming with stop button, thinking block display, and full markdown rendering.
- **Per-user API keys** — Each user manages their own provider keys. Admins can set global keys shared across the instance.
- **Admin panel** — User management, global provider config, model visibility, registration toggle, usage stats.
- **Self-hosted** — Single Docker image, PostgreSQL backend. No external dependencies at runtime.
---
## 🚀 Quick Start
## Quick Start
### Option 1: Offline Mode (No Backend)
### Docker (Recommended)
```bash
# 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
```
**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
# Clone repo
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
cd chat-switchboard
# Configure
cp .env.example .env
# Edit .env with your settings
# Start with Docker
cp server/.env.example server/.env
# Edit .env: set DATABASE_URL, JWT_SECRET, etc.
docker-compose up -d
# Access at http://localhost:3000
```
See [GETTING_STARTED.md](docs/GETTING_STARTED.md) for detailed instructions.
Access at `http://localhost:3000`. First registered user becomes admin.
---
### Manual
## ✨ Core Features
### 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)
### 2. 👥 Channels (User → User + AI)
**Managed mode only**
Multi-user chat rooms where you can @mention AI models:
```
#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...
```
- Public/private/DM channels
- Real-time updates (WebSocket)
- Threaded conversations
- Reactions and formatting
### 3. 📝 Notes & Knowledge Bases
- Markdown notes with folders
- Full-text and semantic search
- RAG (Retrieval Augmented Generation) in managed mode
- Link notes to chats
### 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
# Backend
cd server
cp .env.example .env
go build -o switchboard .
./switchboard
# Frontend — serve src/ with any HTTP server
cd ../src
python3 -m http.server 8080
```
See [PLUGIN_SPEC.md](docs/PLUGIN_SPEC.md) for complete guide.
Point the frontend at the backend by setting the API base URL (defaults to same-origin).
---
## 📚 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
## 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...
┌──────────────────────────┐
│ Frontend (Vanilla JS) │
│ 4 files + vendor libs │
│ No build step required │
└───────────┬──────────────┘
│ REST + SSE
▼
┌──────────────────────────┐
│ Go Backend │
│ ├── Auth (JWT + refresh)│
│ ├── Chat CRUD │
│ ├── Completion proxy │
│ ├── Provider management │
│ ├── Admin endpoints │
│ └── Static file server │
└───────────┬──────────────┘
│
PostgreSQL
```
---
### Frontend (src/)
## 🛠️ Tech Stack
| File | Size | Purpose |
|------|------|---------|
| `api.js` | 240 lines | HTTP client, token management, auto-refresh on 401 |
| `app.js` | 490 lines | State, init flow, auth, chat CRUD, event wiring |
| `ui.js` | 510 lines | DOM rendering, streaming, modals, formatting |
| `debug.js` | 550 lines | Console/network intercept, state inspector (Ctrl+Shift+L) |
| `vendor/` | 62KB | marked.js + DOMPurify (local, CDN fallback) |
### Frontend
- **Vanilla JavaScript** - No framework bloat
- **LocalStorage** - Offline-first
- **WebSocket** - Real-time updates (managed)
No framework. No build step. No node_modules. Works in disconnected (SCIF) environments with vendor libs baked in.
### 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
### Backend (server/)
Go 1.22, ~26 source files. Key packages:
- `handlers/` — Auth, chats, messages, completions, API configs, admin
- `middleware/` — JWT auth, admin role check, rate limiting, error handling, logging
- `providers/` — OpenAI and Anthropic adapters with streaming support
- `models/` — Database models
- `database/` — PostgreSQL connection + migration runner
- `config/` — Environment-based configuration
### API Surface
| Route | Method | Auth | Description |
|-------|--------|------|-------------|
| `/health` | GET | — | Health check + version |
| `/api/v1/auth/register` | POST | — | Create account |
| `/api/v1/auth/login` | POST | — | Get JWT tokens |
| `/api/v1/auth/refresh` | POST | — | Rotate access token |
| `/api/v1/chats` | GET/POST | ✓ | List / create chats |
| `/api/v1/chats/:id` | GET/PUT/DELETE | ✓ | Chat CRUD |
| `/api/v1/chats/:id/messages` | GET | ✓ | Message history |
| `/api/v1/chat/completions` | POST | ✓ | Streaming SSE or sync JSON |
| `/api/v1/models/enabled` | GET | ✓ | Available models |
| `/api/v1/api-configs` | GET/POST/DELETE | ✓ | User provider management |
| `/api/v1/profile` | GET/PUT | ✓ | User profile |
| `/api/v1/settings` | GET/PUT | ✓ | User settings (persisted) |
| `/api/v1/admin/*` | various | admin | User/provider/model/settings management |
---
## 🎨 Screenshots
## Configuration
_(Coming soon - will add workflow builder, channels, chat interface)_
All via environment variables (see `server/.env.example`):
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Backend listen port |
| `DATABASE_URL` | — | PostgreSQL connection string |
| `JWT_SECRET` | — | Token signing key |
| `JWT_EXPIRY` | `15m` | Access token TTL |
| `REFRESH_EXPIRY` | `7d` | Refresh token TTL |
| `CORS_ORIGINS` | `*` | Allowed origins |
| `REGISTRATION_ENABLED` | `true` | Allow new signups |
---
## 🗺️ Roadmap
## Deployment
### Current: Phase 1 - Backend Core ✅
- [x] Frontend (unmanaged mode)
- [ ] Go backend with PostgreSQL
- [ ] User authentication
- [ ] WebSocket server
- [ ] Extension manager
### Docker Compose (unified)
### Next: Phase 2 - Core Features as Plugins
- [ ] Chat Engine (Python)
- [ ] Channels (Go)
- [ ] Notes (Go)
- [ ] RAG Engine (Python)
The provided `Dockerfile` is a 3-stage build:
1. `golang:1.22-bookworm` — compiles Go backend
2. `node:20-alpine` — downloads vendor JS libs via `npm pack`
3. `nginx:1-alpine` — serves frontend, proxies `/api/` to Go backend
### Future: Phase 3+
- [ ] Visual Workflow Builder
- [ ] Desktop app (Tauri)
- [ ] Extension marketplace
- [ ] Mobile PWA
Vendor libs are baked into the image at build time — no CDN access needed at runtime (SCIF-safe).
See [ROADMAP.md](ROADMAP.md) for complete timeline.
### Reverse Proxy
If running behind nginx/Caddy, proxy `/api/` and `/health` to the Go backend. Serve `src/` as static files.
---
## 🤝 Contributing
## Development
We welcome contributions! Here's how:
```bash
# Backend (hot reload with air)
cd server
go install github.com/air-verse/air@latest
air
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
# Frontend — just edit files, hard-refresh browser
# Debug: Ctrl+Shift+L opens debug modal
```
**Good first issues:**
- Frontend UI improvements
- Backend handler implementations
- Example extensions
- Documentation
### Database Migrations
Migrations in `migrations/` run automatically on startup. Current schema:
- `001_full_schema.sql` — users, chats, messages, api_configs
- `002_refresh_tokens.sql` — token rotation
- `003_global_settings.sql` — admin settings table
- `004_model_configs.sql` — per-model enable/disable
---
## 📖 Example Use Cases
## Roadmap
### Personal (Unmanaged)
- Privacy-focused AI assistant
- Offline research tool
- Model comparison testing
See [ROADMAP.md](ROADMAP.md) for the full plan. Next up:
### 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
1. **WebSocket hub** — real-time message delivery, typing indicators
2. **Channels** — multi-user + AI chat rooms with @mentions
3. **Plugin system** — Go-native extensions, installable via admin UI
4. **Notes & Knowledge Base** — markdown notes, document upload, RAG via pgvector
---
## 🆚 Comparison
## License
### 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
MIT — build anything, including commercial products.
---
## 📄 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! 🚀**
**Repository:** https://git.gobha.me/xcaliber/chat-switchboard