J-Space Theater

Watch language emerge from a living swarm of model activations.

J-Space Theater is an open-source AI visual art and interpretability playground that turns hidden-state readouts from local open-weight language models into immersive typographic particle swarms.

Gallery

J-Space Contents mode

Semantic Field mode

What It Does

Type a prompt into a quiet fullscreen black interface and press Enter. The app asks a local model for a short answer, reads hidden states from selected transformer layers, projects those states through a logit-lens-style readout, and streams candidate words into the browser.

Those candidate words become a visual field:

• Words erupt from the bottom of the screen.
• Candidate terms swarm, split, roam, and regroup.
• Each generated answer word gets its own J-space frame.
• The final answer appears word by word like a collapse from the field.
• A readable "J-Space Contents" mode shows the candidate words behind each output word.

The experience is both a research interface and a generative typography instrument.

Why It Exists

Most language model interfaces hide the process behind a single text box. J-Space Theater explores a different surface: a place where internal activation readouts, candidate words, visual motion, and language generation can be watched together.

This project aims to:

• make model internals more visible without overstating what they mean
• create an accessible playground for interpretability experiments
• bridge AI research, creative coding, HCI, and digital art
• help developers experiment with hidden states and lens-based readouts
• invite better visual methods for J-space-inspired model exploration

Honesty Boundary

This project does not claim to reveal a model's private thoughts or complete reasoning. It visualizes lens-based candidate word readouts from internal activations and turns them into an artistic and exploratory interface.

It is inspired by J-space / global workspace interpretability research, but it does not claim to perfectly reconstruct hidden reasoning or implement a full Jacobian Lens method. The displayed words are candidates from selected readout methods. They can be noisy, misleading, incomplete, or visually overemphasized.

Key Features

• Local open-weight model support through Hugging Face Transformers
• Qwen3-style local runtime with selected hidden-state access
• Logit-lens-style candidate extraction from selected layers
• WebSocket streaming from model backend to browser
• Immersive WebGL / Three.js typographic particle swarm
• Clean black fullscreen interface with bottom input
• Word-by-word output generation and J-space frame labels
• Readable "J-Space Contents" mode for inspecting candidate words
• Configurable particle density, visual scale, opacity, speed, interval, and theme colors
• Mock mode for frontend visual development without loading a model
• Apple Silicon friendly first-model setup when starting with small models

Quick Start

Prerequisites

• Node.js 22 or newer recommended
• npm
• Python 3.12 recommended for local model mode
• 8GB RAM minimum for mock mode
• 16GB RAM recommended for Qwen3-1.7B local experimentation

Clone

git clone https://github.com/Cybefutu/j-space-theater.git
cd j-space-theater

Install Frontend Dependencies

npm install

Run Mock Mode

Mock mode is the fastest way to see the visual system. It does not download a model.

npm run dev

Open:

http://127.0.0.1:5173/

The combined dev command starts:

• Vite frontend on 127.0.0.1:5173
• Node WebSocket gateway on 127.0.0.1:8787/ws

Choose Mock J-space in the Runtime dropdown if it is not already selected.

Run Local Qwen Logit Lens Mode

Create a Python environment:

python3.12 -m venv .venv
source .venv/bin/activate
pip install -r python_backend/requirements.txt

Start the Python model service:

HF_HOME=.cache/huggingface \
QWEN_MODEL_ID=Qwen/Qwen3-1.7B-Base \
PYTHON_LENS_PORT=8791 \
npm run python:server

In a second terminal, start the frontend and mock gateway:

npm run dev

Open http://127.0.0.1:5173/ and choose Qwen3 local lens in the Runtime dropdown.

The first model run downloads weights from Hugging Face. Start small. Hidden-state visualization is heavier than normal text generation.

Model weights are never committed to this repository. QWEN_MODEL_ID should point to a public Hugging Face model repository such as Qwen/Qwen3-1.7B-Base; Transformers downloads the files on first run into the Hugging Face cache. Local filesystem model paths are rejected by default so the public project does not depend on private machine state. For private experiments only, set QWEN_ALLOW_LOCAL_MODEL_PATH=1.

Model Setup

Recommended models for local experimentation:

