Document Promptkit report generation
This commit is contained in:
@@ -1,126 +1,43 @@
|
||||
# Application Orchestration Internals
|
||||
|
||||
`internal/app` composes top-level generation, batch, collection-save, and
|
||||
inspection workflows after CLI parsing and configuration loading. It owns
|
||||
workflow ordering, request composition, partial-result handling, and the
|
||||
application-facing interfaces used for tests.
|
||||
`internal/app` owns top-level generation, batch, collection, inspection, and
|
||||
notification ordering after the CLI has parsed arguments and loaded configuration.
|
||||
|
||||
## Inputs And Outputs
|
||||
## Generation
|
||||
|
||||
The package accepts generate, resolved-report, batch, explicit-collection, and
|
||||
inspection requests. Generation and batch requests may supply collaborators for
|
||||
tests; single-report generation uses a Promptkit executor, while batch requests
|
||||
retain a renderer for their compatibility workflow.
|
||||
`GenerateDetailed` resolves one of the four report definitions, initializes an
|
||||
optional debug root, and inspects the exact Promptkit prompt/profile before it
|
||||
collects weather or writes managed state. It then builds facts and modules,
|
||||
saves the YAML data package, persists preparation metadata from the executor
|
||||
callback, executes the prepared prompt, saves execution provenance and raw
|
||||
output, validates generated text, renders Markdown, and optionally copies or
|
||||
notifies from the managed report.
|
||||
|
||||
A report result contains the module snapshot, prompt package, prompt
|
||||
provenance, generated-text artifacts, report and metadata
|
||||
paths, prior snapshot, Recent Changes, and notification information. A batch
|
||||
result contains aggregate counts, per-report outcomes, and an optional batch
|
||||
notification. Inspection returns persisted values only.
|
||||
Failure results retain all safe paths reached so far. Validation rejection
|
||||
persists raw output and execution provenance but does not render a report.
|
||||
|
||||
Exact public command syntax, configuration fields, workspace layout, external
|
||||
protocols, and report definitions belong in [the CLI reference](../cli.md),
|
||||
[the configuration reference](../config.md), [operations](../operations.md),
|
||||
and their focused integration and internal documents.
|
||||
## Batches
|
||||
|
||||
`InspectPromptExecution` is a side-effect-free preflight helper for the prompt
|
||||
workflow. It verifies the exact report prompt version, its required YAML input,
|
||||
the generated-text JSON Schema contract, the selected profile, and any required
|
||||
environment credential before collection or persistence begins. It returns only
|
||||
safe project-owned identity and provenance values.
|
||||
`RunBatchDetailed` constructs a single debug writer and uses the request's
|
||||
single executor. Before collection it inspects Today, Tomorrow, and Daily for
|
||||
morning, or Tomorrow and Daily for evening, deduplicating effective profile
|
||||
inspection. It then collects once, plans eligible Daily dates, and calls the
|
||||
same prompt-generation core sequentially for each planned report. Per-report
|
||||
notification is suppressed; a failed report does not stop later reports.
|
||||
|
||||
## Single-Report Workflow
|
||||
Batch notification is skipped when disabled or when any report failed.
|
||||
Successful notification uses the completed managed report paths only. Batch
|
||||
items retain preparation, execution, and optional debug paths when reached.
|
||||
|
||||
`GenerateDetailed` resolves the requested report using the configured registry
|
||||
and current time, initializes any requested prompt-debug root, verifies the
|
||||
exact Promptkit prompt and selected profile, and only then collects weather
|
||||
data. Debug initialization or inspection failure produces no collection or
|
||||
managed artifacts.
|
||||
## Inspection And Boundaries
|
||||
|
||||
Single-report generation requires a non-nil normalized bundle and then performs this
|
||||
ordered work:
|
||||
Inspection loads persisted state only. It does not collect weather, invoke
|
||||
Promptkit, or upload reports. The app coordinates project-owned contracts but
|
||||
does not parse flags, load YAML, implement transport, construct provider SDKs,
|
||||
or define report-period policy.
|
||||
|
||||
1. Select a state store, determine artifact destinations, and locate a prior
|
||||
compatible snapshot.
|
||||
2. Build report facts and deterministic module snapshots, then save the module
|
||||
snapshot and calculate Recent Changes.
|
||||
3. Serialize and save the prompt data package once, then use those exact bytes
|
||||
for Promptkit execution.
|
||||
4. Save preparation provenance and V2 metadata from the preparation callback
|
||||
before provider execution. When requested, save preparation diagnostics in
|
||||
the isolated debug store before the callback returns. Save execution
|
||||
diagnostics immediately after a completed execution result, then persist raw
|
||||
output and execution provenance before saving updated metadata.
|
||||
5. Validate and save generated text, build and save a render context, and
|
||||
render the managed Markdown template.
|
||||
6. Optionally make an output copy, save final metadata, optionally notify
|
||||
Distributor from the managed report path, and save metadata again when a
|
||||
notification path is produced.
|
||||
Focused checks:
|
||||
|
||||
Every single report looks up its catalog definition, saves raw Promptkit output,
|
||||
preserves safe preparation and execution provenance separately, validates and
|
||||
saves generated text, builds and saves a render context, then renders the
|
||||
embedded Markdown template. Schema and template details remain in their
|
||||
[generated-text](generatedtext.md) and [report-template](reporttemplate.md)
|
||||
owners.
|
||||
|
||||
Preparation and operational execution failures save classified receipts and
|
||||
metadata before returning. A completed Promptkit validation rejection saves raw
|
||||
output, an execution receipt, and metadata before returning. If later report
|
||||
generation fails, the result retains every reached safe artifact path; output
|
||||
copies and notification are skipped until rendering succeeds.
|
||||
|
||||
The optional debug writer receives sensitive content only when explicitly
|
||||
enabled. Its path is added to the report result only after a debug artifact is
|
||||
successfully written; it is never copied into normal state records.
|
||||
|
||||
## Batch And Inspection Workflows
|
||||
|
||||
`RunBatchDetailed` collects once, asks the report registry to plan the batch
|
||||
from that collection, and invokes its isolated Scriptorium compatibility helper
|
||||
independently for every planned report using the same collection and state store. Per-report
|
||||
notification is suppressed. A failed report is recorded and does not prevent
|
||||
later planned reports from running.
|
||||
|
||||
After report generation, the batch notifier is considered once. It is omitted
|
||||
when Distributor or batch notification is disabled, skipped when any report
|
||||
failed, and otherwise receives one multi-file request. A batch notification
|
||||
failure increments the aggregate failure count but does not rewrite successful
|
||||
report items. Notification identities, path mappings, polling, and redaction
|
||||
are owned by the [Distributor adapter](distributor-adapter.md).
|
||||
|
||||
Inspection methods create a state store and load existing report records,
|
||||
metadata, module snapshots, prompt packages, prior snapshots, or source
|
||||
provenance. They neither collect data nor invoke Scriptorium or Distributor.
|
||||
|
||||
## Boundaries And Failure Propagation
|
||||
|
||||
The app layer does not parse flags, load configuration files, implement Weather
|
||||
API transport, invoke provider SDKs, or define report registry policy. It
|
||||
coordinates the relevant collaborators and preserves their error context.
|
||||
|
||||
- Prompt inspection failure stops a single report before collection or durable
|
||||
writes. Collection failure stops a single report or batch before planning.
|
||||
- State, fact, module, prompt-input, preparation, or execution failures stop
|
||||
that report before later report generation.
|
||||
- A terminal Distributor failure is returned with the saved notification
|
||||
information when available.
|
||||
- Batch failures are represented per report and through aggregate batch status.
|
||||
- Persisted artifact paths are carried in results so callers can inspect work
|
||||
completed before a later failure.
|
||||
|
||||
## Tests And Invariants
|
||||
|
||||
Focused tests are in `internal/app/app_test.go` and
|
||||
`internal/app/batch_plan_test.go`, with collection coverage in
|
||||
`internal/collect/collect_test.go`.
|
||||
|
||||
- Production workflows collect through `internal/collect`.
|
||||
- A report uses one explicit normalized collection throughout its generation.
|
||||
- Prompt preparation provenance and metadata are persisted before provider
|
||||
execution.
|
||||
- Recent Changes compare structured module snapshots.
|
||||
- Reports render from a validated typed context, never directly from a raw
|
||||
prompt package.
|
||||
- Only managed Markdown reports are notification sources; output copies are
|
||||
never uploaded.
|
||||
```sh
|
||||
go test ./internal/app ./internal/collect
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user