pi-gnosis

pi-gnosis routes learning requests into saved Circuitry graph programs. Each graph receives two runtime inputs:

• a graph-specific request resource
• gnosis_config, loaded from package config and user config

The graph returns a tutoring, research, note, video, page, lab, or cleanup result for Pi to report.

Runtime contract

{
  "filename": "<package>/graphs/manim-lecture.circuitry.yaml",
  "inputs": {
    "lecture_request": {
      "topic": "linear algebra",
      "scope": "quick intuition",
      "apply_writes": true,
      "render_requested": true
    },
    "gnosis_config": {
      "runtime": { "provider": "pi", "model": "inherit" },
      "paths": {}
    }
  }
}

gnosis_config is part of every pi-gnosis graph run. It supplies artifact roots, note roots, runtime policy, and cleanup boundaries. Artifact-capable graphs reject or report a blocked state when the configured root needed for a write is unavailable.

Runtime inputs are overlays for one execution. Graph YAML is not edited for learner-specific requests.

Graph programs

| Graph | Request resource | Output | | --- | --- | --- | | graphs/tutoring-session.circuitry.yaml | session_request | intake, probe, teaching move, or downstream graph route | | graphs/research.circuitry.yaml | research_request | source-grounded synthesis and optional note-export input | | graphs/note-export.circuitry.yaml | export_request | planned or written Obsidian note update | | graphs/manim-lecture.circuitry.yaml | lecture_request | Manim project, render/preflight status, artifact manifest | | graphs/interactive-artifact.circuitry.yaml | artifact_request | zero-native page/lab/widget artifact manifest | | graphs/cleanup.circuitry.yaml | cleanup_request | cleanup plan and bounded deletion result | | graphs/minimal-smoke.circuitry.yaml | smoke_request | dependency/runtime smoke result |

Configuration

Default config lives at config/gnosis.config.json. User config at ~/.pi/pi-gnosis.json is deep-merged by the package loader.

Default paths:

| Path key | Default | | --- | --- | | temporaryRoot | /tmp/pi-gnosis | | obsidianRoot | notes | | profileNote | notes/profile.md | | manimRoot | /tmp/pi-gnosis/manim | | interactiveArtifactRoot | /tmp/pi-gnosis/interactive-artifacts |

Graph stations that write files consume configured roots; they do not choose storage roots from prose.

Learning surfaces

| Surface | Engine | Persistence | | --- | --- | --- | | Text / ASCII / markdown | Pi conversation | conversation only | | Video / lecture | Manim CE project | configured Manim root | | Temporary page | zero-native | configured interactive artifact root | | Lab / widget | Geist-style learning pattern + zero-native | configured interactive artifact root | | Durable notes | Obsidian-compatible markdown | configured notes root |

Development

npm install
npm test

The test suite checks graph shape, runtime config policy, probe policy, artifact builders, and package contents.

Dependencies

Required:

• @darkhorseprojects/pi-circuitry 0.2.30
• pi-web-access ^0.10.7
• zero-native ^0.2.0

Optional:

• pi-exa-search for Exa-first source discovery

Credits

• Native temporary pages use Vercel Labs zero-native.
• Geist-style lab patterns are adapted from Vercel Labs skill-geist-learning-labs.

License

Apache-2.0. See LICENSE.