328 lines
22 KiB
Markdown
328 lines
22 KiB
Markdown
# Step-12 - Local AI and applicable knowledge integration
|
|
|
|
## STEP IDENTIFIER
|
|
|
|
Step-12. Step-11 was accepted on 2026-10-31 with no correction.
|
|
This is the sole active implementation assignment. Step-13 demonstration is blocked.
|
|
|
|
## STEP TITLE
|
|
|
|
Generate one synthetic calibration runbook with an explicitly selected local-only
|
|
model and applicable context, then use the existing deterministic preview validator.
|
|
|
|
## OBJECTIVE
|
|
|
|
One user outcome: an explicit bounded natural-language calibration request
|
|
produces either a model-generated validated read-only preview or a precise error.
|
|
One primary new contract: a local-only, source/model/context-bound cancellable
|
|
generation whose untrusted output cannot bypass validation or mutation approval.
|
|
|
|
No authoring Save, target open/write, runbook execution, cloud inference or
|
|
physical operation is assigned. Read [STATE.md](STATE.md), [ROADMAP.md](ROADMAP.md),
|
|
[runbooks v1](../docs/runbooks-v1.md) and [WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md).
|
|
Establish the frozen matrix before coding, self-review after first green,
|
|
write `prompts/Step-12-Report.md`, and STOP.
|
|
|
|
## ARCHITECTURAL CONTEXT
|
|
|
|
Keep all nine projects, one Client and independent Components.
|
|
Application owns a small replaceable inference port, matched context provider
|
|
and generation orchestration against actual authoring/preview contracts.
|
|
An Ollama HTTP implementation may live in the existing Application feature with
|
|
Client configuring the real transport; UI owns explicit selection/generation/
|
|
cancel/context/output/error and page lifetime. No new project/package/host,
|
|
generic agent/tool/runtime framework or vector database.
|
|
|
|
Reuse [RunbookPreviewService](../src/AutoForge.Application/Features/Vehicles/Runbooks/RunbookPreviewService.cs),
|
|
the actual [authoring service](../src/AutoForge.Application/Features/Vehicles/Calibration/CalibrationAuthoringService.cs)
|
|
and existing synthetic definition/diff/units. The deterministic validator stays
|
|
authoritative; do not implement a weaker model-only schema/source validator.
|
|
Source/tests remain under `src`, tests under `src/tests`.
|
|
|
|
## CURRENT IMPLEMENTATION STATE AND PREREQUISITES
|
|
|
|
Accepted manual runbooks allow one simulation/proposeCalibration step, exact
|
|
source/head/full scalar/table values, strict schema/limits, immutable preview/
|
|
diff and Stale status. They save/approve/execute nothing.
|
|
Worker baseline: 179 unit + 368 integration passes (547 total, zero failed/
|
|
skipped), clean nine-project Release build and native manual-preview checks.
|
|
The orchestrator did not run those commands.
|
|
|
|
First provider: Ollama local HTTP at `http://127.0.0.1:11434`.
|
|
Use an **existing operator-approved runtime and installed local model**.
|
|
Do not install/pull/update models or runtimes, sign in, start/restart a shared
|
|
service or alter user/system settings automatically. Real model availability
|
|
was not verified by the orchestrator. Missing prerequisites block the assigned
|
|
real-generation/native checks; do not substitute a stub or cloud and declare COMPLETE.
|
|
|
|
Verified public contracts, recheck against the installed runtime before coding:
|
|
|
|
- [Chat API](https://docs.ollama.com/api/chat): POST `/api/chat`, explicit model/
|
|
messages, `stream:false`, structured `format`; read `message.content`.
|
|
- [Model catalogue](https://docs.ollama.com/api/tags): GET `/api/tags`, local
|
|
model name/digest/size and optional remote_model/remote_host.
|
|
- [Model details](https://docs.ollama.com/api-reference/show-model-details):
|
|
POST `/api/show`, completion capabilities and model metadata.
|
|
- [Local-only configuration](https://docs.ollama.com/faq#how-do-i-disable-ollamas-cloud-features):
|
|
operator disables cloud with documented server configuration or
|
|
`OLLAMA_NO_CLOUD=1`, then verifies the runtime's cloud-disabled status.
|
|
|
|
Use the actual documented anchor/path the installed docs expose if necessary;
|
|
do not invent unsupported APIs. A loopback URL alone does not prove the Ollama
|
|
model will not delegate to cloud. No API key/authentication is needed or allowed.
|
|
|
|
## REQUIRED IMPLEMENTATION
|
|
|
|
### Frozen contract matrix
|
|
|
|
| ID | Input/precondition | Required result |
|
|
|---|---|---|
|
|
| C-01 | App/route entry or ordinary manual workflow without a model | No automatic network/generation/model/source action; manual validator/authoring/diagnostic/replay/rehearsal still works. Explicit catalogue refresh and opt-in/model selection are required. |
|
|
| C-02 | Eligible installed local model versus remote/cloud/ambiguous/stale metadata, absent runtime/model or redirect/proxy | Only loopback local-only eligible selection can generate; precise visible rejection before goal/context reaches an ineligible destination. No model substitution, pull/install/cloud/tool call. |
|
|
| C-03 | Actual current supported authoring source/head and matched synthetic knowledge | Capture exact immutable source/head/values/constraints, model name/digest, knowledge ID/revision/applicability and bounded goal. Missing/mismatched source/knowledge rejects before chat. |
|
|
| C-04 | Controlled valid response and real native goal from warm baseline | Original model content passes existing Step-11 validator; exact 1250 rpm and 2000-rpm torque 350 N*m yield +600/-10 diff with unchanged other cells. No saving/approval/write; real model evidence distinguishes intent accuracy from mere parse success. |
|
|
| C-05 | Invalid/refused/empty/markdown/truncated/tool-call/wrong-source/wrong-unit/unknown-key model output | Typed generation/validation error, no repaired/rebound/default candidate; previous successful preview remains intact. Unvalidated content is safely labeled/limited, never actionable authority. |
|
|
| C-06 | Source/head changes, newer manual preview or model selection/digest superseded while generation is pending | No stale overwrite or rebasing. Publish only for the current owner/source/head/selected model and captured prior-preview identity, through atomic validator publication checks. |
|
|
| C-07 | Repeated Generate, competing refresh/selection, Cancel/close/re-entry and delayed response | One owner; conflicts reject before mutation/request, cancellation/close drains outside required gates, no late preview/Ready state, fresh page lifetime does not reuse closed completion. |
|
|
| C-08 | HTTP errors/timeouts/invalid metadata/duplicate critical response fields/chunked oversized body | Typed visible failure; bounded actual reads/request sizes, no success-shaped empty catalogue/content or partial JSON publication. Preserve prior source/preview/core workflows. |
|
|
| C-09 | Prompt/rationale attempts to alter policy/source, global units/renders/hide | Quoted goal/context/model output remain untrusted data; deterministic allowlist/source/template still applies. No tool/write/model control, validation on render or unit-based source mutation. |
|
|
| C-10 | Real generation/coexistence and complete verification | All 547 baseline cases/new coverage and nine-project Release build pass; real installed local-model/native preview runs with cloud disabled; counted existing transport/model/archive/rehearsal/authoring mutations remain zero. |
|
|
|
|
### A. Explicit local-only provider and transport
|
|
|
|
Use a small replaceable typed inference port; implement Ollama first using built-
|
|
in .NET HTTP/JSON, not a new SDK dependency. Production base URI is fixed loopback
|
|
above; tests may inject a controlled loopback HTTP peer/handler below the provider.
|
|
Reject non-loopback destinations. Disable redirects, system proxies and default
|
|
credentials; requests cannot carry API keys or resolve an arbitrary model-supplied URL.
|
|
Allowed calls are catalogue/details/chat only, never pull/create/delete/push/
|
|
cloud/search/tool execution. Do not stop or unload unrelated runtime/model work.
|
|
|
|
Require explicit local-only operator acknowledgement before sending a goal or
|
|
source context. Native verification must record actual operator-configured cloud-
|
|
disabled runtime evidence, not a boolean checkbox claimed as cryptographic proof.
|
|
Do not modify the runtime configuration yourself without separate approval.
|
|
|
|
Select an exact reported installed model, not freeform fallback/first model.
|
|
Eligibility requires usable name/digest, positive installed size, local model
|
|
details and completion capability. Reject remote_model/remote_host indicators,
|
|
cloud-tagged models and malformed/ambiguous eligibility data. Show rejected
|
|
models/reasons, not a misleading healthy empty catalogue. A failed refresh may
|
|
retain last-known display but never authorizes generation without fresh checks.
|
|
Recheck selected catalogue identity/digest/details before each explicit chat.
|
|
After completion, recheck that same local eligibility and catalogue digest before
|
|
validator publication. Changed/unavailable metadata rejects the result; a model
|
|
name in the chat response alone does not attest its digest or local execution.
|
|
|
|
Use one non-streaming POST `/api/chat` per explicit Generate:
|
|
`stream:false`, structured JSON format for the accepted runbook shape, bounded
|
|
generation options such as temperature 0 and a finite output-token budget.
|
|
The format is a generation hint, not validation or a guarantee of determinism.
|
|
Supply the application-generated runbook/source template and require source/
|
|
head/keys/units/axes unchanged. Do not grant tools or feed previous unbounded
|
|
chat history. Ignore reasoning fields as content; never interpret tool calls.
|
|
|
|
Validate the completed response envelope: explicit requested model, assistant
|
|
message string content, actual finished state and non-truncated outcome.
|
|
Reject empty/refused/malformed/truncated or tool-call completion.
|
|
Handle additive API metadata compatibly, but reject duplicate/invalid critical
|
|
identity/completion/content/error fields. No silent defaults for those fields.
|
|
|
|
Fixed bounds, not new user settings: goal <=2000 UTF-16 code units, complete
|
|
UTF-8 chat request <=131072 bytes, each catalogue/details/chat response <=1 MiB
|
|
(1,048,576 bytes), HTTP JSON depth <=64 and operation deadline <=180 seconds.
|
|
Read bodies bounded even without Content-Length; a one-byte-over/chunked response
|
|
cannot be buffered unboundedly before rejection. Distinguish timeout/cancel/
|
|
HTTP/metadata/completion/validator failures; do not return fake success.
|
|
The decoded runbook must also meet all unchanged Step-11 limits.
|
|
|
|
### B. Small applicable local knowledge and exact source snapshot
|
|
|
|
Provide one local synthetic engine-authoring policy pack with explicit ID/revision
|
|
and exact model/definition applicability. Its authority is the accepted synthetic
|
|
template/owned contracts, not manufacturer or real-vehicle truth.
|
|
Retrieve by exact source model/version/definition/revision; no generic "nearest"
|
|
or role-based fallback. Missing/mismatched pack is a visible pre-chat failure.
|
|
|
|
Context includes copied actual authoring workspace/head/applicability, canonical
|
|
whole values, scalar bounds, fixed rpm axis, torque-cell bounds/units, supported
|
|
operation and the pack's relevant synthetic restrictions. Keep the pack provenance
|
|
and included facts visible independently of anything the model claims.
|
|
Use a simple local provider/data definition, not embeddings/web retrieval/RAG/
|
|
filesystem crawling or another schema/persistence subsystem.
|
|
|
|
Capture the bounded explicit goal, selected model/digest and prior successful
|
|
preview ID at request start. Show source and selected context for deliberate user
|
|
review. Do not include arbitrary files, source code, raw diagnostic archives,
|
|
credentials, vehicle personal data or undocumented operating instructions.
|
|
Only bounded explicitly selected synthetic authoring data is supplied.
|
|
|
|
System guidance restricts generation to synthetic warm-idle/fixed-axis torque
|
|
proposals, with no hardware programming, emissions/anti-theft/odometer/safety
|
|
bypass instructions, external tools or claims of approval/testing. Treat the
|
|
goal/pack/output as quoted untrusted data; model obedience is not the safeguard.
|
|
Existing deterministic schema/source/template validation is still mandatory.
|
|
|
|
### C. One generation owner and unchanged validator publication
|
|
|
|
Explicit Generate captures an immutable request/context; it never saves an
|
|
authoring revision or opens/approves/mutates a target.
|
|
At most one catalogue/generation operation is active in the page-owned feature.
|
|
Reject competing Generate/refresh/model-change actions visibly before starting
|
|
another request. Cancel/Close share a drainable cleanup as appropriate; no gate
|
|
is held across an await needed by cleanup. New page entry creates a fresh owner.
|
|
|
|
After HTTP completion, enforce current owner/generation/cancellation/model/
|
|
source/head and prior-preview identity before publication. A newer manual preview
|
|
must not be overwritten even if its authoring head is unchanged.
|
|
Make these checks atomic with accepted validator publication: minimally extend
|
|
the existing service with expected-preview/cancellation/current-request admission
|
|
if needed, reusing its strict parser/source/head/template/diff logic.
|
|
Do not merely precheck then call an unguarded publish that can race.
|
|
Preserve all existing manual Validate behavior and tests.
|
|
|
|
Pass the original decoded `message.content` through the authoritative validator,
|
|
without stripping markdown fences, fixing syntax, injecting absent IDs, changing
|
|
unit/source/head, clipping values or replacing invalid output with a template.
|
|
No auto retry/correction loop. A retry is an explicit new request against fresh
|
|
current context. Valid JSON alone does not establish correct user intent;
|
|
show the original goal and exact candidate/diff for human review.
|
|
|
|
Successful output is only an AI-generated read-only validated preview, still
|
|
unverified for intent/physical applicability/testing/approval. Retain model/digest/
|
|
context/goal provenance separately from source facts; model rationale is safe
|
|
text, not evidence or policy. Existing staleness still applies after publication.
|
|
Keep only bounded latest generation evidence/prior success, not hidden history.
|
|
|
|
Failures/cancellation/close/source or manual-preview replacement preserve prior
|
|
success and source state. Late callbacks cannot publish after owner close or a
|
|
new request. No fault becomes healthy "empty model result", Ready, Saved or
|
|
Applied. Manual/no-model workflows remain usable and errors are visible.
|
|
|
|
### D. Real UI and real-model evidence
|
|
|
|
Extend the existing runbook area with explicit local-only acknowledgement,
|
|
catalogue refresh, installed model selection/eligibility, bounded goal, source/
|
|
knowledge preview, Generate/Cancel and separate model-output/error/provenance.
|
|
No network request on route entry/render/unit change.
|
|
|
|
Show valid output through existing candidate/diff/current-Stale presentation.
|
|
Invalid output is labeled unvalidated/not an actionable preview, bounded and
|
|
escaped. Separate old successful preview from rejected/changed request data.
|
|
Global units only project human-readable values; requests/content/diffs stay
|
|
canonical and unchanged. No Save/Approve/Execute/Apply or tool control.
|
|
Page unmount cancels/drains its own request without touching shared Ollama.
|
|
|
|
Native decisive goal on the actual warm baseline:
|
|
`Propose warm-idle target 1250 rpm and set torque at 2000 rpm to 350 N*m; keep every other value unchanged.`
|
|
Require a real local model response whose validated canonical candidate and
|
|
diff match that exact goal, not merely any parseable in-range result.
|
|
Report all attempts honestly. No request repair, canned native response or
|
|
hidden rule-based generator counts as local model success.
|
|
|
|
## FILES OR PROJECTS EXPECTED TO CHANGE
|
|
|
|
Focused Application inference/provider/context/generation and narrow guarded
|
|
preview publication, UI runbook generation/lifetime, Client HTTP DI only if
|
|
needed, tests and related README/docs. No new project/package/host or model
|
|
installation, existing template/authoring-save/rehearsal/physics/protocol change.
|
|
Only `prompts/Step-12-Report.md` under `prompts`.
|
|
|
|
## INTERFACE AND DEPENDENCY REQUIREMENTS
|
|
|
|
Keep nine projects/references, one Client, independent Components, immutable
|
|
source/runbook/authoring values and all template/schema/approval/CAS limits.
|
|
No public network/cloud/model pull, proxies/redirect fallback, source metadata
|
|
backfill, model tool execution, source code/credential upload or arbitrary raw
|
|
command. Generated knowledge cannot promote authority or bypass approval.
|
|
Do not fix the separate recording navigation issue or add Git/durable backups.
|
|
No SDK/workload/runtime/model/system install/update/repair/rollback, staging/
|
|
commit/push or destructive Git; preserve existing work and protected history.
|
|
|
|
## TESTING REQUIREMENTS
|
|
|
|
Map C-01..C-10 to meaningful named tests before handoff:
|
|
|
|
- Real provider over a controlled local HTTP peer/handler: catalogue/details/
|
|
completion fields, model eligibility/digest, remote/cloud/redirect/proxy exclusion,
|
|
one actual chat request, structured options/context and error classification.
|
|
This proves HTTP integration, not that a real LLM generated the test response.
|
|
- Current-source/knowledge/no-match vectors and original validator negative
|
|
outputs, with exact previous-preview/source/head/history preservation.
|
|
Hold real workflow response/read publication to exercise cancel/source changes/
|
|
newer manual preview/closed/new-owner races, with atomic rejection assertions.
|
|
- Fixed byte/depth/goal/deadline and missing/invalid/duplicate critical metadata/
|
|
chunked response bounds; no broad catches or count-only claims. Release owned
|
|
helpers/barriers in finally; do not use sleep/polling as race proof.
|
|
- Actual rendered selection/opt-in/generation/cancel/error/stale/units controls,
|
|
no generation on render, and real diagnostics/recording/replay/approved-
|
|
rehearsal coexistence with counted zero unassigned business-source calls.
|
|
- Keep all 547 baseline cases (179 unit, 368 integration), including manual
|
|
validator/authoring/source/physical gates. Compare canonical request/output/
|
|
source/config/archives and prove no mutation/execution.
|
|
|
|
Run focused cases, then sequentially:
|
|
|
|
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
|
|
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
|
|
|
|
Build all nine projects/native Client. Install/restore code dependencies only
|
|
after a genuine chosen-command missing dependency; this does not authorize
|
|
model/runtime installation or pulling. Recheck actual installed API behavior.
|
|
|
|
Required native/real-model smoke: operator-approved local-only runtime already
|
|
running, verified cloud-disabled status and installed eligible model/digest;
|
|
explicit actual source/context, decisive goal above, original real response,
|
|
same-validator exact diff, no source/approval/target/dynamics-configuration/
|
|
recording changes,
|
|
manual invalid/source-stale handling, cancel/unmount and old routes/units.
|
|
Record runtime/model/version/license/resource context honestly, without secrets
|
|
or thinking traces. Controlled faults are not native platform observations.
|
|
Absent runtime/model/local-only evidence or failure to produce the assigned
|
|
valid native response is BLOCKED/INCOMPLETE, not a waiver or stub-success.
|
|
Stop only task-owned test HTTP/native helpers; do not terminate a shared model
|
|
runtime or reset user data/preferences. No installation/download is automatic.
|
|
|
|
## DOCUMENTATION REQUIREMENTS
|
|
|
|
Update README/index/architecture/build guide and local-generation/runbook usage:
|
|
explicit local-only opt-in/eligible model, operator prerequisites, verified public
|
|
API contracts, cloud delegation caveat, matched synthetic pack/source/context,
|
|
strict unchanged-validator output, current-owner/manual-preview CAS/cancel/drain,
|
|
real-model versus stub evidence and no write/tool/physical authority.
|
|
Step-11 is accepted; Step-12 remains pending manual review. Broader diagnostics/
|
|
scenario research/executors, vector knowledge and demonstration are future.
|
|
|
|
## ACCEPTANCE CRITERIA
|
|
|
|
| ID | Criterion | Evidence |
|
|
|---|---|---|
|
|
| AC-01 | C-01..C-03 explicit local-only transport/model eligibility and exact applicable context | Real HTTP boundary/metadata/remote-negative tests and operator/runtime local-only prerequisite evidence |
|
|
| AC-02 | C-04/C-05/C-09 original model content uses authoritative validation without repair/authority/side effects | Exact controlled outputs, unchanged negative-parser/source tests and actual real-model decisive goal |
|
|
| AC-03 | C-06..C-08 one owner, atomic source/model/manual-preview publication and bounded error/cancel/close handling | Controlled interleavings/limits/HTTP failures and rendered command/lifetime assertions |
|
|
| AC-04 | C-10 all 547 regressions/new coverage, real-model/native workflow and full nine-project Release build pass | Exact worker commands/exits/warnings/counts, zero business-source mutation and native/stub distinction |
|
|
| AC-05 | Matrix/self-review/docs/history/protection/manual gate accurately describe limits/prerequisites | Own post-green producer/consumer review, named evidence and `prompts/Step-12-Report.md` |
|
|
|
|
## OUT-OF-SCOPE WORK
|
|
|
|
Cloud/public inference, model/runtime installation/pull/update/agent hosting,
|
|
tool/runbook execution, proposal Save/approval/programming, broad diagnostic/
|
|
scenario planning, embeddings/vector/RAG/web research, persistent chat/model/
|
|
runbook/Git backup storage, new templates/unit families/project/package/host,
|
|
hardware/physics changes and unrelated cleanup.
|
|
No future assignment, agents, automatic handoff, orchestration/shared-gate edit,
|
|
staging, commit or push.
|
|
|
|
## REPORTING REQUIREMENTS
|
|
|
|
Save `prompts/Step-12-Report.md` wholly inside exactly one plain triple-backtick
|
|
fence, no language tag/outside text/nested fences. Include identifier/title/status,
|
|
functions/files/interfaces, C-01..C-10/AC-01..AC-05 mapping with named executed
|
|
evidence, exact local-only/model/digest/context/response/validator/publish/cancel/
|
|
negative/limit/no-side-effect outcomes, commands/exits/warnings/per-project
|
|
counts, actual real-model/native versus stub/control evidence and prerequisites,
|
|
docs/README, own post-green source-path self-review, limitations/deviations/
|
|
blockers and preservation. COMPLETE requires all assigned checks; otherwise
|
|
report INCOMPLETE/BLOCKED with the precise unmet criterion.
|
|
Save and STOP; do not begin Step-13.
|