Files

Alexander Whitestone 95d65a1155 feat: extract sovereign work from hermes-agent fork into sidecar

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

2026-04-07 10:11:20 -04:00

2.2 KiB

Raw Blame History

Notebook Workflow for Agent Tasks

This directory demonstrates a sovereign, version-controlled workflow for LLM agent tasks using Jupyter notebooks.

Philosophy

**.py files are the source of truth** — authored and reviewed as plain Python with # %%` cell markers (via Jupytext)
.ipynb files are generated artifacts — auto-created from .py for execution and rich viewing
Papermill parameterizes and executes — each run produces an output notebook with code, narrative, and results preserved
Output notebooks are audit artifacts — every execution leaves a permanent, replayable record

File Layout

notebooks/
  agent_task_system_health.py      # Source of truth (Jupytext)
  agent_task_system_health.ipynb   # Generated from .py
docs/
  NOTEBOOK_WORKFLOW.md             # This document
.gitea/workflows/
  notebook-ci.yml                  # CI gate: executes notebooks on PR/push

How Agents Work With Notebooks

Create — Agent generates a .py notebook using # %% [markdown] and # %% code blocks
Review — PR reviewers see clean diffs in Gitea (no JSON noise)
Generate — jupytext --to ipynb produces the .ipynb before merge
Execute — Papermill runs the notebook with injected parameters
Archive — Output notebook is committed to a reports/ branch or artifact store

Converting Between Formats

# .py -> .ipynb
jupytext --to ipynb notebooks/agent_task_system_health.py

# .ipynb -> .py
jupytext --to py notebooks/agent_task_system_health.ipynb

# Execute with parameters
papermill notebooks/agent_task_system_health.ipynb output.ipynb \
  -p threshold 1.0 -p hostname forge-vps-01

CI Gate

The notebook-ci.yml workflow executes all notebooks in notebooks/ on every PR and push, ensuring that checked-in notebooks still run and produce outputs.

Why This Matters

Problem	Notebook Solution
Ephemeral agent reasoning	Markdown cells narrate the thought process
Stateless single-turn tools	Stateful cells persist variables across steps
Unreviewable binary artifacts	`.py` source is diffable and PR-friendly
No execution audit trail	Output notebook preserves code + outputs + metadata

2.2 KiB Raw Blame History