Configure planner modes

Noēsis supports two planner modes that control the level of governance and observability in your episodes.

Understanding planner modes

Mode	Description	Use when
`meta` (default)	Full governance with MetaPlanner and PreActGovernor	You need auditability, vetoes, and insight KPIs
`minimal`	Skips governance, uses legacy stepwise planner	Quick sanity checks or smoke tests

Setting the planner mode

Python API

import noesis as ns

# Set globally
ns.set(planner_mode="meta")  # Full governance (default)
ns.set(planner_mode="minimal")  # Skip governance

# Check current mode
config = ns.config()
print(config.planner_mode)

Environment variable

export NOESIS_PLANNER=meta
noesis run "my task"

# Or inline
NOESIS_PLANNER=minimal noesis run "my task"

Configuration file

Create a noesis.toml in your project root:

noesis.toml

[noesis]
planner_mode = "meta"
runs_dir = "./.noesis/episodes"

Precedence

Configuration is resolved in this order (highest to lowest):

ns.set() call in code
NOESIS_PLANNER environment variable
noesis.toml configuration file
Default value (meta)

Meta mode (default)

Meta mode enables full governance:

import noesis as ns

ns.set(planner_mode="meta")

episode_id = ns.run("Provision staging infrastructure")

# Check direction and governance events
events = list(ns.events.read(episode_id))
direction = [e for e in events if e["phase"] == "direction"]
governance = [e for e in events if e["phase"] == "governance"]

print(f"Direction events: {len(direction)}")
print(f"Governance events: {len(governance)}")

What meta mode provides

MetaPlanner: Threads through every episode for structured planning
PreActGovernor: Audits actions before execution, can veto
Direction events: Records directive status (applied, blocked, skipped)
Intuition steering handoff: Carries risk_level, strategy_hints, tool_constraints, and scrutiny_level into Direction
Governance events: Records decisions (allow, audit, veto)
Full insight metrics: Plan adherence, veto count, tool coverage

Direction event example

{
  "phase": "direction",
  "payload": {
    "schema_version": "1.2.0",
    "directive_id": "dir_0f7f...",
    "status": "applied",
    "reason": "heuristic-adjustment",
    "diff": [
      {
        "key": "plan.steps[1].description",
        "before": "Execute goal: Review incidents",
        "after": "Execute read-only analysis for goal: Review incidents"
      }
    ],
    "policy_id": "planner.meta",
    "policy_version": "1.0.0",
    "policy_kind": "rules",
    "intuition_event_id": "evt_2d3b...",
    "risk_level": "high",
    "strategy_hints": ["verify_first", "retrieve_more"],
    "tool_constraints": ["read_only"],
    "scrutiny_level": "strict"
  },
  "evidence_ids": ["event:observe:1"],
  "caused_by": "7e0f..."
}

Governance event example

{
  "phase": "governance",
  "payload": {
    "decision": "audit",
    "rule_id": "rules.audit.sensitive",
    "score": 0.6,
    "policy_id": "governance.rules",
    "policy_version": "1.0.0"
  },
  "caused_by": "5c12..."
}

Minimal mode

Minimal mode skips governance for faster execution:

import noesis as ns

ns.set(planner_mode="minimal")

episode_id = ns.run("Quick sanity check")

# No governance events
events = list(ns.events.read(episode_id))
governance = [e for e in events if e["phase"] == "governance"]
assert len(governance) == 0  # No governance in minimal mode

What minimal mode skips

MetaPlanner and PreActGovernor
Direction and governance events
Policy-based vetoes
Some insight metrics (veto_count, plan_adherence)

What minimal mode keeps

The cognitive loop (observe → interpret → plan → act → reflect → learn)
Event timeline (events.jsonl)
Summary artifacts (summary.json)
Basic metrics (success, act_count)

Inspecting governance metrics

When using meta mode, governance metrics are available in the summary:

import noesis as ns

ns.set(planner_mode="meta")
episode_id = ns.run("Sensitive operation", intuition=True)

summary = ns.summary.read(episode_id)
metrics = summary.get("insight", {}).get("metrics", {})

print(f"Plan revisions: {metrics.get('plan_revisions', 0)}")
print(f"Veto count: {metrics.get('veto_count', 0)}")
print(f"Plan adherence: {metrics.get('plan_adherence', 1.0):.2%}")
print(f"Tool coverage: {metrics.get('tool_coverage', 1.0):.2%}")

