Metadata-Version: 2.4
Name: acla-agentic-context-runtime
Version: 4.0.0rc1
Summary: ACLA Agentic Context Runtime: persistent project context, a deterministic Context Compiler and governed Mission Working Sets for AI agents, with lifecycle, observation, REST, UI and MCP surfaces.
Author: Prasad Deshpande
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE-CODE-MIT.txt
Requires-Dist: python-docx<2,>=1.1
Requires-Dist: watchdog<7,>=4
Provides-Extra: rich-sources
Requires-Dist: PyYAML<7,>=6; extra == "rich-sources"
Requires-Dist: python-docx<2,>=1.1; extra == "rich-sources"
Requires-Dist: pypdf<6,>=5; extra == "rich-sources"
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == "mcp"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: reportlab<5,>=4; extra == "test"
Dynamic: license-file

# ACLA Agentic Context Runtime v4

ACLA answers one question for an AI agent: **what should the model know for this mission?**

```text
Persistent Context -> Context Compiler -> Mission Working Set (minimum relevant, current, authoritative) -> Model
```

*An AI agent should remember far more than it processes.*

## Quick start

```text
pip install "acla-agentic-context-runtime[mcp]"
acla init
acla project add MYPROJECT --workspace /path/to/workspace
acla provider add local --type ollama --model qwen3:8b      # optional; SHADOW mode needs no provider
acla start
acla status
acla mission run "What is the current blocker?" --project MYPROJECT
acla stop
```

Everything runtime-specific lives under `ACLA_HOME` (default `~/.acla`); nothing
machine-specific is embedded in the source. See `docs/GETTING-STARTED.md`,
`SECURITY.md`, `RELEASE.md` and `CHANGELOG.md`.

| Surface | Default |
|---|---|
| UI | `http://127.0.0.1:8789/` |
| REST | `http://127.0.0.1:8790/api/v1` (`/status`, `/missions/run`, `/missions/<id>`, `/missions/<id>/replay`) |
| Activity Bus | `http://127.0.0.1:8795/v1/readiness` |
| MCP | `acla mcp serve` (stdio; tools `acla.inspect`, `acla.compile`, `acla.explain`, `acla.validate`, `acla.metrics`, `acla.replay`, `acla.capabilities`, `acla.providers`, `acla.run`) |

---

## Runtime engine background (V3 foundation)

A governed runtime extension of the ACLA Context Compiler research artifact.

V3 preserves the deterministic Context Compiler kernel and V2 runtime contracts, while adding provider health/circuit breakers, measured latency/cost routing, bounded adaptive routing, adapter conformance, heterogeneous read-only source intake, queue/workers, MCR capability binding, EAF authorization/outcome assurance, governed autonomous tool execution and a read-only operations console.

## Core authority model

- **ACLA Context Compiler** decides what information enters model-active context.
- **Inference Routing** selects among already policy-eligible provider/model routes.
- **Adaptive Routing** may adjust bounded preference weights; it cannot rewrite governance gates.
- **MCR Binding** binds requested semantic capabilities to eligible tool/provider routes.
- **EAF Authorization** authorizes actions. Mutating tools require an explicit single-use mission/action grant.
- **Outcome Assurance** requires authoritative action evidence when configured.
- **UI** is read-only and never creates execution authority.

## Engines

See `docs/ENGINE-MATRIX.md` and `docs/architecture.md`.

## Run a local preview

```text
python -m acla_context_compiler.cli run examples/v3-runtime-mission.json
```

## Queue/worker reference

```text
python -m acla_context_compiler.cli queue-enqueue runtime.db examples/v3-runtime-mission.json --job-id DEMO-1
python -m acla_context_compiler.cli worker-once runtime.db --worker-id worker-1
```

The SQLite backend is a reproducible reference queue, not a production distributed broker certification.

## Read-only operations UI

```text
python -m acla_context_compiler.cli ui --host 127.0.0.1 --port 8789
```

## Rich source formats

Core/stdlib formats: `.md`, `.txt`, `.json`, `.csv`, `.html`, `.htm`, `.xml`.

Optional-extra formats: `.yaml`, `.yml`, `.docx`, `.pdf`.

Install the optional readers with the package extra `rich-sources` in an environment allowed to resolve dependencies.

## Safety / qualification boundary

- No live commercial provider calls are included in acceptance.
- No SAP reads or writes are performed.
- No enterprise write adapter is shipped.
- No model output can create write authority.
- No unsigned PowerShell/CMD/BAT/shell operational launch scripts are shipped.
- Trusted digital signing remains a public promotion gate because the author's signing key/certificate is not present in this build environment.

## Paper relationship

V3 is an additive runtime artifact. It does not retroactively alter historical paper measurements, and local/synthetic qualification is not a claim of universal cost or latency improvement.
