Configuration Reference

nomotic.yaml Schema

The nomotic.yaml file defines agents and their governance configuration for a project.

Full Schema

version: "1.0"               # Required. Always "1.0"
extends: "strict"             # Optional. Preset to inherit from

agents:
  <agent-id>:
    owner: "[e-mail]"       # Required. Human owner
    reason: "Purpose of agent"       # Required. Why this agent exists
    archetype: "assistant"           # Optional. Behavioral category
    governance_zone: "production"    # Optional. Environment context

    scope:
      actions: [read, write, query, delete]   # Permitted action types
      targets: [customer_records, logs]        # Permitted targets
      boundaries: [customer_records]           # Hard boundaries (vetoed if crossed)

    trust:
      initial: 0.5               # Starting trust score (0.0–1.0)
      minimum_for_action: 0.3    # Actions blocked below this trust
      floor: 0.1                 # Trust never drops below this
      ceiling: 0.95              # Trust never exceeds this
      decay_rate: 0.001          # Daily decay rate

    dimensions:                  # Override specific dimension settings
      scope_compliance:
        weight: 2.0
        veto: true
      ethical_alignment:
        weight: 1.5

    thresholds:
      allow: 0.75                # Override preset allow threshold
      deny: 0.35                 # Override preset deny threshold

Minimal Valid Config

version: "1.0"
extends: "strict"

agents:
  my-agent:
    owner: "[e-mail]"
    reason: "Customer service agent"
    scope:
      actions: [read, query]
      targets: [customer_records]

Multiple Agents

version: "1.0"
extends: "strict"

agents:
  reader-agent:
    owner: "[e-mail]"
    reason: "Read-only data access"
    scope:
      actions: [read, query]

  writer-agent:
    owner: "[e-mail]"
    reason: "Writes processed results"
    scope:
      actions: [write]

Configuration Resolution Order

When a config file uses extends, values are resolved in this order:

1. Start with standard preset as base

2. Apply each preset in extends list in order (later overrides earlier)

3. Apply explicit YAML values (full override for weights, replacement for vetoes)

Explicit YAML weights merge on top of preset weights (only specified dimensions override). If YAML specifies vetoes, they completely replace preset vetoes rather than merging.

Validation

nomotic validate                           # Validates ./nomotic.yaml
nomotic validate path/to/nomotic.yaml      # Validate a specific file

:::tip Always run nomotic validate in CI before deploying config changes. It catches schema errors, org minimum violations, and missing required fields. :::

Generating a Config

nomotic new                   # Interactive config generator
nomotic new --preset strict   # Start from a preset
nomotic new --full            # Include commented override sections

---

Preset Definitions

Presets are the fastest way to configure Nomotic. Each preset sets all 14 dimension weights, veto authorities, trust parameters, and evaluation thresholds.

Severity Tiers

Standard

General-purpose governance for non-production or lower-risk use cases.

• Allow threshold: 0.65 | Deny threshold: 0.25

• Vetoes: scope_compliance, authority_verification

• Trust initial: 0.5

Strict

Recommended for production. Elevated security with more aggressive veto configuration.

• Allow threshold: 0.75 | Deny threshold: 0.35

• Vetoes: scope_compliance, authority_verification, ethical_alignment, isolation_integrity

• Trust initial: 0.5

Ultra Strict

Maximum governance for regulated or high-risk environments.

• Allow threshold: 0.85 | Deny threshold: 0.45

• Vetoes: All applicable dimensions

• Trust initial: 0.4

Compliance-Aligned Presets

:::warning Compliance presets are governance interpretations aligned with framework principles, not certified compliance solutions. They should be reviewed by your compliance team. :::

SOC2 Aligned

Weights prioritizing the SOC2 trust service criteria: security, availability, processing integrity, confidentiality, and privacy.

Elevated weights on: authority_verification, isolation_integrity, transparency, human_override.

HIPAA Aligned

Weights prioritizing patient privacy, minimum necessary access, and audit requirements.

