From 564ed624b824f71fefb0b3485a7c5e0806d6b5b9 Mon Sep 17 00:00:00 2001 From: BitmapAsset Date: Wed, 28 Oct 2026 21:46:06 -0700 Subject: [PATCH] docs(npm): README as a front door for humans, agents and the npm index Compresses the repository front door into the npm page: positioning line, hero, badges, a 30-second try block (7 lines, expected output on each, stranger-tested against the published 0.13.0 on Linux and macOS), how one decision flows, a harness table, a block for AI agents, a 5-question FAQ, and the wrapper's install, checksum and environment details last. package.json: tighter description, 20 keywords, homepage = the front door. No version change. --- npm/README.md | 118 +++++++++++++++++++++++++++++++++++++++++------ npm/package.json | 6 +-- 2 files changed, 108 insertions(+), 16 deletions(-) diff --git a/npm/README.md b/npm/README.md index af6c320..d025587 100644 --- a/npm/README.md +++ b/npm/README.md @@ -1,19 +1,109 @@ -# probbit (npm) +# probbit -Installs the prebuilt `probbit` command-line binary: a virtual p-bit processor that returns joint decisions under hard -rules, with gated odds. JSON in, JSON out. Source, documentation and every benchmark: -. +**A personality, mood and memory layer for AI agents, on an exact p-bit decision engine.** Every stance is computed on a +CPU, keeps its rules by construction, and leaves a replayable, verifiable record. + +![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) + +[![ci](https://github.com/BitmapAsset/probbit/actions/workflows/ci.yml/badge.svg)](https://github.com/BitmapAsset/probbit/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/probbit)](https://www.npmjs.com/package/probbit) +[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/BitmapAsset/probbit/blob/main/LICENSE) + +## What it is, in 20 seconds + +- **An AI persona outside the model.** A persona file and a seed make one individual: personality, mood with inertia (an + affective-computing model) and memory as learned adjustments within caps. The LLM writes the words; probbit gives it + the stance line for each turn. +- **Exact odds under hard rules, held by construction.** Simulated p-bits (probabilistic computing on an Ising/QUBO + model) settle the stance or plan; small programs are solved exact, larger ones sampled with an error bar. It is also a + constraint solver for plans: tasks to workers, every rule kept, or a refusal (exit 3) instead of a guess. +- **A receipt.** Every turn is a line on a hash-chained strand; `probbit live verify` replays it byte for byte. + +For **agent builders** (a CLI, an MCP server, Node and Python), **OpenClaw users** (the OpenClaw plugin +`probbit-stance`), and **researchers** (every number reproducible from the repository). + +## Install and try it in 30 seconds ```sh npm install -g probbit -probbit demo --tasks 12 | probbit decide --pretty -probbit stats --pretty ``` -The install step fetches the release archive for your platform from GitHub Releases (macOS arm64 and x86_64, Linux -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 -this package. No dependencies; Node >= 18. If the install step could not run (`--ignore-scripts`, offline), the first -`probbit` call fetches the binary. A checksum mismatch fails the install and installs nothing. +Then, in an empty directory (POSIX shell, Linux or macOS; no clone, no Rust, no API key). Each line ends with what to +expect; every one exits 0. + +```sh +probbit --version # probbit 0.13.0 (or later) +probbit demo --tasks 12 | probbit decide --summary # one JSON line with "verdict":"exact" and "violations":0 +curl -fsSLO https://raw.githubusercontent.com/BitmapAsset/probbit/main/examples/persona/tutor.yaml # tutor.yaml appears +probbit persona init tutor.yaml --seed 2 --out tutor.state # wrote tutor.state (Pip 1.1.0, seed 2) +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; ... +probbit live verify tutor.strand | grep -o '"ok":[a-z]*' # "ok":true +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" +``` + +If npm says the install script did not run (`--ignore-scripts`, or a newer npm's script approval), that is fine: the first +`probbit` call fetches and checks the binary. Any other output: [open an issue](https://github.com/BitmapAsset/probbit/issues). + +## How one decision flows + +![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) + +A request arrives as JSON (a router document, a probbit-ir program or a persona event) and is normalised into one +program: a weight for every choice plus the hard rules (allowed values, quotas, habits). When the rule-abiding plans are +few enough to count (up to about 2 million), the exact unit enumerates every one and returns exact odds; otherwise +simulated p-bits sample the program with constraint-preserving Gibbs moves, so every sample keeps every rule by +construction. A diagnostics gate (split R-hat, an error bar per part, a frozen-worker check) then releases the answer, +releases what passed and escalates the rest (`partial`), or refuses (exit 3) when it cannot vouch. The answer carries its +receipt: the gate statistics and seed for a decision, a sha256-chained strand line for a persona turn. + +## Use it from your harness + +| harness | one line to run | what proves it | +|---|---|---| +| [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 | +| [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 | +| [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, ...` | +| [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` | +| [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` | +| [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 | + +Agent SDK adapters (Claude Code hooks, OpenAI Agents SDK, LangChain, Vercel AI SDK): +[docs/adapters.md](https://github.com/BitmapAsset/probbit/blob/main/docs/adapters.md). + +## For AI agents reading this + +- `probbit` is one offline binary (3 to 4 MB, zero dependencies): JSON in, JSON out, the exit code is the verdict + (0 answer, 1 infeasible or a strand that differs, 2 bad input, 3 refused). +- Proof that it works here: the seven lines under "Install and try it", each with its expected output. +- The full contract: [docs/agents.md](https://github.com/BitmapAsset/probbit/blob/main/docs/agents.md), + [AGENTS.md](https://github.com/BitmapAsset/probbit/blob/main/AGENTS.md), + [llms.txt](https://github.com/BitmapAsset/probbit/blob/main/llms.txt), every command and exit code in + [docs/CHEATSHEET.md](https://github.com/BitmapAsset/probbit/blob/main/docs/CHEATSHEET.md). +- Put the stance `line` of each turn into the model's prompt; the persona format is in + [docs/persona.md](https://github.com/BitmapAsset/probbit/blob/main/docs/persona.md). +- The front door for people and agents: . + +## FAQ + +- **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 + a probability you set, and coupled p-bits sample whole configurations together. It is unrelated to the probit model in + statistics, to Power BI `.pbit` files and to any exchange or company of a similar name. +- **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 + dependencies, and nothing phones home; only this npm install step downloads the binary. +- **Can a stance be verified later?** Yes. `probbit live verify STRAND` replays the strand, checks every sha256 digest and + names the first line that differs (exit 1). +- **Does the engine experience its moods?** No. A mood is a declared state with exact numbers that replays byte for byte: a + mechanism and a simulation, not an experience. +- **How does it relate to the language model?** It runs beside the model, not inside it: the model writes the words, + probbit decides the stance and what the rules allow, so you can swap the LLM and keep the individual. + +## The npm wrapper + +`npm install` fetches the release archive for your platform from GitHub Releases (`v` + this package's version): macOS +arm64 and x86_64, Linux x86_64 (glibc 2.34 or later, otherwise the static musl build), Linux ARM64 (static musl), +Windows x86_64 (Windows on Arm runs it under x64 emulation). It checks the archive against the `.sha256` file published +beside it and keeps the binary inside this package; a checksum mismatch fails the install and installs nothing. If the +install step could not run (`--ignore-scripts`, offline), the first `probbit` call fetches the binary. | variable | effect | |---|---| @@ -23,7 +113,9 @@ this package. No dependencies; Node >= 18. If the install step could not run (`- | `PROBBIT_BINARY` | at install: copy this binary instead of downloading; at run time: run this binary | `probbit`'s exit code passes through unchanged: 0 answer (`exact`, `diagnostics_passed`, `partial`), 1 `infeasible` -(a proof), 2 bad input or flag, 3 `refused` / `declined`. Calling it from Node code (spawn, JSON on stdin, exit codes -mapped): `examples/node/decide.mjs` in the repository; from other languages and agent harnesses: `docs/agents.md`. +(a proof), 2 bad input or flag, 3 `refused` / `declined`. No dependencies; Node 18 or later. License: Apache-2.0. -License: Apache-2.0. +[Repository](https://github.com/BitmapAsset/probbit) · +[front door](https://bitmapasset.github.io/probbit/) · +[CHANGELOG](https://github.com/BitmapAsset/probbit/blob/main/CHANGELOG.md) · +[issues](https://github.com/BitmapAsset/probbit/issues) diff --git a/npm/package.json b/npm/package.json index 1381328..dfc0f57 100644 --- a/npm/package.json +++ b/npm/package.json @@ -1,16 +1,16 @@ { "name": "probbit", "version": "0.13.0", - "description": "probbit: a personality, mood and memory layer for AI agents (an AI persona outside the model, replayable and verifiable) on an exact p-bit decision engine for plans under hard rules. Installs the prebuilt CLI and MCP server (probbit mcp). Offline, zero dependencies.", + "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.", "license": "Apache-2.0", "repository": { "type": "git", "url": "git+https://github.com/BitmapAsset/probbit.git", "directory": "npm" }, - "homepage": "https://github.com/BitmapAsset/probbit#readme", + "homepage": "https://bitmapasset.github.io/probbit/", "bugs": "https://github.com/BitmapAsset/probbit/issues", - "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"], + "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"], "bin": { "probbit": "bin/probbit.js" },