Metadata-Version: 2.5
Name: devagent-ignition
Version: 0.1.8
Summary: Offline industrial HMI engineering and Ignition Perspective candidate tools (production deployment not qualified)
Project-URL: Repository, https://github.com/tomha85/devagent-ignition
Project-URL: Documentation, https://github.com/tomha85/devagent-ignition#readme
Author: DevAgent contributors
Keywords: hmi,ignition,industrial-automation,perspective,scada
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.14,>=3.13
Requires-Dist: asyncua==2.1.0
Description-Content-Type: text/markdown

# DevAgent

**AI-assisted industrial HMI engineering for Ignition Perspective**

DevAgent turns customer plant information into reviewable 2D/3D HMI concepts, validated industrial engineering models, and reproducible **native Ignition Perspective candidates**.

[Quick start](#quick-start) · [Architecture](#architecture) · [Creator workflow](#creator-workflow) · [Ignition handoff](#native-ignition-handoff) · [Verification](#verification)

> **Current scope:** engineering and isolated-lab candidates. Authenticated Gateway import, native Perspective runtime FAT, real OPC UA/PLC mapping validation, and production release have **not** been qualified. Production is **HOLD**.

## Capabilities

| Area | What it provides |
| --- | --- |
| **AI-first Creator** | Connect your own supported cloud or local model (BYOM); review proposals before applying them. |
| **Engineering validation** | Check equipment identities, signal roles, topology, provenance, and requirements using deterministic rules. |
| **2D + 3D design** | Explore Original V8 2D Flow and Original R9 Four Spirals demos, or generate a customer-specific preview. |
| **Equipment diagnostics** | Inspect declared motor, VFD, photoeye, fault, quality, and timestamp fields. Missing mappings remain explicit. |
| **Ignition handoff** | Generate a guarded, read-only native Perspective project candidate from a genuine authorized reference export. |
| **Simulation + FAT** | Run isolated synthetic OPC UA tests and generate traceable engineering evidence. |

## Architecture

```text
   CUSTOMER INPUTS
   Requirements | Equipment | Connections | PLC / tag exports
                           |
                           v
                  BYOM AI AGENT
                  Proposal + review
                           |
                           v
              ENGINEERING VALIDATION
         Equipment | Signals | Topology | Safety
                           |
            +--------------+---------------+
            |              |               |
            v              v               v
       2D HMI         3D HMI         Native Ignition
       preview        preview        project candidate
            |              |               |
            +--------------+---------------+
                           |
                           v
               ISOLATED LAB + OFFLINE FAT
                           |
                    Gateway import
                    and runtime tests
                    [NOT YET QUALIFIED]
                           |
                           v
              Real OPC UA source validation
              Independent FAT / site approval
                           |
                           v
                APPROVED PRODUCTION RELEASE
                         [HOLD]
```

**Engineering rule:** AI proposes; deterministic checks validate; simulation and a real test Gateway supply separate evidence; an authorized engineer approves. A synthetic PASS cannot establish physical PLC correctness.

## Quick start

### Install and run (Ubuntu / Linux)

Requires **Python 3.13**. Install the published package from PyPI, then launch the local Creator:

```bash
python3.13 -m pip install --no-cache-dir --index-url https://pypi.org/simple/ devagent-ignition==0.1.1
devagent start
```

Open **http://127.0.0.1:8895/** in your browser. No GitHub clone is required. If port 8895 is in use, run `devagent start --port 8962` and open `http://127.0.0.1:8962/`.

If `devagent` is not found, make sure the Python 3.13 environment you installed into is activated and its `bin` directory is on your `PATH`. Use a dedicated virtual environment if you also have `devagent-ai` installed, since both packages provide a `devagent` executable.

### Develop or verify from source

**Requirements:** Linux/Ubuntu, Git, and Python 3.13. Optional browser and OPC UA tests have additional dependencies.

```bash
git clone https://github.com/tomha85/devagent-ignition.git
cd devagent-ignition

sha256sum -c SHA256SUMS.txt
python3 -m unittest discover -s tests -q
python3 devagent_hmi.py preflight

# Start the local HMI Creator on port 8895.
./start.sh
```

Open **http://127.0.0.1:8895/** on the same computer.

Choose another local port if 8895 is occupied:

```bash
DEVAGENT_SPATIAL_PORT=8962 ./start.sh
```

The local Creator does not automatically connect to an Ignition Gateway or modify PLCs. Use `python3 devagent_hmi.py --help` to explore CLI commands.

## Creator workflow

1. **Connect AI (optional).** Choose your own supported provider/model and test the connection. Review all generated drafts; AI responses are not verified engineering facts.
2. **Describe the site.** Enter plant requirements and provide available equipment, tag, and connection files. See [sample customer inputs](sample_customer_inputs/).
3. **Choose a starting point.** Select **2D Flow**, **3D Flow**, or **New Project**. The Original V8/R9 options are source-backed demos, not a representation of your plant.
4. **Analyze and validate.** Resolve contract errors and review any inferred or missing equipment and signal relationships.
5. **Generate a preview.** Navigate floors, select equipment, and inspect only available diagnostics.
6. **Review evidence.** Keep synthetic testing separate from real PLC data and qualify the application in an isolated Gateway before production consideration.

Validate a model without launching the UI:

```bash
python3 devagent_hmi.py validate --model examples/warehouse.json
```

Other included samples: [single floor](examples/single_floor.json), [warehouse](examples/warehouse.json), and [water treatment](examples/water.json).

### BYOM and data handling

DevAgent supports multiple cloud and local provider adapters, including compatible Ollama/vLLM endpoints. A successful model connection test establishes connectivity, **not engineering correctness**. Follow your organization's rules before sending plant documents, tag exports, or operational data to an external provider.

See [AI provider setup](AGENT_V05.md) for connection details and security limitations.

## Native Ignition handoff

DevAgent includes a Native Ignition Perspective compiler for guarded, read-only offline project candidates. Automated authenticated Gateway deployment: Not implemented; real Gateway runtime FAT and production release remain HOLD.


DevAgent can compile an **offline, read-only Perspective candidate**. It does not yet provide a qualified one-click customer deployment or automatically create real OPC UA connections and Gateway tag providers.

The engineering handoff is:

1. Obtain an authorized, genuine Ignition Perspective project export for the template envelope.
2. Validate the customer model and prepare an engineer-reviewed, lab-scoped binding manifest.
3. Compile and verify the native candidate against the reference ZIP and source hashes.
4. Import only into an approved, backed-up **isolated test Gateway**.
5. Verify actual Perspective rendering, floor/equipment interactions, tag quality, and OPC-to-HMI FAT.
6. Validate real source identity and site behavior independently before requesting production approval.

Create a pending binding manifest (tag paths are intentionally empty):

```bash
python3 devagent_hmi.py v07-binding-skeleton \
  --model examples/warehouse.json \
  --out /tmp/devagent-pending-lab-bindings.json
```

The manifest is not preapproved. An engineer must review its model identity, decisions, and any lab paths before compilation. Discover the exact compiler flags with:

```bash
python3 devagent_hmi.py v083-native-compile --help
python3 devagent_hmi.py v083-native-verify --help
```

**Never infer** OPC UA NodeIds, motor/VFD associations, PE IN/OUT semantics, speeds, fault states, or operating quality from a demo.

Read the [native operator/deployment notes](V083_NATIVE_RUNTIME_AND_DEPLOYMENT.md) and [native binding/FAT guide](V07_NATIVE_IGNITION_AND_FAT.md).

## Verification

```bash
sha256sum -c SHA256SUMS.txt
python3 -m compileall -q devagent_spatial devagent_hmi.py tests
python3 -m unittest discover -s tests -q
python3 devagent_hmi.py preflight
```

GitHub Actions: [.github/workflows/offline-ci.yml](.github/workflows/offline-ci.yml). Its CI jobs cover offline tests, static checks, a browser workflow, and isolated synthetic OPC UA tests. **CI PASS is not a live Gateway FAT or site-acceptance result.**

### Current qualification boundaries

| Gate | State |
| --- | --- |
| Creator 2D/3D reference previews | Implemented; local/browser validation |
| Native Perspective candidate and offline vendor parsing | Offline PASS |
| Isolated synthetic OPC UA protocol checks | Lab-only evidence |
| Authenticated Gateway project import and native rendering | **HOLD** |
| Gateway-connected OPC -> tag -> HMI FAT | **HOLD** |
| Real customer PLC mappings and SAT | **HOLD** |
| Production release | **HOLD** |

Unavailable values must show **NOT MAPPED**, **UNKNOWN**, or a clear BAD/STALE quality indication, not fabricated operating states. START/STOP/RESET actions remain disabled in the unqualified native operator candidate.

## Repository guide

| Path | Purpose |
| --- | --- |
| `devagent_hmi.py`, `start.sh` | CLI and local Creator entry points |
| `devagent_spatial/` | Models, validators, native compiler, simulator, FAT infrastructure |
| `assets/` | Creator UI and HMI visualization |
| `reference/` | Preserved Original V8 and R9 reference sources |
| `examples/`, `templates/`, `sample_customer_inputs/` | Starter plant inputs |
| `tests/`, `scripts/` | Regression and engineering verification |
| `.github/workflows/` | Offline CI automation |

For engineering detail, see the [qualification record](V083_QUALIFICATION.json), [native import milestone](V083_NATIVE_IMPORT_MILESTONE.md), and [production acceptance gates](PRODUCTION_ACCEPTANCE.md). Historical milestones remain in separate documentation; this README is the starting point.

---

**DevAgent's purpose:** faster, more repeatable industrial HMI engineering with explicit signal provenance, deterministic verification, and evidence-based commissioning.
