380012c791
Some checks failed
Architecture Lint / Linter Tests (pull_request) Successful in 22s
Smoke Test / smoke (pull_request) Failing after 22s
Validate Config / YAML Lint (pull_request) Failing after 16s
Validate Config / JSON Validate (pull_request) Successful in 23s
Validate Config / Python Syntax & Import Check (pull_request) Failing after 56s
Validate Config / Python Test Suite (pull_request) Has been skipped
Validate Config / Cron Syntax Check (pull_request) Successful in 11s
Validate Config / Shell Script Lint (pull_request) Failing after 55s
Validate Config / Deploy Script Dry Run (pull_request) Successful in 8s
Validate Config / Playbook Schema Validation (pull_request) Successful in 17s
PR Checklist / pr-checklist (pull_request) Successful in 5m6s
Architecture Lint / Lint Repository (pull_request) Failing after 24s
Extract organizational artifacts from hermes-sovereign/ subdirectory to timmy-config top-level directories for clearer separation of concerns. Moved: - docs/: 19 markdown files from hermes-sovereign/docs/ (DEPLOY.md, SECURITY_AUDIT_REPORT.md, SECURE_CODING_GUIDELINES.md, PERFORMANCE_ANALYSIS_REPORT.md, PERFORMANCE_HOTSPOTS_QUICKREF.md, PERFORMANCE_OPTIMIZATIONS.md, SECURITY_FIXES_CHECKLIST.md, SECURITY_MITIGATION_ROADMAP.md, TEST_ANALYSIS_REPORT.md, TEST_OPTIMIZATION_GUIDE.md, V-006_FIX_SUMMARY.md, and more) - security/: validate_security.py from hermes-sovereign/security/ (creates top-level security/ directory) - wizard-bootstrap/: 7 files from hermes-sovereign/wizard-bootstrap/ (FORGE_OPERATIONS_GUIDE.md, WIZARD_ENVIRONMENT_CONTRACT.md, dependency_checker.py, monthly_audit.py, skills_audit.py, wizard_bootstrap.py, __init__.py) - docs/notebooks/: 2 notebook files from hermes-sovereign/notebooks/ (agent_task_system_health.ipynb, agent_task_system_health.py) Empty source directories (hermes-sovereign/docs/, security/, wizard-bootstrap/, notebooks/) removed. This reorganization establishes timmy-config as the canonical home for operational documentation, security tooling, and wizard bootstrap infrastructure — extracted from the hermes-agent sidecar subtree. Closes #337
2.2 KiB
2.2 KiB
Notebook Workflow for Agent Tasks
This directory demonstrates a sovereign, version-controlled workflow for LLM agent tasks using Jupyter notebooks.
Philosophy
- **
.pyfiles are the source of truth** — authored and reviewed as plain Python with# %%` cell markers (via Jupytext) .ipynbfiles are generated artifacts — auto-created from.pyfor 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
.pynotebook using# %% [markdown]and# %%code blocks - Review — PR reviewers see clean diffs in Gitea (no JSON noise)
- Generate —
jupytext --to ipynbproduces the.ipynbbefore 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 |