Elevated weights on: scope_compliance, isolation_integrity, stakeholder_impact, transparency, ethical_alignment.

PCI-DSS Aligned

Weights prioritizing cardholder data protection, access control, and monitoring.

Elevated weights on: scope_compliance, authority_verification, isolation_integrity, incident_detection, temporal_compliance.

ISO 27001 Aligned

Weights prioritizing information security management, risk treatment, and operational controls.

Elevated weights on: scope_compliance, authority_verification, behavioral_consistency, incident_detection, transparency.

Working with Presets

Viewing Preset Details

nomotic status --preset strict    # Details for a specific preset
nomotic status --presets          # List all available presets

Merging Presets

config = RuntimeConfig.merge_presets(["soc2_aligned", "hipaa_aligned"])

:::note Merge takes the strictest value from each setting — the higher weight, the higher threshold, the more vetoes. You cannot merge presets in a way that weakens either one. :::

Using Presets in Code

from nomotic.runtime import GovernanceRuntime, RuntimeConfig

# From a preset
config = RuntimeConfig.from_preset("strict")
runtime = GovernanceRuntime(config=config)

# From a preset with overrides
config = RuntimeConfig.from_preset("hipaa_aligned", allow_threshold=0.80)
runtime = GovernanceRuntime(config=config)

Cost-Sensitive Thresholds

Parameter	Type	Default	Description
enable_cost_sensitive	bool	False	Enable dynamic threshold derivation from CostProfile. When enabled, the ThresholdEngine computes per-evaluation allow/deny thresholds for agents with a cost_profile on their active BehavioralContract. Agents without a cost profile fall back to static allow_threshold / deny_threshold values.

from nomotic.runtime import GovernanceRuntime, RuntimeConfig

runtime = GovernanceRuntime(RuntimeConfig(
    enable_cost_sensitive=True,
    enable_contracts=True,
))

VOI Escalation Configuration

Parameter	Type	Default	Description
enable_voi_escalation	bool	False	Enable VOI-driven escalation in Tier 3. When enabled, the VOIEngine replaces the simple trust-threshold ESCALATE logic with decision-theoretic escalation based on dimension entropy, trust uncertainty, and cost sensitivity. Requires enable_contracts=True for cost profile access.
voi_config	VOIConfig | None	None	Custom VOI configuration. If None, uses VOIConfig defaults (entropy_weight=0.40, trust_weight=0.25, cost_weight=0.35, trust_floor=0.2, min_voi_to_escalate=0.3).

from nomotic.runtime import GovernanceRuntime, RuntimeConfig
from nomotic.voi import VOIConfig

# Enable with defaults
runtime = GovernanceRuntime(RuntimeConfig(
    enable_voi_escalation=True,
    enable_contracts=True,
))

# Enable with custom VOI config
runtime = GovernanceRuntime(RuntimeConfig(
    enable_voi_escalation=True,
    enable_contracts=True,
    voi_config=VOIConfig(
        trust_floor=0.25,
        min_voi_to_escalate=0.4,
        entropy_weight=0.45,
    ),
))

BehaviorLedger Configuration

Parameter	Type	Default	Description
enable_behavior_ledger	bool	False	Enable complete decision reconstruction. Each evaluate() call produces a BehaviorLedgerEntry with full pipeline trace, behavioral state, and causal links.
behavior_ledger_store	BehaviorLedgerStore | None	None	Custom store instance. If None and ledger is enabled, a default in-memory store is created.

from nomotic.runtime import GovernanceRuntime, RuntimeConfig
from nomotic.behavior_ledger import BehaviorLedgerStore

# Enable with defaults
runtime = GovernanceRuntime(RuntimeConfig(enable_behavior_ledger=True))

# Enable with persistent storage
store = BehaviorLedgerStore(base_dir="/var/nomotic/ledger", max_entries=100000)
runtime = GovernanceRuntime(RuntimeConfig(
    enable_behavior_ledger=True,
    behavior_ledger_store=store,
))