From 51b058616025e53f0559d7f6612b482a5484288a Mon Sep 17 00:00:00 2001 From: xcaliber Date: Tue, 3 Feb 2026 23:12:51 +0000 Subject: [PATCH] Update README with comprehensive project overview --- README.md | 415 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 330 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 1667d98..5f5df16 100644 --- a/README.md +++ b/README.md @@ -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 `` 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! πŸš€**