feat: add AI-assisted ISAC authoring
This commit is contained in:
JB
@@ -1909,6 +1909,61 @@ its state to assistive technology. Focus remains in the active field when the
|
||||
generated script refreshes, and reduced-motion preferences remove expansion
|
||||
and replacement transitions.
|
||||
|
||||
#### AI mechanic drafting
|
||||
|
||||
`MechanicProgramEditor` keeps its complete manual authoring controls available
|
||||
to every authorized data author. Place the optional AI drafting panel inside
|
||||
that editor, after the source description and before the structured mechanic
|
||||
controls. AI assistance must never replace, hide, lock, or reset the manual
|
||||
workflow.
|
||||
|
||||
The panel uses one compact modeled-data surface with a blue information rail.
|
||||
Its heading names `AI MECHANIC DRAFTING` and identifies the output as a draft.
|
||||
An author submits the exact in-game mechanic text and optional context. Keep the
|
||||
source text editable during clarification and preview. Use the standard pending
|
||||
button treatment while a request runs and block duplicate submissions.
|
||||
|
||||
Agents without `ai.mechanic.generate` still see the collapsed panel. Disable
|
||||
its request control, label the state `PERMISSION REQUIRED`, and direct
|
||||
the agent to request permission from an administrator. The disabled state must
|
||||
not expose API configuration, internal prompt content, model controls, or a
|
||||
working form submission.
|
||||
|
||||
The panel presents five explicit states:
|
||||
|
||||
- `READY FOR INPUT` shows the source-text field and Generate Draft action.
|
||||
- `DRAFTING` keeps the submitted text visible, announces progress through a
|
||||
polite live region, and disables repeat actions.
|
||||
- `CLARIFICATION REQUIRED` lists each focused question with its reason and
|
||||
bounded answer control. The author may answer, revise the source text, or
|
||||
return to manual authoring.
|
||||
- `CAPABILITY GAP` names the unsupported behavior and displays the developer
|
||||
handoff, supported approximation, and optional workaround in separate
|
||||
labeled blocks. Do not present a capability gap as validation failure.
|
||||
- `DRAFT PREVIEW` shows assumptions, warnings, readiness, and the generated
|
||||
script before an explicit `APPLY TO EDITOR` action.
|
||||
|
||||
Applying a draft fills the structured fields in the current unsaved editor.
|
||||
It does not save, publish, submit a proposal, close the editor, or discard
|
||||
manual changes without confirmation. Show a concise before-and-after summary
|
||||
when applying the draft would replace configured branches, pools, controls, or
|
||||
outcomes. The standard ISAC save lifecycle begins only after the author reviews
|
||||
and saves the resulting form.
|
||||
|
||||
Use text labels with status colors. Orange marks Generate, Answer, and Apply
|
||||
actions. Blue identifies modeled information, yellow marks assumptions or
|
||||
unsupported coverage, and red marks request or validation failures. Never use
|
||||
model confidence as the only acceptance signal.
|
||||
|
||||
On narrow screens, stack questions, answers, preview metadata, and actions in
|
||||
source order. Keep controls at least 44 pixels tall and keep the draft preview
|
||||
inside the viewport. Focus moves to the first clarification question, the
|
||||
capability-gap heading, or the draft-preview heading when a result arrives.
|
||||
Return focus to the initiating control when the author closes or resets the
|
||||
panel. Announce the result state without reading the complete generated script.
|
||||
Reduced-motion preferences remove pending, disclosure, and preview
|
||||
transitions while preserving textual state changes.
|
||||
|
||||
#### Generated mechanic script
|
||||
|
||||
The shared `PseudoScript` component gives authors and builders a readable
|
||||
@@ -2080,6 +2135,27 @@ to an authorized operator. Use monospaced text for raw loadout and prediction
|
||||
snapshots; labels, findings, and errors stay in the standard operational
|
||||
typeface.
|
||||
|
||||
Calculation revision editors include the optional AI drafting panel after the
|
||||
revision identity and before the manual stage and profile controls. Reuse the
|
||||
`READY FOR INPUT`, `DRAFTING`, `CLARIFICATION REQUIRED`, `CAPABILITY GAP`, and
|
||||
`DRAFT PREVIEW` states from AI mechanic drafting. The panel uses calculation
|
||||
language, identifies the active or edited base revision, and previews changes
|
||||
to stages, weapon profiles, and Skill profiles.
|
||||
|
||||
Agents without `ai.calculation.generate` see the collapsed
|
||||
`PERMISSION REQUIRED` state. Agents with the permission may request and apply a
|
||||
draft, but the panel leaves every manual calculation control available.
|
||||
Applying a draft fills the open unsaved revision form. It does not save the
|
||||
revision, activate it, grant `calculation.publish`, or bypass the activation
|
||||
confirmation. Before applying, show current and proposed counts for stages,
|
||||
weapon profiles, and Skill profiles beside assumptions, warnings, and the
|
||||
generated script.
|
||||
|
||||
Use the same pending, duplicate-request, focus, live-region, mobile stacking,
|
||||
44-pixel target, and reduced-motion rules as the mechanic assistant. A
|
||||
calculation capability gap names the unsupported stage, operator, binding,
|
||||
curve, or runtime behavior and keeps the manual revision editor available.
|
||||
|
||||
### Image Library assignment state
|
||||
|
||||
An ISAC game-data editor registers each uploaded icon in the Image Library. The
|
||||
|
||||
@@ -427,6 +427,101 @@ state changes, phases, and formulas. No route accepts the generated text as
|
||||
input, and no server process executes it. Operators edit structured fields; the
|
||||
formatter regenerates the listing after each change.
|
||||
|
||||
## AI-assisted mechanic drafting
|
||||
|
||||
Manual mechanic authoring remains the complete authoring path. The AI assistant
|
||||
produces an optional draft for the existing structured editor. It cannot save,
|
||||
publish, approve, or submit game data, and it cannot alter application code.
|
||||
An author may ignore, revise, or replace any generated field through the manual
|
||||
controls.
|
||||
|
||||
The shared mechanic editor exposes the mechanic assistant for standard and
|
||||
exotic Talents, OS Protocol Talents, Skill Chip Talents, and Specialization
|
||||
tree-rank effects. Calculation revisions use a separate assistant contract
|
||||
because their typed stage schema and publication authority differ from
|
||||
source-owned mechanic programs.
|
||||
|
||||
The server owns a versioned mechanic-authoring prompt and context builder. Each
|
||||
request receives the source type, progression contract, submitted game text,
|
||||
current draft when supplied, code-defined mechanic registries, and the active
|
||||
ISAC Attribute catalog. Attribute context includes stable IDs, names, units,
|
||||
descriptions, and calculation metadata. The client cannot replace the system
|
||||
instructions, choose arbitrary models, attach files, add tools, or add external
|
||||
URLs.
|
||||
|
||||
The OpenAI integration uses the Responses API with Structured Outputs, no
|
||||
tools, and `store: false`. The application stores the bounded clarification
|
||||
history needed for the current drafting session. Requests use a fixed
|
||||
server-configured model, a privacy-preserving user safety identifier, input and
|
||||
output limits, timeouts, duplicate-request protection, and per-agent rate
|
||||
limits. The API key remains on the server.
|
||||
|
||||
The model returns one structured result:
|
||||
|
||||
- `clarification_required` contains bounded questions whose answers affect the
|
||||
calculation model.
|
||||
- `draft_ready` contains the typed mechanic draft, assumptions, warnings,
|
||||
readiness state, and a short explanation.
|
||||
- `capability_gap` names unsupported runtime behavior, the nearest supported
|
||||
representation, an optional workaround, and the schema, runtime, editor,
|
||||
reference, and test changes a developer would need to add support.
|
||||
|
||||
The server validates `draft_ready` output against the response schema and the
|
||||
same deterministic mechanic parser used by manual authoring. Unknown events,
|
||||
Attributes, value models, scopes, operators, reducers, or outcomes fail
|
||||
validation. The client receives no draft when local validation fails.
|
||||
|
||||
The author reviews a validated draft and chooses whether to apply it to the
|
||||
unsaved editor. Applying a draft changes client form state only. The existing
|
||||
module action performs canonical validation, contribution interception,
|
||||
approval, persistence, and game-data audit logging after the author initiates
|
||||
the normal save flow.
|
||||
|
||||
The `ai.mechanic.generate` permission authorizes generation and clarification
|
||||
requests. The server checks it for every request. Agents without the permission
|
||||
may see the disabled assistant entry point, but they retain all manual controls
|
||||
allowed by their data role.
|
||||
|
||||
Successful generation operations append sanitized events under the
|
||||
`ai_assistance` audit category. Events identify the operator, source type,
|
||||
prompt-context version, model, result type, token usage, request ID, and
|
||||
validation result. Audit snapshots exclude the API key,
|
||||
environment configuration, hidden model reasoning, authentication data, and
|
||||
unbounded prompt content. Applying a draft changes client state and creates no
|
||||
server event. The owning module's game-data audit event remains the record of
|
||||
any saved mechanic change.
|
||||
|
||||
### AI-assisted calculation-revision drafting
|
||||
|
||||
The calculation assistant converts an operator's plain-language combat-model
|
||||
request into an optional draft revision. It receives the current active or
|
||||
edited revision, the calculation-stage vocabulary, weapon and Skill profile
|
||||
contracts, and the active ISAC Attribute catalog. Its versioned prompt,
|
||||
structured response schema, validation, and application adapter remain
|
||||
separate from mechanic drafting.
|
||||
|
||||
The assistant returns clarification questions, a validated revision draft, or
|
||||
a calculation capability gap. A capability gap identifies the missing stage,
|
||||
operator, curve, binding, runtime behavior, or validation rule and lists the
|
||||
application and test changes needed to support it. The server rejects unknown
|
||||
stage keys, locked-position changes, duplicate bindings, invalid Attribute
|
||||
references, unsupported operators, and malformed curve or cap values through
|
||||
the deterministic calculation-revision parser.
|
||||
|
||||
The `ai.calculation.generate` permission authorizes calculation drafting and
|
||||
clarification requests. It does not grant revision mutation or publication.
|
||||
Applying a result changes the open revision form in the client. The operator
|
||||
must review and save that draft through the existing revision action. The
|
||||
separate `calculation.publish` permission and activation confirmation remain
|
||||
mandatory before the saved draft affects loadout results.
|
||||
|
||||
Successful calculation-generation requests append sanitized events under
|
||||
`ai_assistance`. These events use calculation-specific actions, identify the
|
||||
base revision and generated contract version, and follow the same request,
|
||||
token-usage, result, and secret-exclusion rules as mechanic-assistance events.
|
||||
Applying a draft creates no server event. Existing `calculation_configuration`
|
||||
events remain the evidence for revision saves and activation.
|
||||
|
||||
Source authors define the builder controls required by their mechanic as typed
|
||||
toggle, slider, or numeric scenario inputs. Each input records its label,
|
||||
guidance, bounds when applicable, default value, and best-case value. These
|
||||
|
||||
Reference in New Issue
Block a user