Metadata-Version: 2.4
Name: percept-video
Version: 0.1.1
Summary: Percept — neuro-engagement scoring client for the TRIBE v2 endpoint. Score any video 0–100 against a brain-response model.
Author: Dean Barrow
License: MIT License
        
        Copyright (c) 2026 Percept
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Deanbarrow10/pika-plugin
Project-URL: Source, https://github.com/Deanbarrow10/pika-plugin
Keywords: video,engagement,neuro,tribe,pika,fmri,evaluation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# Percept — a Pika plugin

> **The measurement layer Pika is missing.** Every Pika skill *generates* a video.
> This plugin tells you whether it will actually **land** — and then makes it
> better on its own.

Percept scores any video with Meta/FAIR's **TRIBE v2** brain model
(a population-average cortical-response predictor) and turns that into a
decision-ready **0–100 neuro-engagement score**, a per-second attention curve,
four cognitive channel traces, and the single weakest beat to fix. A second skill
wraps that score in an **automatic generate → score → fix → re-score loop**, so a
Pika video improves itself with a neural reward signal and no human in the inner
loop.

It's a drop-in: download the folder, point it at a TRIBE v2 endpoint, and the two
skills appear to the Pika agent.

---

## Why this exists (the gap)

Pika's skill library is entirely **generative** — `ugc-ads`, `app-sizzle`,
`founder-product-video`, `viral-hook`, … all end at *"here's your video."* There
is **no skill that evaluates or optimizes** a video (searching Pika's own skill
registry for "score / evaluate / will this perform / brain response" returns
nothing). So creators ship blind: no signal on what works, no loop to improve it.

This plugin closes that loop.

| | Before | With Neuro-Eval |
|---|---|---|
| After generating | "Looks good?" 🤷 | `61/100`, weak at 0:11–0:14, LANG dip |
| Picking a cut | gut feel | A/B scored, winner by margin |
| Improving | re-prompt and hope | auto loop, score climbs each round |

---

## What's in the box

```
pika-plugin/
├── skills/
│   ├── neuro-eval/SKILL.md       # score a video → engagement report
│   └── neuro-optimize/SKILL.md   # auto loop: generate → score → fix → re-score
├── server/
│   ├── engagement.py             # TRIBE v2 cortical tensor → 0–100 engagement
│   ├── server.py                 # FastAPI /score + /health
│   └── requirements.txt
├── colab/
│   ├── percept_tribev2_server.ipynb   # host TRIBE v2 on a free T4 + public tunnel
│   └── _build_notebook.py             # regenerates the notebook from server/
├── client/
│   └── percept_eval.py          # stdlib CLI: score / A-B a video locally
└── .env.example
```

---

## Setup (≈5 min)

### 1. Host the brain model (Colab, free T4)
TRIBE v2 needs a GPU, so the weights live on Colab — not on the Pika host.

1. Open `colab/percept_tribev2_server.ipynb` in Google Colab.
2. `Runtime → Change runtime type → T4 GPU`.
3. Optional: add a Hugging Face read token to Colab **Secrets** as `HF_TOKEN`
   after accepting access to `meta-llama/Llama-3.2-3B`. Without one, the server
   uses TRIBE's ungated video pathway instead of failing. The notebook downloads
   and verifies V-JEPA2 before accepting requests, bypassing the `hf-xet` stall
   observed during real T4 testing.
4. Run all cells. The last cell prints:
   ```
   NEURO_API_URL = https://<random>.trycloudflare.com
   NEURO_API_KEY = <generated secret>
   ```
   Keep that cell running — it *is* your live endpoint.

### 2. Point the plugin at it
```bash
cp .env.example .env     # then paste in NEURO_API_URL + NEURO_API_KEY
export NEURO_API_URL=https://<random>.trycloudflare.com
export NEURO_API_KEY=<secret>
curl -s "$NEURO_API_URL/health"      # {"ready": true, "cuda": true, ...}
```

`TRIBEV2_TEXT_MODE` controls the gated language path:

- `auto` (default): use text when authorized; retry with the configured ungated
  modalities on failure.
- `off`: reliable ungated scoring for any user.
- `required`: require WhisperX + LLaMA and return a clear diagnostic if unavailable.

`TRIBEV2_MODALITIES` controls the ungated base path:

- `video` (Colab default): one public 4.14 GB V-JEPA2 encoder; most reliable on T4.
- `video,audio`: also download/use the 2.32 GB Wav2Vec-BERT encoder.

The notebook pins the tested TRIBE v2 Git revision, logs the API to
`/content/neuro-server.log`, and exposes authenticated `/diagnostics`. A failed
score prints the exact stage, hint, diagnostics, and log tail instead of only
`HTTPError: 500`.

### Debugged Colab failure

The original HTTP 500/hang had four independent causes:

1. Colab retained a Torchaudio build with a different Torch ABI.
2. dependency resolution replaced TRIBE's exact NumPy 2.2.6 pin.
3. `/health` reported ready before the lazily loaded V-JEPA2 encoder was present.
4. `hf-xet` transferred roughly 3 GB, then deadlocked after a CDN request failed,
   leaving `/score` blocked until its 30-minute client timeout.

The notebook now pins the compatible Torch/Torchaudio/NumPy stack, downloads
V-JEPA2 before server startup via resumable `curl`, verifies its exact byte size
and SHA-256, and defaults to video-only TRIBE inference so Wav2Vec-BERT is not a
hidden 2.32 GB dependency. A real T4 run completed `/score` and a three-candidate
plateau loop using one reused clip.

### 3. Install the skills into Pika
Drop `skills/neuro-eval` and `skills/neuro-optimize` into your Pika plugins source
(the same place the official `Pika-Labs/Pika-Plugins` skills load from). The Pika
agent will then discover them via `search_skill` ("score this video",
"make this video better", …).

---

## Use it

**Score (quick check, no Pika needed):**
```bash
pip install percept-video
percept myclip.mp4
percept cutA.mp4 cutB.mp4    # A/B → names a winner
```

**In Pika (natural language):**
- *"Score this video"* → runs **neuro-eval**, returns the report.
- *"Make this ad more engaging"* → runs **neuro-optimize**, iterates until the
  score plateaus, returns the winning clip + the score history.

---

## The score, briefly
TRIBE v2 predicts average cortical response on the fsaverage5 surface. We read
four engagement families off the Glasser/HCP-MMP atlas — **auditory, language,
attention, visual** — and measure their activation relative to the full cortex
at each timestep. The canonical `adScore` is a transparent weighted sum: 55%
TRIBE cortical features, 30% OpenCV production features, and 15% YOLO
semantic/composition features. Every response includes raw values, normalized
subscores, weights, and contributions. Every upload is normalized to at most
three seconds. The weakest weighted features and explicit generator instruction
become the reward feedback for a maximum-five-iteration Pika optimization loop.

It is a **prediction of population-average response**, not a measurement of any
individual viewer and not a sales guarantee — a strong, fast, directional signal
for the inner loop, with an optional human panel to confirm the final pick.

## Provenance
The scoring math is ported from Percept's production TRIBE v2 worker; this plugin
packages it as a standalone, Pika-installable evaluation + optimization layer.
Model: [`facebook/tribev2`](https://huggingface.co/facebook/tribev2).

> **License note:** the plugin code and bundled YOLO/OpenCV path are separate
> from the TRIBE v2 weights. Meta publishes TRIBE v2 under CC-BY-NC-4.0.
> Commercial ad-scoring use requires permission compatible with that license.
