{"_id":"@blahai/lens","_rev":"3-76a0622b23bd57fb4122b355e9f5ff77","name":"@blahai/lens","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@blahai/lens","version":"1.0.0","keywords":["interpretability","jacobian-lens","logit-lens","evals","llm","conformance"],"license":"MIT","_id":"@blahai/lens@1.0.0","maintainers":[{"name":"thomasdavis","email":"thomasalwyndavis@gmail.com"}],"homepage":"https://evals.blah.dev/docs/lens","bugs":{"url":"https://github.com/thomasdavis/blah.dev/issues"},"bin":{"blah-lens":"dist/cli.js"},"dist":{"shasum":"719c5fa64cddb224256fe7f8d02d7f763cd3325c","tarball":"https://registry.npmjs.org/@blahai/lens/-/lens-1.0.0.tgz","fileCount":26,"integrity":"sha512-191ENHxafrE1bjemrxOH+vuVL2YD6RwMd0n7iZL+u9FP4wQR7IpkTgXcDoK3dacya5bEqDX4EdFl8cKHfVxshg==","signatures":[{"sig":"MEYCIQD3dbn/5gzplgtCRBh0tyBviAo1XGTHpgkGy9zsIBsDwAIhANM1hKxX6lnPY9hS1lPvpm4h2Yw4jbElzLrMfdOqI6W5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":117579},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./runtime":{"types":"./dist/runtime.d.ts","default":"./dist/runtime.js"},"./manifest":{"types":"./dist/manifest.d.ts","default":"./dist/manifest.js"},"./protocol":{"types":"./dist/protocol.d.ts","default":"./dist/protocol.js"},"./validate":{"types":"./dist/validate.d.ts","default":"./dist/validate.js"},"./safetensors":{"types":"./dist/safetensors.d.ts","default":"./dist/safetensors.js"}},"gitHead":"403616b7598b54b9440e2e147052cda308e4c95d","private":false,"scripts":{"cli":"node --experimental-strip-types src/cli.ts","lint":"eslint --max-warnings 0 --cache --cache-location node_modules/.cache/eslint/","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","test:watch":"vitest","check-types":"tsc --noEmit","prepublishOnly":"rm -rf dist && tsc -p tsconfig.build.json"},"_npmUser":{"name":"thomasdavis","email":"thomasalwyndavis@gmail.com"},"repository":{"url":"git+https://github.com/thomasdavis/blah.dev.git","type":"git","directory":"packages/blah-lens"},"_npmVersion":"10.9.8","description":"BLAH Lens Bundle v1 — stack-neutral interoperability format and conformance validator for model-internals analysis on evals.blah.dev","directories":{},"_nodeVersion":"22.23.0","dependencies":{"zod":"^3.25.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.39.1","vitest":"^3.0.0","typescript":"5.9.2","@types/node":"^22.15.3","@repo/eslint-config":"workspace:*","@repo/typescript-config":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/lens_1.0.0_1785625073628_0.514278686739468","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@blahai/lens","version":"1.1.0","keywords":["interpretability","jacobian-lens","logit-lens","evals","llm","conformance"],"license":"MIT","_id":"@blahai/lens@1.1.0","maintainers":[{"name":"thomasdavis","email":"thomasalwyndavis@gmail.com"}],"homepage":"https://evals.blah.dev/docs/lens","bugs":{"url":"https://github.com/thomasdavis/blah.dev/issues"},"bin":{"blah-lens":"dist/cli.js"},"dist":{"shasum":"e124e9fa0a28844234578c37425dea06d98f064d","tarball":"https://registry.npmjs.org/@blahai/lens/-/lens-1.1.0.tgz","fileCount":26,"integrity":"sha512-0+bsRreE6oZfYfDTitQnof+RI9iVxwW+Nj8zpAcK/tinKsw+fvvLqoQaebX9qbZsY6JKW8Y0U3JYzJC7K9I7dg==","signatures":[{"sig":"MEYCIQC3c5a2ZAVx3xlO6w4vQ1CeUE6S08T7K5E3tOjE8Ok5yAIhAPymoTlGSDLa3VW3SXXqFAXcxwdmEkqdJSucVnv3uxKf","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":129465},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./runtime":{"types":"./dist/runtime.d.ts","default":"./dist/runtime.js"},"./manifest":{"types":"./dist/manifest.d.ts","default":"./dist/manifest.js"},"./protocol":{"types":"./dist/protocol.d.ts","default":"./dist/protocol.js"},"./validate":{"types":"./dist/validate.d.ts","default":"./dist/validate.js"},"./safetensors":{"types":"./dist/safetensors.d.ts","default":"./dist/safetensors.js"}},"gitHead":"82315fe60a38aa75398e227f12097680ed031e7b","private":false,"scripts":{"cli":"node --experimental-strip-types src/cli.ts","lint":"eslint --max-warnings 0 --cache --cache-location node_modules/.cache/eslint/","test":"vitest run --passWithNoTests","build":"tsc -p tsconfig.build.json","test:watch":"vitest","check-types":"tsc --noEmit","prepublishOnly":"rm -rf dist && tsc -p tsconfig.build.json"},"_npmUser":{"name":"thomasdavis","email":"thomasalwyndavis@gmail.com"},"repository":{"url":"git+https://github.com/thomasdavis/blah.dev.git","type":"git","directory":"packages/blah-lens"},"_npmVersion":"10.9.8","description":"BLAH Lens Bundle v1 — stack-neutral interoperability format and conformance validator for model-internals analysis on evals.blah.dev","directories":{},"_nodeVersion":"22.23.0","dependencies":{"zod":"^3.25.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.39.1","vitest":"^3.0.0","typescript":"5.9.2","@types/node":"^22.15.3","@repo/eslint-config":"workspace:*","@repo/typescript-config":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/lens_1.1.0_1785626027162_0.3916751141579695","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@blahai/lens","version":"1.2.0","type":"module","private":false,"description":"BLAH Lens Bundle v1 — stack-neutral interoperability format and conformance validator for model-internals analysis on evals.blah.dev","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./manifest":{"types":"./dist/manifest.d.ts","default":"./dist/manifest.js"},"./protocol":{"types":"./dist/protocol.d.ts","default":"./dist/protocol.js"},"./safetensors":{"types":"./dist/safetensors.d.ts","default":"./dist/safetensors.js"},"./validate":{"types":"./dist/validate.d.ts","default":"./dist/validate.js"},"./runtime":{"types":"./dist/runtime.d.ts","default":"./dist/runtime.js"}},"scripts":{"check-types":"tsc --noEmit","lint":"eslint --max-warnings 0 --cache --cache-location node_modules/.cache/eslint/","test":"vitest run --passWithNoTests","test:watch":"vitest","cli":"node --experimental-strip-types src/cli.ts","build":"tsc -p tsconfig.build.json","prepublishOnly":"rm -rf dist && tsc -p tsconfig.build.json"},"dependencies":{"zod":"^3.25.0"},"devDependencies":{"@repo/eslint-config":"workspace:*","@repo/typescript-config":"workspace:*","@types/node":"^22.15.3","eslint":"^9.39.1","typescript":"5.9.2","vitest":"^3.0.0"},"bin":{"blah-lens":"dist/cli.js"},"license":"MIT","keywords":["interpretability","jacobian-lens","logit-lens","evals","llm","conformance"],"homepage":"https://evals.blah.dev/docs/lens","repository":{"type":"git","url":"git+https://github.com/thomasdavis/blah.dev.git","directory":"packages/blah-lens"},"publishConfig":{"access":"public"},"engines":{"node":">=20"},"main":"./dist/index.js","types":"./dist/index.d.ts","_id":"@blahai/lens@1.2.0","gitHead":"75ca7f82d03e50154fed68dd1c033f4145ffc967","bugs":{"url":"https://github.com/thomasdavis/blah.dev/issues"},"_nodeVersion":"22.23.0","_npmVersion":"10.9.8","dist":{"integrity":"sha512-F5xl5eVCFivqOh4C8mhN04a8lyLL8Pqm/JtNS2uWaN2lG5JrhhmQlZckxs4o8AgyNs/6QlTj7wDfRWDoY+Lm0A==","shasum":"9b78f411e50e00508fa384a91f1aee3bcae964b1","tarball":"https://registry.npmjs.org/@blahai/lens/-/lens-1.2.0.tgz","fileCount":26,"unpackedSize":136430,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAsksqfxtt1oihbMswxG5DGtv7cgYutT0iUkMtV1Ed8jAiAt71rsmQiWLANgF6+D/9amviSnFUyiq+ynT3WkAGSqYw=="}]},"_npmUser":{"name":"thomasdavis","email":"thomasalwyndavis@gmail.com"},"directories":{},"maintainers":[{"name":"thomasdavis","email":"thomasalwyndavis@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/lens_1.2.0_1785634978564_0.2964196314452714"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-01T22:57:53.463Z","modified":"2026-08-02T01:42:58.861Z","1.0.0":"2026-08-01T22:57:53.773Z","1.1.0":"2026-08-01T23:13:47.329Z","1.2.0":"2026-08-02T01:42:58.712Z"},"bugs":{"url":"https://github.com/thomasdavis/blah.dev/issues"},"license":"MIT","homepage":"https://evals.blah.dev/docs/lens","keywords":["interpretability","jacobian-lens","logit-lens","evals","llm","conformance"],"repository":{"type":"git","url":"git+https://github.com/thomasdavis/blah.dev.git","directory":"packages/blah-lens"},"description":"BLAH Lens Bundle v1 — stack-neutral interoperability format and conformance validator for model-internals analysis on evals.blah.dev","maintainers":[{"name":"thomasdavis","email":"thomasalwyndavis@gmail.com"}],"readme":"# @blahai/lens\n\n**BLAH Lens Bundle v1** — the stack-neutral interoperability format for\nmodel-internals analysis on [evals.blah.dev](https://evals.blah.dev), and the\nconformance validator for it.\n\n```\nBundle format:    blah-jacobian-lens (version 1)\nRuntime protocol: blah-lens-http/1\nHF library tag:   blah-jlens\n```\n\nNothing here is named after or coupled to any model framework, and nothing here\nexecutes model code. A bundle produced by PyTorch, JAX, MLX, Candle, Rust, Zig or\na bespoke TypeScript engine is indistinguishable to the consumer.\n\n## Validate a bundle\n\n```bash\nnpx @blahai/lens validate ./dist/blah-lens\nnpx @blahai/lens validate --hf your-org/model-name-jlens --revision <sha>\nnpx @blahai/lens validate-runtime --url http://localhost:8000 \\\n  --manifest ./dist/blah-lens/lens-manifest.json\n```\n\nExit codes: `0` pass, `1` fail, `2` partial, `64` usage error. `--json <file>`\nwrites the full report; `--quiet` prints only the verdict.\n\nThis is the same validator evals.blah.dev runs when a bundle is imported, so a\nbundle cannot pass here and be rejected there. If you would rather not install\nanything, the platform exposes it over HTTP:\n\n```bash\ncurl -sX POST https://evals.blah.dev/api/v1/lens/validate \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"lens_repo\":\"your-org/model-name-jlens\",\"lens_revision\":\"<sha>\"}'\n```\n\n## Applying a transport\n\nA Jacobian describes change, not absolute state, so the honest application is\naffine:\n\n```\ntransported = target_mean + (h_s - source_mean_s) @ transpose(J_s)\n```\n\nDeclare `lens.centering.mode: \"affine\"` with a `target_mean_key` and a\n`source_mean_key` per site; the validator then requires those tensors and checks\ntheir shapes. Uncentred application stays available and is warned about.\n\nDeclare which derivative you fitted in `lens.estimator_kind`:\n\n| kind | meaning |\n|---|---|\n| `same_position` | `d target[t] / d site[t]` — what a token-aligned grid shows |\n| `lagged` | `d target[t+lag] / d site[t]` — influence on a later position |\n| `future_integrated` | summed over all later positions — downstream influence, **not** a prediction at `t` |\n\nFor `same_position` and `lagged`, also declare how the position-diagonal was\nisolated. This is not bookkeeping: a vector-Jacobian product with the cotangent\ninjected at every target position at once returns `sum over u >= t` of the\nper-position derivatives, so the batched backward fits `future_integrated` while\nproducing a matrix indistinguishable from a correct diagonal fit.\n\n```json\n\"diagonal_estimator\": { \"method\": \"isolated\" }\n\"diagonal_estimator\": { \"method\": \"hutchinson\", \"probes\": 32, \"seed\": 0 }\n```\n\n`isolated` is one backward per target position, sliced at the matching source\nposition — exact, at T passes per direction. `hutchinson` carries Rademacher\nsigns on the position index so cross-position terms cancel in expectation,\ngiving an unbiased diagonal in one pass; the off-diagonal mass becomes variance\nfalling as `1/sqrt(probes)`, which can flip the argmax of a top-1 readout, so\nthe probe count is required and low-margin readouts should be treated as\nundetermined.\n\n## What it checks\n\nThe manifest schema encodes the mistakes that produce plausible-looking but wrong\nreadouts, and rejects them:\n\n- a transport whose output width is not the target width — the stored convention\n  is `J[output_dimension, input_dimension]`, so a silent transpose is caught\n- a site claiming `logit_lens_supported` from an incompatible width, which would\n  require inventing an implicit projection\n- a mutable branch name where an immutable commit SHA belongs\n- `grid_compatible` asserted alongside sites that are not token-aligned\n- duplicate site IDs or orders, which would make grid rows ambiguous\n- `remote_http` execution without a runtime URL, or `oci` without an image digest\n- affine centering declared without the mean tensors it requires\n\nSafetensors headers are read directly, without a tensor library, and over ranged\nrequests where the reader supports them — validating a multi-gigabyte transport\ncosts kilobytes. Pickle and other executable serializations are rejected.\n\nRuntime conformance exercises what production actually calls, so a server cannot\npass validation and then behave differently when the UI connects. It catches\nstreams that never terminate, `meta` arriving after results, readouts attributed\nto undeclared sites, out-of-order top-k ranks, a runtime serving a different\ncheckpoint than the bundle was fitted on, and a runtime that retokenizes a\nsequence it was asked to replay verbatim.\n\n## Library\n\n```ts\nimport { validateBundle, directoryReader, LensManifest } from \"@blahai/lens\";\n\nconst report = await validateBundle(directoryReader(\"./dist/blah-lens\"));\nif (report.status !== \"pass\") console.error(report.checks.filter((c) => c.status === \"fail\"));\n```\n\nSubpath exports: `@blahai/lens/manifest`, `/protocol`, `/safetensors`,\n`/validate`, `/runtime`.\n\n## Producing a bundle\n\nThe author guide, a copy-paste prompt for a coding agent, and JSON Schemas for\nthe manifest and protocol:\n\n- https://evals.blah.dev/docs/lens\n- https://evals.blah.dev/lens/agent-prompt.txt\n- https://evals.blah.dev/lens/manifest.schema.json\n- https://evals.blah.dev/lens/protocol.schema.json\n\n## Byte-level vocabularies\n\nA byte token such as `0xC3` is not valid UTF-8 and has no faithful JSON string.\nSend its bytes alongside the display form; `bytes_base64` is authoritative\nwherever present.\n\n```json\n{ \"id\": 195, \"text\": \"<0xC3>\", \"bytes_base64\": \"ww==\" }\n```\n\n## Scope\n\nThis is a readout instrument. It is not a sparse autoencoder, and a\nlayer-to-readout Jacobian is not by itself evidence about global workspaces,\nbroadcast or ignition — those need interventions and a control model. Describe\nwhat you publish accordingly.\n\nMIT.\n","readmeFilename":"README.md"}