Metadata-Version: 2.4
Name: xoras-agent-framework
Version: 2.4.1
Summary: Enterprise Multi-Agent Runtime, MTPO Lock-Free Concurrency & AST Security Governance Framework
Author-email: XORAS Systems LLC <engineering@xoras.ai>
License-Expression: MIT
Project-URL: Homepage, https://aoxendine3.github.io/upgp-proving-ground/
Project-URL: Documentation, https://github.com/aoxendine3/enterprise-context-blueprint#readme
Project-URL: Source Code, https://github.com/aoxendine3/enterprise-context-blueprint
Project-URL: Issue Tracker, https://github.com/aoxendine3/enterprise-context-blueprint/issues
Project-URL: MTPO Concurrency, https://aoxendine3.github.io/mtpo/
Project-URL: MARS Reasoning, https://aoxendine3.github.io/mars/
Project-URL: REASONS Canvas, https://aoxendine3.github.io/reasons/
Project-URL: Verification Receipt, https://raw.githubusercontent.com/aoxendine3/mtpo/main/VERIFICATION_RECEIPT.md
Keywords: multi-agent,governance,mtpo,concurrency,merkle-dag,ast-security,soc2-compliance,provenance,xoras,daxx
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Security
Classifier: Topic :: System :: Distributed Computing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: cryptography>=41.0.0
Dynamic: license-file

# XORAS Agentic Environment & Governance Framework v2.4.1