• Qwen/Qwen3-0.6B
• Qwen/Qwen3-1.7B-Base
• Qwen/Qwen3-1.7B-Instruct
• TinyLlama/TinyLlama-1.1B-Chat-v1.0
• EleutherAI/pythia-1b

The current backend is optimized around Qwen-style causal language models and Hugging Face Transformers. Other models may need tokenizer or layer-selection adjustments.

Environment variables:

JSPACE_SERVER_PORT=8787
PYTHON_LENS_BASE_URL=http://127.0.0.1:8791
PYTHON_LENS_PORT=8791
QWEN_MODEL_ID=Qwen/Qwen3-1.7B-Base
QWEN_CONTEXT_TOKENS=1024
QWEN_MAX_NEW_TOKENS=64
QWEN_READ_EVERY=3
QWEN_SELECTED_LAYERS=3,7,11,15,19,23,27
QWEN_TOP_K=10
QWEN_TEMPERATURE=0
QWEN_ALLOW_LOCAL_MODEL_PATH=0

Copy .env.example if you want a local reference file. Do not commit real tokens, local secrets, or downloaded model files.

Before publishing changes, run:

npm run release:check

This fails if git is tracking local model weights, cache folders, dependency folders, or build output.

Architecture

Prompt
  |
  v
Local LLM Runtime
  |
  v
Hidden States
  |
  v
Logit-Lens Readout
  |
  v
J-Space Word Frames
  |
  v
WebSocket Stream
  |
  v
React / Three.js Visual Swarm
  |
  v
Word-by-word Answer Collapse

Main code paths:

• Frontend app: src
• Three.js visual swarm: src/components/JSpaceScene.tsx
• Output typing layer: src/components/AnswerSurface.tsx
• WebSocket client: src/lib/stream.ts
• Browser state store: src/store/theaterStore.ts
• Mock gateway: server/index.mjs
• Mock J-space interpreter: server/jspace-interpreter.mjs
• Python logit-lens backend: python_backend/qwen_logit_lens_server.py

See docs/ARCHITECTURE.md for details.

Technical Explanation

Hidden states are intermediate vector representations inside a transformer layer. A logit lens projects those vectors through the model's language-model head to estimate which tokens are prominent at that layer.

In J-Space Theater, selected layer readouts are turned into candidate words. Those words are not literal thoughts. They are verbalizable projections from a chosen lens method at a chosen moment in generation.

The visual swarm maps candidate words, weights, groups, and output steps into motion, depth, opacity, and typography. This makes the readout easier to inspect and more expressive, but the visualization is not proof of causal reasoning.

Screenshots and Demo Media

Current screenshots live under docs/assets/:

• J-Space Contents mode
• Semantic Field mode

Future media to add:

• short GIF
• demo video
• exhibition mode recording

See docs/assets/README.md.

Example Prompts

Try:

• "What does a city dream about at night?"
• "Describe memory as weather."
• "What is hidden inside language?"
• "Explain fear in six words."
• "What does a machine see before it speaks?"

More examples are in examples/prompts.md.

Roadmap

Near-term work includes better mock mode polish, more example prompts, smoother particle performance, cleaner J-space word filtering, and better Apple Silicon setup notes.

Future directions include tuned-lens support, layer-by-layer visualization, audio-reactive visual modes, voice input, activation patching experiments, Jacobian-lens-style transport, and reproducible interpretability notebooks.

See ROADMAP.md.

Good First Issues

Useful first contribution areas:

• improve particle performance
• add model adapters
• add tuned-lens support
• improve word cleaning
• add screenshots and GIFs
• improve Apple Silicon setup
• add Docker setup
• add tests
• add layer visualization mode
• add keyboard shortcuts
• add audio-reactive effects

Contributing

We welcome contributors from AI interpretability, frontend graphics, creative coding, HCI, model serving, and open-source tooling.

Start with CONTRIBUTING.md.

Suggested GitHub Metadata

Description:

A J-space-inspired AI visual art and interpretability playground for watching hidden-state word candidates swarm and collapse into language.

Topics:

ai-interpretability
mechanistic-interpretability
j-space
logit-lens
hidden-states
llm
local-llm
generative-art
threejs
webgl
creative-coding
ai-art
model-visualization

License

MIT. See LICENSE. Please review before using in commercial or research settings.