Metadata-Version: 2.4
Name: devagent-ai
Version: 0.8.13
Summary: Evidence-driven local autonomous software engineering agent
Author: Tom Ha
Maintainer: Tom Ha
License: MIT
Project-URL: Homepage, https://github.com/tomha85/devagent
Project-URL: Repository, https://github.com/tomha85/devagent
Project-URL: Issues, https://github.com/tomha85/devagent/issues
Project-URL: Changelog, https://github.com/tomha85/devagent/blob/main/CHANGELOG.md
Project-URL: Sponsor, https://github.com/sponsors/tomha85
Keywords: ai,agent,developer-tools,software-engineering,verification,local-first
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: openai>=1.40.0
Requires-Dist: anthropic>=0.34.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: live
Requires-Dist: asyncua<3,>=2.0; extra == "live"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: asyncua<3,>=2.0; extra == "dev"
Dynamic: license-file

# DevAgent

[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![Status: Beta](https://img.shields.io/badge/status-beta-blue.svg)](https://github.com/tomha85/devagent#project-status)
[![Sponsor DevAgent](https://img.shields.io/badge/Sponsor-DevAgent-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/tomha85)

**An evidence-driven engineering agent for software engineering, offline PLC engineering/FAT review, and read-only onsite commissioning.**

> **From requirement to evidence-backed engineering decisions.**

DevAgent is free during public beta. If it saves you engineering time, consider [supporting continued development](https://github.com/sponsors/tomha85).

- **Project:** https://github.com/tomha85/devagent
- **Documentation:** https://github.com/tomha85/devagent#readme
- **Issues:** https://github.com/tomha85/devagent/issues

## General Architecture

DevAgent has **three sibling product branches** under one evidence-driven core. Each branch owns a distinct engineering responsibility, input model, safety boundary, and qualification path.

```text
                         DevAgent Core
              Evidence-Driven Engineering Platform
                              |
          +-------------------+-------------------+
          |                   |                   |
          v                   v                   v
 Software Engineering     DevAgent PLC        DevAgent Live
 Product Branch #1        Product Branch #2   Product Branch #3
          |                   |                   |
 Local / GitHub repo      PLC export           Engineering context
          |               Siemens              + OPC UA endpoint(s)
          |               Rockwell                  |
          |               Schneider                 v
          |                   |              Reconcile / Trust
          v                   v              Freshness / History
 Understand / Plan       Canonical PLC               |
 Modify / Test / Review  Engineering Model           v
          |                   |              Deterministic
          v                   v              Commissioning Diagnosis
 Engineering Report      Analyze / Verify             |
 + Safe Branch           FAT / Release Readiness      v
                                                Evidence / Explanation
                                                + Next Safe Check
```

| Product branch | Primary input | Authority |
| --- | --- | --- |
| **Software Engineering** | Local / GitHub repository | Understand, modify, verify, review, report, publish a safe branch |
| **DevAgent PLC** | Exported PLC engineering artifacts | Offline engineering review, requirements, FAT, evidence, release readiness |
| **DevAgent Live** | Read-only engineering context + OPC UA runtime | Onsite commissioning diagnosis, runtime evidence, history, Q&A - **no PLC control** |

### Read-only PLC to Live integration contract

DevAgent Live is **not a child of DevAgent PLC**. Stable PLC engineering context can cross into Live through a bounded read-only adapter contract. FAT and release-readiness authority stays with DevAgent PLC; OPC UA sessions, runtime trust/history, diagnosis, and commissioning Q&A stay with DevAgent Live.

```text
Canonical PLC Engineering Model
              |
              | READ-ONLY ENGINEERING CONTEXT
              v
       DevAgent Live Adapter <----- OPC UA Runtime Evidence
              |
              v
      Engineering <-> Runtime Join
              |
              v
      Commissioning Diagnosis
```

The read-only engineering-context path does **not** transfer FAT authority, release-readiness authority, or PLC control authority to DevAgent Live.

For the expanded architecture, see:
https://github.com/tomha85/devagent/blob/main/docs/general-architecture.md

## Why DevAgent?

Many AI engineering tools optimize first for generation. DevAgent is built around a different question:

**Can this engineering claim be supported by evidence on the exact analyzed revision, PLC export, or trusted runtime state?**

Core principles include:

- evidence before modification;
- explicit acceptance contracts;
- false-`VERIFIED` resistance;
- minimal-change discipline;
- backups before edits;
- repository-native verification;
- independent review;
- bring-your-own-model support;
- deterministic publication rules;
- a strict read-only commissioning boundary for DevAgent Live.

## Install

Standard package:

```bash
python -m pip install devagent-ai
```

With OPC UA runtime support for DevAgent Live:

```bash
python -m pip install "devagent-ai[live]"
```

Or with pipx:

```bash
pipx install devagent-ai
```

The PyPI distribution is `devagent-ai`; the Python package and CLI command are both `devagent`.

## Software Engineering

Run DevAgent from a repository and describe the engineering outcome:

```bash
cd my-repo
devagent "Fix the websocket reconnect bug and add regression tests"
```

A normal software-engineering path is:

```text
DISCOVER / UNDERSTAND
        |
        v
COMPILE ACCEPTANCE CONTRACT
        |
        v
BASELINE / PLAN / GATHER CONTEXT
        |
        v
IMPLEMENT MINIMAL PATCH
        |
        v
TARGETED + BROAD VERIFICATION
        |
        v
INDEPENDENT REVIEW
        |
        v
FINAL CURRENT-REVISION VERIFICATION
        |
        v
FULL ENGINEERING REPORT
        |
        v
VERIFIED ONLY: COMMIT + FAST-FORWARD PUSH SAFE BRANCH
```

DevAgent runtime does not create pull requests, merge, rebase, force-push, or deploy.

## DevAgent PLC

DevAgent PLC performs offline/pre-site engineering review for supported exports from:

- **Rockwell Studio 5000 / Logix Designer** - full-project `.L5X`;
- **Siemens TIA Portal** - supported exported source/XML engineering artifacts;
- **Schneider Electric EcoStruxure Control Expert / Unity Pro** - supported XML exchange exports, with `.XEF` preferred.

Example:

```bash
devagent plc ./exports/Line1_Controller.L5X \
  --requirements ./requirements/line1.md \
  --ai \
  --output-dir ./plc-review/line1-current
```

The PLC workflow can provide engineering review, requirements verification, risk detection, FAT planning, regression analysis, recommendations, evidence, and release-readiness reporting. Static analysis does not pretend to replace simulator, HIL, field wiring, process physics, or real-controller execution when those are required.

Full PLC guide:
https://github.com/tomha85/devagent/blob/main/docs/plc-engineer-guide.md

## DevAgent Live

DevAgent Live is the separate **read-only onsite commissioning** branch. It can combine supported engineering context with trusted OPC UA runtime evidence to diagnose blockers and explain the next evidence-backed check.

```text
Supported PLC engineering context
              +
      OPC UA runtime endpoint
              |
              v
         DevAgent Live
              |
              v
  reconcile engineering <-> runtime
              |
              v
 deterministic diagnosis + evidence
```

Example:

```bash
devagent live assist \
  --project-folder /path/to/customer-line1 \
  --primary-project plc/Line1.L5X \
  --endpoint opc.tcp://192.168.10.20:4840/ \
  --history-seconds 900 \
  --ai \
  --provider openai \
  --model YOUR_OPENAI_MODEL
```

### READ ONLY safety boundary

```text
READ ONLY
no write
no force
no reset
no bypass
no upload / download
no mode change
no start / stop control
```

The LLM may interpret or explain evidence. It cannot turn model confidence into PLC truth or authorize machine control.

Live documentation:
https://github.com/tomha85/devagent/tree/main/docs/live

## Bring Your Own Model

DevAgent supports OpenAI, Anthropic/Claude, xAI/Grok, Google Gemini, and OpenAI-compatible endpoints behind the same deterministic engineering harness.

Example:

```bash
devagent setup --provider openai --model YOUR_MODEL
export OPENAI_API_KEY=...
devagent doctor --live
```

Provider choice can affect reasoning quality, latency, cost, and privacy characteristics. It does not change DevAgent's deterministic acceptance, verification, safety, reporting, or publication rules.

## Outcome Contract

DevAgent reports bounded engineering outcomes:

- **`VERIFIED`** - required criteria are supported by admissible evidence and final verification/review passes on the current revision;
- **`PARTIALLY_VERIFIED`** - meaningful evidence exists but complete proof is unavailable;
- **`BLOCKED`** - DevAgent cannot safely understand, implement, or verify the request.

A conservative result is preferred over a false `VERIFIED`.

## Project Status

DevAgent is beta software. Qualification claims are tied to explicit test catalogs, pinned revisions, fixtures/external oracles where applicable, and the environments actually exercised. They are not universal-correctness or market-superiority claims.

For the current implementation status, qualification details, limitations, examples, and complete documentation, see the main repository README:
https://github.com/tomha85/devagent#readme

## Support

DevAgent is currently free during public beta.

If DevAgent saves you engineering time, you can support continued development through GitHub Sponsors:
https://github.com/sponsors/tomha85

## License

DevAgent is open source under the MIT License.

Copyright (c) 2026 Tom Ha

Original repository: https://github.com/tomha85/devagent
