Quickstart

Get up and running with Nomotic in under 5 minutes.

1. Install

pip install nomotic

2. Set Up Your Organization

Run the interactive setup once per machine:

nomotic setup

This creates ~/.nomotic/config.json with your organization ID, owner info, default zone, and compliance preset. It also generates your issuer key pair for signing agent certificates.

3. Create Your First Governed Agent

nomotic init --name my-agent --archetype customer-experience

This scaffolds a governed agent project with a nomotic.yaml governance configuration, a working hello_nomotic.py example script, and a .gitignore for local runtime data.

Run without --archetype to get an interactive selection menu with all 22 built-in archetypes.

4. Run Governance

python hello_nomotic.py

Sample output:

[nomotic] Evaluating: read → customer_records
  Verdict: ALLOW | UCS: 0.847 | Tier: 1

[nomotic] Evaluating: delete → production_database
  Verdict: DENY | UCS: 0.182 | Tier: 1 (veto: scope_compliance)

Every action gets a verdict (ALLOW, DENY, ESCALATE, MODIFY, or SUSPEND) with a Unified Confidence Score (UCS) between 0.0 and 1.0.

5. Open the Governance Dashboard

nomotic serve --ui

Open http://localhost:8420/ui in your browser. The dashboard shows real-time governance decisions, agent trust scores, behavioral drift alerts, and a filterable, chain-verified audit trail.

6. Python API

Three lines of code. Full governance.

from nomotic import Nomotic

agent = Nomotic.connect("my-agent")
result = agent.execute(action="query", target="customer_records")

print(result.verdict)    # ALLOW, DENY, ESCALATE, MODIFY, or SUSPEND
print(result.ucs)        # 0.847
print(result.allowed)    # True

Nomotic.connect() handles everything behind the scenes: it loads your agent's certificate and archetype from the nomotic.yaml created in step 3, creates the governance runtime, and configures the audit trail. Every call to execute() evaluates all 13 governance dimensions, updates trust, and writes to the audit log.

Execute a Tool With Governance

To evaluate governance and execute a tool only when approved:

from nomotic import Nomotic

agent = Nomotic.connect("my-agent")
result = agent.execute(
    action="query",
    target="customer_records",
    tool_fn=lambda: db.execute("SELECT * FROM customers"),
)

if result.allowed:
    print(result.data)    # tool output
else:
    print(result.reason)  # denial explanation

If governance approves, the tool runs and result.data contains its return value. If denied, the tool never executes and result.reason explains why.

Governance-Only Check

To check governance without executing anything:

result = agent.check(action="delete", target="production_database")
print(result.verdict)  # DENY
print(result.reason)   # "Scope violation: target not in authorized boundaries"

Reading the Result

Every ExecutionResult includes:

result.allowed           # bool — did governance approve?
result.verdict           # "ALLOW", "DENY", "ESCALATE", "MODIFY", or "SUSPEND"
result.ucs               # float — Unified Confidence Score (0.0–1.0)
result.tier              # int — which evaluation tier decided (1=veto, 2=weighted, 3=deliberative)
result.trust_before      # float — trust score before this action
result.trust_after       # float — trust score after this action
result.trust_delta       # float — change in trust
result.dimension_scores  # dict — per-dimension scores
result.vetoed_by         # list — dimensions that vetoed (empty if allowed)
result.reason            # str — human-readable explanation
result.data              # any — tool return value (None if denied or no tool_fn)
result.duration_ms       # float — evaluation time in milliseconds

7. Advanced: GovernanceRuntime API

For fine-grained control over the governance pipeline, use the runtime directly:

from nomotic import GovernanceRuntime, Action, AgentContext, TrustProfile

runtime = GovernanceRuntime()

runtime.configure_scope(
    agent_id="my-agent",
    scope={"read", "write", "query"},
    boundaries={"customer/*", "order/*"},
)

action = Action(
    agent_id="my-agent",
    action_type="write",
    target="customer/profile",
    parameters={"field": "email"},
)

context = AgentContext(
    agent_id="my-agent",
    trust_profile=TrustProfile(agent_id="my-agent"),
)

result = runtime.evaluate(action, context)
print(f"Verdict: {result.verdict}")
print(f"UCS: {result.ucs:.3f}")
print(f"Tier: {result.tier}")

The GovernanceRuntime gives you direct access to dimension configuration, trust calibration, behavioral fingerprints, drift monitoring, and the full evaluation pipeline. Most integrations should start with Nomotic.connect() and move to the runtime API only when they need this level of control.

Next Steps

• Integration Guides — LangGraph, CrewAI, OpenAI, and Claude framework integrations

• Architecture — how the 13 dimensions, three-tier evaluation, and trust model work

• Behavioral Control Plane — the drift taxonomy, behavioral contracts, and semantic anchoring

• CLI Reference — all 50+ CLI commands

• API Reference — REST API endpoints