Metadata-Version: 2.4
Name: aex
Version: 2.0.0.post1
Summary: AEX v2.0 simple local profile — local-first AI execution governance kernel with deterministic accounting, idempotent admission, and simple local frontend.
Author-email: Auro-rium <auroriumnexus@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Auro-rium/aex
Project-URL: Repository, https://github.com/Auro-rium/aex
Project-URL: Issues, https://github.com/Auro-rium/aex/issues
Keywords: ai,llm,governance,budget,proxy,openai,agents,rate-limiting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.7
Requires-Dist: psutil>=5.9
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: dev
Requires-Dist: langgraph>=0.2; extra == "dev"
Dynamic: license-file

# AEX v2.0 - Auto Execution Kernel (Simple Local Dev Profile)

AEX v2.0 is a local-first governance kernel for agent execution with deterministic accounting.
This profile is intended for local development users.

Core guarantees:
- budget reserve/commit/release lifecycle per `execution_id`
- idempotent request replay behavior
- hash-chained ledger events for tamper evidence
- OpenAI-compatible northbound API with provider abstraction southbound

## v2.0 Runtime Architecture

Control path:
1. Auth (`Bearer` token, scope, TTL)
2. Admission (`execution_id`, rate-limit, policy, route, preflight reserve)
3. Provider dispatch (streaming/non-streaming)
4. Exactly-once settlement (`COMMITTED` or `RELEASED`/`DENIED`/`FAILED`)
5. Hash-chain event append + metrics projection

Execution states:
- `RESERVING -> RESERVED -> DISPATCHED -> COMMITTED`
- failure paths: `RELEASED`, `DENIED`, `FAILED`

## Active Endpoints (Sorted)

Admin:
- `GET /admin/activity`
- `POST /admin/reload_config`
- `GET /admin/replay`
- `GET /dashboard`
- `GET /health`
- `GET /metrics`

Proxy:
- `POST /openai/v1/chat/completions`
- `POST /openai/v1/embeddings`
- `POST /openai/v1/responses`
- `POST /openai/v1/tools/execute`
- `POST /v1/chat/completions`
- `POST /v1/embeddings`
- `POST /v1/responses`
- `POST /v1/tools/execute`

## Data Model (v2.0)

Primary tables:
- `agents` - identity, caps, budget/spend/reserved counters
- `executions` - idempotent execution identity + terminal cache
- `reservations` - reserve/commit/release state
- `event_log` - hash-chained immutable events
- `events` - compatibility/event metrics stream
- `rate_windows` - RPM/TPM windows
- `tool_plugins` - plugin registry

## Startup + Recovery

On daemon startup:
- initialize/migrate DB schema
- run integrity checks
- load model/provider config
- reconcile incomplete executions (release stale reservations, fail broken non-terminal flows)

## Dashboard (Simple Local Frontend)

v2.0 ships with a simple local frontend connected to backend endpoints:
- `GET /health`
- `GET /metrics`
- `GET /admin/replay`
- `GET /admin/activity`

Open:
- `http://127.0.0.1:9000/dashboard`

## Quick Start

```bash
pip install aex

aex init
aex daemon start

aex agent create my-agent 5.00 30 --allow-passthrough

export OPENAI_BASE_URL=http://127.0.0.1:9000/v1
export OPENAI_API_KEY=<AEX_AGENT_TOKEN>
```

## Source Layout

Technical READMEs are provided in each major folder under `src/aex` and `src/aex/daemon`.
