GovernedAgentBase

GovernedAgentBase is the foundation class for building governed agents. It wraps GovernanceRuntime with a simpler interface and provides the govern-execute-validate lifecycle.

Installation

pip install nomotic

Data Classes

GovResult

Returned by govern_action():

@dataclass
class GovResult:
    verdict: str      # "ALLOW", "DENY", "ESCALATE", "BLOCK"
    ucs_score: float  # 0.0–1.0 Unified Compliance Score
    record_id: str    # Audit trail record ID
    allowed: bool     # True only for "ALLOW"

OutputResult

Returned by validate_output():

@dataclass
class OutputResult:
    verdict: str       # Output validation verdict
    output: str        # Original or redacted output
    redacted: bool     # True if output was modified

GovernanceVetoError

Raised by governed_run() when the verdict is DENY or BLOCK:

class GovernanceVetoError(Exception):
    verdict: str
    ucs_score: float
    record_id: str
    action_to_pass: str | None  # Suggested alternative action

Constructor

from nomotic import GovernanceRuntime
from nomotic.governed_agent import GovernedAgentBase

agent = GovernedAgentBase(
    runtime=runtime,              # GovernanceRuntime instance
    certificate=certificate,      # AgentCertificate from nomotic birth
    output_governor=None,         # Optional OutputGovernor for validate_output()
    default_zone=None,            # Optional default governance zone
)

Methods

govern_action()

Pre-action governance evaluation. Does not raise on DENY — check result.allowed.

result = agent.govern_action(
    action_type="write",          # Action type string
    target="customer/profile",    # Target resource
    parameters={"field": "email"},# Optional parameters
    reversible=True,              # Whether the action can be rolled back
    context_overrides=None,       # Optional context overrides
)

if result.allowed:
    # Proceed with action
    pass
else:
    print(f"Denied: UCS={result.ucs_score:.3f}")

validate_output()

Post-generation output validation via the OutputGovernor (if configured):

validation = agent.validate_output(
    output="Here is the customer's data...",
    action_type="read",  # Optional, for context
)

if validation.redacted:
    print("Output was modified for compliance")
print(validation.output)

governed_run()

Full governance lifecycle: govern, execute, validate. Raises GovernanceVetoError on DENY or BLOCK.

from nomotic.governed_agent import GovernanceVetoError

try:
    output = agent.governed_run(
        action_type="read",
        target="customer/profile",
        execute_fn=lambda: fetch_customer_data(),
        reversible=True,
    )
    print(output)
except GovernanceVetoError as e:
    print(f"Vetoed: {e.verdict} (UCS: {e.ucs_score:.3f})")
    if e.action_to_pass:
        print(f"Try instead: {e.action_to_pass}")

Complete Example

from nomotic import GovernanceRuntime
from nomotic.governed_agent import GovernedAgentBase, GovernanceVetoError
from nomotic.authority import CertificateAuthority
from nomotic.keys import SigningKey
from nomotic.store import MemoryCertificateStore

# Set up runtime and certificate
runtime = GovernanceRuntime()
runtime.configure_scope(
    agent_id="support-bot",
    scope={"read", "write", "send"},
    boundaries={"customer/*", "ticket/*"},
)

store = MemoryCertificateStore()
sk, _vk = SigningKey.generate()
ca = CertificateAuthority("local-issuer", sk, store)
cert, _agent_sk = ca.issue(
    agent_id="support-bot",
    archetype="customer-experience",
    organization="acme-corp",
)

# Create governed agent
agent = GovernedAgentBase(runtime=runtime, certificate=cert)

# Evaluate actions
try:
    result = agent.governed_run(
        action_type="read",
        target="customer/order-history",
        execute_fn=lambda: "Order #1234: Widget x2",
    )
    print(f"Result: {result}")
except GovernanceVetoError as e:
    print(f"Blocked: {e.verdict}")