121 lines
7.0 KiB
Markdown
121 lines
7.0 KiB
Markdown
# Operations Guide
|
|
|
|
This runbook covers deployment, normal operation, capacity, sensitive data, and
|
|
recovery. Exact [CLI syntax/statuses](cli.md), [configuration](config.md), and
|
|
[HTTP wire behavior](api.md) remain in their canonical references.
|
|
See the [CLI migration guide](consumers/upgrading-cli.md) for changed jobs and
|
|
the [framework upgrade guide](consumers/upgrading-promptkit.md) for definitions.
|
|
|
|
## Deploy Sources And Process
|
|
|
|
Provide readable application configuration, its selected framework entry file,
|
|
and explicitly imported definitions/resources. Set cwd deliberately: application
|
|
path values are cwd-relative, while framework imports and message resources keep
|
|
their native source contexts. ConfigKit confines source imports/overlays to the
|
|
selected main's canonical root; Scriptorium does not widen it.
|
|
|
|
Engine construction validates selected effective definitions and captures message
|
|
resources/template syntax, including definitions not used by a particular request.
|
|
Schema/artifact reads, credential resolution, and model work retain their native
|
|
preparation/runtime lifecycles. A server constructs one engine at startup and
|
|
does not hot-reload changed files; restart to capture updates. Separate CLI
|
|
invocations load afresh rather than sharing an immutable snapshot.
|
|
|
|
For independent collections, install checkouts beneath the layout selected by
|
|
the [discovery entry](../examples/discovery/framework.yml). Each checkout declares
|
|
its namespace and explicit fragment imports; arbitrary YAML is not a framework
|
|
source. The maintained [discovery example](../examples/config.discovery.yml)
|
|
supports both entry-file spellings and multiple definitions. New checkouts or
|
|
updates become visible to later invocations or a restarted server.
|
|
|
|
Supply only needed credential environment variables through a supervisor or
|
|
secret-management mechanism. Confirm presence without printing their values.
|
|
Raw keys do not belong in arguments or checked-in configuration.
|
|
|
|
## Normal Operator Workflow
|
|
|
|
1. Validate application configuration through the native application scope.
|
|
This does not acquire framework sources or prove provider readiness.
|
|
2. Inspect framework configuration/resources and discover requirements for the
|
|
selected prompt/profile/namespaces. Discovery can precede generated input
|
|
artifacts; completeness does not establish satisfied bindings.
|
|
3. Once artifacts exist, validate the concrete request or inspect prepared
|
|
content. These are provider-free preparation checks with native prerequisites.
|
|
4. Invoke a smoke test only when its provider effects are intended. Findings
|
|
can be unsupported or unsuccessful while the command itself succeeds.
|
|
Smoke tests are not an automatic startup or release prerequisite.
|
|
5. Generate with the same selections and bindings, then inspect the finalized
|
|
status and any returned validation result before accepting the output.
|
|
|
|
Use the [maintained preview script](../examples/render-markdown-summary.sh)
|
|
for a provider-free example, and the [CLI contract](cli.md) for commands.
|
|
A complete discovery report can still list required inputs that are not bound;
|
|
a partial report can still be useful. Consumers own their policy for incomplete
|
|
findings and changed resources between invocations.
|
|
|
|
## Sensitive Data And Retention
|
|
|
|
Artifacts, prompt messages, prepared content, native run reports, metadata,
|
|
diagnostics, and redirected streams are caller-owned potentially sensitive data.
|
|
The separate CLI report contains the full returned result, not metadata alone.
|
|
Control access, retention, encryption, backup, and deletion accordingly.
|
|
Framework effective/explanation views apply native classified-field redaction,
|
|
including history, but do not detect arbitrary secrets. Other content-bearing
|
|
reports are not automatically made safe for publication.
|
|
|
|
Keep main output and report destinations separate. Delivery is nontransactional:
|
|
one destination or partial bytes can remain after failure. An existing report
|
|
can remain on a resultless error; check status and report identity, not just file
|
|
existence. A shell can truncate a redirected destination before the child starts.
|
|
Omit quiet if main stdout must be captured; the separate report effect remains
|
|
independent. Exact delivery behavior belongs to [CLI results](cli.md#results-and-separate-reports).
|
|
|
|
HTTP's optional [execution report](api.md#execution-report) remains a distinct
|
|
terminal-observation projection. Protect its identifiers and any response data.
|
|
It increases encoded response size and remains subject to the configured limit.
|
|
|
|
## HTTP Deployment And Shutdown
|
|
|
|
The service has no built-in authentication/authorization. Deploy on a trusted
|
|
network or behind appropriate authenticated proxy/gateway controls. Use a narrow,
|
|
dedicated artifact root with controlled ownership and permissions when accepting
|
|
file inputs; this is lexical containment, not a symlink sandbox.
|
|
|
|
Use a supervisor for cwd, environment, restart policy, and stream capture.
|
|
Startup information uses native Info reporting, not stdout banners.
|
|
Interrupt/SIGTERM cancels the invocation and closes the listener and active
|
|
connections. Canceled shutdown is nonzero operational termination. There is no
|
|
graceful-drain deadline or promise that context-ignoring work has finished;
|
|
supervisors own forced termination when necessary.
|
|
|
|
## Capacity, Limits, And Recovery
|
|
|
|
One server engine shares backend admission/queue state across concurrent requests.
|
|
That state is transient operational coordination, not a durable workflow or
|
|
queue of resumable runs. HTTP capacity exhaustion retains its
|
|
[API outcome](api.md); callers decide whether another model call is safe.
|
|
|
|
Plan for input/output sizes, schema complexity, provider latency, retries, and
|
|
repair costs. Native transient attempts and repair generations can add calls and
|
|
waiting; engine defaults and per-request overrides belong to
|
|
[configuration](config.md) and the [CLI](cli.md)/[HTTP](api.md) contracts.
|
|
Whole-operation budgets are distinct from per-attempt generation timeouts.
|
|
They remain cooperative and do not include configuration/setup or delivery.
|
|
|
|
Before increasing HTTP byte limits, measure representative requests/artifacts/
|
|
responses, confirm memory/network/provider capacity, retain authentication and
|
|
upstream request controls, and test a representative workload. Do not widen the
|
|
artifact root just to make an arbitrary host path accessible.
|
|
|
|
For failures, capture diagnostics without publishing sensitive data. Verify
|
|
selected configuration, resource identity, readable inputs, profile/credentials,
|
|
and schema deployment. Use native prepared preview to isolate pre-generation
|
|
problems. A completed content-validation failure is distinct from an operational
|
|
failure to validate; consumers choose whether failed content is usable.
|
|
Correct the cause, then issue a new request only when another provider call and
|
|
its cost are acceptable.
|
|
|
|
There is no durable run store, archive, checkpoint, or resume mechanism.
|
|
Cleanup concerns caller-owned files/logs only. Rotate/delete them under the
|
|
deployment's normal retention policy; recovery starts from a new request.
|