# 🔀 Chat Switchboard

**The Plugin-First, Multi-Model AI Platform**

Chat Switchboard is a next-generation AI interface that works offline or managed, with a unique plugin architecture and visual workflow builder.

[![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/)

---

## 🎯 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
# 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
docker-compose up -d

# Access at http://localhost:3000
```

See [GETTING_STARTED.md](docs/GETTING_STARTED.md) for detailed instructions.

---

## ✨ 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
```

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! 🚀**