Metadata-Version: 2.4
Name: a2eo
Version: 0.4.3a0
Summary: A2EO: trusted execution and interoperability between agents and enterprise operations
Author: Kafalah
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Kafalah/a2eo
Project-URL: Repository, https://github.com/Kafalah/a2eo
Project-URL: Documentation, https://github.com/Kafalah/a2eo/tree/main/docs
Project-URL: Issues, https://github.com/Kafalah/a2eo/issues
Project-URL: Changelog, https://github.com/Kafalah/a2eo/blob/main/CHANGELOG.md
Keywords: agent,interoperability,logistics,industrial,connector,aip,a2a,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: COPYRIGHT
Requires-Dist: jsonschema>=4.0
Requires-Dist: fastapi<1,>=0.128
Requires-Dist: uvicorn<1,>=0.48
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.13
Dynamic: license-file

# A2EO v0.4.3-alpha

**Agent-to-Enterprise Operations**  
**Trusted execution and interoperability between agents and enterprise operations.**

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Status](https://img.shields.io/badge/status-experimental%20alpha-orange.svg)](ROADMAP.md)
[![Python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](pyproject.toml)

**Start here:** [中文介绍手册](docs/introduction.zh-CN.md) · [English Introduction](docs/introduction.en.md) · [Handbook / 文档导航](HANDBOOK.md) · [5-minute Quickstart](docs/manuals/01-quickstart-zh-en.md)

> **Experimental public alpha.** A2EO is an agent-native trusted execution and interoperability layer for enterprise operations. Its first domain profile is Industrial & Logistics. A2EO is **not** a replacement for AIP, A2A or MCP, and this release does not claim industry-standard status, certification, vendor compatibility, or production readiness.  
> **公开实验性 Alpha。** A2EO 面向智能体与真实企业业务操作之间的可信执行与互操作。Industrial & Logistics 是当前首个 Domain Profile。A2EO **不替代 AIP、A2A 或 MCP**，本版本也不宣称行业标准、官方认证、Vendor 兼容认证或生产就绪。

## 30-second overview / 30 秒理解

Agents can call APIs. The harder enterprise problem is deciding what to do when a **real external side effect becomes ambiguous**.

```text
Agent -> create purchase order -> ERP commits -> response is lost
                                             |
                                             v
                              Did the PO happen or not?
```

Blind retry can create a duplicate purchase order. Treating a timeout as a definitive failure can also be wrong.

A2EO makes that boundary explicit:

```text
Agent intent
   |
   v
Structured enterprise operation
   |
   +--> identity / delegation / authorization / policy
   +--> stable Effect identity
   +--> deterministic execution
   +--> evidence
   +--> reconciliation / compensation / exceptional human resolution
   |
   v
Connector SPI / SDK -> ERP / MES / WMS / TMS / ...
```

Two rules summarize the current safety model:

- **Agent capability != authorization.**
- **`RESERVED` means external outcome unknown, not “nothing happened”.**

## Where A2EO fits / 与 AIP、A2A、MCP 的关系

```text
        MCP          A2A          AIP        future bindings
         |            |            |               |
         +------------+------------+---------------+
                              |
                              v
                            A2EO
        enterprise-operation semantics + trusted execution
             effects + recovery + compensation + evidence
                              |
                              v
                    Connector SPI / SDK
                              |
                  ERP / MES / WMS / TMS
```

A2EO does **not** compete with or replace AIP, A2A or MCP. They are protocol/binding surfaces; A2EO focuses on what must happen before, during and after a real enterprise operation is allowed to change business state.

> **Core defines WHAT. Binding / Connector defines HOW.**

## Why this can matter / 潜在价值在哪里

Enterprise automation is not only an API-connectivity problem. The hard cases are authorization, duplicate prevention, timeout-after-commit, eventual consistency, compensation, human exception handling and audit evidence. A2EO packages those concerns into reusable, testable semantics instead of leaving each Agent integration to improvise them.

The current Industrial & Logistics profile is the first validation domain, not the permanent scope ceiling. The same execution boundary can be evaluated for manufacturing, maintenance, procurement, warehouse, transport and other enterprise operations when real evidence supports those extensions.

## 5-minute quickstart / 5 分钟快速上手

### Run from source / 从源码运行

```bash
git clone https://github.com/Kafalah/a2eo.git
cd a2eo
python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e .
a2eo happy
```

You should receive JSON containing a deterministic scenario result and audit evidence. This demonstrates the installable reference surface; it is **not** proof of real vendor integration.

Try all built-in scenarios:

```bash
a2eo all
a2eo --version
```

After the package is actually published to PyPI:

```bash
python -m pip install --pre a2eo
a2eo happy
```

For expected output, troubleshooting and offline-install notes, use the [full Quickstart](docs/manuals/01-quickstart-zh-en.md).

## The execution model / 执行模型

A real mutation uses a stable Effect identity:

```text
Stable Effect Key
  -> RESERVE
  -> INVOKE connector
  -> CONFIRM
       or
     lookup / reconcile
       or
     fail closed to durable human intervention
```

If the enterprise system commits but the response is lost, A2EO does not infer business truth from the transport error. Recovery follows the **specific operation's Connector Contract**.

Compensation is another external side effect, not a local rollback:

```text
Source Effect COMPLETED
        |
        v
Compensation Effect Key
  -> RESERVE -> INVOKE -> CONFIRM
                    |
                    +-> lookup / reconcile / manual resolution
```

Forward-operation idempotency does not imply compensation idempotency.

## What is in v0.4.3-alpha / 当前包含什么

v0.4.3-alpha is primarily a **publication-closure and documentation-UX release**. It preserves the verified execution semantics from v0.4.2 while making the public project easier to understand, validate and release.

| Surface | Status |
|---|---|
| A2EO Core enterprise-operation semantics | Experimental Alpha |
| Industrial & Logistics Domain Profile | Experimental Alpha |
| JSON Schemas / invariants | Implemented + Tested |
| Basic Python SDK / Connector SPI | Implemented + Tested |
| Stable Effect + reconciliation | Implemented + Tested |
| Compensation-as-an-Effect | Implemented + Tested |
| Durable exceptional human resolution | Implemented + Tested |
| External HTTP crash-window sandbox | Implemented + Tested |
| AIP v02.01 Direct RPC exact subset | Implemented + Tested subset |
| A2A / MCP mappings | Experimental mappings |
| TypeScript / Java / Go SDKs | Planned, not implemented |
| Real vendor ERP/WMS/TMS compatibility | Not Verified |
| Production IAM / HA / immutable audit | Not Verified |
| Full AIP/A2A/MCP certification | Not Verified |

Always distinguish **Implemented / Tested / Experimental / Mapped / Planned / Not Verified / Certified**.

## Verify the release / 验证发布基线

```bash
python -m pip install -r requirements-dev.txt
python scripts/run_core_gate.py                 # 85 Core
python scripts/run_enterprise_interop_gate.py   # 51 Enterprise Interop
bash scripts/run_integration_gate.sh             # 34 Integration
python scripts/check_release_consistency.py
```

Expected v0.4.3-alpha baseline: **170 tests = 85 Core + 51 Enterprise Interop + 34 Integration**.

The gates remain independent. A convenient wrapper exists at `scripts/run_release_gate.sh`, but one green phase never substitutes for the others.

## Repository map / 仓库地图

- `spec/`, `schemas/`, `conformance/` — versioned semantics, machine-readable contracts and invariants.
- `bindings/` — AIP / A2A / MCP mappings and adapters.
- `connectors/` — Connector SPI, per-operation capability contracts and basic Python SDK.
- `reliability/` — Effect ledger, reconciliation, compensation and manual exceptional resolution.
- `hosted/`, `distributed/`, `external_sandbox/` — reference and failure-injection implementations; **not production claims**.
- `tests/`, `scripts/`, `reports/` — independent gates and release evidence.
- `docs/`, `HANDBOOK.md` — onboarding, architecture, PoC and release guidance.

See [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) for the complete publication layout.

## Choose a reading path / 选择阅读路径

**I have 10 minutes** → [English introduction](docs/introduction.en.md) / [中文介绍](docs/introduction.zh-CN.md)  
**I want to run it** → [Quickstart](docs/manuals/01-quickstart-zh-en.md)  
**I want to understand architecture** → [Architecture](docs/architecture.md)  
**I want to implement a Connector** → [Connector Development](docs/manuals/04-connector-development-guide-zh-en.md)  
**I want to understand compensation/manual resolution** → [v0.4.2 safety manual](docs/manuals/12-compensation-manual-resolution-v0.4.2-zh-en.md)  
**I want to verify conformance** → [Conformance Testing](docs/manuals/07-conformance-testing-guide-zh-en.md)  
**I want to run an enterprise PoC** → [Hosting & PoC](docs/manuals/08-hosting-poc-guide-zh-en.md)  
**I want to publish/contribute** → [CONTRIBUTING](CONTRIBUTING.md) · [Public Release Guide](docs/public-release-guide-zh-en.md)

## Claim boundary / 声明边界

This alpha may describe the listed implemented/tested subsets. It must **not** be presented as Production Ready, Stable, Certified, full protocol conformance, real SAP/用友/金蝶 compatibility, Production IAM/HA, immutable production audit, or enterprise security certification without new evidence.

The repository's reference scenarios intentionally stop short of unattended real purchasing/payment/industrial safety control.

## License / 开源许可证

Project-original A2EO content is licensed under the **Apache License 2.0** unless a file explicitly states otherwise.

**Copyright 2026 Kafalah**

See [LICENSE](LICENSE), [NOTICE](NOTICE), [COPYRIGHT](COPYRIGHT), and [docs/licensing-zh-en.md](docs/licensing-zh-en.md). Third-party dependencies, standards, trademarks and vendor APIs retain their own terms.
