# Requirements: v1.4 Hermes as Default Inference Provider + Web Control Plane **Version:** 1.4 **Status:** Queued **Depends on:** v1.2.0.1 (nxr), v1.2.1 (Universal Skills), v1.3 (Web Chat) **Source PRD:** `~/Downloads/nexus-v1.4-prd.md` --- ## Summary | Category | Count | |----------|-------| | ONBOARD | 8 | | SCORE | 6 | | UPGRADE | 6 | | WEBCP | 14 | | SCAN | 5 | | SKILL | 7 | | NXR | 9 | | DATA | 7 | | **Total** | **62** | --- ## ONBOARD — Free-by-Default Onboarding - [ ] **ONBOARD-01** CLI onboarding (`npx buildthis`) prompts the user to optionally install Hermes Agent, explaining it runs entirely on free models with zero API key required. - [ ] **ONBOARD-02** CLI onboarding detects available local AI capabilities at install time: Ollama (model loaded, GPU/RAM), faster-whisper, and flags their availability in output and in the `onboarding` DB record. - [ ] **ONBOARD-03** When the user accepts Hermes install, onboarding automatically creates three default agents (PM, Engineer, Hermes) with role-appropriate free models assigned via the scoring algorithm. - [ ] **ONBOARD-04** Onboarding output displays each created agent's name, assigned model, model metadata (context window, capabilities), and pre-loaded skillset. - [ ] **ONBOARD-05** The zero-key experience allows all agents to run without an OpenRouter API key using the `openrouter/free` auto-router; free tier rate limits (50 req/day without credits, 1000/day with $10+) are communicated clearly at the end of onboarding. - [ ] **ONBOARD-06** When local Ollama is detected during onboarding, auxiliary tasks (compression, vision, web extract) are automatically configured to route locally at zero cost with no rate limits. - [ ] **ONBOARD-07** The web onboarding wizard (`/setup`) is feature-equivalent to the CLI flow: five steps (workspace name, Hermes install pitch, auto-create agents, optional API key paste, dashboard redirect) and is idempotent with the CLI flow. - [ ] **ONBOARD-08** Running both the CLI onboarding and web wizard produces the same default state and causes no duplication — the `onboarding` table record prevents re-execution. --- ## SCORE — Model Scoring Engine - [ ] **SCORE-01** A deterministic scoring function exists in `nxr` that assigns a numeric score to any free model for a given role using the formula: `(context_length * 0.3) + (has_tools * 30) + (has_reasoning * 20) + (throughput * 0.1)`. - [ ] **SCORE-02** The scoring function filters the `or_model_catalog` to only `is_free = 1 AND is_available = 1` models, applies role requirements (tools support, vision, reasoning, minimum context window), and returns the highest-scoring model for the role. - [ ] **SCORE-03** If no model satisfies the role requirements, the function falls back to `openrouter/free` auto-router; if Ollama is available, local Qwen3.5 9B is the emergency fallback. - [ ] **SCORE-04** The scoring function covers all six role categories: `pm`, `engineer`, `hermes`, `creative`, `research`, and `custom` — each with documented minimum requirements. - [ ] **SCORE-05** Scoring results are persisted to the `model_scores` libSQL table with `model_id`, `role`, composite score, sub-scores (context, tools, reasoning, throughput), `is_free`, and `scored_at` timestamp. - [ ] **SCORE-06** The scoring function is callable from both the `nxr` CLI (`nxr agents rescore`) and from the Go HTTP backend API (`POST /api/models/rescore`), producing identical output for the same catalog state. --- ## UPGRADE — API Key Upgrade Flow - [ ] **UPGRADE-01** `nxr upgrade` (interactive mode) validates the provided OpenRouter API key, detects account balance, and displays the free tier unlock status (50/day → 1000/day). - [ ] **UPGRADE-02** After key validation, `nxr upgrade` presents a per-agent upgrade preview showing each agent's current free model and its recommended paid replacement with price per million tokens and context window. - [ ] **UPGRADE-03** The user can respond `Y` (upgrade all), `n` (store key only, keep free models), or `custom` (per-agent model picker TUI) — each path executes correctly and writes to config atomically. - [ ] **UPGRADE-04** `nxr upgrade --all` upgrades all agents to their recommended paid models non-interactively; `nxr upgrade --agent ""` upgrades a single named agent. - [ ] **UPGRADE-05** `nxr upgrade --revert` switches all agents back to their last-recorded free model assignments; agent memory, skills, and session history are preserved across all upgrade and revert operations. - [ ] **UPGRADE-06** The web agent manager (`/agents/manage`) exposes a "Bulk Upgrade" button and per-agent upgrade controls that call `POST /api/agents/bulk-upgrade` or `GET /api/agents/:id/recommend` respectively, with the same logic as the CLI flow. --- ## WEBCP — Web Control Plane (Nexus Hub) ### Process Control (`/hermes`) - [ ] **WEBCP-01** The `/hermes` page displays live Hermes process status: PID, uptime, current model, and tmux viewer count; data is fetched from `GET /api/hermes/ps`. - [ ] **WEBCP-02** The `/hermes` page provides Start, Stop, and Restart buttons that call `POST /api/hermes/up`, `POST /api/hermes/down`, and `POST /api/hermes/restart` respectively, with visible success/failure feedback. - [ ] **WEBCP-03** The `/hermes` page shows an Ollama status card with loaded model, GPU usage, and throughput when Ollama is available. ### Model Switcher (`/models/switch`) - [ ] **WEBCP-04** The `/models/switch` page renders a visual slot editor showing all 7 routing slots (primary, fallback, simple, vision, web_extract, approval, compression) with their currently assigned models. - [ ] **WEBCP-05** Clicking any slot opens a model picker modal with fuzzy search and filter toggles (free, tools, vision, reasoning, MoE); selecting a model and confirming calls `PUT /api/routing/:slot` and writes `config.yaml` atomically. - [ ] **WEBCP-06** The model picker modal displays a price comparison side panel showing cost per million input/output tokens for the currently selected model vs. the active slot model. ### Agent Manager (`/agents/manage`) - [ ] **WEBCP-07** The `/agents/manage` page lists all agents with per-agent model assignment, role-aware model recommendation (from `GET /api/agents/:id/recommend`), last heartbeat, message count, cost, and error rate. - [ ] **WEBCP-08** The `/agents/manage` page allows skill assignment per agent using category templates, calling `POST /api/agents/:id/skills`. - [ ] **WEBCP-09** The `/agents/manage` page includes a "Create Agent" flow: category picker → auto model assignment → auto skill suggestion → name input → confirm — calling the existing agent creation API with the new `role`, `skillset`, and `model_auto_assigned` fields. ### Budget Dashboard (`/budget`) - [ ] **WEBCP-10** The `/budget` page shows a real-time free tier gauge (requests used / daily limit) sourced from `hermes_tracking.db` usage data. - [ ] **WEBCP-11** The `/budget` page shows per-agent cost breakdown for today, last 7 days, and last 30 days, plus a cost projection graph and a rate limit event log. - [ ] **WEBCP-12** The `/budget` page provides an "Export as CSV" action that downloads the usage data for the selected time range. ### Notifications Center (`/notifications`) - [ ] **WEBCP-13** The `/notifications` page displays all notification types from v1.2.1 plus new v1.4 types: rate limit warnings, agent auto-upgrade events, and model availability alerts; each notification can be marked read via `PUT /api/notifications/:id/read`. - [ ] **WEBCP-14** The `/notifications` page includes per-type Telegram forwarding toggles that persist via `POST /api/notifications/settings`. --- ## SCAN — Scanner Updates - [ ] **SCAN-01** After each 6-hourly OpenRouter catalog scan, the scanner re-scores all free models for every role category using the SCORE-01 algorithm and persists results to `model_scores`. - [ ] **SCAN-02** If a re-score reveals a better free model for an active agent's role, the scanner creates a notification with the old model name, new model name, role, and score delta — plus a one-click upgrade action. - [ ] **SCAN-03** A config flag `auto_upgrade_free_models` in `~/.hermes/config.yaml` (default `false`) controls whether the scanner auto-switches agents to better free models or only notifies. - [ ] **SCAN-04** The scanner queries `model_usage` to compute average free requests per hour for the current day and projects whether the workspace will hit the daily limit before midnight UTC; this projection is surfaced in the dashboard and `nxr budget`. - [ ] **SCAN-05** Rate limit threshold warnings are triggered at 70% (dashboard warning), 90% (Telegram notification if gateway configured), and 100% (agents queue tasks until midnight UTC reset, or route to local Qwen if available). --- ## SKILL — Default Skillsets and Agent Templates - [ ] **SKILL-01** The PM agent is created with exactly 8 pre-loaded skills: `planning`, `task-breakdown`, `prioritization`, `status-reporting`, `dependency-mapping`, `sprint-planning`, `risk-assessment`, `stakeholder-comms`. - [ ] **SKILL-02** The Engineer agent is created with exactly 8 pre-loaded skills: `coding`, `debugging`, `git-workflow`, `testing`, `code-review`, `refactoring`, `architecture`, `documentation`. - [ ] **SKILL-03** The Hermes agent is created with exactly 8 pre-loaded skills: `memory`, `web-search`, `file-ops`, `cron`, `usage-tracker`, `model-scanner`, `skill-creator`, `session-search`. - [ ] **SKILL-04** All agent skill assignments go through Hermes's skill assignment system so that the existing `listSkills`/`syncSkills` adapter API sees the skills correctly. - [ ] **SKILL-05** When creating a custom agent, the user can select a role category (tech, creative, business, research, media, personal); each category has a suggested skill template that pre-populates the skill selector. - [ ] **SKILL-06** Custom category skill templates are defined for all 6 categories: tech (coding, debugging, git-workflow, testing, architecture), creative (creative-writing, screenwriting, worldbuilding, dialogue), business (strategy, proposal-writing, market-analysis, financial-modeling), research (paper-analysis, literature-review, data-analysis, methodology), media (journalism, copywriting, social-media, content-strategy), personal (goal-setting, language-tutoring, fitness, travel-planning). - [ ] **SKILL-07** Skills assigned during onboarding or agent creation are suggestions only — users can add or remove skills freely after creation, and skills from `agentskills.io` are installable via `hermes skills search`. --- ## NXR — nxr Additions - [ ] **NXR-01** `nxr init` runs the interactive onboarding wizard: workspace name, Hermes install prompt, auto-creates PM + Engineer + Hermes with free models, optional API key prompt, and displays the ready summary. - [ ] **NXR-02** `nxr init --free` skips the API key prompt and runs in pure free mode without interactive prompts beyond workspace name. - [ ] **NXR-03** `nxr init --key ` accepts a pre-set API key and uses it during init without prompting. - [ ] **NXR-04** `nxr upgrade` runs the interactive upgrade picker as described in UPGRADE-01 through UPGRADE-03. - [ ] **NXR-05** `nxr upgrade --all` and `nxr upgrade --agent ""` run non-interactively as described in UPGRADE-04. - [ ] **NXR-06** `nxr upgrade --revert` reverts all agents to free models as described in UPGRADE-05. - [ ] **NXR-07** `nxr agents recommend` prints a table showing the recommended model for each agent based on its role, pulled from the scoring algorithm. - [ ] **NXR-08** `nxr agents rescore` re-runs the free model scoring algorithm for all agents and updates `model_scores`; output shows any model changes. - [ ] **NXR-09** `nxr agents create --role --name --free` creates a new agent with auto-selected free model and auto-applied skill template for the given role; TUI Tab 5 gains a "Create Agent" wizard with the same category → model → skills → name flow. --- ## DATA — Data Model Changes - [ ] **DATA-01** The `agents` table in `hermes_tracking.db` gains a `role TEXT` column storing one of: `pm`, `engineer`, `hermes`, `custom`. - [ ] **DATA-02** The `agents` table gains a `skillset TEXT` column storing a JSON array of skill name strings. - [ ] **DATA-03** The `agents` table gains a `model_score REAL DEFAULT 0` column storing the auto-calculated quality score at the time of last model assignment. - [ ] **DATA-04** The `agents` table gains a `model_auto_assigned INTEGER DEFAULT 0` column; value `1` indicates nxr selected the model automatically. - [ ] **DATA-05** The `agents` table gains `workspace_id TEXT` and `is_default INTEGER DEFAULT 0` columns; `is_default = 1` marks agents created during onboarding. - [ ] **DATA-06** A new `model_scores` table is created in `hermes_tracking.db` (libSQL) with columns: `id`, `model_id`, `role`, `score`, `context_score`, `tools_score`, `reasoning_score`, `throughput_score`, `is_free`, `scored_at`; unique constraint on `(model_id, role, scored_at)`; indexes on `role` and `is_free`. - [ ] **DATA-07** A new `onboarding` table is created in `hermes_tracking.db` (libSQL) with columns: `id`, `completed_at`, `workspace_name`, `has_openrouter_key`, `has_ollama`, `has_whisper`, `agents_created` (JSON array of agent IDs), `initial_free_models` (JSON snapshot of model assignments at creation). --- ## Out of Scope The following are explicitly excluded from v1.4 per PRD Section 13: - **Multi-user auth for web dashboard** — single-user, localhost only; future milestone - **Self-hosted model registries beyond Ollama** — future consideration - **Model training or fine-tuning** — models used as-is from OpenRouter - **Auto-spending user money** — free-by-default; paid models require explicit opt-in every time - **Guaranteed free model availability** — scanner detects and adapts when models leave the free tier; no SLA - **WebSocket live terminal stream (`WS /api/hermes/stream`)** — stretch goal; `nxr watch` is the primary observation path; ship without and add later - **Paperclip agent orchestration replacement** — Hermes provides inference, Paperclip provides orchestration; they are complementary - **Blog auto-generation triggers** — PRD Section 11 is informational context for v1.2.1 auto-blogging system; not a v1.4 implementation requirement --- ## Traceability | Requirement | Phase | Status | |-------------|-------|--------| | ONBOARD-01 | Phase 30 | Pending | | ONBOARD-02 | Phase 30 | Pending | | ONBOARD-03 | Phase 30 | Pending | | ONBOARD-04 | Phase 30 | Pending | | ONBOARD-05 | Phase 30 | Pending | | ONBOARD-06 | Phase 30 | Pending | | ONBOARD-07 | Phase 30 | Pending | | ONBOARD-08 | Phase 30 | Pending | | SCORE-01 | Phase 28 | Pending | | SCORE-02 | Phase 28 | Pending | | SCORE-03 | Phase 28 | Pending | | SCORE-04 | Phase 28 | Pending | | SCORE-05 | Phase 28 | Pending | | SCORE-06 | Phase 28 | Pending | | UPGRADE-01 | Phase 31 | Pending | | UPGRADE-02 | Phase 31 | Pending | | UPGRADE-03 | Phase 31 | Pending | | UPGRADE-04 | Phase 31 | Pending | | UPGRADE-05 | Phase 31 | Pending | | UPGRADE-06 | Phase 31 | Pending | | WEBCP-01 | Phase 34 | Pending | | WEBCP-02 | Phase 34 | Pending | | WEBCP-03 | Phase 34 | Pending | | WEBCP-04 | Phase 34 | Pending | | WEBCP-05 | Phase 34 | Pending | | WEBCP-06 | Phase 34 | Pending | | WEBCP-07 | Phase 34 | Pending | | WEBCP-08 | Phase 34 | Pending | | WEBCP-09 | Phase 34 | Pending | | WEBCP-10 | Phase 34 | Pending | | WEBCP-11 | Phase 34 | Pending | | WEBCP-12 | Phase 34 | Pending | | WEBCP-13 | Phase 34 | Pending | | WEBCP-14 | Phase 34 | Pending | | SCAN-01 | Phase 32 | Pending | | SCAN-02 | Phase 32 | Pending | | SCAN-03 | Phase 32 | Pending | | SCAN-04 | Phase 32 | Pending | | SCAN-05 | Phase 32 | Pending | | SKILL-01 | Phase 29 | Pending | | SKILL-02 | Phase 29 | Pending | | SKILL-03 | Phase 29 | Pending | | SKILL-04 | Phase 29 | Pending | | SKILL-05 | Phase 29 | Pending | | SKILL-06 | Phase 29 | Pending | | SKILL-07 | Phase 29 | Pending | | NXR-01 | Phase 30 | Pending | | NXR-02 | Phase 30 | Pending | | NXR-03 | Phase 30 | Pending | | NXR-04 | Phase 31 | Pending | | NXR-05 | Phase 31 | Pending | | NXR-06 | Phase 31 | Pending | | NXR-07 | Phase 33 | Pending | | NXR-08 | Phase 33 | Pending | | NXR-09 | Phase 33 | Pending | | DATA-01 | Phase 27 | Pending | | DATA-02 | Phase 27 | Pending | | DATA-03 | Phase 27 | Pending | | DATA-04 | Phase 27 | Pending | | DATA-05 | Phase 27 | Pending | | DATA-06 | Phase 27 | Pending | | DATA-07 | Phase 27 | Pending |