Blame for DETAILS.md

# JEVision — fast image-aware decisions

## License and commercial use

**Noncommercial use:** available under [CC BY-NC-SA 4.0](LICENSE), subject to attribution and share-alike requirements. **Commercial use requires a separate license.**

**Permanent commercial license: US$1,000 per model**, as a one-time payment for this model's released revision. Models are licensed separately; this payment does not cover other models on the account.

<p align="center">
  <a href="https://buymeacoffee.com/penecho"><img src="https://img.shields.io/badge/BUY_US_A_COFFEE-FFDD00?style=for-the-badge&amp;logo=buymeacoffee&amp;logoColor=000000" alt="Buy us a coffee"></a>
  <a href="COMMERCIAL-LICENSE.md"><img src="https://img.shields.io/badge/COMMERCIAL_LICENSE_TERMS-087f83?style=for-the-badge" alt="Read commercial license terms"></a>
</p>

Select USD and include **`heack/JEVision`**, your Hugging Face username, and the licensee's name in the payment message. This grants self-hosted commercial use, not a hosted API subscription. Prior valid licenses and upstream third-party rights remain unaffected.



JEVision reads **images and text**, evaluates the candidate answers you supply, and returns probabilities. It uses a Qwen3.5-4B-Base visual encoder, a trained LoRA adapter, a pointer head, and an optimized W8A8 inference engine. This release is checkpoint **step 7000**. It supports visual classification and decisions without generating a long text response.

**Approximately 0.4 seconds per request on the measured workload:** warm local inference on an RTX 5060 Ti 16 GB measured a median of **356 ms**, P95 **408 ms**, and maximum **427 ms** over 100 replay requests containing 1,563 judgments. 89/100 completed within 400 ms and 100/100 within 500 ms. These figures exclude model loading, network latency, and queueing; input size, question count, hardware, and concurrent workloads affect speed.

## Evaluation

The 2026-10-06 engine evaluation used 900 labeled states and 2,423 questions. This is an internal mixed-domain evaluation, not a public leaderboard or an independent audit. Sketch labels include teacher-generated silver labels; photo labels include VQA human consensus and teacher labels; text includes deterministic tasks.

| Slice | Optimized engine accuracy |
|---|---:|
| All questions | 94.14% |
| Sketch | 87.28% |
| Photo | 93.81% |
| Text | 100.00% |

The original implementation also scored 94.14% overall. Across the separate 100-request replay, decision agreement with the original implementation was 98.72%; numerical results are not bit-identical. See [evaluation.json](evaluation.json) for aggregate measurements and source-report provenance. The replay inputs are not included because they contain application activity.

## Package and requirements

The adapter and pointer head are included. The upstream base model is downloaded separately at pinned revision `1001bb4d826a52d1f399e183466143f4da7b741b`. The model requires the included custom code; a generic text-generation pipeline does not implement its image-conditioned decision head.

The optimized path requires Linux, an NVIDIA CUDA GPU, PyTorch, Triton, and compatible inference dependencies. Validation target: RTX 5060 Ti 16 GB, PyTorch 2.9.1 with CUDA 13.0, Transformers 5.17.0. The public Dockerfile pins the tested PyTorch base and installs the release dependencies; no private runtime image is required. Other devices and platforms have not been verified for this release.

## Usage

The verified setup is Docker on Linux (or Docker Desktop with NVIDIA GPU support on Windows). Download this repository and build the public runtime:

```bash
hf download heack/JEVision --local-dir jevision
cd jevision
docker build -t jevision-local .
docker run --rm -v "$PWD:/release" -w /release jevision-local download_base.py --root /release/data
docker run --rm --gpus all -v "$PWD:/release" -w /release jevision-local example.py --root /release/data --checkpoint /release
```

These shell commands use Linux/WSL syntax. They download the pinned upstream base once; retain the `data` directory between runs. The model file download requires sufficient additional disk space. The initial build and CUDA/kernel initialization take several minutes.

The default example creates red, blue, and green images and checks that changing the image changes the selected answer. It writes timing and probabilities to `verification.json`. Initialization and kernel preparation happen once; keep the loaded engine alive for repeated requests.

For your own image:

```bash
docker run --rm --gpus all -v "$PWD:/release" -w /release jevision-local \
  example.py --root /release/data --checkpoint /release --image photo.png --question "Which animal is visible?" --choices cat,dog,bird
```

Images are resized by the processor within the trained bound (200,704 pixels). Questions and candidate descriptions matter. Probabilities indicate model preference, not guaranteed correctness. The color smoke test validates the image input path; it does not independently establish the full evaluation scores.

## Fresh usage verification (2026-10-21)

The exact packaged `example.py`, adapter, head, and custom code passed on an RTX 5060 Ti in an isolated container using the existing `penecho/judge-runtime:20261006-engine-v3` runtime (image ID `sha256:05fe98a3f656219e9cd919828061df81128855f664e9c4c39bf9cb514043a339`). All nine color-image checks passed; warm median latency was 40.9 ms for these simple images, and first initialization took 214.8 seconds. This small synthetic test is distinct from the approximately 0.4-second application workload above. See [verification.json](verification.json). A second independent check built the included Dockerfile from the public, digest-pinned PyTorch base and installed `requirements.txt` from the package registry. All nine checks also passed in that clean environment, with warm median 44.0 ms and initialization 237.3 seconds. See [verification-clean.json](verification-clean.json). Both temporary verification containers were automatically removed.

## Attribution

Base: [Qwen3.5-4B-Base](https://huggingface.co/Qwen/Qwen3.5-4B-Base). The pointer-head serialization and architecture derive from [Kev](https://huggingface.co/jaredpalmer/kev-4b), at the revision recorded in `training/judge/config.json`. Preserve applicable upstream Apache-2.0 notices. The publisher’s model contribution is licensed for noncommercial use; upstream Apache-2.0 rights remain unchanged.