Governance decisions

The PreActGovernor can make three decisions:

Decision	Effect	When it happens
`allow`	Action proceeds normally	No policy concerns
`audit`	Action proceeds, marked for review	Medium-risk operations
`veto`	Action blocked	High-risk or policy violations

Handling vetoes

Vetoes are emitted by Governance (not Direction) and only block actions in governance_mode="enforce":

import noesis as ns

ns.set(planner_mode="meta")
ns.set(governance_mode="enforce")

episode_id = ns.run("DROP TABLE users", intuition=True)
events = list(ns.events.read(episode_id))

governance_veto = next(
    (
        e
        for e in events
        if e["phase"] == "governance" and e.get("payload", {}).get("decision") == "veto"
    ),
    None,
)

if governance_veto:
    print("Governance vetoed the action")
    print(governance_veto["payload"]["rule_id"])

If governance_pause_on_veto=true, enforce vetoes pause the run with runtime lifecycle events (run.interrupt, run.checkpoint) instead of immediate termination.

Switching modes dynamically

You can switch modes between episodes:

import noesis as ns

# Run with full governance
ns.set(planner_mode="meta")
governed_ep = ns.run("Critical operation", intuition=True)

# Run quick test without governance
ns.set(planner_mode="minimal")
test_ep = ns.run("Quick test")

# Back to governed mode
ns.set(planner_mode="meta")
another_governed_ep = ns.run("Another critical operation", intuition=True)

CLI usage

Toggle modes from the command line:

# Meta mode (default)
noesis run "Sensitive task"

# Minimal mode via environment
NOESIS_PLANNER=minimal noesis run "Quick test"

When to use each mode

Use meta mode for:

Production workloads
Compliance-sensitive operations
Operations requiring audit trails
Tasks with intuition policies
Any operation that might need to be vetoed

Use minimal mode for:

Development and testing
Quick sanity checks
Benchmarking adapter performance
Operations that don’t need governance overhead

Troubleshooting

No direction events appearing

You’re likely in minimal mode. Check with:

config = ns.config()
print(config.planner_mode)  # Should be "meta"

Set to meta mode: ns.set(planner_mode="meta")

Veto not blocking actions

Ensure Governance is enforcing:

ns.set(planner_mode="meta")
ns.set(governance_mode="enforce")
ns.run("task", intuition=True)

In governance_mode="audit" or off, veto-like risk signals can still appear in direction/intuition artifacts, but they do not block actuation.

Governance metrics are zero

Governance metrics only populate in meta mode with active policies:

ns.set(planner_mode="meta")
ns.run("task", intuition=MyPolicy())  # Need a policy

Get started

Tutorials

How-to guides

Explanation

Configure planner modes

Understanding planner modes

Setting the planner mode

Python API

Environment variable

Configuration file

Precedence

Meta mode (default)

What meta mode provides

Direction event example

Governance event example

Minimal mode

What minimal mode skips

What minimal mode keeps

Inspecting governance metrics

Governance decisions

Handling vetoes

Switching modes dynamically

CLI usage

When to use each mode

Use meta mode for:

Use minimal mode for:

Troubleshooting

Next steps

Write policies

Export metrics

​Understanding planner modes

​Setting the planner mode

​Python API

​Environment variable

​Configuration file

​Precedence

​Meta mode (default)

​What meta mode provides

​Direction event example

​Governance event example

​Minimal mode

​What minimal mode skips

​What minimal mode keeps

​Inspecting governance metrics

​Governance decisions

​Handling vetoes

​Switching modes dynamically

​CLI usage

​When to use each mode

​Use meta mode for:

​Use minimal mode for:

​Troubleshooting

​Next steps

Write policies

Export metrics

Understanding planner modes

Setting the planner mode

Python API

Environment variable

Configuration file

Precedence

Meta mode (default)

What meta mode provides

Direction event example

Governance event example

Minimal mode

What minimal mode skips

What minimal mode keeps

Inspecting governance metrics

Governance decisions

Handling vetoes

Switching modes dynamically

CLI usage

When to use each mode

Use meta mode for:

Use minimal mode for:

Troubleshooting

Next steps