---
title: Claw Brain
emoji: 🧠
colorFrom: gray
colorTo: green
sdk: gradio
app_file: app.py
python_version: "3.11"
suggested_hardware: a10g-large
pinned: false
license: cc-by-nc-4.0
short_description: TRIBE v2 cortical-response simulation for gameplay content
---

# CLAW/BRAIN

A Hugging Face Space for exploratory analysis of predicted average-subject cortical responses to gameplay video and audio using [Meta TRIBE v2](https://huggingface.co/facebook/tribev2).

The Space intentionally skips automatic speech transcription. TRIBE's upstream demo invokes WhisperX through `uvx`, which adds another multi-gigabyte ASR stack and gated text encoder. Gameplay video and audio remain enabled; text-derived features are treated as missing.

The upstream `tribev2` Python package is vendored in this repository, with its original license preserved in `TRIBEV2_LICENSE`. Hugging Face ZeroGPU currently builds with Python 3.10 while upstream package metadata declares Python 3.11; the inference sources used here are Python 3.10-compatible. The bundled `exca` wheel only relaxes its `Requires-Python` metadata to 3.10; its code is otherwise unchanged.

## What the Space reports

- **Response intensity:** RMS magnitude of the predicted cortical pattern, normalized within the uploaded clip.
- **Pattern shift:** timestep-to-timestep change in the predicted cortical pattern.
- **Response persistence:** smoothed response-intensity trajectory.
- **Hemisphere balance:** descriptive difference between absolute left- and right-hemisphere response.
- Optional alignment with gameplay markers such as reward cues, near misses, wins, and round transitions.

These metrics are descriptive model outputs. They are not measurements of dopamine, addiction, emotion, attention, or a specific player's physiology. Those outcomes require a consented calibration dataset and independent validation.

## Space setup

1. Create a **Gradio Space** and upload this directory.
2. Choose GPU hardware. `A10G Large` or stronger is recommended; CPU inference is not practical for normal use.
3. In **Settings → Secrets**, add `HF_TOKEN` containing a read-scoped Hugging Face token.
4. Optional: enable persistent storage. Model and feature caches use `/data/clawbrain-cache` when it is writable.

Do not commit a Hugging Face token to this repository.

## Gameplay event CSV

The optional event file has this schema:

```csv
time_s,event,category
8.5,reward cue,reward
11.0,near miss,reward
15.2,win reveal,reward
```

## Local development

Python 3.11 and a CUDA-capable environment are recommended.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
huggingface-cli login
python app.py
```

Run the lightweight analysis tests without loading TRIBE:

```bash
pip install numpy pandas plotly pytest
pytest -q
```

## Licensing and validation

TRIBE v2 is released under **CC BY-NC 4.0**. A commercial Clawbuster deployment requires separate permission from the model owner. Physiological calibration data also requires informed consent, privacy controls, retention limits, and an explicit harm-prevention policy.