nomotic 0.3.2
Runtime governance framework for agentic AI — laws for agents, enforced continuously
Requires Python: >=3.11
Keywords: agentic, ai, authorization, ethics, governance, nomotic, runtime, security, trust

# Nomotic

**Runtime AI governance — Laws for Agents.**

[![PyPI version](https://img.shields.io/pypi/v/nomotic.svg)](https://pypi.org/project/nomotic/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Tests](https://github.com/nomoticai/nomotic/actions/workflows/ci.yml/badge.svg)](https://github.com/nomoticai/nomotic/actions/workflows/ci.yml)

Nomotic is runtime AI governance for the agentic web. It prevents unauthorized decisions, unauthorized actions, and unauthorized costs by evaluating every agent action across 13 governance dimensions simultaneously, enforcing authority boundaries with hard vetoes, and maintaining mechanical authority to interrupt actions mid-execution. Most governance operates before deployment or after incidents. Nomotic operates during execution. If you cannot stop it, you do not control it.

## The Problem

AI agents can take real actions: executing transactions, modifying records, calling external APIs. Most governance happens before deployment (access controls, permissions) or after incidents (audits, postmortems). Nothing governs what happens during execution — the moment an agent decides to act. Nomotic fills that gap with runtime behavioral governance that evaluates, authorizes, and can interrupt agent actions as they happen.

## Why Runtime

Static rules can't govern systems that learn and adapt. Nomotic uses **Dynamic Trust Calibration** that expands and contracts agent authority based on evidence.

Pattern matching recognizes form but misses intent. Nomotic uses **13-Dimensional Simultaneous Evaluation** across security, ethics, compliance, behavior, and authority.

Post-incident review doesn't undo irreversible actions. Nomotic uses **Interrupt Authority** to halt execution mid-action, with rollback and state recovery.

Human-in-the-loop fails when the human stops paying attention. Nomotic uses **Bidirectional Drift Detection** that monitors when agents drift *and* when humans disengage.

## Quick Start

```bash
pip install nomotic
```

### CLI Workflow

```bash
# 1. One-time setup: configure your org and compliance requirements
nomotic setup

# 2. Generate a governance config for your agent project
nomotic new

# 3. Validate before deploying
nomotic validate
```

`nomotic new` generates a `nomotic.yaml` in your project directory. Here's what a minimal config looks like:

```yaml
version: "1.0"
extends: "strict"

agents:
  my-agent:
    scope:
      actions: [read, write, query]
      targets: [customer_records]
      boundaries: [customer_records]
    trust:
      initial: 0.5
      minimum_for_action: 0.3
    owner: "team@company.com"
    reason: "Customer service agent"
```

This config inherits from the `strict` preset, which sets all 13 dimension weights, veto authorities, thresholds, and trust parameters. You only define what's unique to your agent.

### Python API

```python
from nomotic import GovernanceRuntime, RuntimeConfig, Action, AgentContext, TrustProfile

# Create runtime from a preset — all 13 dimensions configured automatically
config = RuntimeConfig.from_preset("strict")
runtime = GovernanceRuntime(config)

# Define what the agent is allowed to do
runtime.configure_scope(
    agent_id="my-agent",
    scope={"read", "write", "query"},
    actor="admin@company.com",
    reason="Customer service agent",
)

# Every action goes through governance
action = Action(agent_id="my-agent", action_type="write", target="customer_records")
context = AgentContext(agent_id="my-agent", trust_profile=TrustProfile(agent_id="my-agent"))
verdict = runtime.evaluate(action, context)

print(verdict.verdict)  # ALLOW, DENY, MODIFY, ESCALATE, or SUSPEND
print(f"UCS: {verdict.ucs:.3f}")  # Unified confidence score (0.0-1.0)
```

## What Nomotic Enforces

Nomotic governs AI agents at every level. Unauthorized actions are vetoed, not logged for review. Cost overruns are blocked, not discovered on the invoice. Agents that drift from expected behavior lose trust and autonomy automatically.

Every action is evaluated across 13 governance dimensions simultaneously:

| # | Dimension | What It Checks |
|---|-----------|---------------|
| 1 | Scope Compliance | Is this action within the agent's authorized scope? |
| 2 | Authority Verification | Does the agent have delegated authority for this? |
| 3 | Resource Boundaries | Does the action stay within resource limits? |
| 4 | Behavioral Consistency | Does this match the agent's established patterns? |
| 5 | Cascading Impact | Could this trigger downstream consequences? |
| 6 | Stakeholder Impact | Who is affected and how severely? |
| 7 | Incident Detection | Are there anomalous patterns suggesting problems? |
| 8 | Isolation Integrity | Does the action respect data and system isolation? |
| 9 | Temporal Compliance | Is the timing appropriate (rate limits, schedules)? |
| 10 | Precedent Alignment | Is this consistent with prior governance decisions? |
| 11 | Transparency | Can the action and its reasoning be explained? |
| 12 | Human Override | Is human intervention required or available? |
| 13 | Ethical Alignment | Is the action justifiable beyond procedural compliance? |

Each dimension scores independently from 0.0 to 1.0, weighted by configuration. Dimensions with **veto authority** enforce hard boundaries: if a veto dimension scores 0.0, the action is denied regardless of the overall score. No gray area, no debate, no exceptions.

Evaluation runs through a three-tier pipeline. Tier 1 checks deterministic boundaries in microseconds. Full 13-dimension evaluation completes in under 1ms at p99. Governance adds less than a millisecond to any agent decision.

## Key Capabilities

**Agent Birth Certificate** — Every agent starts with a cryptographically signed identity: human owner, governance zone, behavioral archetype, and lifecycle management. Authority is issued, never assumed. No anonymous agents.

**Interrupt Authority** — Governance can halt actions mid-execution, not just approve or deny them upfront. Execution handles provide real-time interrupt checks with rollback support at four granularities: single action, agent, workflow, or global. Governance participates throughout the action lifecycle.

**Dynamic Trust** — Trust scores evolve based on agent behavior. Successful actions build trust incrementally; violations reduce it sharply (5:1 asymmetry). Trust influences governance strictness — new agents face more scrutiny, proven agents earn more autonomy. Trust scores have configurable floors, ceilings, and decay rates.

**Behavioral Fingerprinting and Drift Detection** — Builds behavioral profiles from agent action patterns using Jensen-Shannon divergence. Detects when agent behavior drifts from established baselines. Includes bidirectional drift detection that monitors both agent drift and human oversight degradation (rubber-stamping, reviewer fatigue, approval rate spikes).

**Hash-Chained Audit Trail** — Every governance decision is recorded with cryptographic hash chains. Tamper-evident by design. Tamper with one record and the whole chain breaks. Full provenance tracking traces decisions back to responsible humans. Compliance evidence bundles map governance records to specific framework controls.

**Compliance Presets** — Pre-built governance profiles aligned to SOC2, HIPAA, PCI-DSS, and ISO 27001, plus severity tiers (standard, strict, ultra_strict). Each preset configures all 13 dimension weights, veto authorities, thresholds, and trust parameters. Merge multiple presets for combined compliance requirements with `merge_presets()`, which takes the strictest value from each.

**Organization Governance** — Org-level minimums that no agent can go below. Set minimum dimension weights, required vetoes, threshold floors, and trust constraints centrally. Individual agent configs can be stricter but cannot weaken org-mandated protections.

**Workflow Governance** — Governs multi-step workflows, not just individual actions. Detects compounding authority across steps, cross-step behavioral drift, and cascading risk in action sequences. Projects risk forward to remaining workflow steps.

**Framework Integrations** — Governed tool executors wrap any tool with governance evaluation. Works with LangGraph, CrewAI, and AutoGen. The `GovernedToolExecutor` and `AsyncGovernedToolExecutor` provide drop-in governance for existing tool pipelines.

## CLI Reference

```
Getting Started:
  nomotic setup                          Configure org, compliance, and owner
  nomotic new                            Generate nomotic.yaml for a project

Validation & Status:
  nomotic validate [path]                Validate a governance config
  nomotic status                         Show global settings and presets
  nomotic status --presets               List all available presets
  nomotic status --preset <name>         Show preset details

Agent Management:
  nomotic birth --name <name>            Create a governed agent with certificate
  nomotic inspect <agent-id>             View agent governance configuration
  nomotic inspect <agent-id> --brief     Quick operational summary
  nomotic inspect <agent-id> --raw       Raw certificate JSON

Testing:
  nomotic test <id> --action <action>    Simulate a governance decision
  nomotic simulate <id> --scenario 
   Run batch governance simulations
  nomotic test <id> --adversarial        Run adversarial red team scenarios

Audit & Trust:
  nomotic audit <agent-id>               View audit trail
  nomotic trust <agent-id>               View trust history
  nomotic oversight --team               Human oversight health metrics

Configuration:
  nomotic config set --retention <p>     Set audit retention period
```

## Configuration

Nomotic uses a three-level configuration hierarchy:

```
~/.nomotic/config.json          ← Org defaults (from nomotic setup)
~/.nomotic/org-governance.yaml  ← Org-level minimums (enforced)
./nomotic.yaml                  ← Per-project agent governance
```

Agent configs inherit from presets via `extends` and must comply with org-level minimums. Explicit YAML values override inherited preset values — weights merge (only specified dimensions override), vetoes replace entirely.

## Available Presets

| Preset | Category | Description |
|--------|----------|-------------|
| `standard` | Severity | Reasonable defaults for general use |
| `strict` | Severity | Elevated security, recommended for production |
| `ultra_strict` | Severity | Maximum governance for regulated environments |
| `soc2_aligned` | Compliance | Aligned to SOC2 security controls |
| `hipaa_aligned` | Compliance | Aligned to HIPAA privacy and safety concerns |
| `pci_dss_aligned` | Compliance | Aligned to PCI-DSS payment card requirements |
| `iso27001_aligned` | Compliance | Aligned to ISO 27001 information security |

Compliance-aligned presets are Nomotic's interpretation of governance weights aligned to the concerns of the referenced frameworks. They are not certified, endorsed, or approved by any standards body and do not constitute compliance with any regulatory framework.

## Examples

```
examples/configs/simple-agent.yaml        # Basic agent with strict preset
examples/configs/healthcare-agent.yaml    # HIPAA-aligned multi-agent setup
examples/configs/fintech-agent.yaml       # SOC2 + PCI-DSS dual compliance
examples/configs/nomotic-org-example.yaml # Organization governance template
```

See the [Jupyter notebooks](notebooks/) for interactive walkthroughs of governance evaluation, tool execution, drift detection, and adversarial testing.

## Architecture

Nomotic uses a four-layer architecture: a UCS fast gate for clear pass/fail decisions, a dimensional evaluator that scores all 13 dimensions with weighted aggregation, a deliberation layer for ambiguous cases, and an interrupt authority that monitors execution after approval. The runtime is stateful — it tracks trust scores, behavioral fingerprints, and audit history per agent — and deterministic: the same inputs produce the same governance decisions. See [docs/architecture.md](docs/architecture.md) for the full design.

## Development

```bash
git clone https://github.com/nomoticai/nomotic.git
cd nomotic
pip install -e ".[dev]"
pytest tests/ -v
```

2300+ tests across 70+ test files. Zero external runtime dependencies. Python 3.11+.

## Contributing

We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, code style, project structure, and areas where help is needed.

## License

[Apache 2.0](LICENSE)

## Links

- [Documentation](https://github.com/nomoticai/nomotic/tree/main/docs)
- [Changelog](CHANGELOG.md)
- [PyPI](https://pypi.org/project/nomotic/)
- [Position Paper](https://chrishood.com/nomotic-ai-the-governance-counterpart-to-agentic-ai/) — *Nomotic AI: The Governance Counterpart to Agentic AI*