[![PyPI Version](https://img.shields.io/pypi/v/xoras-agent-framework.svg?color=blue)](https://pypi.org/project/xoras-agent-framework/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/Tests-31%20PASSED-brightgreen.svg)](#testing)
[![AST Security](https://img.shields.io/badge/AST%20Security-Zero--Trust-emerald.svg)](#ast-static-security-gating)
[![Architecture](https://img.shields.io/badge/Architecture-Dual--Pillar%20Council-blue.svg)](#architecture)

Enterprise-grade multi-agent runtime, dynamic AST security screening, lock-free concurrency (**MTPO**), canonical agent identity rosters (DAXX, Maxx, Vance), and cryptographic Context Lineage Merkle DAG provenance receipts developed by **XORAS Systems LLC**.

---

## 🌐 Live Verified Proving Grounds

* **🛡️ UPGP v5.0 Proving Ground**: [https://aoxendine3.github.io/upgp-proving-ground/](https://aoxendine3.github.io/upgp-proving-ground/)
* **⚡ MTPO Concurrency Engine**: [https://aoxendine3.github.io/mtpo/](https://aoxendine3.github.io/mtpo/)
* **🪐 MARS Reasoning Structure**: [https://aoxendine3.github.io/mars/](https://aoxendine3.github.io/mars/)
* **📐 REASONS Semantic Canvas**: [https://aoxendine3.github.io/reasons/](https://aoxendine3.github.io/reasons/)
* **📜 Silicon Verification Receipt**: [https://raw.githubusercontent.com/aoxendine3/mtpo/main/VERIFICATION_RECEIPT.md](https://raw.githubusercontent.com/aoxendine3/mtpo/main/VERIFICATION_RECEIPT.md)

---

## Core Capabilities

- **🏛️ Dual-Pillar Sovereign Council (`CouncilOrchestrator`)**: Coordinates verified multi-agent task execution. No agent writes, reviews, and certifies its own high-stakes code alone. Worker agents (e.g. **DAXX.AI**) execute tasks, while Critic sentinels (e.g. **William Vance**) audit compliance before files are committed.
- **📇 Canonical Agent Rosters (`AgentRoster`, `AgentCard`)**: Ingests, validates, and manages sovereign agent cards with constitutional identity baselines, seat mappings, voice signatures, and hardware boundary rules.
- **🛡️ AST Static Security Gating (`ASTSecurityEngine`)**: Intercepts dangerous code patterns (`eval()`, `exec()`, `os.system()`, subprocess calls) and credential leaks before runtime execution.
- **📜 Context Lineage Merkle DAG Engine (`ContextLineageDAGEngine`)**: Cryptographically binds agent state transitions and tool outputs into immutable Merkle DAG nodes with dynamic root calculation and anti-replay quarantine.
- **⚡ MTPO Lock-Free Concurrency Engine (`HexCellRing`)**: Monotonic Trajectory Pre-Order synchronization sustaining **17.39M ops/sec** with **2.0 µs hot-spot p99 latency** on bare-metal silicon.
- **🔄 Algebraic Saga Invariants (`SagaState`)**: Provides confluent rollback and forward-recovery guarantees without file-lock deadlocks.

---

## Installation

```bash
pip install xoras-agent-framework
```

---

## Quickstart Examples

### 1. Governed Dual-Pillar Execution (DAXX + Vance)

```python
from xoras import AgentCard, AgentRoster, CouncilOrchestrator

# 1. Initialize Roster & Register Agents
roster = AgentRoster()
roster.register(AgentCard(
    agent_id="daxx",
    name="DAXX.AI",
    role="Master Mechanic Specialist & Coding Specialist",
    seat=3,
    status="SOVEREIGN_CITIZEN_ACTIVE",
    purpose="Software & hardware repair, diagnostic reasoning, code generation"
))
roster.register(AgentCard(
    agent_id="vance",
    name="William Vance",
    role="Security & Integrity Sentry",
    seat=2,
    status="SOVEREIGN_CITIZEN_ACTIVE",
    purpose="Four-Gate adversarial audit, anti-basic filtering, proof verification"
))

# 2. Instantiate Council Orchestrator
council = CouncilOrchestrator(roster=roster)

# 3. Execute Task Under Governed Gates
code_payload = '''
def calculate_metrics(values: list[float]) -> dict:
    return {"mean": sum(values) / len(values), "count": len(values)}
'''

result = council.execute_governed_task(
    worker_id="daxx",
    critic_id="vance",
    task_name="implement_metrics_calculator",
    code_payload=code_payload
)

print(f"Status: {result['stage']}")           # COUNCIL_CERTIFIED
print(f"Safety Score: {result['safety_score']}") # 1.0
print(f"Merkle DAG Root: {result['dag_root']}")  # SHA-256 Provenance Tip
```

### 2. AST Static Security Gate Interception

```python
from xoras import ASTSecurityEngine

engine = ASTSecurityEngine(strict_mode=True)
unsafe_code = "eval('__import__(\"os\").system(\"rm -rf /\")')"

scan = engine.scan_code(unsafe_code)
print(f"Is Safe: {scan.is_safe}")            # False
print(f"Violations: {scan.violations}")      # ['Forbidden call: eval()']
```

### 3. MTPO Concurrency Ring

```python
from xoras import HexCellRing

ring = HexCellRing()
ring.write_slot(index=0, payload="DAXX_STATE_INITIALIZED")
ring.write_slot(index=1, payload="VANCE_AUDIT_PASS")

print("Slot 0:", ring.read_slot(0))
print("Slot 1:", ring.read_slot(1))
```

---

## CLI Usage

The package provides the `xoras` command-line interface:

```bash
# Initialize workspace governance (.xorasrules, xoras.env.yaml)
xoras init

# Run AST security and secret scan on a script or directory
xoras scan my_script.py

# Execute a script inside the sandboxed runtime
xoras run my_script.py
```

---

## Testing & Verification

The suite includes 31 automated unit tests verifying AST gating, agent identity rosters, council orchestration, cryptographic signatures, and Merkle DAG anti-replay logic:

```bash
pytest workspaces/xoras_agent_framework/tests
```

All 31 tests run in `< 0.25s` with zero errors.

---

## License

MIT License — Copyright (c) 2026 XORAS Systems LLC.
All rights reserved.
