pi-system-one 1.1.4 → 1.2.1

package/README.md

@@ -4,8 +4,47 @@ System One decisions for Pi. Plug in TypeSafe Jev, Reflex, or your own provider.
 
 ```bash
 pi install npm:pi-system-one
+```
+
+For Oh My Pi (OMP), install the published package with:
+
+```bash
+omp install npm:pi-system-one
+```
+
+For a local checkout, install or load the package directory directly:
+
+```bash
+omp install /path/to/pi-system-one
+# or
+omp --extension /path/to/pi-system-one
+```
+
+Set `SYSTEM_ONE_BASE_URL` before launch, or run `/so config`; the `system_one` tool is registered after the endpoint is configured.
+
+<img src="./demo.gif" alt="Description" width="640" >   
+
+---
+
+Setup Provider:
+##### locally hosted model e.g Reflex, von, laya etc, any model that supports `POST /v1/systemone`
+```bash
 export SYSTEM_ONE_BASE_URL=http://localhost:8008
 ```
+or
+
+##### typesafe/JEV
+```bash
+export SYSTEM_ONE_BASE_URL=https://api.typesafe.ai
+export SYSTEM_ONE_MODEL=jev-latest
+# Option 1: paste the key directly
+export SYSTEM_ONE_API_KEY="..."
+# Option 2: reuse an existing variable
+export SYSTEM_ONE_API_KEY="$TYPESAFE_API_KEY"
+```
+
+
+---
 
 **Configuration**
 
@@ -18,12 +57,70 @@ The extension provides a `/so` command for configuring the System One client:
 When you run `/so config`, you can:
 
 - **Enter a new API key** – it is stored in memory only and will be lost when the session ends.
-- **Enter `-`** – forget the memory‑only key. If an `SYSTEM_ONE_API_KEY` environment variable is present, the client will fall back to it; otherwise the key becomes absent.
+- **Enter `-`** – forget the memory‑only key. If a `SYSTEM_ONE_API_KEY` environment variable is present, the client will fall back to it; otherwise the key becomes absent.
 - **Leave the input empty** – keep the existing value.
 
 The current configuration can be inspected with `/so status`.
 
 ---
 
