baae383c76
CEO ask #5 complete: browsable paginated run list + full input/output inspection per pipeline stage. ## What was built ### Generations list (prautoblogger-gen-history) Hidden admin page (options.php-parent, priority 14) showing all pipeline runs newest first, 20 per page. Each row: article title (linked to dossier when a post exists), start date, status chip, distinct model(s), settled cost, duration. Queries bounded (LIMIT/OFFSET) — no unbounded SELECT *. New files: - includes/admin/class-gen-history-query.php — paginated run list + per-run I/O queries - includes/admin/class-gen-history-page.php — hidden admin page + asset enqueue - assets/css/gen-history.css, assets/js/gen-history.js — table + drill-down UI - templates/admin/gen-history-page.php — HTML template ### Per-step input + output drill-down (Stage I/O) 'Stage I/O' toggle opens an AJAX-loaded inline panel. For each generation_log stage: - input_system: system-role message content from generation_log.request_json - input_user: last user-role message from request_json (rendered instruction) - output: model response from run_stages.meta_json.output - output_pruned: true when meta_json present but output key absent (retention prune) New AJAX endpoint: prautoblogger_gen_run_io (manage_options + nonce) New file: includes/ajax/class-gen-run-io-handler.php ### gen-log INPUT/OUTPUT coverage verified - INPUT: generation_log.request_json stores the chat body WITHOUT the Authorization header (Request_Recorder captures body after build_body(), before headers are added). System + user message content extracted and surfaced. - OUTPUT: run_stages.meta_json.output is the LLM response text (Run_Stage_State::done()). Image/log-only stages (image_a, image_b, llm_research, image_prompt_rewrite) have no run_stages row; output is null, NOT pruned. Pruned outputs are flagged honestly. ### Dossier as entry point Runs with a linked post show a 'Dossier' button deep-linking into the existing dossier (which renders full per-stage I/O with editorial context). Stage I/O is complementary — works for failed/orphan runs and provides the same data in a lighter inline UI. ### Stage-list-driven Stage labels via Stage_Display_Map::label() — Phase 2b curate/seo appear automatically. ### Dead prautoblogger_pipeline_history endpoint Not dead — it IS used by pipeline-settings.js for prompt version history (M3 feature). Left in place. No dangling endpoint. ## M3 P2 sweep - Removed dead data-preview-nonce and data-diff-nonce HTML attrs from pipeline-settings-prompt-panel.php (JS uses prabPipeline.*Nonce from wp_localize_script, not data-* attrs — confirmed by grep). - Removed 3 redundant wp_create_nonce() calls from class-pipeline-settings-renderer.php (preview_nonce, history_nonce, diff_nonce keys that fed the now-removed dead attrs). - Updated CONTEXT.md: added M3 + M4 terminology tables. - Updated ARCHITECTURE.md: added ajax/ section to file tree; M3/M4 design notes. - Updated INFORMATION-ARCHITECTURE.md: prautoblogger-gen-history entry. ## Security - manage_options cap + prautoblogger_gen_run_io nonce on the AJAX endpoint. - All output esc_html()/esc_url() server-side before JSON-encoding. - JS renders prompt/response text via textContent — never innerHTML. - No writes from history UI; request_json never contains auth headers. ## Version: v0.25.0 → v0.26.0 Agent-Session: pipeline-settings-m4
149 lines
11 KiB
Markdown
149 lines
11 KiB
Markdown
# PRAutoBlogger — Domain Glossary
|
||
|
||
Per DoD v1.2.0 §7, this file defines domain terms introduced by structural changes.
|
||
Update when a PR introduces new terms not covered here.
|
||
|
||
For full design rationale see `ARCHITECTURE.md` (§21–§25) and `CONVENTIONS.md`.
|
||
|
||
---
|
||
|
||
## Pipeline Settings (introduced v0.23.0)
|
||
|
||
| Term | Definition |
|
||
|------|-----------|
|
||
| **step** | One LLM-powered stage in the article-generation pipeline (Research, Analysis, Writer, Editorial, Image). Non-LLM stages (Scoring, Publish) are not surfaced here. |
|
||
| **step rail** | The vertical navigation column in the Pipeline Settings page; one button per step. |
|
||
| **step panel** | The right-hand content area in the Pipeline Settings page that shows model, params, and prompts for the selected step. |
|
||
| **pipeline-ui** | The author tag written to the prompts table when an operator edits a prompt via the Pipeline Settings page (e.g. `pipeline-ui:rhys`). |
|
||
| **system instruction** | The system prompt for an LLM step — sets role, constraints, and style for the model. Stored in the prompt registry under a key like `research.system`. |
|
||
| **agent prompt** | A user-turn prompt for an LLM step — contains the task the model must perform. Stored under keys like `content.single_pass`, `content.draft`. |
|
||
| **system_key** | The registry key string for a step's system instruction (e.g. `research.system`). Defined in `PRAutoBlogger_Pipeline_Settings_Step_Map`. |
|
||
| **agent_key** | A registry key string for one of a step's agent/user prompts. A step may have zero or more agent keys. |
|
||
| **prompt key** | Generic term covering both system_key and agent_key — a dotted string like `content.single_pass` that uniquely identifies a prompt in the registry. |
|
||
| **prompt slug** | URL/form-safe encoding of a prompt key: dots replaced with hyphens (e.g. `content-single_pass`). Used as HTML field values and `?prompt_key=` query params. |
|
||
| **reset-to-default** | A Pipeline Settings action that creates a new prompt version with the canonical seed body (`PRAutoBlogger_Prompt_Registry::default_body()`), effectively restoring factory settings for that key. |
|
||
| **step map** | `PRAutoBlogger_Pipeline_Settings_Step_Map` — the single source of truth for step metadata, model option keys, and prompt key allowlists. |
|
||
| **save handler** | `PRAutoBlogger_Pipeline_Settings_Save_Handler` — stateless class that verifies nonce/cap, validates against allowlists, and persists model or prompt changes. |
|
||
|
||
## Prompt Registry Terms (introduced v0.16.0–v0.18.0)
|
||
|
||
| Term | Definition |
|
||
|------|-----------|
|
||
| **prompt version** | An immutable row in `wp_prautoblogger_prompts`. Once written, the body never changes; a new edit creates a new version row. |
|
||
| **active version** | The single version per prompt key flagged `is_active = 1`. Older versions are retained for history/rollback. |
|
||
| **seed** | Version 1 of a prompt key, written by the activator migration (`seed_v1()`). Author tag: `seed`. |
|
||
|
||
---
|
||
|
||
## Core Domain Terms (introduced v0.22.1)
|
||
|
||
**run**
|
||
A single end-to-end article generation cycle: orchestrate → generate idea(s) →
|
||
finalize. Represented as a row in `wp_prautoblogger_runs` (status, cost ceiling,
|
||
timestamps). One run may produce multiple articles if the daily idea-count > 1.
|
||
|
||
**run\_stages** (`wp_prautoblogger_run_stages`)
|
||
Sub-steps within a run (research, analysis, generation, publish). Each stage has
|
||
its own status and can be replayed independently via `Rerun_Executor`. Generation
|
||
checkpoint runs populate stages as Article_Worker progresses.
|
||
|
||
**checkpoint**
|
||
The persistence boundary between pipeline ticks. After each tick the idea queue
|
||
and run state are written to `wp_options` so a process kill cannot lose work. The
|
||
next tick reads the queue option and continues. See §25 of ARCHITECTURE.md.
|
||
|
||
**idea queue** (`prautoblogger_article_queue` option)
|
||
Serialized array of `Article_Idea` objects written by `on_orchestrate_tick()` and
|
||
consumed one-at-a-time by successive `on_generate_tick()` calls. Deleted on
|
||
finalize or cleanup.
|
||
|
||
**Generation\_Lock** (`wp_prautoblogger_generation_lock` or `wp_options`)
|
||
DB mutex that prevents two concurrent runs. Acquired at the start of
|
||
`on_orchestrate_tick()`, released by `Helpers::finalize()` or on error/halt.
|
||
|
||
---
|
||
|
||
## Execution Modes (introduced v0.22.1)
|
||
|
||
### Async (wp-cron driven)
|
||
|
||
Default path for the Board "New Article" button and the plain
|
||
`wp prautoblogger generate` WP-CLI command.
|
||
|
||
1. `kick_off()` schedules `prautoblogger_gen_orchestrate` and calls `fire_cron_now()`.
|
||
2. `on_orchestrate_tick()` runs in a background PHP process, schedules
|
||
`prautoblogger_gen_tick`, and calls `fire_cron_now()` to spawn the next process.
|
||
3. Each `on_generate_tick()` spawns the next until the queue drains.
|
||
|
||
Limitation: Hostinger kills background PHP processes at ~10 min. Orchestrate tick
|
||
(LLM-free) and individual generate ticks (one LLM call each) are both well within
|
||
this limit; the checkpoint design is the mitigation.
|
||
|
||
### Sync (VPS-driven / `--sync`)
|
||
|
||
Used by the Coolify KVM8 VPS systemd timer via `infra/vps/orchestrate-generation.sh`
|
||
in `peptide-e2e`. Introduced v0.22.1.
|
||
|
||
1. `run_sync()` sets `Generation_Checkpoint_Runner::$sync_mode = true`.
|
||
2. Calls `on_orchestrate_tick()` **in-process** (no background spawn).
|
||
3. Loops calling `on_generate_tick()` directly until queue empty or terminal state.
|
||
4. `$sync_mode = true` suppresses all `wp_schedule_single_event` +
|
||
`fire_cron_now` calls inside both tick methods, preventing a competing
|
||
background cron chain from forming in parallel.
|
||
|
||
The VPS SSH session is held open; the process is not subject to Hostinger's
|
||
background-kill constraint.
|
||
|
||
---
|
||
|
||
## Table Shorthand
|
||
|
||
Throughout the codebase `wp_prautoblogger_*` tables are referenced by their
|
||
`$wpdb->` property names (e.g. `$wpdb->prab_runs`, `$wpdb->prab_run_stages`).
|
||
Full table names are defined in `class-activator.php`.
|
||
|
||
---
|
||
|
||
*See also: `ARCHITECTURE.md` §25 (checkpoint design), `CONVENTIONS.md` (coding rules).*
|
||
|
||
---
|
||
|
||
## Pipeline Settings M2 (v0.24.0)
|
||
|
||
| Term | Definition |
|
||
|------|-----------|
|
||
| **step context** | A routing key (`global\|research\|analysis\|writer\|editorial`) that identifies which group of option fields is being edited in the `save_step_settings` handler. Validated against the `PRAutoBlogger_Pipeline_Settings_Option_Fields::contexts()` allowlist before any write. Distinct from "step" (the display unit in the step rail) — `global` is a context with no corresponding step button. |
|
||
| **Global Content Context** | The editable form block rendered above the step rail in the Pipeline Settings page (v0.24.0). Surfaces `prautoblogger_niche_description` and any future cross-step fields. Uses `step_context=global` in its save form. Not associated with an LLM step. |
|
||
| **option field** | A `wp_option`-backed field surfaced in a step panel or the Global Content Context block. Defined in `PRAutoBlogger_Pipeline_Settings_Option_Fields_Data`. Distinct from a "prompt panel" (which edits the prompt registry). Types: `textarea`, `select`, `number`, `toggle`, `checkboxes`. |
|
||
| **step option** | Synonym for option field when it appears inside a step panel (i.e., not in the Global Content Context). |
|
||
| **`step_context`** | The POST key that routes `save_step_settings` to the correct field set. Expected values: `global`, `research`, `analysis`, `writer`, `editorial`. Validated with `sanitize_key()` before use. |
|
||
| **`pipeline_action=save_step_settings`** | POST contract key introduced in M2. Triggers `PRAutoBlogger_Pipeline_Settings_Save_Handler::handle_step_settings_save()`. Parallel to the existing `save_model`, `save_prompt`, and `reset_prompt` action values. |
|
||
| **relocated-tabs concept** | The Settings tabs `prautoblogger_models`, `prautoblogger_content`, and `prautoblogger_sources` were retired in M2; their 17 option fields moved to per-step panels in the Pipeline page. The `wp_option` keys are unchanged — only the admin UI surface that edits them moved. See `CONVENTIONS.md §Retired Settings Tabs`. |
|
||
|
||
---
|
||
|
||
## Pipeline Settings M3 (v0.25.0)
|
||
|
||
| Term | Definition |
|
||
|------|-----------|
|
||
| **assembled instructions** | The fully-rendered text the LLM actually received for a given prompt key — all `{{ token }}` placeholders substituted with live data. Surfaced in the Template/Preview toggle on the Pipeline Settings page. Preferred source: last successful `generation_log.request_json` row for the stage; fallback: sample render with `[token_name]` placeholders. |
|
||
| **Template mode** | The default view of a prompt panel: shows the editable textarea with raw template text (including `{{ token }}` placeholders). Editing here writes a new version to the prompt registry. |
|
||
| **Preview mode** | Read-only view of a prompt panel: shows the assembled instructions the LLM received in the last run (or a sample render if no run exists). No save path in PHP or JS. |
|
||
| **Template-vs-Preview guardrail** | The Template and Preview panes are mutually exclusive. Preview has no save path server-side (no write handler) or client-side (JS sends no save POST when in preview mode). Prevents accidental edits to the rendered output. |
|
||
| **version diff** | An LCS-based line-level diff between two prompt versions (or a version and the factory default). Rendered server-side as `{type, text}` lines (added/removed/context/omitted); the JS applies colours without parsing unified-diff format. Context window: 3 lines before/after each changed block. |
|
||
|
||
---
|
||
|
||
## Pipeline Settings M4 (v0.26.0)
|
||
|
||
| Term | Definition |
|
||
|------|-----------|
|
||
| **Generation History** | The `prautoblogger-gen-history` admin page: paginated list of all pipeline runs, newest first. Entry point to the per-step I/O drill-down. |
|
||
| **run row** | A single entry in the Generation History list. Corresponds to one `prautoblogger_runs` ledger row. Shows title (from linked post), date, status chip, models used, cost, duration. |
|
||
| **Stage I/O** | The inline drill-down panel for a run: shows every generation_log stage's full INPUT (system + user message content from `request_json`) and OUTPUT (model response from `run_stages.meta_json.output`). Loaded via AJAX on first toggle; cached client-side for subsequent toggles. |
|
||
| **input_system** | The `system`-role message content extracted from `generation_log.request_json`. The prompt template the LLM received. May be null for image/non-chat stages. |
|
||
| **input_user** | The last `user`-role message content from `request_json`. The rendered, token-filled instruction the LLM received. |
|
||
| **output** | The LLM's raw response text from `run_stages.meta_json.output`. Null when the stage is log-only (image_a, image_b, llm_research, image_prompt_rewrite — no run_stages row). |
|
||
| **output_pruned** | True when `run_stages.meta_json` exists but has no `output` key — indicating the output was pruned by the `prautoblogger_request_json_retention_days` setting. The UI shows an explicit message instead of a blank field. |
|
||
| **log-only stage** | A generation_log stage with no corresponding run_stages row. Image stages (image_a, image_b, image_prompt_rewrite) and llm_research fall here. Their output is null (not pruned) in the drill-down. |
|