nornyx 1.5.0

A generalized agentic contract/control-plane language for governed AI software delivery.

Nornyx

A generalized agentic contract/control-plane language for governed AI software delivery.

pip install nornyx

Your AI-engineering rules live scattered across AGENTS.md, a skills folder, prompt/context packs, a harness script, an eval config, policy docs, evidence templates, and approval checklists — and they drift out of sync. Nornyx makes them one checked source of truth: write a single .nyx file, then generate and validate all those artifacts from it.

one .nyx contract  ──►  AGENTS.md · skills/ · harness.yaml · policy.yaml
                        evals.yaml · context.yaml · evidence_contract.md

Nornyx does not replace Codex, Claude Code, Cursor, Copilot, CI/CD, or human review. It compiles, checks, and generates the control artifacts those execution surfaces follow.

Install

pip install nornyx          # from PyPI
# or pin from source:
pip install "nornyx @ git+https://github.com/mazinmarji/nornyx@v1.1.1"

Requires Python 3.10+. The only runtime dependency is PyYAML.

Quick start (5 minutes)

# 0. drop the bundled example contracts into ./examples/
nornyx examples

# 1. check a contract
nornyx check examples/governed_delivery_control_plane.nyx

# 2. generate the control artifacts from it
nornyx generate examples/governed_delivery_control_plane.nyx --out generated/cp

# 3. build a provenance-hashed context pack
nornyx context-build examples/governed_delivery_control_plane.nyx --repo . --out generated/context.json

# 4. inspect the schema
nornyx schema --version 1.0

(If you didn't install the console script, use python -m nornyx.cli ....)

nornyx generate writes AGENTS.md, skills/, harness.yaml, policy.yaml, evals.yaml, context.yaml, and evidence_contract.md into the output folder — regenerate any time the .nyx changes, and nornyx check keeps them honest.

Shell/editor completion

nornyx complete emits JSON completion items for .nyx documents. Nornyx does not install a shell hook by default; this command is the completion data source to wire into shell functions, editor adapters, or small helper scripts.

Top-level block suggestions:

nornyx complete --prefix con

Reference-aware suggestions:

nornyx complete examples/governed_delivery_control_plane.nyx --path agent.policy --prefix Safe

The command prints LSP-shaped objects with label, kind, detail, and insertText, so wrappers can parse the labels and present them as candidates.

A contract looks like this

nornyx: "0.1"
project:
  name: GovernedDelivery

contexts:
  - name: RepoContext
    include: ["src/**/*.py", "docs/**/*.md"]
    authority: ["docs/SECURITY.md"]
    taint:                       # trust boundaries are first-class
      repo: trusted_repo_file
      user_prompt: untrusted
      external_web: untrusted

policies:
  - name: SafeEditPolicy
    rules:
      - deny secrets_to_llm
      - require tests_if_code_changed
      - require evidence_if_harness_completed

agents:
  - name: Builder
    role: "Implement small scoped patches."
    skills: [PatchBuilder, TestRepair, EvidencePack]
    policy: SafeEditPolicy

harnesses:
  - name: DevHarness
    context: RepoContext
    flow:
      - agent: Builder
        action: implement
      - tool: tests
        action: run
      - evidence: DevEvidence
        action: pack
    gate:
      - require: tests.pass
      - require: human_approval_before_merge

Use it in your repo

Going from the demo to your own project is four steps:

# 1. scaffold a .nyx for your repo (pick a profile, default ai_coding)
nornyx init --name YourRepo --out nornyx.nyx

# 2. edit nornyx.nyx — your contexts, policies, agents, harness — then check it
nornyx check nornyx.nyx

# 3. generate the artifacts and put AGENTS.md where your agent reads it
nornyx generate nornyx.nyx --out .nornyx/
cp .nornyx/AGENTS.md AGENTS.md          # the file Claude Code / Cursor / Copilot read

# 4. commit nornyx.nyx (the source) and the artifacts you use

Keep them from drifting. Commit the generated directory and add a check that it still matches the contract — in CI or a pre-commit hook:

nornyx drift nornyx.nyx --out .nornyx   # nonzero exit if ANY artifact drifts

nornyx drift compares every generated artifact by hash (not just AGENTS.md), so a change to policy.yaml is caught too. Across many repos, declare your org policy once in a workspace manifest and verify each repo matches it:

nornyx workspace-check --manifest nornyx.workspace.yaml

Now the .nyx is the single source of truth: edit it, regenerate, and the check fails loudly if any artifact drifts. Full walkthrough: docs/USE_IN_YOUR_REPO.md.

Reference a shared policy instead of copying it

A policy can reference a canonical definition rather than copy its rules, so there is nothing to drift in the first place:

policies:
  - name: SafeDeliveryPolicy
    ref: ../governance/nornyx.workspace.yaml#SafeDeliveryPolicy   # single source

ref is <path>#<PolicyName>, resolved from a local .nyx contract or a workspace manifest. The canonical rules live in one place; edit them there and every referencing contract is updated. nornyx check and nornyx generate resolve the reference and inline the real rules into policy.yaml. See the bundled org_policies.nyx and governed_service.nyx examples.

Govern packages as untrusted input

Governed package commands treat folders, repos, plugins, agent kits, and MCP bundles as inert inputs. The scanner inventories files, hashes contents, detects risk surfaces, redacts secret-like values, and emits evidence reports:

nornyx package scan ./some-package --out dist/package-scan
nornyx package radar ./some-package --out dist/radar_report.json
nornyx package register ./some-package --contract examples/governed_package/register_existing.nyx --out dist/registered-package

External evidence can be imported from existing reports without making those tools mandatory:

nornyx package evidence import syft syft-report.json --out dist/external-evidence
nornyx package evidence import gitleaks gitleaks-report.json --out dist/external-evidence

Nornyx does not install, execute, start MCP servers, activate hooks, upload data, approve, or claim a package is safe. It can say that a package was inventoried, risk-surfaced, evidence-bound, hash-locked, and approval-gated.

Why Nornyx

• One source of truth for agent/skill/harness/policy/eval/evidence artifacts — no more drift.
• Context trust model: mark which context is trusted vs untrusted so untrusted input can't define policy, and deny secrets_to_llm at the contract level.
• Generators + a checker: turn .nyx into the files your tools read, and verify references and required fields.
• Generated-artifact drift gate: catch when regenerated output diverges from a committed baseline.
• YAML-compatible syntax — no new parser to learn for v0.1.

Scope and safety

Nornyx v0.1 is an executable specification layer, not a runtime. It does not implement autonomous system modification, production deployment, destructive tool use, credential handling, or arbitrary command execution. The name Nornyx is a provisional working brand (no formal legal clearance claimed).

Learn more

• Positioning
• 5-minute adoption
• Governed Package Profile
• Public boundary policy
• Nornyx Graph demo · expanded
• Schema targets and examples
• Roadmap toward a stable generalized contract language: see docs/03_ROADMAP_TO_v1_AND_BEYOND.md.

Development

git clone https://github.com/mazinmarji/nornyx && cd nornyx
pip install -e ".[dev]"
python -m pytest -q

License

MIT — see LICENSE. Copyright (c) 2026 Mazin Marji and Nornyx Contributors.