J-Space Local

J-Space Local is a local-first macOS desktop application for fitting, applying, and exploring Jacobian Lenses on open-weight decoder language models.

It implements the average-Jacobian method from Anthropic's Jacobian Lens reference implementation: capture residual-stream activations, transport them into a target-layer basis with a fitted average input-output Jacobian, then use the selected model's final normalization and unembedding to rank vocabulary readouts.

The result approximates what an activation is disposed to make a model verbalize across the fitting contexts. It is not a transcript of reasoning, proof of a concept's presence, ground-truth semantics, or evidence of subjective experience.

Status

The text-model application is implemented through packaging. The current Apple Silicon .app owns a frozen authenticated backend, inspects local safetensors models before loading, validates versioned lenses, applies the actual Jacobian method, renders an interactive layer × position matrix, tracks exact ranks for pinned tokens, saves private sessions, exports JSON/CSV/PNG, and fits resumable lenses from explicit local corpora.

The package is ad-hoc signed for local integrity, not Developer ID signed or notarized. The locally cached openbmb/MiniCPM5-1B BF16 checkpoint at revision 4e9de7a0778dc1c362e983e6858f0e77542cbdca has been inspected, loaded, fitted, reapplied, and manually checked in the exact release .app without a download. That evidence applies only to this pinned checkpoint; generic decoder-family support remains experimental. VLM product support is not claimed.

Release evidence is recorded in the acceptance audit and dated test report. The pinned upstream review is in REFERENCE_AUDIT.md, and the truthful checkpoint table is in docs/compatibility.md.

For day-to-day use, start with the user guide. The dated test report records the exact release checks and their limits. Planned work is tracked in the roadmap, and publishing notes define the GitHub and Hugging Face release boundaries.

The native release screenshot shows the pinned 1.08B-parameter checkpoint and its exact-fingerprint fitted lens running inside J-Space Local.app. The actual-model row ranks Paris first; the fitted layer-0-to-1 lens is intentionally a one-prompt acceptance artifact, not evidence of interpretability quality.

This second screenshot is the broader production React/D3 matrix exercised against the offline deterministic Qwen3-shaped fixture. It demonstrates the multi-layer rendered product state; the random fixture tokens do not carry interpretability meaning.

Requirements

• Apple Silicon Mac running macOS 14 or later for the packaged app
• A local Hugging Face-compatible decoder checkpoint with safetensors weights
• A compatible .jlens directory, or a local corpus from which to fit one
• For development: Python 3.12 via uv, Node 22+, pnpm 11+, Rust/Cargo, and Xcode command-line tools

Models, lenses, and corpora are not bundled and are never downloaded implicitly. Keep them in any local folders you control and select them explicitly.

Build and open the packaged app

From a clean checkout:

cd backend
uv sync --extra dev --frozen

cd ../apps/desktop
pnpm install --frozen-lockfile

cd ../..
./scripts/build-desktop.sh
./scripts/test-package.sh
open "apps/desktop/src-tauri/target/release/bundle/macos/J-Space Local.app"

The application is written to:

apps/desktop/src-tauri/target/release/bundle/macos/J-Space Local.app

The local build is ad-hoc signed. It passes strict codesign integrity checks but is not notarized, so a quarantined copy may be blocked by Gatekeeper. For a copy you trust, use Finder's Open context-menu action and the normal macOS confirmation flow; do not disable Gatekeeper globally. See docs/packaging.md for the sidecar design, package audit, app-data location, size, signing, and platform limitations.

Use the app

1. Choose a local model folder. Inspect it before enabling weight loading, then select device and dtype.
2. Choose a compatible .jlens folder and inspect its identity, dimensions, checksum, and compatibility state.
3. Enter a prompt, review its model tokenization, select fitted layers and token positions, and run analysis.
4. Hover or select matrix cells to inspect bounded top-k vocabulary results. Pin up to five token IDs for exact full-vocabulary ranks, trajectories, and the rank heatmap.
5. Save the complete result locally or export versioned JSON, normalized CSV, or the visible matrix as PNG.

The actual model-output row is visually distinct from fitted-lens rows. Long prompts use a selectable 16/32/64-token window rather than mounting an unbounded matrix.

Fit a local lens

Fitting is an advanced, potentially slow and memory-intensive workflow. Its quality depends on the checkpoint, corpus, source and target layers, valid positions, and sample count. Start with a preflight estimate and a small corpus. The desktop's Fit lens · Experimental workspace accepts a local UTF-8 .txt, local .jsonl, pasted lines, or the bundled deterministic test corpus; it never scrapes or downloads data.

The CLI exposes the same runner:

cd backend
mkdir -p /absolute/path/to/output
uv run jspace-local fit \
  --model /absolute/path/to/model \
  --corpus-file /absolute/path/to/prompts.txt \
  --output-dir /absolute/path/to/output \
  --name my-lens \
  --layers 0,4,8 \
  --target-layer 12 \
  --max-seq-len 128 \
  --prompts 100 \
  --dim-batch 8 \
  --skip-first 16 \
  --checkpoint-every 1 \
  --seed 0 \
  --device cpu \
  --dtype float32 \
  --preflight-only

