Install
One command. No dependencies, no network at runtime, about 0.65 ms per read.
npx skills add https://github.com/valencefly/valence
Or clone it and run it; there is nothing to build.
# clone and watch it discriminate
git clone https://github.com/valencefly/valence valence
cd valence
node bin/valence.mjs demo
Use it from the shell
Three reads, recorded when the site was built and checked against the data on every rebuild.
$ scripts/valence read "the build failed and the oncall page fired"
compartment sign <- aversive appetitive -> z
a1 + │██▏ +0.57
b'1 + ▎│ -0.06
b'2 + ▎██│ -0.59
b1 + │██▎ +0.59
b2 + │████ +1.09
g3 + ▌████│ -1.20
g4 + ▉██│ -0.78
g5 + ██│ -0.54
CA 0 │█▋ +0.42
a'1 - █│ -0.29
a'2 - │█▉ +0.49
a'3 - ▋██│ -0.70
a2 - │█▊ +0.46
a3 - │██▎ +0.60
g1 - ▎█│ -0.32
g2 - ▍███│ -0.92
scalar ▉│ -0.0792 (appetitive - aversive)
KC sparsity: 446/4064 active = 10.97% APL iterations: 8
$ scripts/valence read --json '{"pnl":-0.42,"latency_ms":812}'
compartment sign <- aversive appetitive -> z
a1 + │███▏ +0.84
b'1 + ▋██│ -0.70
b'2 + ▉███│ -1.05
b1 + │███▌ +0.94
b2 + │██████▎ +1.70
g3 + ▍████│ -1.18
g4 + ▍██│ -0.63
g5 + ▊█│ -0.47
CA 0 │████▎ +1.13
a'1 - ▏██████│ -1.67
a'2 - ▊██│ -0.72
a'3 - ▏█████│ -1.39
a2 - │█▎ +0.32
a3 - │████▊ +1.28
g1 - │█▏ +0.30
g2 - ▉███│ -1.04
scalar │█ +0.0952 (appetitive - aversive)
KC sparsity: 512/4064 active = 12.60% APL iterations: 8
$ echo "some agent state" | scripts/valence read --raw
{
"compartments": [
"CA",
"a'1",
"a'2",
"a'3",
"a1",
"a2",
"a3",
"b'1",
"b'2",
"b1",
"b2",
"g1",
"g2",
"g3",
"g4",
"g5"
],
"valence": [
0,
-1,
-1,
-1,
1,
-1,
-1,
1,
1,
1,
1,
-1,
-1,
1,
1,
1
],
"valenceStrength": [
0,
0.6585,
0.9013,
0.9618,
0.5814,
0.9843,
0.9928,
0.6051,
0.9964,
0.9493,
0.9743,
0.7268,
0.3348,
0.7956,
0.9483,
0.9762
],
"readout": [
-0.21014084294339208,
1.4235751850405907,
0.504213671460711,
-0.15787550463841007,
-0.7336208241868762,
-0.2383325670923828,
-0.38794246787612463,
-0.4401512800492261,
-0.6655724242497418,
-0.5052443665753525,
-0.4826156584497767,
4.237169306743741,
0.892537132411855,
-0.04635605739028418,
1.2326308742042802,
1.6288268199009823
],
"scalar": -0.2892151935025283,
"appetitive": -0.0015128645994993695,
"aversive": 0.89619210800714,
"kcActive": 589,
"kcRate": 0.14493110236220472,
"mode": {
"projection": "linear",
"sparsify": "apl",
"aplWeights": "real",
"kcMbon": "real",
"kcMbonShuffle": 0
}
}
scripts/valence demoThree snapshots, three texts, and where the layer fails on purpose.scripts/valence gatesEvery arm, green and red, exit codes checked.scripts/valence infoProvenance: every query, every row count, the valence table.scripts/valence fit rows.jsonA per-channel scale from a JSON array of snapshots.
Use it from Node
read returns the same 10 fields the CLI prints with --raw.
import { read, fitScale, applyScale } from './src/valence.mjs';
const out = read('deploy succeeded, all tests green');
out.readout; // one z-score per compartment, against the null distribution
out.scalar; // appetitive minus aversive
out.compartments; // the compartment names, in readout order
out.valence; // the sign of each compartment
out.kcRate; // the fraction of Kenyon cells active on this read
out.kcTotal; // how many there are, so nothing downstream hard-codes it
compartments- The names, in the order every array uses: CA, a'1, a'2, a'3, a1, a2, a3, b'1, b'2, b1, b2, g1, g2, g3, g4, g5 .
valence- The sign per compartment: 0, -1, -1, -1, 1, -1, -1, 1, 1, 1, 1, -1, -1, 1, 1, 1 .
valenceStrength- How lopsided each compartment's dopamine input is.
readout- One z-score per compartment.
scalar- Appetitive minus aversive, strength weighted.
appetitive,aversive- The two halves of the scalar.
kcActive,kcRate- Kenyon cells active on this read, count and fraction.
mode- Which projection, sparsifier and weights ran.