# 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`. ```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: ```powershell 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: ```powershell 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: ```powershell 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`; `object scripts set` writes the matching script body attribute through GRAccess. Mutating script and attribute commands prefer `ConfigurableAttributes[...]` before `Attributes[...]`, because script extension settings such as `TriggerPeriod`, `TriggerType`, `Expression`, and `ExecuteText` are configuration attributes in common GRAccess builds. 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: ```powershell 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: ```powershell graccess object scripts create --galaxy ZB --name '$MyTemplate' --type template --script OnScan --file OnScan.txt --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. ```powershell 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: ```powershell 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: ```powershell 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: ```powershell graccess validate --request plan.json --llm-json ``` Batch validation or execution: ```powershell graccess batch --file plan.json --mode validate --llm-json graccess batch --file plan.json --mode execute --llm-json ``` Plan shape: ```json { "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: ```powershell 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.