Remove --preflight-only to run. Add --test-prompt "A short local test" to load and immediately apply the completed lens. Ctrl-C requests cancellation between backward passes and preserves only complete prompts in an atomic checkpoint. Resume with the identical model, selected corpus, layer/configuration parameters, and seed plus --resume; mismatches are rejected.

CLI inspection and application

The offline diagnostic generates a deterministic tiny Qwen3-shaped Transformers fixture, fits real Jacobians, saves/reloads a safe lens, and applies it:

cd backend
uv sync --extra dev --frozen
uv run jspace-local smoke

Apply to explicit local paths:

uv run jspace-local inspect-model /absolute/path/to/model
uv run jspace-local inspect-lens /absolute/path/to/lens.jlens \
  --model /absolute/path/to/model
uv run jspace-local apply \
  --model /absolute/path/to/model \
  --lens /absolute/path/to/lens.jlens \
  --prompt "Your prompt" \
  --device cpu \
  --dtype float32

Loading is local-only, requires safetensors model weights, and always sets trust_remote_code=False.

For a user-supplied built-in causal-decoder checkpoint, run the separate opt-in validation without any download. The expected identity defaults to Qwen3:

cd backend
uv run python ../scripts/validate-qwen-model.py \
  --model /absolute/path/to/Qwen3-checkpoint \
  --expected-weights-sha256 <recorded-64-hex-fingerprint> \
  --device cpu \
  --dtype float32

Add --lens /absolute/path/to/compatible.jlens to validate application. Add --fit-output /existing/output/directory to perform the deliberately expensive one-prompt fit/reapply check. The script rejects unexpected identities, remote-code-only checkpoints, over-one-billion-parameter models (unless explicitly overridden), incompatible lenses, and fingerprint mismatches.

For another built-in Transformers causal architecture, explicitly add --expected-model-type and --expected-architecture; use --allow-larger only after reviewing the local memory and fitting cost. The MiniCPM5-1B acceptance run used llama, LlamaForCausalLM, CPU BF16, and exact config/weights fingerprints recorded in docs/compatibility.md.

Development and tests

Run the desktop with an automatically owned development backend:

./scripts/dev.sh

Do not start the API separately. The desktop binds Vite and the backend only to explicit IPv4 loopback addresses.

Run the verification layers:

./scripts/test-backend.sh
./scripts/test-frontend.sh
./scripts/test-integration.sh
./scripts/test-package.sh

Build components independently with ./scripts/build-sidecar.sh and ./scripts/build-desktop.sh; remove generated artifacts with ./scripts/clean.sh. The regular suite and package smoke use forced offline mode and do not require model downloads.

Troubleshooting

• Backend startup fails: use the visible retry action and read the bounded diagnostic. A release build must retain Contents/Resources/binaries/jspace-sidecar/; rerun ./scripts/build-desktop.sh if it is missing.
• Gatekeeper blocks the app: the repository build is not notarized. Use the normal Finder Open confirmation only for a bundle you built or otherwise trust.
• Model is rejected before load: verify config.json, local tokenizer files, and safetensors weight shards are complete. Remote-code-only architectures are intentionally unsupported.
• Lens is incompatible: compare model ID/revision, configuration fingerprint, architecture, hidden size, layer count, vocabulary size, and lens tensor dimensions. Do not bypass an incompatible state.
• Fitting is too slow or runs out of memory: reduce prompt count, sequence length, selected source layers, or dimension batch; CPU is the safest baseline. Keep the checkpoint and resume with the exact same configuration.
• A saved session cannot rerun: reopened results remain readable when model/lens paths moved. Relocate and load compatible artifacts, then use the saved configuration for a new run.

Privacy and security

Prompts, corpora, model weights, activations, checkpoints, lenses, results, sessions, and exports remain on the local machine. Inference, application, and fitting make no required network requests and need no hosted-model API key. The backend binds an ephemeral 127.0.0.1 port, authenticates every product route with a new per-launch secret, limits request sizes, and stops with the desktop process.

New lenses use JSON plus safetensors. Legacy pickle-backed PyTorch lenses are warning-gated, loaded on CPU with weights_only=True, and never treated as fully identified. See docs/api.md, docs/architecture.md, and docs/lens-format.md.

Roadmap and boundaries

The next priorities are a signed and notarized macOS distribution, stronger named-checkpoint evidence, and evaluation of deeper multi-prompt lenses. VLM and cross-platform work remain gated on architecture- and platform-specific acceptance tests. See ROADMAP.md for release stages and exit criteria.

License and attribution

J-Space Local is licensed under Apache 2.0. See LICENSE, NOTICE, docs/attribution.md, the generated THIRD_PARTY_NOTICES.md, and the bundled exact-text collection THIRD_PARTY_LICENSES.md.