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
163 lines
3.6 KiB
Markdown
163 lines
3.6 KiB
Markdown
# 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:**
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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:**
|
|
```bash
|
|
python wizard-bootstrap/dependency_checker.py
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Enforcement
|
|
|
|
### New Wizard Onboarding
|
|
|
|
Run the bootstrap script before going online:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
```
|