Metadata-Version: 2.4
Name: xoras-agent-framework
Version: 2.0.0
Summary: Enterprise Multi-Agent Runtime & AST Security Governance Framework
Author-email: XORAS Systems LLC <engineering@xoras.ai>
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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.0

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://xoras.ai)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Security](https://img.shields.io/badge/AST%20Security-PASSED-success.svg)](#ast-static-security-gating)
[![Build](https://img.shields.io/badge/tests-9%20passed-brightgreen.svg)](#testing)

**XORAS Agentic Environment & Governance Framework** is an enterprise-grade multi-agent runtime, dynamic AST security scanner, and cryptographic provenance platform developed by **XORAS Systems LLC**.

---

## Key Features

- **AST Static Security Gating (`env-integrity-sentry`)**: Real-time Abstract Syntax Tree parsing and secret scanning that intercepts dangerous code injections (`eval`, `exec`, `subprocess shell=True`) and credential leaks prior to execution.
- **Cryptographic Trace Receipts (`xoras.evidence.v1`)**: Every agent state transition and tool invocation generates an Ed25519 / HMAC SHA-256 signed JSON-L trace receipt for 100% zero-falsification audit trails.
- **Swarm Agent Orchestrator**: Multi-agent state graph pipeline coordinating **Architect**, **Engineer**, and **Auditor** roles with consensus gating and fallback remediation.
- **Zero-Drift Specification (`.xorasrules` & `xoras.env.yaml`)**: Standardized environment rules, role permissions, memory hierarchies, and workspace boundary controls.
- **Interactive Web Dashboard & Product Landing Page**: Embedded web UI serving live trace logs, AST playgrounds, and product metrics (`xoras serve`).

---

## Architecture Overview

```mermaid
flowchart TD
    UserRequest["User / Trigger Payload"] --> SwarmOrchestrator["Swarm Orchestrator (Architect)"]
    SwarmOrchestrator --> ASTEngine["AST Security Engine (Auditor)"]
    
    ASTEngine -- "Pass (Safety Score = 1.0)" --> RuntimeHarness["XORAS Runtime Harness (Engineer)"]
    ASTEngine -- "Fail (Restricted Token)" --> RejectReceipt["Log Rejection & Signed Receipt"]
    
    RuntimeHarness --> ToolExec["Subprocess / File I/O Sandbox"]
    ToolExec --> EvidenceSigner["Cryptographic Signer (HMAC / Ed25519)"]
    EvidenceSigner --> JSONLTrace["xoras_agent_traces.jsonl"]
```

---

## Quickstart & Installation

### 1. Install Package
```bash
pip install xoras-agent-framework
```

### 2. Initialize Governance Environment
```bash
xoras init
```
This generates `.xorasrules` and `xoras.env.yaml` in your workspace root.

### 3. Scan Scripts for AST Violations
```bash
xoras scan my_script.py
```

### 4. Run Scripts in Isolated Sandbox
```bash
xoras run my_script.py
```

### 5. Serve Interactive Web Dashboard
```bash
xoras serve --port 8080
```
Open `http://localhost:8080` to view the live product landing page and interactive AST playground.

---

## Python API Usage

```python
from xoras import XORASAgentEnvironment, SwarmOrchestrator

# Initialize environment
env = XORASAgentEnvironment(config_path="xoras.env.yaml")

# Run multi-agent orchestrator pipeline
orchestrator = SwarmOrchestrator(env=env)
result = orchestrator.run_pipeline(
    task_description="Deploy verified configuration file",
    code_payload='{"status": "active", "version": "2.0.0"}',
    target_path="artifacts/deploy_config.json"
)

print("Pipeline Success:", result["success"])
print("Trace Signature:", result["last_signature"])
```

---

## Testing

Run the automated test suite:
```bash
PYTHONPATH=. pytest tests/
```

---

## Documentation

- [AST Security Gating Specification](docs/architecture/AST_SECURITY_GATING.md)
- [Cryptographic Provenance Receipts](docs/architecture/CRYPTOGRAPHIC_PROVENANCE.md)
- [API Reference](docs/API_REFERENCE.md)

---

## License

Distributed under the MIT Enterprise License. See `LICENSE` for details.  
&copy; 2026 XORAS Systems LLC. All rights reserved.
