Getting Started with NexusAegis

NexusAegis installs on Python 3.11+ with zero external core dependencies and exposes CLI commands, the Python kernel API, Stdio MCP tools, and the Streamable HTTP/SSE Portal.

Install & run the live PCAE demo

v1.1.0

Run locally

git clone https://github.com/codesphere-u/nexus-aegis.git
cd nexus-aegis && pip install -e .
nexus-aegis demo && nexus-aegis benchmark

CLI Subcommands

Command	Function
`nexus-aegis demo`	Run compliant PR vs reward-hacked PR demo with selective-disclosure proof check.
`nexus-aegis attest FILE [--markdown] [--disclose-gate G]`	Evaluate an `AgentRunBundle` and output signed certificate, PR card, or redacted proof.
`nexus-aegis verify-proof FILE [--root HASH]`	Verify an offline Merkle inclusion proof against a Merkle root.
`nexus-aegis gates [--json]`	List all 7 PCAE gates and upstream Codesphere stack components.
`nexus-aegis benchmark [--json]`	Run the 35-scenario recall, FPR, proof verify, and latency suite.
`nexus-aegis mcp` / `serve-http`	Start Stdio JSON-RPC 2.0 MCP server or HTTP/SSE portal.

Python Kernel API

Instantiate NexusAegisKernel with an AgentRunBundle to evaluate all 7 gates, mint a Merkle root, and extract selective-disclosure proofs.

Attest & Render PR Cards

from nexus_aegis import AgentRunBundle, NexusAegisKernel, render_pr_attestation_markdown

kernel = NexusAegisKernel()
cert = kernel.attest(bundle)
disclosure = kernel.extract_selective_disclosure_proof(cert, "G5_ANTI_REWARD_HACK")
assert kernel.verify_selective_disclosure(disclosure) is True
print(render_pr_attestation_markdown(cert))

Selective Disclosure Guarantees

External CI checks call verify_merkle_inclusion_proof(proof, expected_root_hash=root) using only the leaf hash and 4 sibling hashes, keeping private prompts redacted.

MCP Server Integration

Run nexus-aegis mcp to expose 4 read-only JSON-RPC 2.0 tools, curated specification resources, and 3 diagnostic prompts.

Tools & Resources

aegis_attest_agent_run — Run G1-G7 gates on an AgentRunBundle and return certificate + PR card.
aegis_verify_merkle_proof — Verify an RFC 6962 inclusion proof or selective-disclosure payload.
aegis_list_gates — Retrieve metadata and invariants across G1 through G7.
aegis_run_benchmark — Run the 35-scenario evaluation suite in JSON format.
Resources: aegis://gates/catalog, aegis://merkle/rfc6962-spec, aegis://benchmark/summary, aegis://gates/{gate_id}.

MCP Prompts

Registered prompts: audit-agent-pr, verify-selective-disclosure, and remediate-gate-violation.

HTTP Portal & CI Quality Gate

Serve interactive PCAE attestations, Streamable HTTP/SSE MCP, and Prometheus metrics on Python 3.11+ with optional FastAPI ASGI wrapping (api.index:app).

REST Endpoints

GET / — Interactive browser PCAE Portal or JSON manifest.
GET / HEAD /health, /healthz, /readyz, /info, GET /metrics.
POST /mcp & GET /mcp — Streamable HTTP JSON-RPC 2.0 & SSE.
GET /api/gates, GET|POST /api/demo, POST /api/attest, POST /api/verify-proof, GET|POST /api/benchmark.

Quality Gate

ruff check .
mypy nexus_aegis api scripts tests/test_website_and_docs.py
pytest -v --cov=nexus_aegis --cov-fail-under=90
python3 scripts/smoke_test.py