Documentation Index Fetch the complete documentation index at: https://docs.noesis.systems/llms.txt
Use this file to discover all available pages before exploring further.
Noēsis can be configured through multiple sources. This page documents all available options and how to set them.
Configuration precedence Configuration is resolved in this order (highest to lowest priority):
ns.set() callsEnvironment variables (e.g., NOESIS_PLANNER)noesis.tomlDefault values
Configuration options runs_dir Directory where episode artifacts are stored (episodes root).
Source Setting Python ns.set(runs_dir="./my-runs")Environment NOESIS_RUNS_DIR=./my-runsTOML runs_dir = "./my-runs"Default ".noesis/episodes"
planner_mode Controls planning strategy and direction behavior.
Source Setting Python ns.set(planner_mode="meta")Environment NOESIS_PLANNER=metaTOML planner_mode = "meta"Default "meta"
Values :Value Description metaMetaPlanner-enabled planning (direction search / directives) minimalMinimal planning; skips direction search and runs a simple planner
planner_mode controls planning strategy. Governance is controlled separately via governance_mode and governance_failure_policy.
agents Reserved/unused in v1.0.0. Parsed into the runtime config but not read by the CLI/runtime execution paths in this release.
Source Setting Python ns.set(agents="agents.yaml")Environment NOESIS_AGENTS=agents.yamlTOML agents = "agents.yaml"Default "agents.yaml"
tasks Reserved/unused in v1.0.0. Parsed into the runtime config but not read by the CLI/runtime execution paths in this release.
Source Setting Python ns.set(tasks="tasks.yaml")Environment NOESIS_TASKS=tasks.yamlTOML tasks = "tasks.yaml"Default "tasks.yaml"
timeout_sec Episode timeout in seconds.
Source Setting Python ns.set(timeout_sec=120)Environment NOESIS_TIMEOUT_SEC=120TOML timeout_sec = 120Default 60
learn_mode Controls how learning proposals are handled.
Source Setting Python ns.set(learn_mode="record")Environment NOESIS_LEARN_MODE=recordTOML learn_mode = "record"Default "record"
Values :Value Description offDisable learning recordRecord proposals only applyAuto-apply approved proposals
learn_auto_apply_min_confidence Minimum confidence for auto-applying learn proposals.
Source Setting Python ns.set(learn_auto_apply_min_confidence=0.9)Environment NOESIS_LEARN_AUTO_APPLY_MIN_CONFIDENCE=0.9TOML learn_auto_apply_min_confidence = 0.9Default 0.75
learn_auto_apply_min_successes Minimum successful triggers before auto-applying.
Source Setting Python ns.set(learn_auto_apply_min_successes=5)Environment NOESIS_LEARN_AUTO_APPLY_MIN_SUCCESSES=5TOML learn_auto_apply_min_successes = 5Default 3
intuition_mode Controls intuition advisory posture.
Source Setting Python ns.set(intuition_mode="advisory")Environment NOESIS_INTUITION_MODE=advisoryTOML intuition_mode = "advisory"Default "advisory"
Values :Value Description advisoryIntuition provides hints only interventiveIntuition can modify plans hybridCombination based on confidence
direction_min_confidence Minimum confidence threshold for applying plan directives.
Source Setting Python ns.set(direction_min_confidence=0.8)Environment NOESIS_DIRECTION_MIN_CONFIDENCE=0.8TOML direction_min_confidence = 0.8Default 0.5
governance_mode Controls pre-act governance behavior.
Source Setting Python ns.set(governance_mode="enforce")Environment NOESIS_GOVERNANCE_MODE=enforceTOML governance_mode = "enforce"Default "off"
Values :Value Description offGovernance disabled auditRecord decisions; never blocks execution enforceVeto blocks Act; runtime terminates by default or pauses/checkpoints when governance_pause_on_veto=true
governance_failure_policy How to handle governance errors/timeouts.
Source Setting Python ns.set(governance_failure_policy="fail_closed")Environment NOESIS_GOVERNANCE_FAILURE_POLICY=fail_closedTOML governance_failure_policy = "fail_closed"Default Depends on mode (audit→fail_open, enforce→fail_closed)
Values :Value Description fail_openOn error, allow action to proceed fail_closedOn error, treat as veto
governance_timeout_ms Reserved/unused in v1.0.0. Parsed into the runtime config but not enforced during episode execution in this release.
Source Setting Python ns.set(governance_timeout_ms=250)Environment NOESIS_GOVERNANCE_TIMEOUT_MS=250TOML governance_timeout_ms = 250Default None
governance_pause_on_veto Enable pause semantics for enforce-mode vetoes. When enabled, Noēsis emits:
run.interruptrun.checkpoint
and halts side effects instead of finalizing/sealing the run.
Source Setting Python ns.set(governance_pause_on_veto=True)Environment NOESIS_GOVERNANCE_PAUSE_ON_VETO=trueTOML governance_pause_on_veto = trueDefault false
policy_aliases Mapping of policy alias → import spec. Used by the CLI --policy flag to resolve short names.
Source Setting Python ns.set(policy_aliases={"safe": "my.module:SafetyPolicy"})TOML policy_aliases = { safe = "my.module:SafetyPolicy" }Default {}
learn_home Directory for learning data storage.
Source Setting Python ns.set(learn_home="./learn")Environment NOESIS_LEARN_HOME=./learnTOML learn_home = "./learn"Default ~/.noesis/state
prompt_provenance_enabled Enable prompt provenance logging.
Source Setting Python ns.set(prompt_provenance_enabled=True)Environment NOESIS_PROMPT_PROVENANCE_ENABLED=trueTOML prompt_provenance_enabled = trueDefault false
prompt_provenance_mode Mode for prompt provenance storage.
Source Setting Python ns.set(prompt_provenance_mode="hash_only")Environment NOESIS_PROMPT_PROVENANCE_MODE=hash_onlyTOML prompt_provenance_mode = "hash_only"Default "hash_only"
Values :Value Description fullStore full prompt content hash_onlyStore only content hashes (default) redactedStore redacted content
prompt_provenance_mode="full" may record prompt content. Use hash_only or redacted for sensitive environments.
Configuration file Noēsis searches for a config file by walking upward from the current working directory. Supported filenames are noesis.toml and .noesis.toml.
The recommended form is a [noesis] table (if the table is missing, Noēsis falls back to treating the full TOML file as the config mapping):
[ noesis ] runs_dir = "./.noesis/episodes" agents = "agents.yaml" tasks = "tasks.yaml" planner_mode = "meta" learn_mode = "record" learn_home = "./learn" intuition_mode = "advisory" direction_min_confidence = 0.7 governance_mode = "off" governance_failure_policy = "fail_open" governance_pause_on_veto = false learn_auto_apply_min_confidence = 0.85 learn_auto_apply_min_successes = 3 prompt_provenance_enabled = false prompt_provenance_mode = "hash_only"
Environment variables The following runtime configuration options have environment variable equivalents:
Option Environment variable runs_dirNOESIS_RUNS_DIRplanner_modeNOESIS_PLANNERagentsNOESIS_AGENTStasksNOESIS_TASKStimeout_secNOESIS_TIMEOUT_SEClearn_modeNOESIS_LEARN_MODElearn_homeNOESIS_LEARN_HOMEintuition_modeNOESIS_INTUITION_MODEdirection_min_confidenceNOESIS_DIRECTION_MIN_CONFIDENCEgovernance_modeNOESIS_GOVERNANCE_MODEgovernance_failure_policyNOESIS_GOVERNANCE_FAILURE_POLICYgovernance_timeout_msNOESIS_GOVERNANCE_TIMEOUT_MSgovernance_pause_on_vetoNOESIS_GOVERNANCE_PAUSE_ON_VETOlearn_auto_apply_min_confidenceNOESIS_LEARN_AUTO_APPLY_MIN_CONFIDENCElearn_auto_apply_min_successesNOESIS_LEARN_AUTO_APPLY_MIN_SUCCESSESprompt_provenance_enabledNOESIS_PROMPT_PROVENANCE_ENABLEDprompt_provenance_modeNOESIS_PROMPT_PROVENANCE_MODE
policy_aliases has no environment variable form in v1.0.0 (configure it via ns.set() or noesis.toml).NOESIS_DIR_MIN_CONFIDENCE is a deprecated alias for NOESIS_DIRECTION_MIN_CONFIDENCE (if set, Noēsis warns and uses it).
Example :# Set via environment export NOESIS_PLANNER = meta export NOESIS_RUNS_DIR = ./ artifacts export NOESIS_DIRECTION_MIN_CONFIDENCE = 0.8 export NOESIS_AGENTS = agents . yaml export NOESIS_TASKS = tasks . yaml # Or inline NOESIS_PLANNER = minimal NOESIS_RUNS_DIR = ./artifacts noesis run "quick test"
Python API Setting configuration import noesis as ns # Set individual options ns.set( runs_dir = "./artifacts" ) ns.set( planner_mode = "meta" ) ns.set( direction_min_confidence = 0.8 ) # Set multiple at once ns.set( runs_dir = "./artifacts" , planner_mode = "meta" , learn_mode = "record" , prompt_provenance_enabled = False , )
Reading configuration import noesis as ns config = ns.get() # returns a mapping print ( f "Runs dir: { config[ 'runs_dir' ] } " ) print ( f "Planner mode: { config[ 'planner_mode' ] } " ) print ( f "Direction min confidence: { config[ 'direction_min_confidence' ] } " )
Resetting configuration import noesis as ns # Set back to defaults explicitly ns.set( runs_dir = "./.noesis/episodes" , planner_mode = "meta" , direction_min_confidence = 0.5 , governance_mode = "off" , governance_pause_on_veto = False , learn_mode = "record" , learn_auto_apply_min_confidence = 0.75 , learn_auto_apply_min_successes = 3 , prompt_provenance_enabled = False , prompt_provenance_mode = "hash_only" , )
Per-episode parameters Some parameters can be set per episode at call time:
import noesis as ns # Global config ns.set( planner_mode = "meta" ) # Per-episode parameters episode_id = ns.run( "quick test" , seed = 42 , # reproducibility seed tags = { "env" : "staging" }, # metadata tags intuition = True , # enable/disable intuition )
Global configuration (via ns.set()) applies to all episodes. Per-call parameters like seed, tags, and intuition are set at run time.
CLI configuration Most CLI configuration is done via environment variables:
NOESIS_RUNS_DIR = ./artifacts noesis run "task" NOESIS_PLANNER = minimal noesis run "task" NOESIS_DIRECTION_MIN_CONFIDENCE = 0.8 noesis run "task"
Configuration validation Noēsis validates configuration on startup:
import noesis as ns # Invalid planner mode raises ValueError try : ns.set( planner_mode = "invalid" ) except ValueError as e: print ( f "Invalid config: { e } " )
Best practices Use environment variables for deployment. Set NOESIS_RUNS_DIR, NOESIS_PLANNER, and related knobs per environment.
Don’t commit secrets. If using noesis.toml, ensure it doesn’t contain sensitive values and is in .gitignore if needed.
Use per-call seeds for debugging. Pass seed= to ns.run/ns.solve when you need reproducibility; unset it for production.
Example configurations Development [ noesis ] runs_dir = "./.noesis/episodes" planner_mode = "minimal" direction_min_confidence = 0.5 governance_mode = "off" governance_pause_on_veto = false prompt_provenance_enabled = false
Staging [ noesis ] runs_dir = "./.noesis/episodes" planner_mode = "meta" learn_mode = "record" direction_min_confidence = 0.5 governance_mode = "audit" governance_pause_on_veto = false prompt_provenance_enabled = false
Production [ noesis ] runs_dir = "/var/noesis/episodes" planner_mode = "meta" learn_mode = "record" governance_mode = "enforce" governance_failure_policy = "fail_closed" governance_pause_on_veto = true learn_auto_apply_min_confidence = 0.95 learn_auto_apply_min_successes = 5 prompt_provenance_enabled = true prompt_provenance_mode = "hash_only"
Next steps
Quickstart Get started with Noēsis.
Planner modes Configure governance levels.
