智能AI工作流

Prerequisites

• Deno runtime
• uv package manager
• A model API key (Anthropic) or a local inference endpoint (Ollama, etc.)

Install

git clone https://github.com/haileyok/victrola.git
cd victrola
uv sync --frozen

Usage

uv run python main.py serve  # web interface at http://localhost:8000
uv run python main.py main   # headless; runs the scheduler + Discord bot only

All commands accept --model-api, --model-name, --model-api-key, --model-endpoint to override config at launch.

Configuration

Copy .env.example to .env and fill in. Minimal setup for Anthropic:

MODEL_API=anthropic
MODEL_API_KEY=sk-ant-...
MODEL_NAME=claude-sonnet-4-5-20250929

For local Ollama (Gemma 4, etc.):

MODEL_API=openapi
MODEL_ENDPOINT=http://localhost:11434/v1
MODEL_NAME=gemma4:26b-moe
MODEL_API_KEY=ollama      # Ollama ignores the value; just can't be empty

Sub-agent (used by summarize and anything else that needs a lighter model) defaults to the same key as the main model if left empty:

SUB_MODEL_API=anthropic
SUB_MODEL_NAME=claude-haiku-4-5-20251001

Umans AI (optional)

Umans AI is a subscription-based inference provider with an Anthropic-compatible endpoint. To use it:

MODEL_API=umans
MODEL_API_KEY=sk-...
MODEL_NAME=umans-glm-5.2

Available models include umans-glm-5.2, umans-kimi-k2.7, umans-coder, and umans-flash.

Embeddings (optional)

Embeddings (for memory search and RAG recall) use a local Ollama instance:

EMBEDDING_ENDPOINT=http://localhost:11434
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_DIMENSIONS=768

If Ollama isn't running, memory writes store NULL embeddings and searches fall back to keyword-only.

Discord chat (optional)

You can chat with the agent from Discord in addition to the web interface. Each thread in a dedicated channel is a chat session.

Setup (one-time):

1. discord.com/developers/applications → New Application → "Victrola" 2. Bot tab → Reset Token → copy (save as DISCORD_BOT_TOKEN secret in the web interface) 3. Bot tab → Privileged Gateway Intents → enable "Message Content Intent" (required — otherwise the bot can't read message text) 4. OAuth2 → URL Generator: - Scopes: bot - Bot Permissions (principle of least privilege): - View Channel - Read Message History - Create Public Threads - Send Messages in Threads - Visit the generated URL → pick your server → Authorize 5. In your server, create a text channel (default name victrola-sessions — configurable via DISCORD_SESSIONS_CHANNEL in .env)

Usage:

• Post a top-level message in the channel → the bot creates a thread from that message and the agent responds inside.
• Or create a thread yourself (with any first message) → the agent responds in the thread.
• Reply in an existing thread to continue that session.
• Only the agent's final text response appears in the thread. Tool activity (TypeScript the agent writes + tool results) is hidden from Discord to keep threads readable — use the web interface if you want to review that.

The bot only starts when DISCORD_BOT_TOKEN is configured. Without it the web interface and scheduler still run normally.

Signal chat (optional)

You can chat with the agent from Signal in addition to the web interface. Signal becomes the default notification channel when configured — scheduled task results and notify.send calls route there automatically.

Requires signal-cli-rest-api running as an external service. This is a REST wrapper around signal-cli that victrola polls for incoming messages and uses to send responses.

Setup:

1. Run signal-cli-rest-api via Docker:

   docker run -d \
     -e MODE=normal \
     -p 8080:8080 \
     -v ./signal-cli-config:/home/.local/share/signal-cli \
     bbernhard/signal-cli-rest-api:latest
   

1. Register a new Signal account (or link to an existing one via QR code). A dedicated phone number for the bot is simplest — see the signal-cli-rest-api docs for registration/linking details.

3. Configure .env:

   SIGNAL_SERVICE=127.0.0.1:8080
   SIGNAL_BOT_PHONE=+1234567890
   SIGNAL_OPERATOR_PHONE=+0987654321
   

1. Restart victrola. The bot polls for messages every ~2 seconds and maintains a single persistent chat session (signal-persistent) that survives restarts.

Usage:

• Send a Signal message to the bot's number — the agent processes it and responds via Signal.
• The session is persistent: conversation history and compaction state survive restarts.
• Long responses are chunked into multiple messages at ~1900 chars.
• Image attachments are supported (ephemeral — not persisted to the conversation store).
• The agent's notify.signal and notify.send tools work independently of the chat loop, so you can send notifications even when the bot isn't running.

Custom endpoint

Override the Umans API base URL if needed:

UMANS_ENDPOINT=https://api.code.umans.ai

terminal 2 — frontend dev server (hot reload, proxies /api to :8000)

cd web && npm run dev ```

The Vite dev server runs at http://localhost:5173 with API requests proxied to the backend on port 8000. For production, build the frontend (cd web && npm run build) and it will be served directly by FastAPI at http://localhost:8000.