智能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

Docker (recommended for deployment)

Victrola ships as a single Docker image published to ghcr.io/haileyok/victrola. The image bundles Python, Deno, Playwright Chromium, and the pre-built frontend — everything needed to run the full agent.

Building locally

If you want to build the image yourself instead of pulling from ghcr.io:

```bash docker build -t victrola .

Then reference `image: victrola` in docker-compose.yaml

```

The Dockerfile uses a multi-stage build: Stage 1 compiles the React frontend with Node, Stage 2 assembles the Python runtime with Deno and Playwright Chromium.

Quick start

```bash

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

WORKSPACE_DIR=data/workspace
WORKSPACE_MAX_SIZE_MB=1024

1. Configure

cp .env.example .env

Edit .env — at minimum set MODEL_API, MODEL_API_KEY, MODEL_NAME

Environment

The Docker image sets sensible container defaults: - WEB_HOST=0.0.0.0 (binds all interfaces so the port mapping works) - WEB_PDF_CHROMIUM_NO_SANDBOX=1 (Chromium can't use its namespace sandbox as non-root in a container)

Override anything else in your .env file — model config, Discord/Signal settings, embeddings endpoint, etc.

Optional external services

These are not included in the compose file because they're deployment-specific. If you use them, run them alongside Victrola:

• Ollama (embeddings for memory search / RAG recall): Point EMBEDDING_ENDPOINT at your Ollama instance. If Ollama isn't running, memory degrades gracefully to keyword-only search.
• signal-cli-rest-api (Signal chat): Follow the Signal setup docs and point SIGNAL_SERVICE at it.

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.

Google Meet links (optional)

The agent can create standalone Google Meet links via meet.create_link. This uses the Google Meet REST API (spaces.create) to generate a meeting space and return a meeting_uri like https://meet.google.com/abc-mnop-xyz. The link is standalone — it is not tied to a calendar event, so there is no duplication when the real event lives in Fastmail or another calendar.

Return value: { success, meeting_uri, meeting_code, space_name }. The meeting_uri is the full join URL; meeting_code is the short code (e.g. abc-mnop-xyz); space_name is Google's internal resource ID. Both meeting_code and space_name may be null.

One-time setup:

1. Go to Google Cloud Console → create (or select) a project 2. Enable the Google Meet API (APIs & Services → Library → search "Google Meet") 3. APIs & Services → OAuth consent screen → configure as External, add your email as a test user 4. APIs & Services → Credentials → Create Credentials → OAuth client ID (Application type: Web application). Add https://developers.google.com/oauthplayground as an authorized redirect URI. 5. Obtain a refresh token with the https://www.googleapis.com/auth/meetings.space.created scope. The easiest way is the OAuth Playground: - Click the gear icon (top right) → check "Use your own OAuth credentials" → paste your client ID and secret from step 4 - In the left panel, find "Google Meet API v2" → expand → check meetings.space.created - Click "Authorize APIs" → grant consent → click "Exchange authorization code for tokens" - Copy the refresh_token value 6. In the victrola web interface → Secrets page, add three secrets: - GOOGLE_CLIENT_ID — your OAuth client ID - GOOGLE_CLIENT_SECRET — your OAuth client secret - GOOGLE_REFRESH_TOKEN — the refresh token from step 5

Note on token expiration: If the OAuth consent screen is left in "Testing" status, Google refresh tokens expire after 7 days. For durable use, publish the consent screen (requires verification if using sensitive scopes — but meetings.space.created is non-sensitive, so publishing is straightforward). If links stop working after a week, this is the likely cause.

The agent can now call meet.create_link from execute_code. The optional access_type parameter controls who can join without knocking: - open (default) — anyone with the link can join without knocking - trusted — org members and invited users join without knocking; others must knock - restricted — only invited users join without knocking; everyone else must knock

Troubleshooting: If the tool returns an OAuth error, the refresh token may have expired or been revoked. Re-authorize via the OAuth Playground (step 5) and update the GOOGLE_REFRESH_TOKEN secret.

Compaction (optional)

When a conversation grows too large, older messages are summarized by the sub-agent into a single summary turn. The most recent ~25% of the threshold is kept as raw messages; everything older is replaced with the summary. Compaction checkpoints are persisted to the store, so summaries are reused on reload instead of re-summarizing.

The threshold is configurable in .env:

COMPACT_THRESHOLD_CHARS=240000   # ~60k tokens at ~4 chars/token

Requires a sub-agent LLM (SUB_MODEL_* config). If no sub-agent is configured, compaction is a no-op and conversations grow unbounded.

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.