Skip to main content
Install from source while the PyPI name is pending: 
git clone https://github.com/saraeloop/noesis.git
cd noesis
uv tool install .
# or: pipx install .
When the PyPI release is live, you can use uv add noesis or pip install noesis. Import as import noesis as ns.

​
Core functions

​
ns.run()

Execute a baseline episode using the current session. 
episode_id = ns.run(
    task: str,
    *,
    seed: int = 0,
    intuition: bool | Intuition | None = True,
    tags: dict[str, object] | None = None,
    context: Any | None = None,
) -> str
​
task
string
required
Task or goal for the episode.
​
seed
int
default:"0"
Seed for reproducibility.
​
intuition
bool | Intuition | None
default:"True"
True enables the default intuition policy, False disables it, or pass an Intuition implementation.
​
tags
dict
Metadata tags attached to the episode.
​
context
RuntimeContext
default:"None"
Optional runtime context. If provided, execution bypasses the default session.
Returns: Episode ID (e.g., "ep_2024_abc123_s0") Example: 
import noesis as ns

episode_id = ns.run("Draft release notes")
episode_id = ns.run("Draft release notes", intuition=False, tags={"env": "staging"})
Context example: 
ctx = {"tenant": "acme", "user_id": "u_123"}

episode_id = ns.run("Summarize this incident", context=ctx)
summary = ns.summary.read(episode_id, context=ctx)
The structure of context is integration-specific; it is passed through to the runtime and ports.

​
ns.solve()

Execute an episode through a specific adapter/graph. 
episode_id = ns.solve(
    task: str,
    *,
    using: GraphSource,  # import path, callable, or adapter
    seed: int = 0,
    intuition: bool | Intuition | None = True,
    tags: dict[str, object] | None = None,
    context: Any | None = None,
) -> str
​
using
GraphSource
required
Adapter name/import path or callable to execute the task.
Example: 
import noesis as ns

# Callable adapter
def to_upper(task: str) -> dict:
    return {"result": task.upper()}

episode_id = ns.solve("process this", using=to_upper)
episode_id = ns.solve("process this", using="my.module:adapter_fn")

​
ns.summary.read()

Load the summary for an episode. 
summary = ns.summary.read(episode_id: str, *, context: Any | None = None) -> dict
Returns: Summary dictionary (task, metrics, flags, manifest, etc.).

​
ns.events.read()

Load the event timeline for an episode. 
events = ns.events.read(
    episode_id: str,
    *,
    stream: bool = False,
    context: Any | None = None,
) -> Iterable[dict]
Set stream=True to iterate lazily.

​
ns.list_runs()

List recent episodes (newest first). 
episodes = ns.list_runs(
    limit: int = 50,
    since: str | None = None,
    *,
    context: Any | None = None,
    strict_manifest: bool = False,
) -> list[dict]
Each row includes episode_id, task, started_at, flags, success, manifest, and manifest_status (when strict_manifest=True).

​
ns.last()

Get the most recent episode ID. 
episode_id = ns.last(*, context: Any | None = None) -> str | None

​
ns.set() / ns.get()

Update or read the current configuration snapshot. 
ns.set(runs_dir="./runs/demo", planner_mode="minimal", direction_min_confidence=0.7)
config = ns.get()  # returns a mapping of current config values
Common keys: runs_dir, planner_mode (meta/minimal), direction_min_confidence, learn_home, learn_mode, learn_auto_apply_min_confidence, learn_auto_apply_min_successes, intuition_mode, timeout_sec, prompt_provenance_enabled, prompt_provenance_mode, agents, tasks.

​
Intuition and policies

​
ns.DirectedIntuition

Base class for policies that can emit hints, interventions, or vetoes. 
import noesis as ns
from noesis.domain.faculties.intuition import IntuitionEvent

class SafetyPolicy(ns.DirectedIntuition):
    __version__ = "1.0"

    def advise(self, state: dict) -> IntuitionEvent | None:
        task = str(state.get("task", "")).lower()
        if "delete" in task:
            return self.veto(
                advice="Blocked: delete operation",
                rationale="Delete requires manual approval",
                target="plan",
            )
        return None
Helper methods:
  • hint(advice, confidence=0.5, rationale=None, evidence_ids=None, target="input", scope="episode")
  • intervene(advice, patch, confidence=0.6, rationale=None, evidence_ids=None, target="input", scope="episode")
  • veto(advice, confidence=0.8, rationale=None, evidence_ids=None, target="plan", scope="episode")

​
IntuitionEvent (schema)

Fields include kind, advice, confidence, policy_id, policy_version, policy_kind, applied, rationale, evidence_ids, patch, target, scope, and blocking (plus schema_version).

​
NoesisVeto

Raised when a policy vetoes an episode. 
from noesis import NoesisVeto

try:
    ns.run("DELETE * FROM users", intuition=True)
except NoesisVeto as e:
    print(f"Vetoed: {e}")

​
Session management

Use sessions when you need isolated configuration, explicit lifecycle control, or registered ports. 
from noesis import SessionBuilder

session = SessionBuilder.from_env().build()
with session:
    ep = session.run("Process customer request")
    summary = session.summary.read(ep)
SessionBuilder reads config from env/TOML; you can also inject ports before building. Within a session, run/solve behave like the module-level helpers but share the session’s config and runtime context.

​
Module facades

  • ns.summary.read(episode_id, context=None): read summary.json.
  • ns.events.read(episode_id, stream=False, context=None): iterate events; pass stream=True to lazily consume.
  • ns.context: helpers for building runtime contexts and attaching ports (advanced use — see the “Add a memory port” guide).
  • ns.learn.emit(...): advanced learning signal emission (see noesis.learn; patterns live in guides such as export metrics/learning signals).

​
Episode index

​
EpisodeIndex

Manage an on-disk episode manifest (and optional FAISS similarity index). 
from noesis.episode import EpisodeIndex

store = EpisodeIndex(
    root="./runs/_episodes",
    ttl_days=14,
    enable_faiss=False,  # set True if faiss + numpy installed and you provide embeddings
)
Core methods:
  • append(episode_id, summary_path, state_path, status, task, using, provenance=None, embedding=None)
  • iter(include_expired=False) → iterator of EpisodeRecord
  • search(embedding, k=5) → similarity matches (empty if FAISS disabled)
  • vacuum() → prune expired records

​
Type definitions

​
IntuitionEvent

Returned by policy methods. See schema above for fields.

​
Environment variables

VariableDescription
NOESIS_RUNS_DIRArtifact storage directory
NOESIS_PLANNERPlanner mode (meta/minimal)
NOESIS_DIRECTION_MIN_CONFIDENCEDirection minimum confidence
NOESIS_INTUITION_MODEIntuition mode
NOESIS_TIMEOUT_SECDefault timeout (seconds)
NOESIS_LEARN_HOMELearning artifacts directory
NOESIS_LEARN_MODELearning mode
NOESIS_LEARN_AUTO_APPLY_MIN_SUCCESSESMinimum successes before auto-apply
NOESIS_LEARN_AUTO_APPLY_MIN_CONFIDENCEConfidence threshold for auto-apply
NOESIS_PROMPT_PROVENANCE_ENABLEDEnable prompt provenance (true/false)
NOESIS_PROMPT_PROVENANCE_MODEPrompt provenance mode
NOESIS_AGENTSAgent registry override
NOESIS_TASKSTasks registry override

​
Next steps

CLI reference

Command-line interface documentation.

Write policies

Create intuition policies.