Metadata-Version: 2.5
Name: cortex-runtime
Version: 0.7.0rc1
Summary: Spatiotemporal authority and semantic verification framework for autonomous workflows
Project-URL: Homepage, https://github.com/Iradukunda-Fils/Cortex
Project-URL: Documentation, https://github.com/Iradukunda-Fils/Cortex#readme
Project-URL: Repository, https://github.com/Iradukunda-Fils/Cortex.git
Project-URL: Issues, https://github.com/Iradukunda-Fils/Cortex/issues
Author: Iradukunda Fils
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,architecture,capability-security,sandbox,spatiotemporal,verification,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Requires-Dist: jsonschema<5.0.0,>=4.0.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: pyyaml<7.0.0,>=6.0.0
Requires-Dist: typing-extensions>=4.5.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pyright>=1.1.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Description-Content-Type: text/markdown

<p align="left">
  <img src="docs/assets/images/cortex-logo.png" alt="Cortex Logo" width="95" align="left" style="margin-right: 18px; margin-bottom: 10px;" />
  <h1 style="border: none; margin: 0; padding: 0;">Cortex Framework</h1>
  <h3 style="border: none; margin: 4px 0 10px 0; font-weight: 600; font-size: 1.15em;">Spatiotemporal Authority, Capability-Security & Semantic Verification Framework</h3>
  <a href="https://pypi.org/project/cortex-runtime/"><img src="https://img.shields.io/pypi/v/cortex-runtime.svg" alt="PyPI Version"></a> <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python Version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a> <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/managed--with-uv-purple.svg" alt="Managed with uv"></a> <a href="docs/architecture/cortex_release_readiness_final.md"><img src="https://img.shields.io/badge/Release-v0.7.0rc1-brightgreen.svg" alt="Release Candidate Status"></a>
</p>
<br clear="left"/>

> **Cortex** is an open-source, capability-secured spatiotemporal authority and formal verification framework for autonomous workflows, AI agents, and microservices. It enforces fail-closed physical containment, cryptographic witness journaling, content-addressed evidence tracking, and machine-checked invariant safety across polyglot execution runtimes.

---

## 🏛️ Architecture & Security Principles

Cortex enforces a zero-trust, capability-attenuated execution kernel governed by two core rules:

$$ \boxed{\textbf{Authority Decides}} \quad \text{and} \quad \boxed{\textbf{Adapter Executes}} $$

```
                                  CANONICAL EXECUTION FLOW
                                  
[ CortexClient ]
       │
       ▼ (1. Reserve Capacity Vector: RAM, CPU, PIDs)
[ ResourceAuthority ] ─── Validates host capacity & issues reservation_id
       │
       ▼ (2. Restrict Capabilities & Issue HMAC Token)
[ GatewayAuthorizationGate ] ─── Computes HMAC execution_token & context
       │
       ▼ (3. Launch Contained Subprocess Worker)
[ WorkerSupervisor ] ─── Setsid, unshares netns/PID, attaches cgroup v2
       │
       ▼ (4. Subprocess Execution)
[ Worker Process ] ─── Formulates EffectRequest (NO secrets embedded)
       │
       ▼ (5. Secure Execution Pipeline)
[ EffectExecutionPipeline ]
   ├── A. Replay Lookup (EffectResultStore)
   ├── B. Gateway Credential Resolution (CredentialBroker vault)
   ├── C. Adapter Invocation (ResourceContract)
   ├── D. Authoritative CAS Spooling (if evidence > 4KiB)
   └── E. Reconcile State (EffectReconciliationEngine)
       │
       ▼ (6. Physical Side-Effect Actuation)
[ External System / Resource ]
```

---

## 📚 Documentation Portal

For detailed architectural specifications, security audits, and release protocols:

| Document | Description |
| :--- | :--- |
| 📋 [**Documentation Truth Audit**](docs/architecture/cortex_documentation_truth_audit.md) | Authoritative claim tracing matrix across documentation tiers. |
| 🔬 [**Architecture Consistency Report**](docs/architecture/cortex_architecture_consistency_report.md) | Architectural DSRP model, execution path, and low-level security audit fixes. |
| 🔌 [**API & Plugin Contract Status**](docs/architecture/cortex_api_and_plugin_contract_status.md) | Boundaries between Native Plugins (`BasePlugin`), Subprocess Workers, and Adapters. |
| 🛡️ [**Deployment Truth Matrix**](docs/architecture/cortex_deployment_truth_matrix.md) | OS kernel dependencies (Landlock LSM, cgroups v2, NetNS) and environment rules. |
| 🏁 [**Release Readiness Final Report**](docs/architecture/cortex_release_readiness_final.md) | Immutable commit binding, defect resolution register, and final release sign-off. |
| ⚙️ [**Release Process & Governance**](docs/release/cortex_release_process_and_governance.md) | Step-by-step release protocol, PyPI OIDC publishing, and release gates. |
| 🔒 [**CI/CD Security & Scalability Audit**](docs/architecture/cortex_cicd_security_and_scalability_audit.md) | Audit of GitHub Actions workflows, OIDC authentication, and security governance. |

---

## ⚡ Developer Quickstart & Installation

### 📦 1. Installing `cortex-runtime`

#### Stable Releases (PyPI)
```bash
# Using uv (Recommended)
uv add cortex-runtime

# Using pip
pip install cortex-runtime
```

#### Pre-Release Candidates (e.g. `v0.7.0rc1`)
```bash
# Using uv (allow latest pre-release candidate)
uv add --prerelease=allow cortex-runtime

# Using uv (install exact pre-release version)
uv add cortex-runtime==0.7.0rc1

# Using pip (allow latest pre-release candidate)
pip install --pre cortex-runtime

# Using pip (install exact pre-release version)
pip install cortex-runtime==0.7.0rc1
```

### 🛠️ 2. Local Repository Development Setup

#### Option A: Setup via `uv` (Recommended)
```bash
git clone https://github.com/Iradukunda-Fils/Cortex.git
cd Cortex
uv venv && source .venv/bin/activate
uv sync --all-extras
```

#### Option B: Setup via Standard `pip`
```bash
git clone https://github.com/Iradukunda-Fils/Cortex.git
cd Cortex
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

### 🚀 3. Deploying Pre-Releases to PyPI

To build and deploy a pre-release candidate (such as `v0.7.0rc1`) to PyPI:
```bash
# 1. Build distribution artifacts locally using uv
uv build

# 2. Assign release candidate tag & push to GitHub (triggers keyless PyPI OIDC publish)
git tag -a v0.7.0rc1 -m "Release Candidate v0.7.0rc1"
git push origin v0.7.0rc1
```

### 🧪 4. Run Verification & Test Suite
```bash
# Run canonical 7-gate verification pipeline
./scripts/verify.sh

# Run Rust emulator test suite
cargo test --manifest-path cortex-emulator/Cargo.toml

# Run Go CBE codec conformance suite
cd cortex-go && go test -v ./...
```

---

## 💻 Developer Code Example: Governed Effect Execution

```python
from cortex.client import CortexClient
from cortex.tools.kernel.effect_gateway import CapabilitySet, SignedIntent

# 1. Initialize Cortex Client with strict capability bounds
client = CortexClient(
    granted_capabilities=CapabilitySet({"STORAGE_READ", "HTTP_REQUEST"}),
    host_memory_ceiling_mb=1024,
)

# 2. Formulate signed intent payload
intent = SignedIntent(
    resource_id="adapter.mcp.stdio.v1",
    operation_type="read_record",
    arguments={"record_id": "rec_9901"},
)

# 3. Execute governed effect through secure pipeline
outcome = client.execute_effect(intent)

print(f"Status: {outcome.status}")  # ExecutionStatus.EFFECT_CONFIRMED
if outcome.evidence:
    print(f"Evidence (Ref: {outcome.evidence.is_reference}): {outcome.evidence.data.decode('utf-8')}")
```

---

## 📄 Licensing

Licensed under the **Apache License, Version 2.0**. See [LICENSE](LICENSE) for details.
