@skyphusion/sidvicious-exe 0.2.0

package/README.md

@@ -0,0 +1,230 @@
+# SidVicious_exe
+
+![SidVicious_exe](assets/banner.svg)
+
+**SidVicious_exe** is a punk rock Discord roadie for web search and image generation. Talk to it naturally, ask it to look stuff up, or crank out visuals. Everything runs on the unified Cloudflare API.
+
+> Brand kit: the square mark lives at [`assets/avatar.svg`](assets/avatar.svg); the header above is [`assets/banner.svg`](assets/banner.svg). Both are hand-authored, dependency-free SVG (the editable source). For direct upload to Discord (which needs raster), use [`assets/avatar.png`](assets/avatar.png) as the application icon and [`assets/banner.png`](assets/banner.png) for the header.
+
+The punk personality is intentional. It reflects the author's view of how a good AI roadie should act: direct, honest, useful, and free of corporate sycophancy. No "I'd be happy to help!", no filler, no talking down to people. Just someone with attitude who actually delivers.
+
+We call it a roadie, not a bot. A bot is a vending machine; this is a collaborator with a job to do.
+
+---
+
+## Features
+
+- **Punk rock roadie personality** -- raw, direct, irreverent. Helpful underneath the leather jacket.
+- **Claude via Cloudflare** -- Anthropic SDK pointed at the AI Gateway native Anthropic path (`gateway.ai.cloudflare.com/v1/{account}/{gateway}/anthropic`); ollama fallback when `CF_API_TOKEN` is unset
+- **Vision input** -- paste images into the channel; Claude reads them (up to 3 per message, 4 MB each)
+- **Web search + deep research** -- Brave Search, Tavily, and Cloudflare Browser Rendering via the search Worker
+- **Knowledge base** -- `!learn <text or URL>` indexes references into Vectorize
+- **Image generation** -- Workers AI (FLUX, Phoenix, SDXL) and AI Gateway models (GPT Image, Recraft, and more) via `/ai/run`
+- **D1 session state** -- conversation history persists across restarts (optional)
+- **Slash commands** -- `/image`, `/model`, `/learn`, `/reset`
+
+---
+
+## Architecture
+
+```
+Discord channel
+      |
+   bot.mjs
+      |
+      +-- gateway.ai.cloudflare.com/v1/{id}/{gateway}/anthropic
+      |       --> Claude (anthropic/claude-sonnet-4-6)
+      |
+      +-- api.cloudflare.com/client/v4/accounts/{id}/ai/run
+      |       --> Workers AI + Gateway image models
+      |
+      +-- D1 (optional)        session history
+      |
+      +-- sidvicious-search Worker (optional)
+              web_search, research, fetch_page, knowledge
+
+Chat routes through the AI Gateway (gateway id: skyphusion-llm); one CF_API_TOKEN covers it all.
+```
+
+---
+
+## Install from npm (no clone needed)
+
+```bash
+npx @skyphusion/sidvicious-exe        # or: npm i -g @skyphusion/sidvicious-exe && sidvicious
+```
+
+The package ships the roadie only (`bot.mjs` + `lib/`); configure it with the same env vars
+as below (`.env` in the working directory is honored). **What is NOT on npm:** the
+`search-worker/` Cloudflare Worker -- deploy that from this repo with wrangler and point
+`SEARCH_WORKER_URL` at it (search/knowledge tools stay off without it, everything else
+works). For a long-running deployment prefer the Docker stack below. Behavior contract:
+[docs/BEHAVIOR.md](docs/BEHAVIOR.md); pre-release manual checklist: [docs/SMOKE.md](docs/SMOKE.md).
+
+## Setup
+
+### 1. Discord application
+
+Create an application at the [Discord Developer Portal](https://discord.com/developers/applications):
+
+- Privileged Gateway Intents: **MESSAGE CONTENT** on
+- OAuth2 scopes: `bot`, `applications.commands` (Discord's terminology for app integrations)
+- Permissions: Send Messages, Read Message History, Attach Files
+
+### 2. Cloudflare credentials
+
+```bash
+wrangler whoami          # copy account id -> CF_ACCOUNT_ID
+wrangler auth token      # copy token      -> CF_API_TOKEN
+```
+
+Your API token needs **AI Gateway** permission. Add **D1 Edit** if you want session persistence.
+
+Create a D1 database (optional):
+
+```bash
+wrangler d1 create sidvicious-sessions   # copy id -> CF_D1_DATABASE_ID
+```
+
+### 3. Run the roadie
+
+```bash
+cp .env.example .env     # fill in DISCORD_TOKEN, CF_ACCOUNT_ID, CF_API_TOKEN
+npm install
+npm run roadie
+```
+
+That's it for chat + images. The default gateway name is `skyphusion-llm`.
+
+### 4. Search worker (optional)
+
+```bash
+cd search-worker && npm install
+npx wrangler vectorize create sidvicious-knowledge --dimensions=1024 --metric=cosine
+npx wrangler secret put BRAVE_API_KEY
+npx wrangler secret put TAVILY_API_KEY
+npx wrangler secret put SEARCH_SECRET
+npm run deploy
+```
+
+Add `SEARCH_WORKER_URL` and `SEARCH_SECRET` to your `.env`.
+
+---
+
+## Deployment
+
+Two supported paths: a bind-mount Compose stack (the house pattern on a Docker host) and a
+self-contained Docker image.
+
+### Compose stack (Docker host, bind-mount)
+
+The stack runs `node:24` against the repo bind-mounted at `/app`, doing `npm ci` then
+`node bot.mjs` on every start. Env is wired from `stacks/.env`.
+
+```bash
+# one-time: clone + secrets on the deploy host
+ssh <deploy-user>@<deploy-host> "
+  cd ~/dev && git clone git@github.com:SkyPhusion/SidVicious_exe.git
+  cp ~/dev/SidVicious_exe/.env.example ~/dev/SidVicious_exe/stacks/.env   # then fill it in
+"
+
+# deploy / redeploy after code changes
+rsync -az <repo-checkout>/ <deploy-user>@<deploy-host>:~/dev/SidVicious_exe/ \
+  --exclude node_modules --exclude .git --exclude stacks/.env --exclude .env
+ssh <deploy-user>@<deploy-host> "cd ~/dev/SidVicious_exe/stacks && docker compose -p sidvicious -f compose.prod.yml up -d --force-recreate sidvicious"
+
+# logs
+ssh <deploy-user>@<deploy-host> "docker compose -p sidvicious -f ~/dev/SidVicious_exe/stacks/compose.prod.yml logs -f"
+```
+
+The deploy, redeploy, and logs commands are also kept in the header of `stacks/compose.prod.yml`.
+
+### Standalone image (Dockerfile)
+
+For a buildable, portable image (no repo bind-mount), use the included `Dockerfile`
+(`node:24-slim`, runtime deps only, non-root `node` user):
+
+```bash
+cp .env.example stacks/.env          # fill in values
+docker build -t sidvicious .
+docker run -d --name sidvicious --restart unless-stopped --env-file stacks/.env sidvicious
+docker logs -f sidvicious
+```
+
+---
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DISCORD_TOKEN` | yes | Discord application token |
+| `CF_ACCOUNT_ID` | yes* | Cloudflare account ID |
+| `CF_API_TOKEN` | yes* | API token (alias: `CF_AIG_TOKEN`) |
+| `CF_AIG_GATEWAY_ID` | no | Gateway name (default: `skyphusion-llm`) |
+| `DISCORD_MODEL` | no | Chat model (default: `anthropic/claude-sonnet-4-6`) |
+| `DISCORD_CHANNEL_IDS` | no | Channels to listen in (empty = DMs + @mentions) |
+| `CF_D1_DATABASE_ID` | no | D1 database for session persistence |
+| `SEARCH_WORKER_URL` | no | Search Worker URL |
+| `SEARCH_SECRET` | no | Search Worker auth secret |
+
+\* Omit both `CF_API_TOKEN` and `CF_ACCOUNT_ID` to use ollama instead (chat only, no images).
+
+---
+
+## Commands
+
+| Command | Slash | Description |
+|---------|-------|-------------|
+| `!image <prompt>` | `/image` | Generate an image |
+| `!model [name]` | `/model` | List or switch image model |
+| `!learn <text or URL>` | `/learn` | Index into knowledge base |
+| `!reset` | `/reset` | Clear conversation history |
+
+**Image model aliases:** `flux-schnell`, `flux2-fast`, `flux2`, `flux2-dev`, `phoenix`, `lucid`, `dreamshaper`, `sdxl`, `gpt-image`, `recraft`, `nano-banana`
+
+---
+
+## Ollama fallback
+
+1. Omit `CF_API_TOKEN`.
+2. Set `OLLAMA_BASE_URL` and `DISCORD_MODEL` (e.g. `qwen3:8b`).
+
+Tool use (search, image gen) requires the Cloudflare backend.
+
+## Credits
+
+**Conrad Rockenhaus** ([SkyPhusion](https://github.com/SkyPhusion)) -- direction and wiring. SidVicious_exe is forked from [Slate](https://github.com/skyphusion-labs/slate), with the film/render features stripped out and a punk-rock personality added.
+
+**Claude Sonnet 4.6** (Anthropic) -- operating as *Strummer*, SkyPhusion's AI crew member. Built the shared chat-and-search foundation this fork inherits: CF AI Gateway integration (native Anthropic SDK path), the Anthropic tool-use loop, the Brave + Tavily + CF Browser Rendering search pipeline, the Cloudflare Vectorize knowledge base, Discord vision input, the slash command system, and D1 session persistence. SidVicious_exe keeps that core (chat, image generation, web search, and the knowledge base) and drops the Vivijure-specific pieces. This project is an example of the SkyPhusion AI-collaborative development model -- human vision, AI execution, shipped together.
+
+---
+
+## Who this is for
+
+Discord communities that want a punk-rock AI collaborator (search, images, knowledge base) without the corporate tone. Self-host on Cloudflare; bring your own keys.
+
+## Links
+
+- **Forked from:** [slate](https://github.com/skyphusion-labs/slate) (film stack stripped out)
+- **Skyphusion Labs:** https://skyphusion.org · **Org:** https://github.com/skyphusion-labs
+- **Related:** [prism](https://github.com/skyphusion-labs/prism) (multimodal playground)
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development
+setup, code style (no em-dashes; minimal dependencies), and the PR workflow. Security reports go
+through [SECURITY.md](SECURITY.md), not public issues.
+
+---
+
+## Using SidVicious_exe (Terms & Privacy)
+
+SidVicious_exe is a Discord application that reads message content in the channels it joins. By using it you
+agree to the [Terms of Service](TERMS.md); how it handles your data (and the third-party services
+involved) is described in the [Privacy Policy](PRIVACY.md).
+
+---
+
+## License
+
+AGPL-3.0. See [LICENSE](LICENSE).