1 line
44 KiB
JSON
1 line
44 KiB
JSON
{"repo": "a-c-i-software-and-development/m.u.s.e", "files": {"recovered-agent-sources/device-consolidation-2026-07-12/working-tree-overlays/private-jarvis-branch/.env.example": {"bb78a5bf1c4373672a949056d256c75cc3165945": {"t": 1785595289.518871, "n": 23017, "h": "2735c5faa53001b1", "c": "# JARVIS Prime Environment Configuration\n# Copy this file to .env and fill in your API keys\n\n# =============================================================================\n# LLM PROVIDER (OpenRouter)\n# =============================================================================\n# OpenRouter provides access to many models through one API\n# All LLM calls go through OpenRouter - no direct provider keys needed\n# Get your key at: https://openrouter.ai/keys\n# OPENROUTER_API_KEY=\n\n# Default model is configured in ~/.hermes/config.yaml (model.default).\n# Use 'hermes model' or 'hermes setup' to change it.\n# LLM_MODEL is no longer read from .env — this line is kept for reference only.\n# LLM_MODEL=anthropic/claude-opus-4.6\n\n# =============================================================================\n# LLM PROVIDER (NovitaAI)\n# =============================================================================\n# NovitaAI — 90+ models, pay-per-use\n# Get your key at: https://novita.ai/settings/key-management\n# NOVITA_API_KEY=\n# NOVITA_BASE_URL=https://api.novita.ai/openai/v1 # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (Google AI Studio / Gemini)\n# =============================================================================\n# Native Gemini API via Google's OpenAI-compatible endpoint.\n# Get your key at: https://aistudio.google.com/app/apikey\n# GOOGLE_API_KEY=your_google_ai_studio_key_here\n# GEMINI_API_KEY=your_gemini_key_here # alias for GOOGLE_API_KEY\n# Optional base URL override (default: Google's OpenAI-compatible endpoint)\n# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai\n\n# =============================================================================\n# LLM PROVIDER (Ollama Cloud)\n# =============================================================================\n# Cloud-hosted open models via Ollama's OpenAI-compatible endpoint.\n# Get your key at: https://ollama.com/settings\n# OLLAMA_API_KEY=your_ollama_key_here\n# Optional base URL override (default: https://ollama.com/v1)\n# OLLAMA_BASE_URL=https://ollama.com/v1\n\n# =============================================================================\n# LLM PROVIDER (z.ai / GLM)\n# =============================================================================\n# z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)\n# Get your key at: https://z.ai or https://open.bigmodel.cn\n# GLM_API_KEY=\n# GLM_BASE_URL=https://api.z.ai/api/paas/v4 # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (Kimi / Moonshot)\n# =============================================================================\n# Kimi Code provides access to Moonshot AI coding models (kimi-k2.5, etc.)\n# Get your key at: https://platform.kimi.ai (Kimi Code console)\n# Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.\n# Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.\n# KIMI_API_KEY=\n# KIMI_BASE_URL=https://api.kimi.com/coding/v1 # Default for sk-kimi- keys\n# KIMI_BASE_URL=https://api.moonshot.ai/v1 # For legacy Moonshot keys\n# KIMI_BASE_URL=https://api.moonshot.cn/v1 # For Moonshot China keys\n# KIMI_CN_API_KEY= # Dedicated Moonshot China key\n\n# =============================================================================\n# LLM PROVIDER (Arcee AI)\n# =============================================================================\n# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)\n# Get an Arcee key at: https://chat.arcee.ai/\n# ARCEEAI_API_KEY=\n# ARCEE_BASE_URL= # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (MiniMax)\n# =============================================================================\n# MiniMax provides access to MiniMax models (global endpoint)\n# Get your key at: https://www.minimax.io\n# MINIMAX_API_KEY=\n# MINIMAX_BASE_URL=https://api.minimax.io/v1 # Override default base URL\n\n# MiniMax China endpoint (for users in mainland China)\n# MINIMAX_CN_API_KEY=\n# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1 # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (OpenCode Zen)\n# =============================================================================\n# OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)\n# Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth\n# OPENCODE_ZEN_API_KEY=\n# OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1 # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (OpenCode Go)\n# =============================================================================\n# OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)\n# $10/month subscription. Get your key at: https://opencode.ai/auth\n# OPENCODE_GO_API_KEY=\n\n# =============================================================================\n# LLM PROVIDER (Hugging Face Inference Providers)\n# =============================================================================\n# Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint.\n# Free tier included ($0.10/month), no markup on provider rates.\n# Get your token at: https://huggingface.co/settings/tokens\n# Required permission: \"Make calls to Inference Providers\"\n# HF_TOKEN=\n# OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1 # Override default base URL\n\n# =============================================================================\n# LLM PROVIDER (Qwen OAuth)\n# =============================================================================\n# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).\n# No API key needed — credentials come from ~/.qwen/oauth_creds.json.\n# Optional base URL override:\n# HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1\n\n# =============================================================================\n# LLM PROVIDER (Xiaomi MiMo)\n# =============================================================================\n# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).\n# Get your key at: https://platform.xiaomimimo.com\n# XIAOMI_API_KEY=your_key_here\n# Optional base URL override:\n# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1\n\n# =============================================================================\n# TOOL API KEYS\n# =============================================================================\n\n# Exa API Key - AI-native web search and contents\n# Get at: https://exa.ai\n# EXA_API_KEY=\n\n# Parallel API Key - AI-native web search and extract\n# Get at: https://parallel.ai\n# PARALLEL_API_KEY=\n\n# Firecrawl API Key - Web search, extract, and crawl\n# Get at: https://firecrawl.dev/\n# FIRECRAWL_API_KEY=\n\n\n# FAL.ai API Key - Image generation\n# Get at: https://fal.ai/\n# FAL_KEY=\n\n# Honcho - Cross-session AI-native user modeling (optional)\n# Builds a persistent understanding of the user across sessions and tools.\n# Get at: https://app.honcho.dev\n# Also requires ~/.honcho/config.json with enabled=true (see README).\n# HONCHO_API_KEY=\n\n# =============================================================================\n# HYPERLIQUID OPTIONAL SKILL\n# =============================================================================\n# Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid\n#\n# Hyperliquid API base URL override\n# Default: https://api.hyperliquid.xyz\n# HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz\n#\n# Default address for account-level commands like state, fills, orders, and review\n# HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000\n\n# =============================================================================\n# TERMINAL TOOL CONFIGURATION\n# =============================================================================\n# Backend type: \"local\", \"singularity\", \"docker\", \"modal\", or \"ssh\"\n# Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).\n# Use 'hermes setup' or 'hermes config set terminal.backend docker' to change.\n# Supported: local, docker, singularity, modal, ssh\n#\n# Only override here if you need to force a backend without touching config.yaml:\n# TERMINAL_ENV=local\n\n# Override the container runtime binary (e.g. to use Podman instead of Docker).\n# Useful on systems where Docker's storage driver is broken or unavailable.\n# HERMES_DOCKER_BINARY=/usr/local/bin/podman\n\n# Container images (for singularity/docker/modal backends)\n# TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20\n# TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20\nTERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20\n\n\n# Working directory for terminal commands\n# For local backend: \".\" means current directory (resolved automatically)\n# For remote backends (ssh/docker/modal/singularity): use an absolute path\n# INSIDE the target environment, or leave unset for the backend's default\n# (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path.\n# Usually managed by config.yaml (terminal.cwd) — uncomment to override\n# TERMINAL_CWD=.\n\n# Default command timeout in seconds\nTERMINAL_TIMEOUT=60\n\n# Cleanup inactive environments after this many seconds\nTERMINAL_LIFETIME_SECONDS=300\n\n# =============================================================================\n# SSH REMOTE EXECUTION (for TERMINAL_ENV=ssh)\n# =============================================================================\n# Run terminal commands on a remote server via SSH.\n# Agent code stays on your machine, commands execute remotely.\n#\n# SECURITY BENEFITS:\n# - Agent cannot read your .env file (API keys protected)\n# - Agent cannot modify its own code\n# - Remote server acts as isolated sandbox\n# - Can safely configure passwordless sudo on remote\n#\n# TERMINAL_SSH_HOST=192.168.1.100\n# TERMINAL_SSH_USER=agent\n# TERMINAL_SSH_PORT=22\n# TERMINAL_SSH_KEY=~/.ssh/id_rsa\n\n# =============================================================================\n# SUDO SUPPORT (works with ALL terminal backends)\n# =============================================================================\n# If set, enables sudo commands by piping password via `sudo -S`.\n# Works with: local, docker, singularity, modal, and ssh backends.\n# \n# SECURITY WARNING: Password stored in plaintext. Only use on trusted machines.\n# \n# ALTERNATIVES:\n# - For SSH backend: Configure passwordless sudo on the remote server\n# - For containers: Run as root inside the container (no sudo needed)\n# - For local: Configure /etc/sudoers for specific commands\n# - For CLI: Leave unset - you'll be prompted interactively with 45s timeout\n#\n# SUDO_PASSWORD=your_password_here\n\n# =============================================================================\n# MODAL CLOUD BACKEND (Optional - for TERMINAL_ENV=modal)\n# =============================================================================\n# Modal uses CLI authentication, not environment variables.\n# Run: pip install modal && modal setup\n# This will authenticate via browser and store credentials locally.\n# No API key needed in .env - Modal handles auth automatically.\n\n# =============================================================================\n# BROWSER TOOL CONFIGURATION (agent-browser + Browserbase)\n# =============================================================================\n# Browser automation requires Browserbase cloud service for remote browser execution.\n# This allows the agent to navigate websites, fill forms, and extract information.\n#\n# STEALTH MODES:\n# - Basic Stealth: ALWAYS active (random fingerprints, auto CAPTCHA solving)\n# - Advanced Stealth: Requires BROWSERBASE_ADVANCED_STEALTH=true (Scale Plan only)\n\n# Browserbase API Key - Cloud browser execution\n# Get at: https://browserbase.com/\n# BROWSERBASE_API_KEY=\n\n# Browserbase Project ID - From your Browserbase dashboard\n# BROWSERBASE_PROJECT_ID=\n\n# Enable residential proxies for better CAPTCHA solving (default: true)\n# Routes traffic through residential IPs, significantly improves success rate\nBROWSERBASE_PROXIES=true\n\n# Enable advanced stealth mode (default: false, requires Scale Plan)\n# Uses custom Chromium build to avoid bot detection altogether\nBROWSERBASE_ADVANCED_STEALTH=false\n\n# Browser engine for local mode (default: auto = Chrome)\n# \"auto\" — use Chrome (don't pass --engine flag)\n# \"lightpanda\" — use Lightpanda (1.3-5.8x faster navigation, no screenshots)\n# \"chrome\" — explicitly request Chrome\n# Requires agent-browser v0.25.3+. Lightpanda commands that fail or return\n# empty results are automatically retried with Chrome.\n# Also configurable via browser.engine in config.yaml.\n# AGENT_BROWSER_ENGINE=auto\n\n# Browser session timeout in seconds (default: 300)\n# Sessions are cleaned up after this duration of inactivity\nBROWSER_SESSION_TIMEOUT=300\n\n# Browser inactivity timeout - auto-cleanup inactive sessions (default: 120 = 2 min)\n# Browser sessions are automatically closed after this period of no activity\nBROWSER_INACTIVITY_TIMEOUT=120\n\n# Extra Chromium launch flags passed to agent-browser, comma- or newline-separated.\n# Hermes auto-injects \"--no-sandbox,--disable-dev-shm-usage\" when it detects root\n# or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark,\n# many container images), so leave this unset unless you need extra flags.\n# Setting this disables the auto-injection.\n# AGENT_BROWSER_ARGS=--no-sandbox\n\n# Camofox local anti-detection browser (Camoufox-based Firefox).\n# Set CAMOFOX_URL to route the browser tools through a local Camofox server\n# instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md.\n# CAMOFOX_URL=http://localhost:9377\n\n# Externally managed Camofox sessions — when another app owns the visible\n# Camofox browser, set these so Hermes shares the same userId/profile instead\n# of creating its own isolated session.\n# CAMOFOX_USER_ID=\n# CAMOFOX_SESSION_KEY=\n# Set to true to reuse an already-open Camofox tab for this identity before\n# creating a new one (useful for gateway restarts).\n# CAMOFOX_ADOPT_EXISTING_TAB=false\n\n# =============================================================================\n# SESSION LOGGING\n# =============================================================================\n# Session trajectories are automatically saved to logs/ directory\n# Format: logs/session_YYYYMMDD_HHMMSS_UUID.json\n# Contains full conversation history in trajectory format for debugging/replay\n\n# =============================================================================\n# VOICE TRANSCRIPTION & OPENAI TTS\n# =============================================================================\n# Required for voice message transcription (Whisper) and OpenAI TTS voices.\n# Uses OpenAI's API directly (not via OpenRouter).\n# Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.\n# Get at: https://platform.openai.com/api-keys\n# VOICE_TOOLS_OPENAI_KEY=\n\n# =============================================================================\n# SLACK INTEGRATION\n# =============================================================================\n# Slack Bot Token - From Slack App settings (OAuth & Permissions)\n# Get at: https://api.slack.com/apps\n# SLACK_BOT_TOKEN=xoxb-...\n\n# Slack App Token - For Socket Mode (App-Level Tokens in Slack App settings)\n# SLACK_APP_TOKEN=xapp-...\n\n# Slack allowed users (comma-separated Slack user IDs)\n# SLACK_ALLOWED_USERS=\n\n# =============================================================================\n# TELEGRAM INTEGRATION\n# =============================================================================\n# Telegram Bot Token - From @BotFather (https://t.me/BotFather)\n# TELEGRAM_BOT_TOKEN=\n# TELEGRAM_ALLOWED_USERS= # Comma-separated user IDs\n# TELEGRAM_HOME_CHANNEL= # Default chat for cron delivery\n# TELEGRAM_HOME_CHANNEL_NAME= # Display name for home channel\n# TELEGRAM_CRON_THREAD_ID= # Forum topic ID for cron deliveries; overrides TELEGRAM_HOME_CHANNEL_THREAD_ID for cron so replies work in topic mode\n\n# Webhook mode (optional — for cloud deployments like Fly.io/Railway)\n# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.\n# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram\n# TELEGRAM_WEBHOOK_PORT=8443\n# TELEGRAM_WEBHOOK_SECRET= # Recommended for production\n\n# WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair)\n# WHATSAPP_ENABLED=false\n# WHATSAPP_ALLOWED_USERS=15551234567\n\n# Email (IMAP/SMTP — send and receive emails as Hermes)\n# For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords\n# EMAIL_ADDRESS=hermes@gmail.com\n# EMAIL_PASSWORD=xxxx xxxx xxxx xxxx\n# EMAIL_IMAP_HOST=imap.gmail.com\n# EMAIL_IMAP_PORT=993\n# EMAIL_SMTP_HOST=smtp.gmail.com\n# EMAIL_SMTP_PORT=587\n# EMAIL_POLL_INTERVAL=15\n# EMAIL_ALLOWED_USERS=your@email.com\n# EMAIL_HOME_ADDRESS=your@email.com\n\n# Gateway-wide: allow ALL users without an allowlist (default: false = deny)\n# Only set to true if you intentionally want open access.\n# GATEWAY_ALLOW_ALL_USERS=false\n\n# =============================================================================\n# RESPONSE PACING\n# =============================================================================\n# Human-like delays between message chunks on messaging platforms.\n# Makes the bot feel less robotic.\n# HERMES_HUMAN_DELAY_MODE=off # off | natural | custom\n# HERMES_HUMAN_DELAY_MIN_MS=800 # Min delay in ms (custom mode)\n# HERMES_HUMAN_DELAY_MAX_MS=2500 # Max delay in ms (custom mode)\n\n# =============================================================================\n# DEBUG OPTIONS\n# =============================================================================\nWEB_TOOLS_DEBUG=false\nVISION_TOOLS_DEBUG=false\nMOA_TOOLS_DEBUG=false\nIMAGE_TOOLS_DEBUG=false\n\n# =============================================================================\n# CONTEXT COMPRESSION (Auto-shrinks long conversations)\n# =============================================================================\n# When conversation approaches model's context limit, middle turns are\n# automatically summarized to free up space.\n#\n# Context compression is configured in ~/.hermes/config.yaml under compression:\n# CONTEXT_COMPRESSION_ENABLED=true # Enable auto-compression (default: true)\n# CONTEXT_COMPRESSION_THRESHOLD=0.85 # Compress at 85% of context limit\n# Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview)\n\n# =============================================================================\n# SKILLS HUB (GitHub integration for skill search/install/publish)\n# =============================================================================\n\n# GitHub Personal Access Token — for higher API rate limits on skill search/install\n# Get at: https://github.com/settings/tokens (Fine-grained recommended)\n# GITHUB_TOKEN=github-token-placeholder\n\n# GitHub App credentials (optional — for bot identity on PRs)\n# GITHUB_APP_ID=\n# GITHUB_APP_PRIVATE_KEY_PATH=\n# GITHUB_APP_INSTALLATION_ID=\n\n# Groq API key (free tier — used for Whisper STT in voice mode)\n# GROQ_API_KEY=\n\n# =============================================================================\n# STT PROVIDER SELECTION\n# =============================================================================\n# Default STT provider is \"local\" (faster-whisper) — runs on your machine, no API key needed.\n# Install with: pip install faster-whisper\n# Model downloads automatically on first use (~150 MB for \"base\").\n# To use cloud providers instead, set GROQ_API_KEY or VOICE_TOOLS_OPENAI_KEY above.\n# Provider priority: local > groq > openai\n# Configure in config.yaml: stt.provider: local | groq | openai\n\n# =============================================================================\n# STT ADVANCED OVERRIDES (optional)\n# =============================================================================\n# Override default STT models per provider (normally set via stt.model in config.yaml)\n# STT_GROQ_MODEL=whisper-large-v3-turbo\n# STT_OPENAI_MODEL=whisper-1\n\n# Override STT provider endpoints (for proxies or self-hosted instances)\n# GROQ_BASE_URL=https://api.groq.com/openai/v1\n# STT_OPENAI_BASE_URL=https://api.openai.com/v1\n\n# =============================================================================\n# MICROSOFT TEAMS INTEGRATION\n# =============================================================================\n# Register a Bot in Azure: https://dev.botframework.com/ → \"Register a bot\"\n# Or use Azure Portal: Azure Active Directory → App registrations → New registration\n# Then add the bot to Teams via the Bot Framework or App Studio.\n#\n# TEAMS_CLIENT_ID= # Azure AD App (client) ID\n# TEAMS_CLIENT_SECRET= # Azure AD client secret value\n# TEAMS_TENANT_ID= # Azure AD tenant ID (or \"common\" for multi-tenant)\n# TEAMS_ALLOWED_USERS= # Comma-separated AAD object IDs or UPNs\n# TEAMS_ALLOW_ALL_USERS=false # Set true to skip the allowlist\n# TEAMS_HOME_CHANNEL= # Default channel/chat ID for cron delivery\n# TEAMS_HOME_CHANNEL_NAME= # Display name for the home channel\n# TEAMS_PORT=3978 # Webhook listen port (Bot Framework default)\n\n# =============================================================================\n# GOOGLE CHAT INTEGRATION\n# =============================================================================\n# Connects via Cloud Pub/Sub pull subscription (no public URL required).\n# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.\n# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.\n# 2. Create a Service Account with roles/pubsub.subscriber on the\n# subscription (NOT project-wide); download the JSON key.\n# 3. Configure your Chat app at console.cloud.google.com/apis/credentials\n# → Google Chat API → Configuration → Cloud Pub/Sub topic.\n# 4. (Optional, for native attachment delivery) Each user runs\n# `/setup-files` once in their own DM after Pub/Sub is wired up.\n#\n# GOOGLE_CHAT_PROJECT_ID= # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)\n# GOOGLE_CHAT_SUBSCRIPTION_NAME= # Full path: projects/<id>/subscriptions/<name>\n# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON= # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)\n# GOOGLE_CHAT_ALLOWED_USERS= # Comma-separated emails allowed to talk to the bot\n# GOOGLE_CHAT_ALLOW_ALL_USERS=false # Set true to skip the allowlist\n# GOOGLE_CHAT_HOME_CHANNEL= # Default space (spaces/XXXX) for cron delivery\n# GOOGLE_CHAT_HOME_CHANNEL_NAME= # Display name for the home channel\n"}}, "hermes_cli/local_models/dspark.py": {"bb78a5bf1c4373672a949056d256c75cc3165945": {"t": 1785746646.4075994, "n": 9894, "h": "2b560ac4f1abe8fb", "c": "\"\"\"DSpark speculative-decoding launch plans (DeepSeek + PKU, MIT).\n\nDSpark (arXiv:2606.19348, open-sourced 2026-06-27 in\nhttps://github.com/deepseek-ai/DeepSpec) attaches a small block-drafting\nmodule to a target model so the target verifies several drafted tokens per\nforward pass — 60-85% faster generation with *identical* output quality.\nThis module turns that into launch plans for the runtimes Muse already\nknows, following the ``server_adapters`` contract: **plans only, nothing is\nexecuted or downloaded here**.\n\nThree serving paths, fastest-to-adopt first:\n\n1. **DeepSeek API** — nothing to install. ``api.deepseek.com`` has served\n V4-Flash/V4-Pro with DSpark server-side since 2026-06-27; routing to the\n ``deepseek`` provider already gets the speedup.\n2. **llama.cpp** — community GGUF conversions of the official draft models\n ride the existing ``--spec-draft-*`` flags (same flag family\n ``jarvis_prime.llama_client.SpecDecodeConfig`` verified).\n3. **vLLM** — speculators-format conversions ride ``--speculative-config``;\n the self-contained ``DeepSeek-V4-*-DSpark`` checkpoints serve directly.\n\nThe draft catalog below mirrors DeepSpec's released checkpoints (Qwen3\n4B/8B/14B, Gemma4-12B) plus the vLLM-ready conversions published alongside.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport re\nfrom dataclasses import dataclass\nfrom typing import Optional\n\nfrom hermes_cli.jarvis_prime.llama_client import SpecDecodeConfig\nfrom hermes_cli.local_models.server_adapters import LaunchPlan, get_adapter\n\n\n# DSpark's deployed configuration drafts 5 tokens per verify step\n# (\"DSpark-5\" in the paper); llama.cpp draft windows are tuned separately\n# via SpecDecodeConfig defaults.\nDEFAULT_NUM_SPECULATIVE_TOKENS = 5\n\n\n@dataclass(frozen=True)\nclass DsparkDraft:\n \"\"\"One official DSpark draft model and its runtime-ready conversions.\"\"\"\n\n family: str # normalized target family key, e.g. \"qwen3-8b\"\n target_hf: str # verified target checkpoint on Hugging Face\n draft_hf: str # official DeepSpec draft (safetensors)\n draft_gguf: str = \"\" # community GGUF conversion — llama.cpp path\n draft_speculators: str = \"\" # speculators-format conversion — vLLM path\n\n @property\n def tokens(self) -> frozenset[str]:\n return frozenset(self.family.split(\"-\"))\n\n\n# Official DeepSpec draft checkpoints (deepseek-ai, MIT) and the\n# runtime-ready conversions verified on Hugging Face as of 2026-07-02.\nOFFICIAL_DRAFTS: tuple[DsparkDraft, ...] = (\n DsparkDraft(\n family=\"qwen3-4b\",\n target_hf=\"Qwen/Qwen3-4B\",\n draft_hf=\"deepseek-ai/dspark_qwen3_4b_block7\",\n ),\n DsparkDraft(\n family=\"qwen3-8b\",\n target_hf=\"Qwen/Qwen3-8B\",\n draft_hf=\"deepseek-ai/dspark_qwen3_8b_block7\",\n draft_gguf=\"ankk98/dspark-qwen3-8b-block7-Q4_K_M-GGUF\",\n draft_speculators=\"mgoin/Qwen3-8B-speculator.dspark\",\n ),\n DsparkDraft(\n family=\"qwen3-14b\",\n target_hf=\"Qwen/Qwen3-14B\",\n draft_hf=\"deepseek-ai/dspark_qwen3_14b_block7\",\n ),\n DsparkDraft(\n family=\"gemma4-12b\",\n target_hf=\"google/gemma-4-12B-it\",\n draft_hf=\"deepseek-ai/dspark_gemma4_12b_block7\",\n draft_gguf=\"ankk98/dspark-gemma4-12b-block7-Q4_0-GGUF\",\n ),\n)\n\n# Self-contained DSpark checkpoints — target weights with the draft module\n# already attached. vLLM serves these directly, no --speculative-config.\n# Server-class hardware (V4 is a ~671B/889B-param MoE family).\nDSPARK_CHECKPOINTS: dict[str, str] = {\n \"deepseek-v4-flash\": \"deepseek-ai/DeepSeek-V4-Flash-DSpark\",\n \"deepseek-v4-pro\": \"deepseek-ai/DeepSeek-V4-Pro-DSpark\",\n}\n\n\n_SPLIT = re.compile(r\"[^a-z0-9.]+\")\n\n\ndef _norm_tokens(model: str) -> set[str]:\n \"\"\"Tokenize a model ref for family matching.\n\n Handles HF ids (\"Qwen/Qwen3-8B\"), Ollama refs (\"qwen3:8b\"), and GGUF\n paths (\"~/models/qwen3-8b-instruct-Q4_K_M.gguf\") alike. Size tokens keep\n their ``b`` suffix so \"8b\" can't match \"80b\". Adjacent tokens are also\n merged so spelled-out generations match the family keys (\"gemma-4\" and\n \"gemma4\" both yield \"gemma4\", \"qwen-3\" yields \"qwen3\").\n \"\"\"\n name = model.rsplit(\"/\", 1)[-1].lower()\n name = name.removesuffix(\".gguf\")\n parts = [t for t in _SPLIT.split(name) if t]\n tokens = set(parts)\n tokens.update(a + b for a, b in zip(parts, parts[1:]))\n return tokens\n\n\ndef resolve_draft(model: str) -> Optional[DsparkDraft]:\n \"\"\"The official DSpark draft for ``model``, or ``None`` if not covered.\"\"\"\n tokens = _norm_tokens(model)\n for draft in OFFICIAL_DRAFTS:\n if draft.tokens <= tokens:\n return draft\n return None\n\n\ndef resolve_checkpoint(model: str) -> Optional[str]:\n \"\"\"The self-contained DSpark checkpoint for a DeepSeek-V4 ref, if any.\"\"\"\n if \"deepseek\" not in model.lower():\n return None\n tokens = _norm_tokens(model)\n for family, checkpoint in DSPARK_CHECKPOINTS.items():\n # \"v4\" and the variant (\"flash\"/\"pro\") must both appear.\n if set(family.split(\"-\")) - {\"deepseek\"} <= tokens:\n return checkpoint\n return None\n\n\ndef build_dspark_plan(\n model: str,\n *,\n runtime: Optional[str] = None,\n port: Optional[int] = None,\n draft: Optional[str] = None,\n num_speculative_tokens: int = DEFAULT_NUM_SPECULATIVE_TOKENS,\n) -> LaunchPlan:\n \"\"\"A DSpark-accelerated launch plan for ``model``.\n\n ``runtime`` may be ``\"llama.cpp\"`` or ``\"vllm\"``; when omitted it is\n inferred (GGUF path → llama.cpp, else first installed of vllm/llama.cpp,\n else vllm). ``draft`` overrides the draft-model ref — for llama.cpp it\n should be a local GGUF path once downloaded.\n \"\"\"\n checkpoint = resolve_checkpoint(model)\n resolved = resolve_draft(model)\n\n if runtime is None:\n if model.lower().endswith(\".gguf\"):\n runtime = \"llama.cpp\"\n elif checkpoint is not None:\n runtime = \"vllm\"\n else:\n installed = [r for r in (\"vllm\", \"llama.cpp\") if get_adapter(r).is_installed()]\n runtime = installed[0] if installed else \"vllm\"\n\n key = runtime.strip().lower()\n if key == \"llama.cpp\":\n return _llamacpp_plan(model, resolved, draft=draft, port=port)\n if key == \"vllm\":\n return _vllm_plan(\n model,\n resolved,\n checkpoint=checkpoint,\n draft=draft,\n port=port,\n num_speculative_tokens=num_speculative_tokens,\n )\n raise KeyError(f\"dspark runtime must be 'llama.cpp' or 'vllm', got {runtime!r}\")\n\n\ndef _llamacpp_plan(\n model: str,\n resolved: Optional[DsparkDraft],\n *,\n draft: Optional[str],\n port: Optional[int],\n) -> LaunchPlan:\n adapter = get_adapter(\"llama.cpp\")\n draft_ref = draft or (resolved.draft_gguf if resolved else \"\")\n if not draft_ref:\n known = \", \".join(d.family for d in OFFICIAL_DRAFTS if d.draft_gguf)\n return LaunchPlan(\n runtime=\"dspark\",\n command=(),\n base_url=adapter.base_url(port),\n notes=(\n f\"No GGUF DSpark draft known for {model!r} (GGUF drafts exist for: \"\n f\"{known}). Pass draft= with a local draft GGUF, or use the vllm \"\n \"runtime with the safetensors draft.\"\n ),\n )\n spec = SpecDecodeConfig(draft_model_path=draft_ref)\n base = adapter.launch_plan(model, port=port)\n pull: tuple[str, ...] = ()\n if \"/\" in draft_ref and not draft_ref.lower().endswith(\".gguf\"):\n pull = (\"huggingface-cli\", \"download\", draft_ref)\n return LaunchPlan(\n runtime=\"dspark\",\n command=base.command + spec.to_server_args(),\n base_url=base.base_url,\n pull_command=pull,\n notes=(\n \"llama.cpp speculative decoding with the DSpark draft; flag family \"\n \"verified in jarvis_prime.llama_client. Draft must be a local GGUF \"\n \"path at launch — the pull_command downloads it (consent-gated).\"\n ),\n )\n\n\ndef _vllm_plan(\n model: str,\n resolved: Optional[DsparkDraft],\n *,\n checkpoint: Optional[str],\n draft: Optional[str],\n port: Optional[int],\n num_speculative_tokens: int,\n) -> LaunchPlan:\n adapter = get_adapter(\"vllm\")\n if checkpoint is not None:\n base = adapter.launch_plan(checkpoint, port=port)\n return LaunchPlan(\n runtime=\"dspark\",\n command=base.command,\n base_url=base.base_url,\n notes=(\n f\"{checkpoint} ships with the DSpark draft module attached — vLLM \"\n \"serves it directly (no --speculative-config). Server-class GPUs \"\n \"required; V4 is a large MoE family.\"\n ),\n )\n draft_ref = draft or (\n (resolved.draft_speculators or resolved.draft_hf) if resolved else \"\"\n )\n if not draft_ref:\n known = \", \".join(d.family for d in OFFICIAL_DRAFTS)\n return LaunchPlan(\n runtime=\"dspark\",\n command=(),\n base_url=adapter.base_url(port),\n notes=(\n f\"No DSpark draft known for {model!r} (official drafts cover: \"\n f\"{known}). Pass draft= with a draft-model ref, or train one with \"\n \"DeepSpec (github.com/deepseek-ai/DeepSpec).\"\n ),\n )\n spec_config = json.dumps(\n {\"model\": draft_ref, \"num_speculative_tokens\": num_speculative_tokens}\n )\n base = adapter.launch_plan(model, port=port)\n return LaunchPlan(\n runtime=\"dspark\",\n command=base.command + (\"--speculative-config\", spec_config),\n base_url=base.base_url,\n notes=(\n \"vLLM speculative decoding with the DSpark draft. speculators-format \"\n \"drafts (…-speculator.dspark) auto-detect the method; for raw DeepSpec \"\n \"drafts check your vLLM version's DSpark support.\"\n ),\n )\n"}, "e5100cda2a53313493493227be71352e0f22c125": {"t": 1785766543.1384976, "n": 9894, "h": "2b560ac4f1abe8fb", "c": "\"\"\"DSpark speculative-decoding launch plans (DeepSeek + PKU, MIT).\n\nDSpark (arXiv:2606.19348, open-sourced 2026-06-27 in\nhttps://github.com/deepseek-ai/DeepSpec) attaches a small block-drafting\nmodule to a target model so the target verifies several drafted tokens per\nforward pass — 60-85% faster generation with *identical* output quality.\nThis module turns that into launch plans for the runtimes Muse already\nknows, following the ``server_adapters`` contract: **plans only, nothing is\nexecuted or downloaded here**.\n\nThree serving paths, fastest-to-adopt first:\n\n1. **DeepSeek API** — nothing to install. ``api.deepseek.com`` has served\n V4-Flash/V4-Pro with DSpark server-side since 2026-06-27; routing to the\n ``deepseek`` provider already gets the speedup.\n2. **llama.cpp** — community GGUF conversions of the official draft models\n ride the existing ``--spec-draft-*`` flags (same flag family\n ``jarvis_prime.llama_client.SpecDecodeConfig`` verified).\n3. **vLLM** — speculators-format conversions ride ``--speculative-config``;\n the self-contained ``DeepSeek-V4-*-DSpark`` checkpoints serve directly.\n\nThe draft catalog below mirrors DeepSpec's released checkpoints (Qwen3\n4B/8B/14B, Gemma4-12B) plus the vLLM-ready conversions published alongside.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport re\nfrom dataclasses import dataclass\nfrom typing import Optional\n\nfrom hermes_cli.jarvis_prime.llama_client import SpecDecodeConfig\nfrom hermes_cli.local_models.server_adapters import LaunchPlan, get_adapter\n\n\n# DSpark's deployed configuration drafts 5 tokens per verify step\n# (\"DSpark-5\" in the paper); llama.cpp draft windows are tuned separately\n# via SpecDecodeConfig defaults.\nDEFAULT_NUM_SPECULATIVE_TOKENS = 5\n\n\n@dataclass(frozen=True)\nclass DsparkDraft:\n \"\"\"One official DSpark draft model and its runtime-ready conversions.\"\"\"\n\n family: str # normalized target family key, e.g. \"qwen3-8b\"\n target_hf: str # verified target checkpoint on Hugging Face\n draft_hf: str # official DeepSpec draft (safetensors)\n draft_gguf: str = \"\" # community GGUF conversion — llama.cpp path\n draft_speculators: str = \"\" # speculators-format conversion — vLLM path\n\n @property\n def tokens(self) -> frozenset[str]:\n return frozenset(self.family.split(\"-\"))\n\n\n# Official DeepSpec draft checkpoints (deepseek-ai, MIT) and the\n# runtime-ready conversions verified on Hugging Face as of 2026-07-02.\nOFFICIAL_DRAFTS: tuple[DsparkDraft, ...] = (\n DsparkDraft(\n family=\"qwen3-4b\",\n target_hf=\"Qwen/Qwen3-4B\",\n draft_hf=\"deepseek-ai/dspark_qwen3_4b_block7\",\n ),\n DsparkDraft(\n family=\"qwen3-8b\",\n target_hf=\"Qwen/Qwen3-8B\",\n draft_hf=\"deepseek-ai/dspark_qwen3_8b_block7\",\n draft_gguf=\"ankk98/dspark-qwen3-8b-block7-Q4_K_M-GGUF\",\n draft_speculators=\"mgoin/Qwen3-8B-speculator.dspark\",\n ),\n DsparkDraft(\n family=\"qwen3-14b\",\n target_hf=\"Qwen/Qwen3-14B\",\n draft_hf=\"deepseek-ai/dspark_qwen3_14b_block7\",\n ),\n DsparkDraft(\n family=\"gemma4-12b\",\n target_hf=\"google/gemma-4-12B-it\",\n draft_hf=\"deepseek-ai/dspark_gemma4_12b_block7\",\n draft_gguf=\"ankk98/dspark-gemma4-12b-block7-Q4_0-GGUF\",\n ),\n)\n\n# Self-contained DSpark checkpoints — target weights with the draft module\n# already attached. vLLM serves these directly, no --speculative-config.\n# Server-class hardware (V4 is a ~671B/889B-param MoE family).\nDSPARK_CHECKPOINTS: dict[str, str] = {\n \"deepseek-v4-flash\": \"deepseek-ai/DeepSeek-V4-Flash-DSpark\",\n \"deepseek-v4-pro\": \"deepseek-ai/DeepSeek-V4-Pro-DSpark\",\n}\n\n\n_SPLIT = re.compile(r\"[^a-z0-9.]+\")\n\n\ndef _norm_tokens(model: str) -> set[str]:\n \"\"\"Tokenize a model ref for family matching.\n\n Handles HF ids (\"Qwen/Qwen3-8B\"), Ollama refs (\"qwen3:8b\"), and GGUF\n paths (\"~/models/qwen3-8b-instruct-Q4_K_M.gguf\") alike. Size tokens keep\n their ``b`` suffix so \"8b\" can't match \"80b\". Adjacent tokens are also\n merged so spelled-out generations match the family keys (\"gemma-4\" and\n \"gemma4\" both yield \"gemma4\", \"qwen-3\" yields \"qwen3\").\n \"\"\"\n name = model.rsplit(\"/\", 1)[-1].lower()\n name = name.removesuffix(\".gguf\")\n parts = [t for t in _SPLIT.split(name) if t]\n tokens = set(parts)\n tokens.update(a + b for a, b in zip(parts, parts[1:]))\n return tokens\n\n\ndef resolve_draft(model: str) -> Optional[DsparkDraft]:\n \"\"\"The official DSpark draft for ``model``, or ``None`` if not covered.\"\"\"\n tokens = _norm_tokens(model)\n for draft in OFFICIAL_DRAFTS:\n if draft.tokens <= tokens:\n return draft\n return None\n\n\ndef resolve_checkpoint(model: str) -> Optional[str]:\n \"\"\"The self-contained DSpark checkpoint for a DeepSeek-V4 ref, if any.\"\"\"\n if \"deepseek\" not in model.lower():\n return None\n tokens = _norm_tokens(model)\n for family, checkpoint in DSPARK_CHECKPOINTS.items():\n # \"v4\" and the variant (\"flash\"/\"pro\") must both appear.\n if set(family.split(\"-\")) - {\"deepseek\"} <= tokens:\n return checkpoint\n return None\n\n\ndef build_dspark_plan(\n model: str,\n *,\n runtime: Optional[str] = None,\n port: Optional[int] = None,\n draft: Optional[str] = None,\n num_speculative_tokens: int = DEFAULT_NUM_SPECULATIVE_TOKENS,\n) -> LaunchPlan:\n \"\"\"A DSpark-accelerated launch plan for ``model``.\n\n ``runtime`` may be ``\"llama.cpp\"`` or ``\"vllm\"``; when omitted it is\n inferred (GGUF path → llama.cpp, else first installed of vllm/llama.cpp,\n else vllm). ``draft`` overrides the draft-model ref — for llama.cpp it\n should be a local GGUF path once downloaded.\n \"\"\"\n checkpoint = resolve_checkpoint(model)\n resolved = resolve_draft(model)\n\n if runtime is None:\n if model.lower().endswith(\".gguf\"):\n runtime = \"llama.cpp\"\n elif checkpoint is not None:\n runtime = \"vllm\"\n else:\n installed = [r for r in (\"vllm\", \"llama.cpp\") if get_adapter(r).is_installed()]\n runtime = installed[0] if installed else \"vllm\"\n\n key = runtime.strip().lower()\n if key == \"llama.cpp\":\n return _llamacpp_plan(model, resolved, draft=draft, port=port)\n if key == \"vllm\":\n return _vllm_plan(\n model,\n resolved,\n checkpoint=checkpoint,\n draft=draft,\n port=port,\n num_speculative_tokens=num_speculative_tokens,\n )\n raise KeyError(f\"dspark runtime must be 'llama.cpp' or 'vllm', got {runtime!r}\")\n\n\ndef _llamacpp_plan(\n model: str,\n resolved: Optional[DsparkDraft],\n *,\n draft: Optional[str],\n port: Optional[int],\n) -> LaunchPlan:\n adapter = get_adapter(\"llama.cpp\")\n draft_ref = draft or (resolved.draft_gguf if resolved else \"\")\n if not draft_ref:\n known = \", \".join(d.family for d in OFFICIAL_DRAFTS if d.draft_gguf)\n return LaunchPlan(\n runtime=\"dspark\",\n command=(),\n base_url=adapter.base_url(port),\n notes=(\n f\"No GGUF DSpark draft known for {model!r} (GGUF drafts exist for: \"\n f\"{known}). Pass draft= with a local draft GGUF, or use the vllm \"\n \"runtime with the safetensors draft.\"\n ),\n )\n spec = SpecDecodeConfig(draft_model_path=draft_ref)\n base = adapter.launch_plan(model, port=port)\n pull: tuple[str, ...] = ()\n if \"/\" in draft_ref and not draft_ref.lower().endswith(\".gguf\"):\n pull = (\"huggingface-cli\", \"download\", draft_ref)\n return LaunchPlan(\n runtime=\"dspark\",\n command=base.command + spec.to_server_args(),\n base_url=base.base_url,\n pull_command=pull,\n notes=(\n \"llama.cpp speculative decoding with the DSpark draft; flag family \"\n \"verified in jarvis_prime.llama_client. Draft must be a local GGUF \"\n \"path at launch — the pull_command downloads it (consent-gated).\"\n ),\n )\n\n\ndef _vllm_plan(\n model: str,\n resolved: Optional[DsparkDraft],\n *,\n checkpoint: Optional[str],\n draft: Optional[str],\n port: Optional[int],\n num_speculative_tokens: int,\n) -> LaunchPlan:\n adapter = get_adapter(\"vllm\")\n if checkpoint is not None:\n base = adapter.launch_plan(checkpoint, port=port)\n return LaunchPlan(\n runtime=\"dspark\",\n command=base.command,\n base_url=base.base_url,\n notes=(\n f\"{checkpoint} ships with the DSpark draft module attached — vLLM \"\n \"serves it directly (no --speculative-config). Server-class GPUs \"\n \"required; V4 is a large MoE family.\"\n ),\n )\n draft_ref = draft or (\n (resolved.draft_speculators or resolved.draft_hf) if resolved else \"\"\n )\n if not draft_ref:\n known = \", \".join(d.family for d in OFFICIAL_DRAFTS)\n return LaunchPlan(\n runtime=\"dspark\",\n command=(),\n base_url=adapter.base_url(port),\n notes=(\n f\"No DSpark draft known for {model!r} (official drafts cover: \"\n f\"{known}). Pass draft= with a draft-model ref, or train one with \"\n \"DeepSpec (github.com/deepseek-ai/DeepSpec).\"\n ),\n )\n spec_config = json.dumps(\n {\"model\": draft_ref, \"num_speculative_tokens\": num_speculative_tokens}\n )\n base = adapter.launch_plan(model, port=port)\n return LaunchPlan(\n runtime=\"dspark\",\n command=base.command + (\"--speculative-config\", spec_config),\n base_url=base.base_url,\n notes=(\n \"vLLM speculative decoding with the DSpark draft. speculators-format \"\n \"drafts (…-speculator.dspark) auto-detect the method; for raw DeepSpec \"\n \"drafts check your vLLM version's DSpark support.\"\n ),\n )\n"}}}} |