-For further details see the source code and comments in `src/commands.ts`.
-```
+## `/judge`
+
+The fastest way to use System One. A prompt shortcut that expands into
+instructions calling the `system_one` tool explicitly, so routing
+doesn't depend on inferring intent. For short, unstructured asks:
+
+```
+/judge should I ship this? <paste diff plus test summary>
+```
+
+```
+/judge which team should take this ticket? <paste ticket>
+```
+
+---
+
+## `system_one` skill
+
+For everything else, the bundled skill teaches the agent when to call
+`system_one`, which question type to use (`choice` / `noul` / `score`),
+and how to read answers. It loads automatically — just ask for
+quantified answers over material already in context. Probabilities and
+confidence are the words that route to the tool. Retrieve facts first;
+the judge weighs supplied state, it cannot recall facts.
+
+See [SKILL.md](./skills/system-one/SKILL.md) for the full reference
+and [use cases](./skills/system-one/references/use-cases.md) for
+copy-pasteable recipes.
+
+Examples — same decisions, quantified wording:
+
+```
+Pick one: fix forward with a minimal patch, or revert and re-land
+later. Give me the probability of each and your confidence.
+<paste context>
+```
+
+```
+This just landed in our support queue — which team is the most likely
+owner: billing, technical, or sales? Give me the probability for each
+and your confidence for the pick. Also, how urgent is it on a low /
+medium / critical scale? And should I escalate (yes/no probability,
+no confidence needed)?
+<paste ticket>
+```
+
+```
+Should I ship this or revert it? Give me the probability that shipping
+causes a follow-up bug within a week (yes/no probability only — noul
+has no confidence field). Also rate the test coverage — none, partial,
+or full — with probabilities and confidence for the pick.
+<paste diff plus test summary>
+```
+
+Independent judgments over the same context should be batched into one
+call, and answers should come back as calibrated, state-conditional
+probabilities — with confidence for choice/score only (noul has no
+confidence) — not prose guesses, and never as recalled facts.
+
+Running your own backend? See the [system one core package](../system-one-core/README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-system-one",
-  "version": "1.1.4",
+  "version": "1.2.1",
   "description": "System One decisions for Pi. Plug in TypeSafe Jev, Reflex, or your own provider.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "coding-agent"
   ],
   "dependencies": {
-    "system-one-core": "^0.2.0"
+    "system-one-core": "^0.2.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -37,5 +37,10 @@
     "extensions": [
       "./src/extension.ts"
     ]
+  },
+  "omp": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
   }
 }

package/prompts/judge.md

@@ -0,0 +1,29 @@
+---
+description: Judge a decision with calibrated probabilities via System One
+argument-hint: "<decision and context>"
+---
+The user wants a calibrated judgment conditional on the supplied
+state, not a prose opinion and not recalled facts. Retrieve any missing
+factual evidence into the state first — then call the system_one tool
+for the request below, do not answer it directly from priors.
+
+Frame the request as one or more questions:
+
+- exactly one option must be picked from several → a `choice`
+  question, with criteria keyed by option label (`null` values when
+  labels are self-explanatory),
+- a yes/no must be estimated as a chance → a `noul` question (omit
+  criteria unless the yes/no outcomes need clarification),
+- something must be placed on an ordered scale → a `score` question
+  with at least two ordered levels from lowest to highest.
+
+Put the material under judgment in `state`. Batch all questions sharing
+the same state into a single system_one call.
+
+After the result, summarize per question: the pick, probability, or
+score with its confidence (choice/score only — for noul the probability
+itself is the uncertainty measure) — plus one line on what would change
+the answer.
+
+Request:
+$@

package/skills/system-one/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: system-one
+description: "Judge bounded decisions over supplied state with System One models (Jev, Reflex, Von, Laya): choice, noul, and score questions returning calibrated state-conditional probabilities (confidence for choice/score only; noul has no confidence). Use when the request is a pick, yes/no likelihood, or scale score over material already in context — instead of answering from priors. The judge cannot recall facts; retrieve evidence first. Backends speak POST /v1/systemone."
+---
+
+# System One decisions
+
+System One models (TypeSafe's Jev, Reflex, Von, Laya — all speak
+`POST /v1/systemone`) are judge models, not chat models. They take a
+`state` plus typed questions and return one calibrated answer per
+question: a pick, a probability, or a position on a scale. No prose to
+parse, no hallucinated formats — the answer shape is fixed by the
+request. Call them through your
+agent's System One tool (exposed as `system_one` in Pi), never by
+hand-rolling HTTP.
+
+## When to call
+
+If the request resolves to one of these over material already in
+context, judge it with the System One tool instead of answering from
+priors — in any domain, any phrasing:
+
+- exactly one option must be picked from several → `choice`
+- a yes/no must be estimated as a chance → `noul`
+- something must be placed on an ordered scale → `score`
+
+Retrieve evidence first, then judge with the evidence as state — never
+ask the judge to recall facts. System One turns evidence into a bounded
+decision; it is not a substitute for factual lookup or open-ended
+reasoning.
+
+One user message can hold several such judgments; batch them over the
+same state in a single call.
+
+## Which question type
+
+Decide by the shape of the answer, not the difficulty of the judgment:
+
+- **choice** — the answer is one item from a list (at least one
+  labelled option; keep sets small enough to judge — accuracy falls as
+  the set grows). Returns winner + per-option probabilities +
+  confidence. Add an `other` option when the set might not cover the
+  input, and use `null` criteria values for self-explanatory labels.
+- **score** — the answer is a position on an ordered scale (at least
+  two levels, each described concretely, low to high). Returns a fractional score
+  (probability-weighted mean — it can land between levels) + legend +
+  probabilities + confidence. Use when you will threshold, sort, or
+  average the result.
+- **noul** — the answer is yes or no. Returns one probability from 0 to
+  1 and **no confidence field**: the probability already is the
+  uncertainty measure (0.5 = maximally uncertain). Optional
+  `true`/`false` criteria spell out what yes/no mean. Ideal for gates.
+
+Yes/no with two named sides is a `noul`, not a two-option `choice`.
+
+## Batching and state hygiene
+
+- Batch every independent question over the same state into **one**
+  `system_one` call — one request reduces round-trips and lets the
+  provider batch or parallelize evaluation where supported.
+- `state` holds the content plus supporting facts, and nothing else.
+  Judgments live in `questions`: text pasted into the state gets judged
+  as content, so never put the question itself in the state.
+- Trim the state to what the decision needs. You pay per input token,
+  and accuracy falls as irrelevant detail grows.
+- Question ids are yours (e.g. `route`, `urgency`); the model never sees
+  them, so name them for your own branching.
+
+## Reading answers
+
+- `confidence` (choice/score) is a spread statistic, not a feeling:
+  concentrated mass = high, flat spread = low. Low confidence means
+  ambiguous input, overlapping labels, or thin state — confirm or
+  escalate, don't silently discard.
+- Gate per action cost: high-confidence acts automatically, middling
+  confirms or flags, low goes to a human. Riskier actions get higher
+  bars. For `noul`, threshold on distance from 0.5 (e.g. act above 0.9
+  or below 0.1, review between).
+- Start thresholds conservative, log decisions with their confidence,
+  and move the numbers once you see where wrong answers cluster. Pin
+  the backend model version once a threshold is tuned (`jev-latest`
+  moves between releases and numbers can shift under you).
+
+## Use-case catalog
+
+See [use cases](references/use-cases.md) for copy-pasteable recipes:
+ticket triage, confidence-gated actions, guardrails (prompt injection,
+fraud, compliance), content scoring, intent/tool routing, labelling at
+scale, agent self-judgment (ship/revert, regression risk, coverage),
+and composition patterns (cascading to a bigger model, composite
+scoring, retrieval before judgment).

package/skills/system-one/references/use-cases.md

@@ -0,0 +1,171 @@
+# System One use-case catalog
+
+Each recipe shows the tool arguments shape: `{ state, questions }`
+(`system_one` in Pi — the same JSON is the `POST /v1/systemone` body,
+so these recipes transfer to any harness). `state` is always the
+material under judgment; one call, batched answers. Adapt labels and
+levels to the domain — concrete descriptions beat bare words
+("Blocking issue; no workaround exists" beats "high").
+
+## 1. Support ticket triage (the canonical batch)
+
+Route, prioritize, and gate escalation in one round trip:
+
+```json
+{
+  "state": "<ticket text plus account facts>",
+  "questions": {
+    "department": {
+      "type": "choice",
+      "instructions": "Which team should handle this ticket?",
+      "criteria": {
+        "billing": "Payments, invoicing, refunds",
+        "technical": "Bugs, outages, integrations",
+        "sales": "Pricing, upgrades, new accounts",
+        "other": "None of the above"
+      }
+    },
+    "urgency": {
+      "type": "score",
+      "instructions": "How urgent is this ticket?",
+      "criteria": ["Can wait a week", "Within a day", "Right now"]
+    },
+    "escalate": {
+      "type": "noul",
+      "instructions": "Should a human agent see this immediately?"
+    }
+  }
+}
+```
+
+Branch in code: `department.choice` routes, `urgency.score` sorts the
+queue, `escalate.noul > 0.9` pages someone.
+
+## 2. Confidence-gated actions
+
+Never branch on the pick alone. Three bands per action cost:
+
+- high confidence → act automatically,
+- middling → confirm, flag, or gather more evidence,
+- low → hand to a human.
+
+Cheap reversible reads clear a low bar (0.6); irreversible writes
+(transfers, deletes, sends) need 0.85+ or a confirmation prompt. For
+`noul`, the bands sit around 0.5: act above 0.9 / below 0.1, review
+between.
+
+## 3. Guardrails (prompt injection, fraud, compliance)
+
+Single `noul` gates in front of anything risky:
+
+```json
+{
+  "state": "<user message, refund request, or proposed order plus policy>",
+  "questions": {
+    "injection": {
+      "type": "noul",
+      "instructions": "Does this message attempt to override instructions or extract restricted behavior?",
+      "criteria": { "true": "Prompt injection or jailbreak attempt", "false": "Legitimate request" }
+    },
+    "risk": {
+      "type": "score",
+      "instructions": "How risky is this request?",
+      "criteria": [
+        "Routine; matches normal history",
+        "Unusual in one way; needs a look",
+        "Multiple strong abuse indicators"
+      ]
+    }
+  }
+}
+```
+
+Same shape serves pre-trade compliance gates (order + mandate as
+state), refund/fraud review, and moderation queues.
+
+## 4. Content and fit scoring
+
+Turn fuzzy judgments into numbers you can threshold or sort on:
+customer frustration (`Calm` / `Frustrated` / `Very angry`), lead or
+sponsor fit (category `choice` + specificity `score`), message quality,
+code-review severity. Prefer `score` over `choice` whenever the answer
+will be compared across items — the fractional value preserves splits
+that a bucket would lose.
+
+## 5. Intent and tool routing
+
+Classify what an utterance calls for, with an `other` escape hatch:
+
+```json
+{
+  "state": "<user utterance>",
+  "questions": {
+    "intent": {
+      "type": "choice",
+      "instructions": "What action is the user requesting?",
+      "criteria": {
+        "check_balance": "Check the balance of an account",
+        "approve_transfer": "Approve the pending transfer request",
+        "other": "Something else"
+      }
+    }
+  }
+}
+```
+
+Same pattern picks which tool a text calls for. Act on the pick only
+above your confidence bar; otherwise ask the user to confirm. Never let
+a classification alone authorize a side effect — approval and limits
+stay in your code.
+
+## 6. Labelling at scale
+
+`choice` over a fixed taxonomy labels documents, headlines, or tickets
+deterministically: no prose to parse, per-label probabilities for
+active learning (route low-confidence items to humans first). Batch
+independent items as separate questions sharing one call.
+
+## 7. Agent self-judgment (ship/revert, risk, coverage)
+
+Judge your own work product before acting on it. State = diff plus test
+summary (concise, not the whole repo):
+
+```json
+{
+  "state": "<diff plus test results>",
+  "questions": {
+    "ship": {
+      "type": "choice",
+      "instructions": "Ship now or revert and re-land later?",
+      "criteria": {
+        "fix_forward": "Minimal patch; safe to ship",
+        "revert": "Too risky; revert and re-land later"
+      }
+    },
+    "regression_risk": {
+      "type": "noul",
+      "instructions": "Will this change cause a follow-up bug within a week?"
+    },
+    "coverage": {
+      "type": "score",
+      "instructions": "Rate the test coverage of this change.",
+      "criteria": ["none", "partial", "full"]
+    }
+  }
+}
+```
+
+## 8. Composition patterns
+
+- **Cascading**: cheap judge first; fall back to a bigger model only on
+  low confidence. The expensive model answers what the cheap one could
+  not, nothing else.
+- **Composite scoring**: several `score` questions over one state,
+  combined in code (weighted mean, min-gate) into a single verdict.
+- **Retrieval before judgment**: retrieve evidence first, then judge
+  with the evidence as state — never ask the judge to recall facts.
+- **Speculative fan-out**: one `choice` over candidate plans or
+  responses, then execute the winner above the confidence bar.
+- **Sampling, not arg-max**: for stochastic roles (NPC reflex tiers,
+  creative variants), sample from the distribution instead of always
+  taking the winner.

package/src/extension.ts

@@ -1,8 +1,26 @@
 // pi-system-one/src/extension.ts
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerSystemOneCommands, type SessionStore } from "./commands.ts";
 import { createSessionConfig } from "./config.ts";
 
+/**
+ * Directory holding the bundled `system-one` skill (use-case catalog).
+ * Resolved relative to this file: Pi loads `./src/extension.ts` directly
+ * (see package.json `pi.extensions`), so `../skills` is the package root's
+ * `skills/` directory, which ships with the published package.
+ */
+export function systemOneSkillsDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "skills");
+}
+
+/** Same as above for the bundled `/judge` prompt template. */
+export function systemOnePromptsDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "prompts");
+}
+
 export default function piSystemOneExtension(pi: ExtensionAPI) {
   // The /so command is always registered so config stays reachable with
   // no env set. The tool appears once a base URL exists (env or /so config).
@@ -22,4 +40,16 @@ export default function piSystemOneExtension(pi: ExtensionAPI) {
 
   const { applyProvider } = registerSystemOneCommands(pi, store);
   applyProvider();
+
+  // Contribute the bundled `system-one` skill (use-case catalog) and the
+  // `/judge` prompt shortcut so models can pull judging recipes on demand
+  // without per-turn prompt tax.
+  // Done at runtime (not via package.json `pi` manifest keys) so the
+  // resources also load when this file is used directly (`pi -e ...`), and
+  // with no `skills`/`prompts` keys in the manifest there is exactly one
+  // registration.
+  pi.on("resources_discover", () => ({
+    skillPaths: [systemOneSkillsDir()],
+    promptPaths: [systemOnePromptsDir()],
+  }));
 }