95d65a1155
Extracted 52 files from Timmy_Foundation/hermes-agent (gitea/main) into hermes-sovereign/ directory to restore clean upstream tracking. Layout: docs/ 19 files — deploy guides, performance reports, security docs, research security/ 5 files — audit workflows, PR checklists, validation scripts wizard-bootstrap/ 7 files — wizard environment, dependency checking, auditing notebooks/ 2 files — Jupyter health monitoring notebooks scripts/ 5 files — forge health, smoke tests, syntax guard, deploy validation ci/ 2 files — Gitea CI workflow definitions githooks/ 3 files — pre-commit hooks and config devkit/ 8 files — developer toolkit (Gitea client, health, notebook runner) README.md 1 file — directory overview Addresses: #337, #338
3.6 KiB
Wizard Environment Contract
Version: 1.0.0 Owner: Wizard Council (Bezalel Epic-004) Last updated: 2026-04-06
This document defines the minimum viable state every forge wizard must maintain. A wizard that satisfies all requirements is considered forge-ready.
1. Python Runtime
| Requirement | Minimum | Notes |
|---|---|---|
| Python version | 3.11 | 3.12+ recommended |
| Virtual environment | Activated | source venv/bin/activate before running |
Run python --version to verify.
2. Core Package Dependencies
All packages in requirements.txt must be installed and importable.
Critical packages: openai, anthropic, pyyaml, rich, requests, pydantic, prompt_toolkit.
Verify:
python wizard-bootstrap/wizard_bootstrap.py
3. LLM Provider Key
At least one LLM provider API key must be set in ~/.hermes/.env:
| Variable | Provider |
|---|---|
OPENROUTER_API_KEY |
OpenRouter (200+ models) |
ANTHROPIC_API_KEY |
Anthropic Claude |
ANTHROPIC_TOKEN |
Anthropic Claude (alt) |
OPENAI_API_KEY |
OpenAI |
GLM_API_KEY |
z.ai/GLM |
KIMI_API_KEY |
Moonshot/Kimi |
MINIMAX_API_KEY |
MiniMax |
4. Gitea Authentication
| Requirement | Details |
|---|---|
| Variable | GITEA_TOKEN or FORGE_TOKEN |
| Scope | Must have repo read/write access |
| Forge URL | https://forge.alexanderwhitestone.com (or FORGE_URL env var) |
The wizard must be able to create and merge PRs on the forge.
5. Telegram Connectivity (Gateway Wizards)
Wizards that operate via the messaging gateway must also satisfy:
| Requirement | Details |
|---|---|
| Variable | TELEGRAM_BOT_TOKEN |
| Home channel | TELEGRAM_HOME_CHANNEL |
| API reachability | api.telegram.org must be reachable |
CLI-only wizards may skip Telegram checks.
6. HERMES_HOME
| Requirement | Details |
|---|---|
| Default | ~/.hermes |
| Override | HERMES_HOME env var |
| Permissions | Owner-writable (700 recommended) |
The directory must exist and be writable before any hermes command runs.
7. Skill Dependencies (Per-Skill)
Each skill may declare binary and environment-variable dependencies in its
SKILL.md frontmatter:
---
name: my-skill
dependencies:
binaries: [ffmpeg, imagemagick]
env_vars: [MY_API_KEY]
---
A wizard must satisfy all dependencies for any skill it intends to run.
Check all skill deps:
python wizard-bootstrap/dependency_checker.py
8. Enforcement
New Wizard Onboarding
Run the bootstrap script before going online:
python wizard-bootstrap/wizard_bootstrap.py
Resolve all failures before beginning work.
Ongoing Compliance
A monthly audit runs automatically (see wizard-bootstrap/monthly_audit.py).
The report is saved to ~/.hermes/wizard-council/audit-YYYY-MM.md and posted
to the wizard-council-automation Telegram channel.
Skill Drift
Run the skills audit to detect and fix drift:
python wizard-bootstrap/skills_audit.py # detect
python wizard-bootstrap/skills_audit.py --fix # sync
9. Contract Versioning
Changes to this contract require a PR reviewed by at least one wizard council member. Bump the version number and update the date above with each change.
Quick Reference
# Full environment validation
python wizard-bootstrap/wizard_bootstrap.py
# Skills drift check
python wizard-bootstrap/skills_audit.py
# Dependency check
python wizard-bootstrap/dependency_checker.py
# Full monthly audit (all three checks, saves report)
python wizard-bootstrap/monthly_audit.py