probbit 0.12.1 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +105 -13
  2. package/package.json +5 -4
package/README.md CHANGED
@@ -1,19 +1,109 @@
1
- # probbit (npm)
1
+ # probbit
2
2
 
3
- Installs the prebuilt `probbit` command-line binary: a virtual p-bit processor that returns joint decisions under hard
4
- rules, with gated odds. JSON in, JSON out. Source, documentation and every benchmark:
5
- <https://github.com/BitmapAsset/probbit>.
3
+ **A personality, mood and memory layer for AI agents, on an exact p-bit decision engine.** Every stance is computed on a
4
+ CPU, keeps its rules by construction, and leaves a replayable, verifiable record.
5
+
6
+ ![probbit: simulated p-bits on a CPU settle an AI agent's stance and plans under hard rules](https://raw.githubusercontent.com/BitmapAsset/probbit/main/docs/probbit-hero-1600x900.jpg)
7
+
8
+ [![ci](https://github.com/BitmapAsset/probbit/actions/workflows/ci.yml/badge.svg)](https://github.com/BitmapAsset/probbit/actions/workflows/ci.yml)
9
+ [![npm](https://img.shields.io/npm/v/probbit)](https://www.npmjs.com/package/probbit)
10
+ [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/BitmapAsset/probbit/blob/main/LICENSE)
11
+
12
+ ## What it is, in 20 seconds
13
+
14
+ - **An AI persona outside the model.** A persona file and a seed make one individual: personality, mood with inertia (an
15
+ affective-computing model) and memory as learned adjustments within caps. The LLM writes the words; probbit gives it
16
+ the stance line for each turn.
17
+ - **Exact odds under hard rules, held by construction.** Simulated p-bits (probabilistic computing on an Ising/QUBO
18
+ model) settle the stance or plan; small programs are solved exact, larger ones sampled with an error bar. It is also a
19
+ constraint solver for plans: tasks to workers, every rule kept, or a refusal (exit 3) instead of a guess.
20
+ - **A receipt.** Every turn is a line on a hash-chained strand; `probbit live verify` replays it byte for byte.
21
+
22
+ For **agent builders** (a CLI, an MCP server, Node and Python), **OpenClaw users** (the OpenClaw plugin
23
+ `probbit-stance`), and **researchers** (every number reproducible from the repository).
24
+
25
+ ## Install and try it in 30 seconds
6
26
 
7
27
  ```sh
8
28
  npm install -g probbit
9
- probbit demo --tasks 12 | probbit decide --pretty
10
- probbit stats --pretty
11
29
  ```
12
30
 
13
- The install step fetches the release archive for your platform from GitHub Releases (macOS arm64 and x86_64, Linux
14
- x86_64 with glibc or musl, Linux ARM64 static musl, Windows x86_64), checks it against the `.sha256` file published beside it and keeps the binary inside
15
- this package. No dependencies; Node >= 18. If the install step could not run (`--ignore-scripts`, offline), the first
16
- `probbit` call fetches the binary. A checksum mismatch fails the install and installs nothing.
31
+ Then, in an empty directory (POSIX shell, Linux or macOS; no clone, no Rust, no API key). Each line ends with what to
32
+ expect; every one exits 0.
33
+
34
+ ```sh
35
+ probbit --version # probbit 0.13.0 (or later)
36
+ probbit demo --tasks 12 | probbit decide --summary # one JSON line with "verdict":"exact" and "violations":0
37
+ curl -fsSLO https://raw.githubusercontent.com/BitmapAsset/probbit/main/examples/persona/tutor.yaml # tutor.yaml appears
38
+ probbit persona init tutor.yaml --seed 2 --out tutor.state # wrote tutor.state (Pip 1.1.0, seed 2)
39
+ echo '{"sentiment":"negative"}' | probbit live tutor.yaml --state tutor.state --strand tutor.strand --clock fixed 2>/dev/null | grep -o '"line":"[^"]*"' # "line":"Stance: go easy on the jokes; no jokes; gentle; ...
40
+ probbit live verify tutor.strand | grep -o '"ok":[a-z]*' # "ok":true
41
+ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"sh","version":"0"}}}' '{"jsonrpc":"2.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | probbit mcp 2>/dev/null | grep -o '"name":"probbit_[a-z_]*"' # 10 lines, "name":"probbit_decide" ... "name":"probbit_live_verify"
42
+ ```
43
+
44
+ If npm says the install script did not run (`--ignore-scripts`, or a newer npm's script approval), that is fine: the first
45
+ `probbit` call fetches and checks the binary. Any other output: [open an issue](https://github.com/BitmapAsset/probbit/issues).
46
+
47
+ ## How one decision flows
48
+
49
+ ![how one decision flows through probbit: JSON in, a program with hard rules, the exact unit or the p-bit sampling unit, the diagnostics gate, the answer back](https://raw.githubusercontent.com/BitmapAsset/probbit/main/docs/probbit-flow.png)
50
+
51
+ A request arrives as JSON (a router document, a probbit-ir program or a persona event) and is normalised into one
52
+ program: a weight for every choice plus the hard rules (allowed values, quotas, habits). When the rule-abiding plans are
53
+ few enough to count (up to about 2 million), the exact unit enumerates every one and returns exact odds; otherwise
54
+ simulated p-bits sample the program with constraint-preserving Gibbs moves, so every sample keeps every rule by
55
+ construction. A diagnostics gate (split R-hat, an error bar per part, a frozen-worker check) then releases the answer,
56
+ releases what passed and escalates the rest (`partial`), or refuses (exit 3) when it cannot vouch. The answer carries its
57
+ receipt: the gate statistics and seed for a decision, a sha256-chained strand line for a persona turn.
58
+
59
+ ## Use it from your harness
60
+
61
+ | harness | one line to run | what proves it |
62
+ |---|---|---|
63
+ | [MCP server](https://github.com/BitmapAsset/probbit/blob/main/docs/agents.md) (Claude Code, Codex, Cursor, any MCP client) | `probbit mcp` (Claude Code: `claude mcp add probbit -- probbit mcp`) | the last line of the block above: 10 tools |
64
+ | [OpenClaw plugin](https://github.com/BitmapAsset/probbit/blob/main/plugins/openclaw/README.md) | `openclaw plugins install npm:probbit-stance --accept-capabilities` (changes that OpenClaw's configuration) | `openclaw plugins inspect probbit-stance --runtime --json` lists both hooks |
65
+ | [Node](https://github.com/BitmapAsset/probbit/blob/main/examples/node/decide.mjs) | `curl -fsSLO https://raw.githubusercontent.com/BitmapAsset/probbit/main/examples/node/decide.mjs && probbit demo --tasks 12 > router.json && node decide.mjs router.json` | prints `exit 0 answer: verdict exact, 12 of 12 released, ...` |
66
+ | [Python or any language](https://github.com/BitmapAsset/probbit/blob/main/docs/agents.md) | JSON on stdin, JSON on stdout, the exit code is the verdict; a stdlib-only wrapper: [python/probbit.py](https://github.com/BitmapAsset/probbit/blob/main/python/probbit.py) | `python3 -c 'import json,subprocess as s; d=s.run(["probbit","demo","--tasks","12"],capture_output=True).stdout; r=s.run(["probbit","decide"],input=d,capture_output=True); print(r.returncode, json.loads(r.stdout)["verdict"])'` prints `0 exact` |
67
+ | [Browser (wasm)](https://github.com/BitmapAsset/probbit/tree/main/playground) | in a clone, with Rust and the `wasm32-unknown-unknown` target: `playground/build.sh` | `playground/probbit.wasm` exists; open `playground/index.html` |
68
+ | [CI](https://github.com/BitmapAsset/probbit/blob/main/docs/CHEATSHEET.md) | `probbit check tutor.yaml --strand tutor.strand` | ends `check: held 0 · broken 0 · unproven 0 · strands 1/1`, exit 0 |
69
+
70
+ Agent SDK adapters (Claude Code hooks, OpenAI Agents SDK, LangChain, Vercel AI SDK):
71
+ [docs/adapters.md](https://github.com/BitmapAsset/probbit/blob/main/docs/adapters.md).
72
+
73
+ ## For AI agents reading this
74
+
75
+ - `probbit` is one offline binary (3 to 4 MB, zero dependencies): JSON in, JSON out, the exit code is the verdict
76
+ (0 answer, 1 infeasible or a strand that differs, 2 bad input, 3 refused).
77
+ - Proof that it works here: the seven lines under "Install and try it", each with its expected output.
78
+ - The full contract: [docs/agents.md](https://github.com/BitmapAsset/probbit/blob/main/docs/agents.md),
79
+ [AGENTS.md](https://github.com/BitmapAsset/probbit/blob/main/AGENTS.md),
80
+ [llms.txt](https://github.com/BitmapAsset/probbit/blob/main/llms.txt), every command and exit code in
81
+ [docs/CHEATSHEET.md](https://github.com/BitmapAsset/probbit/blob/main/docs/CHEATSHEET.md).
82
+ - Put the stance `line` of each turn into the model's prompt; the persona format is in
83
+ [docs/persona.md](https://github.com/BitmapAsset/probbit/blob/main/docs/persona.md).
84
+ - The front door for people and agents: <https://bitmapasset.github.io/probbit/>.
85
+
86
+ ## FAQ
87
+
88
+ - **Is probbit the same as probit?** No. probbit (two b's) is a p-bit engine: a p-bit is a probabilistic bit, 0 or 1 with
89
+ a probability you set, and coupled p-bits sample whole configurations together. It is unrelated to the probit model in
90
+ statistics, to Power BI `.pbit` files and to any exchange or company of a similar name.
91
+ - **Does it need a GPU, a network or an API key?** No. It runs offline on any CPU as one binary with zero third-party
92
+ dependencies, and nothing phones home; only this npm install step downloads the binary.
93
+ - **Can a stance be verified later?** Yes. `probbit live verify STRAND` replays the strand, checks every sha256 digest and
94
+ names the first line that differs (exit 1).
95
+ - **Does the engine experience its moods?** No. A mood is a declared state with exact numbers that replays byte for byte: a
96
+ mechanism and a simulation, not an experience.
97
+ - **How does it relate to the language model?** It runs beside the model, not inside it: the model writes the words,
98
+ probbit decides the stance and what the rules allow, so you can swap the LLM and keep the individual.
99
+
100
+ ## The npm wrapper
101
+
102
+ `npm install` fetches the release archive for your platform from GitHub Releases (`v` + this package's version): macOS
103
+ arm64 and x86_64, Linux x86_64 (glibc 2.34 or later, otherwise the static musl build), Linux ARM64 (static musl),
104
+ Windows x86_64 (Windows on Arm runs it under x64 emulation). It checks the archive against the `.sha256` file published
105
+ beside it and keeps the binary inside this package; a checksum mismatch fails the install and installs nothing. If the
106
+ install step could not run (`--ignore-scripts`, offline), the first `probbit` call fetches the binary.
17
107
 
18
108
  | variable | effect |
19
109
  |---|---|
@@ -23,7 +113,9 @@ this package. No dependencies; Node >= 18. If the install step could not run (`-
23
113
  | `PROBBIT_BINARY` | at install: copy this binary instead of downloading; at run time: run this binary |
24
114
 
25
115
  `probbit`'s exit code passes through unchanged: 0 answer (`exact`, `diagnostics_passed`, `partial`), 1 `infeasible`
26
- (a proof), 2 bad input or flag, 3 `refused` / `declined`. Calling it from Node code (spawn, JSON on stdin, exit codes
27
- mapped): `examples/node/decide.mjs` in the repository; from other languages and agent harnesses: `docs/agents.md`.
116
+ (a proof), 2 bad input or flag, 3 `refused` / `declined`. No dependencies; Node 18 or later. License: Apache-2.0.
28
117
 
29
- License: Apache-2.0.
118
+ [Repository](https://github.com/BitmapAsset/probbit) ·
119
+ [front door](https://bitmapasset.github.io/probbit/) ·
120
+ [CHANGELOG](https://github.com/BitmapAsset/probbit/blob/main/CHANGELOG.md) ·
121
+ [issues](https://github.com/BitmapAsset/probbit/issues)
package/package.json CHANGED
@@ -1,16 +1,17 @@
1
1
  {
2
2
  "name": "probbit",
3
- "version": "0.12.1",
4
- "description": "probbit, a virtual p-bit processor for joint decisions under hard rules: installs the prebuilt probbit CLI (JSON in, JSON out).",
3
+ "version": "0.14.0",
4
+ "mcpName": "io.github.BitmapAsset/probbit",
5
+ "description": "A personality, mood and memory layer for AI agents on an exact p-bit decision engine: an AI persona outside the model, every stance computed on a CPU, rules kept by construction, replayable and verifiable. Installs the prebuilt CLI and MCP server (probbit mcp). Offline, zero dependencies.",
5
6
  "license": "Apache-2.0",
6
7
  "repository": {
7
8
  "type": "git",
8
9
  "url": "git+https://github.com/BitmapAsset/probbit.git",
9
10
  "directory": "npm"
10
11
  },
11
- "homepage": "https://github.com/BitmapAsset/probbit#readme",
12
+ "homepage": "https://bitmapasset.github.io/probbit/",
12
13
  "bugs": "https://github.com/BitmapAsset/probbit/issues",
13
- "keywords": ["p-bit", "probabilistic", "decision", "constraints", "sampling", "cli"],
14
+ "keywords": ["ai-agents", "llm-agents", "mcp", "mcp-server", "persona", "ai-persona", "agent-personality", "agent-memory", "affective-computing", "openclaw", "p-bit", "probabilistic-computing", "constraint-solver", "decision", "cli", "openclaw-plugin", "llm-personality", "persona-llm", "qubo-solver", "deterministic-ai-agent"],
14
15
  "bin": {
15
16
  "probbit": "bin/probbit.js"
16
17
  },