OpenJev

# OpenJev

Open source System One–style decision engine inspired by [TypeSafe Jev](https://docs.typesafe.ai).

Give it **state** and typed **questions** — get structured answers (choice, score, or probability), not free-form text.

OpenJev uses a **parallel sampler**:

1. **Fixed answer space** — no free-form text generation  
2. **Each option scored independently** against the same state  
3. **Scores normalized** (logit → softmax) into a probability distribution  
4. **All questions run in parallel** (`Promise.all`)

## Tutorial

Watch the walkthrough:

**https://youtu.be/xtXq279B4Go**

[](https://youtu.be/xtXq279B4Go)

## Quick start

```bash
cd OpenJev
npm install
cp .env.example .env   # add OPENAI_API_KEY (or another provider key)
npm run dev
```

Open **http://localhost:3001**

| Field    | Example                            |
|----------|------------------------------------|
| mode     | `parallel` (default) or `oneshot`  |
| model    | `gpt-4o-mini`, `qwen-3.8-27b`, …   |
| base url | provider base, or empty for OpenAI |
| api key  | optional if set in `.env`          |

```bash
export OPENAI_API_KEY=sk-...
npm run dev
```

## Why parallel mode is more reliable

| Mode | Behavior | Failure mode |
|------|----------|--------------|
| **parallel** (default) | One tiny `{"p": 0–1}` call **per option**, then softmax | Rare — each call is tiny and constrained |
| **oneshot** | One big structured JSON for all questions | Model drops keys, invents labels, invalid JSON |

Example: choice with 4 options → 4 parallel micro-calls. Score with 4 levels → same. Noul → 1 call. Questions themselves also run in parallel.

## API

```http
POST /api/evaluate
Content-Type: application/json
```

```json
{
  "state": "Charged twice again!! Second month in a row.",
  "mode": "paralle