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
58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# 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
|
|
|
|
1. **Create** — Agent generates a `.py` notebook using `# %% [markdown]` and `# %%` code blocks
|
|
2. **Review** — PR reviewers see clean diffs in Gitea (no JSON noise)
|
|
3. **Generate** — `jupytext --to ipynb` produces the `.ipynb` before merge
|
|
4. **Execute** — Papermill runs the notebook with injected parameters
|
|
5. **Archive** — Output notebook is committed to a `reports/` branch or artifact store
|
|
|
|
## Converting Between Formats
|
|
|
|
```bash
|
|
# .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 |
|