Browse the documentation

Early preview

Releasing a prompt change

In the Open Engineering Language, a prompt change is a release of business logic. Four commands take it from your working project to an approved rollout: oel prompt-package records what a node's behavior is, oel prompt-plan shows what a release would change, oel prompt-publish stores the package and oel prompt-activate begins the rollout you approved. None of them starts a model or reads a credential, and none changes what is running until you approve a plan by its digest.

The steps

oel prompt-diff --old ./released --new ./working --entry advisor.node.oel
oel prompt-package --root ./working --entry advisor.node.oel --model advisor-model --provider main --context-policy default --configuration-sha256 SHA256 --source-revision r42 > candidate.json
oel eval --root ./working --suite suite.json --native-root DIRECTORY --worker WORKER --worker-sha256 SHA256 --output report.json
oel prompt-plan --baseline baseline.json --candidate candidate.json --report report.json --rollout percent:10 --output plan.json
oel prompt-publish --store ./releases --tenant acme --agent advisor --package candidate.json --root ./working
oel prompt-activate --store ./releases --tenant acme --agent advisor --baseline baseline.json --candidate candidate.json --report report.json --rollout percent:10 --root ./working --approver NAME --approve PLAN_SHA256

oel prompt-diff compares two versions of a project and oel eval produces the evaluation report the plan needs. Promotion to stable and rollback are the same store commands, oel prompt-promote and oel prompt-rollback; oel prompt-status shows what is active.

oel prompt-package

oel prompt-package --root PROJECT --entry NAME.node.oel --model LABEL --provider LABEL --context-policy LABEL --configuration-sha256 SHA256 --source-revision LABEL

It prints the node's behavior package as JSON, with the package's digest. The package is immutable and identified by its content: the digest of the resolved prompt, the digest of the node's input and output contract, the model, provider, context policy and configuration you name, and the source revision.

OptionMeaning
--root PROJECTThe project folder.
--entry NAME.node.oelThe node to package.
--model, --providerThe labels of the model binding the release uses.
--context-policyThe label of the rules that build the node's context.
--configuration-sha256The digest of the configuration the release runs with.
--source-revisionA label for the source revision the package was made from.

Locked dependencies

When the project's pack.oel declares packages, the behavior was built against the packages its pack.lock pins, so the package records them. It carries the identity of the accepted lock and, for every locked package, its id, name, version and archive digest. A package of a project without dependencies has neither, and its digest is the one it always had.

oel prompt-package reads only the project's two files and consults no registry. It refuses to make a package when:

  • pack.oel declares dependencies and the project has no pack.lock (PROMPT_LOCK_MISSING);
  • pack.lock cannot be read (PROMPT_LOCK_UNREADABLE) or was resolved for another folder than the project root (PROMPT_LOCK_SCOPE);
  • the lock was resolved from other pack.oel content than the current one, so it is stale (PROMPT_LOCK_STALE);
  • the lock is not a closed graph, because a package or the project itself depends on a package the lock does not pin (PROMPT_LOCK_GRAPH);
  • a locked package that is installed in the project's .package folder holds other content than the lock pins, or is only partly installed (PROMPT_LOCK_GRAPH, naming the pin). A locked package that is not installed at all is reported in the dependency_graph summary, not refused: the lock is the pin and the folder is a convenience.

Each refusal is a structured diagnostic in JSON with a code, a message and a detail. Run oel pack install and review the new lock, then package the node again.

oel prompt-plan

oel prompt-plan --baseline PACKAGE.json --candidate PACKAGE.json --report EVAL_REPORT.json --rollout full|percent:N|tenants:A,B

A plan is the reviewable statement of a release. It names the digests of the baseline and the candidate, the kinds of change between them, the rollout and the evaluation report that backs it. The plan is refused when the evaluation evidence is not promotable, belongs to another node, or when the candidate equals the baseline. A change of the node's contract is refused unless you pass --allow-contract-change.

OptionMeaning
--baseline, --candidateThe two packages, as oel prompt-package printed them.
--reportThe offline evaluation report of the candidate. A live evaluation is never promotable.
--rolloutfull, percent:N for a share of subjects, or tenants:A,B for named tenants.
--allow-contract-changeAllow a candidate whose input or output contract differs from the baseline's.
--output PLAN.jsonAlso write the plan to a file.
--root PROJECTAlso check the candidate against the project's current lock.

The kinds of change are prompt, source, contract, model, provider, configuration, context_policy and dependencies. dependencies means the accepted lock differs between the two packages.

The plan prints a dependencies block that shows what the candidate puts into service: its lock identity, the lock identity of the baseline, every pin of the candidate and the pins that moved. A moved pin shows the version and archive digest on each side, or that the package is new or dropped. The plan's digest covers the candidate package and with it its lock and pins, so approving the plan approves them.

With --root PROJECT, the plan is also refused (PROMPT_LOCK_CHANGED) when the candidate was packaged under a lock that is no longer the project's accepted one. The diagnostic names each pin that moved since, so you package the node again and run the evaluation again instead of releasing a behavior that no longer matches its dependencies.

oel prompt-publish

oel prompt-publish --store DIRECTORY --tenant T --agent A --package PACKAGE.json [--root PROJECT]

It stores the package in the release store by its content and changes nothing that is active. The report names the package digest, the lock identity the package carries and the number of pins. With --root PROJECT the same lock check as in the plan applies.

oel prompt-activate

oel prompt-activate --store DIRECTORY --tenant T --agent A --baseline PACKAGE.json --candidate PACKAGE.json --report EVAL_REPORT.json --rollout full|percent:N|tenants:A,B --approver NAME --approve PLAN_SHA256

It begins the rollout of an approved plan. The command builds the plan again from the same files, and the approval must name that plan's digest, the plan_digest that oel prompt-plan printed. An approval can therefore only name a plan a reviewer could have been shown. Writes to the store are compare-and-swap: a stale or concurrent write is refused as a conflict and is never merged. With --root PROJECT the lock check applies here too.

Runs already under way stay pinned to the version they were admitted with. Evaluations and prompt releases describes promotion and rollback.

Output

Every command prints a JSON report. The lock refusals above print their diagnostic as JSON, with a code, a message and a detail that names the pins involved, so a script can read the reason without parsing text.