wwtools/graccesscli/docs/llm-integration.md

LLM Integration Guide

This document is the implemented machine-facing contract for using graccess_cli as an LLM automation layer for AVEVA/Wonderware System Platform IDE work through GRAccess.

The CLI still preserves legacy human output and existing --json shapes. LLMs should use --llm-json for a stable envelope.

Stable Envelope

Galaxy-bound routed commands and LLM helper commands accept --llm-json.

{
  "success": true,
  "command": "object snapshot",
  "galaxy": "ZB",
  "target": "TestMachine",
  "data": {},
  "commandResult": null,
  "warnings": [],
  "unavailable": [],
  "error": null,
  "exitCode": 0
}

Failures use the same envelope with success=false, error, and exitCode.

Discovery

Use capabilities before generating plans:

graccess capabilities --json
graccess capabilities --llm-json

The capability registry is code-backed, not scraped from prose. It returns command name, dispatcher command/subcommand, argument metadata, mutation status, session routing support, confirmation target rule, and output schema name.

Read Workflow

Prefer session mode for repeated reads:

graccess session start --galaxy ZB --node .
graccess object snapshot --galaxy ZB --name TestMachine --type template --llm-json

object snapshot includes object details, all attributes, configurable attributes, extended attributes, relationships, lineage, children, contained objects, package-backed attribute values/script bodies where available, and Unavailable entries for COM-backed sections that cannot be read safely.

Useful read commands:

graccess object get --galaxy ZB --name TestMachine --type template --llm-json
graccess object lineage --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object children --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object attribute value get --galaxy ZB --name TestMachine --type template --attribute Description --llm-json
graccess object scripts list --galaxy ZB --name TestMachine --type template --llm-json
graccess object scripts get --galaxy ZB --name TestMachine --type template --script UpdateTestChangingInt --llm-json

The CLI tries direct GRAccess reads first. If direct GRAccess does not expose inheritance, attribute values, or script bodies, read commands may export the target object to a temporary .aaPKG, parse textual/package entries, recurse into nested package archives, parse binary UTF-16 script extension records, and delete the temp files. SQL Server repository reads are not part of normal CLI behavior and should only be used for development verification/debugging.

Script body access is adapter-dependent. For ScriptExtension objects, a bare script name maps to .ExecuteText. Mutating script and attribute commands prefer ConfigurableAttributes[...] before Attributes[...]. On the local GRAccess build, body fields such as ExecuteText and Expression are package-only and are not persisted by IAttribute.SetValue, so the CLI fails fast for those writes instead of returning a false success. Mutable settings such as TriggerPeriod and TriggerType remain available through object scripts settings set. If neither direct GRAccess nor the package fallback exposes body text, script read commands return structured unavailable details instead of pretending success.

Use the script settings wrapper for IDE-style script configuration:

graccess object scripts settings set --galaxy ZB --name '$TestMachine' --type template --script UpdateTestChangingInt --trigger-period-ms 500 --lock-trigger-period --confirm --confirm-target '$TestMachine' --llm-json

Use the create wrapper for new object-level script extensions:

graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --trigger-type Periodic --trigger-period-ms 1000 --confirm --confirm-target '$MyTemplate' --llm-json

Inheritance And Embedded Objects

For template families, model inheritance and containment explicitly. Do not rely on a single field being populated by every GRAccess version.

graccess object snapshot --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object lineage --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object children --galaxy ZB --name '$TestMachine' --type template --llm-json
graccess object query-condition --galaxy ZB --type all --condition derivedOrInstantiatedFrom --value '$gMachine' --llm-json
graccess object query-condition --galaxy ZB --type all --condition basedOn --value '$gMachine' --llm-json
graccess object query-condition --galaxy ZB --type all --condition containedBy --value '$TestMachine' --llm-json

Read data.Lineage, data.Children, data.ContainedObjects, data.Object.DerivedFrom, data.Object.BasedOn, ContainedName, and HierarchicalName when available. The documented ZB $TestMachine family is an example: $TestMachine extends $gMachine, while $TestMachine.DelmiaReceiver and $TestMachine.MESReceiver are contained embedded templates.

Create derived templates and instances with contained objects when the family requires embedded children:

graccess template derive --galaxy ZB --name '$gMachine' --type template --new-name '$MyMachine' --confirm --confirm-target '$gMachine' --llm-json
graccess template instantiate --galaxy ZB --name '$TestMachine' --type template --new-name TestMachine_021 --create-contained --confirm --confirm-target '$TestMachine' --llm-json

Edit contained child templates or instances by targeting their own object names, such as $TestMachine.DelmiaReceiver or DelmiaReceiver_001, and use normal checkout/save/checkin safety.

Validation And Batch

Per-command dry-run validates command shape and confirmation without calling mutating GRAccess methods:

graccess object attribute value set --galaxy ZB --name TestMachine --type template --attribute Description --value Updated --data-type string --confirm --confirm-target TestMachine --dry-run --llm-json

Plan validation:

graccess validate --request plan.json --llm-json

Batch validation or execution:

graccess batch --file plan.json --mode validate --llm-json
graccess batch --file plan.json --mode execute --llm-json

Plan shape:

{
  "Galaxy": "ZB",
  "Node": ".",
  "Commands": [
    {
      "Command": "object checkout",
      "Args": {
        "name": "TestMachine",
        "type": "template",
        "confirm": true,
        "confirm-target": "TestMachine"
      }
    }
  ]
}

Every mutating step must include its own confirm=true and exact confirm-target. There is no global mutation confirmation. Batch execute stops on first failure.

IDE Intent Wrappers

Use intent-level commands instead of generic property edits when possible:

graccess area list --galaxy ZB --llm-json
graccess area create --galaxy ZB --template '$Area' --name Area_Test --confirm --confirm-target '$Area' --llm-json
graccess engine list --galaxy ZB --llm-json
graccess engine create --galaxy ZB --template '$AppEngine' --name AppEngine_Test --confirm --confirm-target '$AppEngine' --llm-json
graccess instance assign-area --galaxy ZB --name TestMachine_001 --area Area_Test --confirm --confirm-target TestMachine_001 --llm-json
graccess instance assign-engine --galaxy ZB --name TestMachine_001 --engine AppEngine_Test --confirm --confirm-target TestMachine_001 --llm-json
graccess instance assign-container --galaxy ZB --name TestMachine_001 --container ParentObject --confirm --confirm-target TestMachine_001 --llm-json
graccess io assign --galaxy ZB --name TestMachine_001 --attribute DeviceAddress --value D100 --confirm --confirm-target TestMachine_001 --llm-json

object set --property area|host|container|toolset|security-group attempts to resolve the named GRAccess object first, then falls back to raw string assignment for version-specific setters.

Safety Rules

1. Start with capabilities and read-only snapshots.
2. Do not mutate without an exact object or file target.
3. Never use wildcard bulk mutation in production.
4. Use --dry-run --llm-json before mutation plans.
5. Snapshot before editing and re-read after editing.
6. Stop after the first failed mutation or CommandResult.Successful=false.
7. Treat missing or unavailable fields as unknown, not false.
8. Prefer test objects or derived templates before production targets.
9. Use session mode for repeated galaxy-bound commands.
10. Use deployment commands only when the user explicitly names targets.