pi-gnosis 0.1.0

package/graphs/minimal-smoke.circuitry.yaml

@@ -0,0 +1,32 @@
+circuitry: "0.2"
+title: "Pi-GNOSIS Minimal Smoke Program"
+description: "Small Circuitry graph for validating provider, model inheritance, resource inputs, skill loading, and expected JSON output."
+runtime:
+  provider: pi
+  model: inherit
+validation:
+  rules:
+    - no-self-loops
+    - no-unknown-edge-endpoints
+    - no-cycles
+    - rule: require-executable-inputs
+      executableKinds: [agent, tool]
+resources:
+  smoke_request:
+    type: text
+    value: |
+      Verify pi-gnosis graph wiring. Do not browse. Do not write files.
+  smoke_agent:
+    type: agent
+    identity: "Pi-GNOSIS Smoke Agent"
+    model: inherit
+    inputs: [smoke_request]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      status: str
+      provider: str
+      model: str
+      note: str
+    instructions: |
+      Return a tiny JSON object confirming that this graph uses provider pi and model inherit. Output only valid JSON matching expect.

package/graphs/note-export.circuitry.yaml

@@ -0,0 +1,116 @@
+circuitry: "0.2"
+title: "Pi-GNOSIS Obsidian Export Program"
+description: |
+  Frozen Circuitry program that turns canonical DAG state into learner-facing Obsidian-compatible notes under a safe notes root.
+runtime:
+  provider: pi
+  model: inherit
+validation:
+  rules:
+    - no-self-loops
+    - no-unknown-edge-endpoints
+    - no-cycles
+    - rule: require-executable-inputs
+      executableKinds: [agent, tool]
+resources:
+  export_request:
+    type: text
+    label: "Note export request"
+    value: |
+      topic: ""
+      dag_state_path: ".pi-gnosis/state"
+      note_path: "notes"
+      apply_writes: false
+      overwrite_policy: "preserve-user-edits"
+  obsidian_contract:
+    type: text
+    label: "Obsidian contract"
+    value: |
+      Obsidian is learner-facing memory, not canonical source truth. Export 00-map.md, source-ledger.md, concepts/*.md, misconceptions.md, probes.md, review-plan.md, reflection-log.md, and manifest.md. Preserve user edits where possible. Link concepts, sources, and probes.
+  write_policy:
+    type: text
+    label: "Write policy"
+    value: |
+      Manifest first. Write only under the configured note_path. Do not delete notes. Do not overwrite user-authored sections unless explicitly asked. Mark generated sections with stable headers so future runs can update them safely.
+  dag_state_importer:
+    type: agent
+    identity: "DAG State Importer"
+    model: inherit
+    inputs: [export_request, obsidian_contract]
+    skills: [pi-gnosis]
+    tools: [read_file, grep]
+    expect:
+      imported_state_summary: str
+      source_ledger_available: bool
+      claim_ledger_available: bool
+      kt_dag_available: bool
+      missing_inputs:
+        type: list
+        items: str
+    instructions: |
+      Read only the requested DAG state. Summarize available ledgers and missing inputs. Do not write. Output only valid JSON matching expect.
+  note_plan_builder:
+    type: agent
+    identity: "Obsidian Note Plan Builder"
+    model: inherit
+    inputs: [dag_state_importer, obsidian_contract, write_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      files_to_create_or_update:
+        type: list
+        items:
+          path: str
+          purpose: str
+          update_policy: str
+      generated_section_ids:
+        type: list
+        items: str
+      user_edit_risks:
+        type: list
+        items: str
+    instructions: |
+      Build a manifest-first note plan. Use the Obsidian contract. Make clear which sections are generated and which are preserved. Output only valid JSON matching expect.
+  note_writer:
+    type: agent
+    identity: "Obsidian Note Writer"
+    model: inherit
+    inputs: [note_plan_builder, dag_state_importer, obsidian_contract, write_policy]
+    skills: [pi-gnosis]
+    tools: [read_file, write_file, edit_file]
+    expect:
+      files_written_or_planned:
+        type: list
+        items: str
+      manifest_path: str
+      skipped_files:
+        type: list
+        items: str
+      warnings:
+        type: list
+        items: str
+    instructions: |
+      If apply_writes is false, return planned content only. If writes are enabled by Pi, write only under note_path, manifest first. Preserve user sections. Include source ids and open-ended probes. Output only valid JSON matching expect.
+  note_quality_gate:
+    type: agent
+    identity: "Obsidian Note Quality Gate"
+    model: inherit
+    inputs: [note_writer, obsidian_contract, dag_state_importer]
+    skills: [pi-gnosis]
+    tools: [read_file, grep]
+    expect:
+      status: str
+      missing_required_notes:
+        type: list
+        items: str
+      unsupported_claims:
+        type: list
+        items: str
+      weak_learning_sections:
+        type: list
+        items: str
+      cleanup_candidates:
+        type: list
+        items: str
+    instructions: |
+      Verify generated notes against the contract. Check for missing source ids, missing probes, missing review prompts, broken internal links if possible, and accidental overwrite risk. Output only valid JSON matching expect.

package/graphs/research.circuitry.yaml

@@ -0,0 +1,309 @@
+circuitry: "0.2"
+title: "Pi-GNOSIS Research Program"
+description: |
+  Frozen Circuitry program for delegated source-grounded research. The graph is the multi-agent workflow: scope, query planning, source discovery, fetching, claim extraction, critique, and KT-DAG seeding.
+runtime:
+  provider: pi
+  model: inherit
+validation:
+  rules:
+    - no-self-loops
+    - no-unknown-edge-endpoints
+    - no-cycles
+    - rule: require-executable-inputs
+      executableKinds: [agent, tool]
+resources:
+  user_request:
+    type: text
+    label: "Learning/research request"
+    value: |
+      topic: "automated research pipelines and agentic tutors"
+      purpose: "learn"
+      output_modes: ["dag_state", "obsidian_notes"]
+      note_path: "notes"
+      dag_state_path: ".pi-gnosis/state"
+      depth: "working"
+      learner_context: ""
+      constraints: ""
+      apply_writes: false
+  package_config:
+    type: text
+    label: "Pi-GNOSIS config snapshot"
+    value: |
+      package: pi-gnosis
+      circuitry: "0.2"
+      runtime_provider: pi
+      model: inherit
+      required_tools: [web_search, fetch_content]
+      optional_tools: [exa_search]
+      required_dependency: pi-web-access
+      optional_dependency: pi-exa-search
+  research_policy:
+    type: text
+    label: "Research policy"
+    value: |
+      Use source-ledger and claim-ledger thinking. Prefer primary papers, official docs, standards, textbook-like references, systematic reviews, and repo documentation. Separate evidence, interpretation, disagreement, and speculation. Do not use popularity as truth. Do not hide uncertainty.
+  learning_policy:
+    type: text
+    label: "Learning policy"
+    value: |
+      The learner may stop, resume, or jump topics. Build reusable state, not a one-shot explanation. Prefer open-ended probes and teach-back evidence. Never generate multiple-choice diagnostic probes.
+  storage_contract:
+    type: text
+    label: "Storage contract"
+    value: |
+      DAG state is canonical: source ledgers, claim ledgers, KT DAG, learner state, probe outcomes, review schedules, and manifests. Obsidian is learner-facing memory: notes, links, reflections, and study prompts.
+  prior_knowledge_audit:
+    type: agent
+    identity: "Prior Knowledge Auditor"
+    model: inherit
+    inputs: [user_request, learning_policy, storage_contract]
+    skills: [pi-gnosis]
+    tools: [read_file, grep]
+    expect:
+      note_evidence:
+        type: list
+        items:
+          path: str
+          evidence: str
+      inferred_prior_knowledge:
+        type: list
+        items: str
+      stale_or_missing_areas:
+        type: list
+        items: str
+      confidence: str
+    instructions: |
+      Read only if note paths or prior DAG state are available. Infer prior knowledge only from user-provided context, existing notes, or prior state. If no readable notes exist, say so. Output only valid JSON matching expect.
+  scope_architect:
+    type: agent
+    identity: "Research Scope Architect"
+    model: inherit
+    inputs: [user_request, package_config, research_policy, learning_policy, prior_knowledge_audit]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      scope: str
+      key_questions:
+        type: list
+        items: str
+      prerequisites:
+        type: list
+        items: str
+      likely_controversies:
+        type: list
+        items: str
+      source_targets:
+        type: list
+        items: str
+      invalid_shortcuts:
+        type: list
+        items: str
+    instructions: |
+      Convert the user request into a research scope. Identify prerequisite concepts, source classes, high-risk claims, and things not to conclude without evidence. This is a planning node; do not browse here. Output only valid JSON matching expect.
+  query_planner:
+    type: agent
+    identity: "Search Query Planner"
+    model: inherit
+    inputs: [scope_architect, research_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      exa_queries:
+        type: list
+        items: str
+      web_queries:
+        type: list
+        items: str
+      official_docs_targets:
+        type: list
+        items: str
+      scholar_targets:
+        type: list
+        items: str
+      exclusion_filters:
+        type: list
+        items: str
+    instructions: |
+      Produce multiple independent queries. Include fresh/recent queries when the subject is changing. Include official repo/docs queries for software dependencies. Include academic queries for pedagogy and research workflows. Output only valid JSON matching expect.
+  source_discovery:
+    type: agent
+    identity: "Source Discovery Agent"
+    model: inherit
+    inputs: [query_planner, package_config]
+    skills: [pi-gnosis, exa-web-research, librarian]
+    tools: [exa_search, web_search]
+    expect:
+      candidate_sources:
+        type: list
+        items:
+          id: str
+          title: str
+          url: str
+          source_type: str
+          reason: str
+          priority: int
+      rejected_patterns:
+        type: list
+        items: str
+      search_log:
+        type: list
+        items: str
+    instructions: |
+      Use exa_search first when available for source discovery. Use web_search when Exa is unavailable or when broad/fresh search is better. Do not synthesize the answer. Return candidate URLs, why they matter, and rejected source patterns. Output only valid JSON matching expect.
+  source_fetcher:
+    type: agent
+    identity: "Source Fetch and Extract Agent"
+    model: inherit
+    inputs: [source_discovery, research_policy]
+    skills: [pi-gnosis, librarian]
+    tools: [fetch_content, web_search]
+    expect:
+      fetched_sources:
+        type: list
+        items:
+          id: str
+          title: str
+          url: str
+          date: str
+          author_or_org: str
+          extracted_summary: str
+          limitations: str
+      unavailable_sources:
+        type: list
+        items:
+          url: str
+          reason: str
+    instructions: |
+      Fetch the highest-priority sources with fetch_content. If a source cannot be fetched, record that plainly. Preserve URLs and dates where available. Do not invent metadata. Output only valid JSON matching expect.
+  source_ledger_builder:
+    type: agent
+    identity: "Source Ledger Builder"
+    model: inherit
+    inputs: [source_fetcher, research_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      source_ledger:
+        type: list
+        items:
+          id: str
+          source: str
+          source_type: str
+          date: str
+          reliability_notes: str
+          useful_for:
+            type: list
+            items: str
+          caveats: str
+      missing_source_classes:
+        type: list
+        items: str
+    instructions: |
+      Convert fetched sources into a source ledger. Classify official docs, primary research, benchmark/evaluation, review/survey, tooling repo, commentary, or tutorial. Output only valid JSON matching expect.
+  claim_extractor:
+    type: agent
+    identity: "Claim Ledger Extractor"
+    model: inherit
+    inputs: [source_ledger_builder, scope_architect]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      claims:
+        type: list
+        items:
+          id: str
+          claim: str
+          source_ids:
+            type: list
+            items: str
+          confidence: str
+          disagreement: str
+          implications_for_pi_gnosis: str
+      definitions:
+        type: list
+        items:
+          term: str
+          definition: str
+          source_ids:
+            type: list
+            items: str
+      open_questions:
+        type: list
+        items: str
+    instructions: |
+      Extract atomic claims and definitions. Every claim must cite source ids from the source ledger or be marked as a hypothesis. Separate consensus from disagreement. Output only valid JSON matching expect.
+  synthesis_critic:
+    type: agent
+    identity: "Synthesis Critic"
+    model: inherit
+    inputs: [claim_extractor, source_ledger_builder, research_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      unsupported_or_weak_claims:
+        type: list
+        items: str
+      missing_counterevidence:
+        type: list
+        items: str
+      stale_risk:
+        type: list
+        items: str
+      pass_conditions:
+        type: list
+        items: str
+      verdict: str
+    instructions: |
+      Audit the claim ledger. Flag unsupported claims, missing source classes, stale evidence, and overbroad synthesis. This is a quality gate before teaching artifacts. Output only valid JSON matching expect.
+  kt_dag_seed_builder:
+    type: agent
+    identity: "KT DAG Seed Builder"
+    model: inherit
+    inputs: [claim_extractor, synthesis_critic, prior_knowledge_audit, learning_policy, storage_contract]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      kt_dag:
+        type: dict
+      concept_nodes:
+        type: list
+        items:
+          id: str
+          label: str
+          prerequisites:
+            type: list
+            items: str
+          evidence_source_ids:
+            type: list
+            items: str
+          misconception_risk: int
+          decay_risk: int
+      learner_state_update:
+        type: dict
+      recommended_next_graphs:
+        type: list
+        items: str
+    instructions: |
+      Build a transparent KT DAG seed: concepts, prerequisite edges, contrast edges, misconception risks, decay risks, and learner evidence. Do not mark mastery without open-ended evidence. Recommend follow-up graphs, such as tutoring-session, note-export, or manim-lecture. Output only valid JSON matching expect.
+  research_output_manifest:
+    type: agent
+    identity: "Research Output Manifest Writer"
+    model: inherit
+    inputs: [source_ledger_builder, claim_extractor, synthesis_critic, kt_dag_seed_builder, storage_contract]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      dag_state_files_to_write:
+        type: list
+        items: str
+      obsidian_exports_to_offer:
+        type: list
+        items: str
+      temp_artifacts:
+        type: list
+        items: str
+      cleanup_graph_recommended: bool
+      summary_for_pi: str
+    instructions: |
+      Produce a manifest for the main Pi agent. Do not write files in this graph unless explicitly instructed by Pi runtime policy. Include a cleanup recommendation for temporary artifacts. Output only valid JSON matching expect.

package/graphs/tutoring-session.circuitry.yaml

@@ -0,0 +1,130 @@
+circuitry: "0.2"
+title: "Pi-GNOSIS Tutoring Session Program"
+description: |
+  Frozen Circuitry program for one non-linear tutoring turn. It reads DAG/notes evidence, chooses an open-ended probe or explanation, updates learner state, and tells Pi whether to continue, pause, export notes, or switch modality.
+runtime:
+  provider: pi
+  model: inherit
+validation:
+  rules:
+    - no-self-loops
+    - no-unknown-edge-endpoints
+    - no-cycles
+    - rule: require-executable-inputs
+      executableKinds: [agent, tool]
+resources:
+  session_context:
+    type: text
+    label: "Session context"
+    value: |
+      topic: ""
+      learner_message: ""
+      dag_state_path: ".pi-gnosis/state"
+      note_path: "notes"
+      preferred_mode: "pi decides"
+      user_may_quit_any_time: true
+  tutoring_policy:
+    type: text
+    label: "Tutoring policy"
+    value: |
+      This is non-linear. The learner may stop, resume, jump ahead, ask for a video, ask for notes, or change goals. Ask at most one modality or preference question when needed. Never use multiple-choice diagnostic probes. Use open-ended evidence to update KT state.
+  kt_policy:
+    type: text
+    label: "KT policy"
+    value: |
+      Maintain an explainable KT DAG. Store evidence records rather than opaque mastery labels. Concepts can have prerequisite, contrast, misconception, analogy, and transfer edges. Move on only when evidence supports it or when the user requests a different path.
+  learner_state_reader:
+    type: agent
+    identity: "Learner State Reader"
+    model: inherit
+    inputs: [session_context, kt_policy]
+    skills: [pi-gnosis]
+    tools: [read_file, grep]
+    expect:
+      relevant_concepts:
+        type: list
+        items: str
+      evidence_found:
+        type: list
+        items: str
+      uncertain_state:
+        type: list
+        items: str
+      recommended_focus: str
+    instructions: |
+      Read available DAG state and Obsidian notes if paths exist. Summarize only evidence relevant to the current learner message. If no state exists, report empty state. Output only valid JSON matching expect.
+  turn_intent_router:
+    type: agent
+    identity: "Turn Intent Router"
+    model: inherit
+    inputs: [session_context, learner_state_reader, tutoring_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      user_intent: str
+      should_teach_now: bool
+      should_probe_now: bool
+      should_offer_modality_choice: bool
+      should_pause_or_resume: str
+      recommended_graph_after_turn: str
+    instructions: |
+      Decide what Pi should do next: explain, probe, ask one modality question, resume from notes, export notes, create a Manim lecture, or pause. Do not force a linear curriculum. Output only valid JSON matching expect.
+  open_probe_designer:
+    type: agent
+    identity: "Open Probe Designer"
+    model: inherit
+    inputs: [learner_state_reader, turn_intent_router, tutoring_policy, kt_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      probes:
+        type: list
+        items:
+          type: str
+          prompt: str
+          targeted_concepts:
+            type: list
+            items: str
+          rubric: str
+          answer_key_visibility: str
+      forbidden_formats_checked: bool
+    instructions: |
+      If probing is appropriate, write short open-ended prompts only. Allowed types include recall, explain, transfer, contrast, debug, teach-back, source-check, and worked example. Recognition-only formats are forbidden. Output only valid JSON matching expect.
+  teaching_move_planner:
+    type: agent
+    identity: "Teaching Move Planner"
+    model: inherit
+    inputs: [learner_state_reader, turn_intent_router, open_probe_designer, tutoring_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      next_pi_message: str
+      explanation_strategy: str
+      scaffold_level: str
+      what_not_to_reveal_yet:
+        type: list
+        items: str
+      user_exit_paths:
+        type: list
+        items: str
+    instructions: |
+      Draft Pi's next conversational move. Keep it natural. If asking a probe, do not include the answer before the learner responds. If explaining, include a concrete example and ask for a short teach-back. Output only valid JSON matching expect.
+  state_update_writer:
+    type: agent
+    identity: "Learner State Update Writer"
+    model: inherit
+    inputs: [learner_state_reader, turn_intent_router, open_probe_designer, teaching_move_planner, kt_policy]
+    skills: [pi-gnosis]
+    tools: []
+    expect:
+      learner_state_patch:
+        type: dict
+      evidence_to_wait_for:
+        type: list
+        items: str
+      next_review_or_probe_targets:
+        type: list
+        items: str
+      output_manifest: dict
+    instructions: |
+      Produce a state patch to be saved by Pi if appropriate. Do not claim the learner knows a concept until evidence exists. Include what evidence to wait for after Pi sends the next message. Output only valid JSON matching expect.

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "pi-gnosis",
+  "version": "0.1.0",
+  "description": "Circuitry-first Pi package for source-grounded research, non-linear tutoring, Obsidian learning memory, and Manim lecture generation.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "private": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "circuitry",
+    "agentic-workflow",
+    "research",
+    "tutoring",
+    "knowledge-tracing",
+    "obsidian",
+    "manim"
+  ],
+  "bin": {
+    "pi-gnosis": "./bin/pi-gnosis.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./config": "./src/config.js",
+    "./graph-template": "./src/graph-template.js",
+    "./validator": "./src/graph-validator.js",
+    "./scheduler": "./src/review-scheduler.js",
+    "./storage-contract": "./src/storage-contract.js",
+    "./probe-policy": "./src/probe-policy.js",
+    "./cleanup-policy": "./src/cleanup-policy.js",
+    "./manim-project": "./src/manim-project.js"
+  },
+  "files": [
+    "bin/",
+    "config/",
+    "graphs/",
+    "skills/",
+    "framework/",
+    "src/",
+    "scripts/",
+    "examples/",
+    "README.md",
+    "pi.json",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node test/run-tests.js && python3 scripts/check-circuitry-v02.py graphs/*.circuitry.yaml && npm pack --dry-run > /tmp/pi-gnosis-pack.txt",
+    "test:node": "node test/run-tests.js",
+    "test:graphs": "python3 scripts/check-circuitry-v02.py graphs/*.circuitry.yaml",
+    "validate:graphs": "python3 scripts/check-circuitry-v02.py graphs/*.circuitry.yaml",
+    "list:graphs": "node bin/pi-gnosis.js graphs"
+  },
+  "dependencies": {
+    "@darkhorseprojects/pi-circuitry": "github:darkhorseprojects/pi-circuitry#v0.2.6",
+    "pi-web-access": "^0.10.7"
+  },
+  "optionalDependencies": {
+    "pi-exa-search": "github:najibninaba/pi-exa-search#main"
+  },
+  "peerDependencies": {
+    "@darkhorseprojects/circuitry-core": ">=0.2.6"
+  },
+  "peerDependenciesMeta": {
+    "@darkhorseprojects/circuitry-core": {
+      "optional": true
+    }
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "graphs": [
+      "./graphs"
+    ],
+    "config": "./config/gnosis.config.json"
+  }
+}