LocalJev

# LocalJev

A local, Jev-compatible `POST /v1/systemone` API written in TypeScript for
[Bun](https://bun.sh/), backed by DiffusionGemma through an OpenAI-compatible
Chat Completions endpoint.

The defaults target:

- inference server: `http://127.0.0.1:8000`
- model: `diffusiongemma-26B-A4B-it-4bit`
- LocalJev API: `http://127.0.0.1:8080`

## Why a bridge is needed

[Jev](https://typesafe.ai/) uses a typed decision API rather than an OpenAI chat API.
[OpenJev](https://github.com/razorback16/openjev) implements the Jev wire protocol and
obtains probabilities with a special one-step DiffusionGemma **structured read**. Its
backend depends on unmerged vLLM request extensions such as
`diffusion_seed_canvas`, `diffusion_read_only`, and requested token logprobs.

The normal oMLX API does not expose those primitives. LocalJev therefore takes the
portable approach:

1. translate `state` and typed Jev questions into a classification prompt;
2. ask DiffusionGemma for a JSON probability scalar/vector;
3. validate the complete result and retry malformed output;
4. normalize vectors and calculate Jev-compatible choices, expected scores, and
   entropy-based confidence;
5. return the normal Jev response shape.

This is wire-compatible, but not mathematically equivalent to OpenJev's logit read.
The probabilities are generated/self-reported by the model rather than read directly
from its logits. Evaluate their calibration on your own workload before relying on
them for consequential decisions.

## Run with oMLX

Requires Bun 1.2+ and a running oMLX server.

```sh
bun install
cp .env.example .env
$EDITOR .env # replace the upstream API-key placeholder
bun run start
```

Bun loads `.env` automatically. Alternatively, set the key in your shell before
starting the server:

```fish
# fish
se