Piko API

Base URL & auth

Piko is an HTTP service in front of your own OpenAI-compatible engine. It never holds a second model: the weights that answer your chat are the weights that decide. The service binds one host and port and speaks two routes over the same process.

http://127.0.0.1:8787

When the server is started with an API key, the POST routes become bearer-guarded. The refusal uses the Jev `401` shape, so an SDK parses it without changes:

Authorization: Bearer <your-key>

Quickstart

# 1. point the service at your engine, then start it
export NOTJEV_BASE_URL=http://127.0.0.1:8080
export NOTJEV_MODEL=gemma-4-12b
notjev serve --port 8787 &

# 2. wait for health
until curl -sf localhost:8787/health >/dev/null; do sleep 0.2; done

# 3. read a decision
curl -s localhost:8787/v1/decide -H 'content-type: application/json' -d '{
  "state": "The minister announced a plan on Tuesday.",
  "questions": [
    { "id": "kind", "question": "event type", "options": ["ANNOUNCE", "MEET", "VOTE"] }
  ]
}'

POST /v1/decide

The native route. One state, N questions, typed answers — a verdict, a margin and an abstention per question. All N questions share the state, so the engine's prefix cache makes the tail nearly free; the readout is still one token per question.

curl -s localhost:8787/v1/decide -H 'content-type: application/json' -d '{
  "state": "The minister announced a plan on Tuesday.\n",
  "theta": 0.5,
  "questions": [
    { "id": "kind",   "question": "event type",            "options": ["ANNOUNCE", "MEET", "VOTE"] },
    { "id": "policy", "question": "is this about policy?", "noul": { "yes": "YES", "no": "NO" } },
    { "id": "depth",  "question": "how concrete is it?",   "score": 5 }
  ]
}'

{
  "model": "gemma-4-12b",
  "theta": 0.5,
  "ms": 74,
  "results": [
    {
      "id": "kind", "kind": "choice", "choice": "ANNOUNCE", "value": "ANNOUNCE",
      "p1": 0.990, "p2": 0.008, "margin": 0.982, "band": "certain", "prior": 0.95,
      "coverage": 0.991, "degraded": false, "undecided": false, "theta": 0.5,
      "probabilities": [0.990, 0.008, 0.002],
      "options": ["ANNOUNCE", "MEET", "VOTE"],
      "ms": 25, "model": "gemma-4-12b"
    }
  ]
}

POST /v1/systemone

The Jev wire contract — the one-endpoint contract of TypeSafe's Jev and the OpenJev ecosystem. A typesafe-sdk (or anything that speaks the contract) pointed at this server works unchanged, against any engine you configure. Answers come back grouped by type.

curl -s localhost:8788/v1/systemone -H 'content-type: application/json' -d '{
  "state": "The minister announced a plan on Tuesday.",
  "questions": {
    "policy": { "type": "noul", "instructions": "is this about policy?" },
    "kind":   { "type": "choice", "instructions": "event type",
                "criteria": { "ANNOUNCE": "someone makes something public",
                              "MEET": "two parties meet",
                              "VOTE": "a ballot is held" } }
  }
}'

{
  "model": "gemma-4-12b",
  "answers": {
    "nouls": {
      "policy": { "type": "noul", "noul": 0.971, "confidence": 0.877,
        "notjev": { "margin": 0.942, "band": "certain", "coverage": 0.993, "degraded": false,
                    "undecided": false, "theta": 0.5 } }
    },
    "choices": {
      "kind": { "type": "choice", "choice": "ANNOUNCE", "confidence": 0.842,
        "probabilities": { "ANNOUNCE": 0.99, "MEET": 0.008, "VOTE": 0.002 },
        "notjev": { "margin": 0.982, "band": "certain", "coverage": 0.991 } }
    },
    "scores": {}
  },
  "usage": { "input_tokens": 142, "output_tokens": 2 }
}

GET /v1/models

Lists the configured engine and the aliases an SDK may ask for by default. They all resolve to the same engine.

{
  "object": "list",
  "data": [
    { "object": "model", "id": "gemma-4-12b" },
    { "object": "model", "id": "notjev-latest" },
    { "object": "model", "id": "jev-latest" },
    { "object": "model", "id": "jev-preview" }
  ]
}

GET /health

Liveness and the configuration the process is running with — the first thing to check before blaming a verdict.

{ "ok": true, "baseUrl": "http://127.0.0.1:8080", "model": "gemma-4-12b", "theta": 0.5 }

Question forms

There are three shapes of question, and only three. In each case you write the possible answers down first — Piko can only ever return one of them, so there is no way for it to invent a value you did not offer. That is the property that makes an answer safe to act on.

A true / false question named noul may also be sent as "type": "boolean" — the two are the same form.

The decision object

What a single question returns. Fields marked extension live in the notjev block on the wire contract — they are the instrument the contract has no room for.

Errors

Errors are named: the caller never has to guess from a stack. The 422 shape is FastAPI's, because that is what Jev clients parse.

Abstention & theta

An answer is only returned when margin ≥ theta. Under that bar, choice is null and the question stays pending — ask it again when things have changed, rather than accepting a guess. theta is the one dial worth tuning: raise it and you get fewer answers that are right more often.

Limits

Everything the service will not do, stated plainly. A refusal here is deliberate and always named in the response, never a silent guess.

Known limitations

• The numbers are provenance, not a promise. Measured latency and cost come from one card; your engine, your model and your prompt length will differ.
• Letter prior. A model may favour early letters (A over M). The repository ships a correction (NOTJEV_LETTER_PRIOR); it is off unless you set it.
• Multimodal is quantizer-dependent. The vision path has failed silently on some quantized exports (every image read the same). Verify one image before trusting a run.
• Determinism. Above a high confidence, answers are near-stable across machines; store the band, not the raw float.

Clients · cURL

curl -s localhost:8787/v1/decide \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer $NOTJEV_API_KEY' \
  -d '{"state":"…","questions":[{"id":"q","question":"…","options":["A","B"]}]}'

Clients · JavaScript

Works in Node ≥ 20, using the fetch that Node already ships.

const { createClient } = require('notjev');
const jev = createClient();          // NOTJEV_BASE_URL, NOTJEV_MODEL, NOTJEV_API_KEY, NOTJEV_THETA

const a = await jev.decide({
  state   : 'A: "Sarah Knafo"\nB: "Sarah Knafot" (seen in an audio transcript)\n',
  question: 'verdict',
  options : ['SAME', 'OTHER'],
  theta   : 0.5,
});
console.log(a.choice, a.p1.toFixed(3), a.band, a.coverage.toFixed(3));
// null 0.500 0.000 med 0.983   <- exactly torn on this pair: no verdict at theta 0.5

const b = await jev.noul('The minister announced a plan.\n', 'is this about policy?',
  { yes: 'YES', no: 'NO' });
console.log(b.value, b.p1.toFixed(3));                 // true 0.970

const s = await jev.score('The minister announced a plan.\n', 'how concrete is it?', 5);
console.log(s.value, s.expectation.toFixed(2));        // 3 3.41

Talk to the service over HTTP instead

const r = await fetch('http://127.0.0.1:8787/v1/decide', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    state: state,
    questions: [{ id: 'kind', question: 'event type', options: ['ANNOUNCE', 'MEET', 'VOTE'] }],
  }),
});
const { results } = await r.json();

Clients · Python

Nothing Python-specific is required — it is JSON over HTTP, so requests or httpx is enough:

import httpx

r = httpx.post("http://127.0.0.1:8787/v1/decide", json={
    "state": "The minister announced a plan on Tuesday.",
    "theta": 0.5,
    "questions": [
        {"id": "kind", "question": "event type", "options": ["ANNOUNCE", "MEET", "VOTE"]},
        {"id": "draft", "question": "is this a draft?", "noul": {"yes": "YES", "no": "NO"}},
    ],
})
for row in r.json()["results"]:
    print(row["id"], row["choice"], row["margin"], row["undecided"])

Running the server

notjev serve [--port 8787] [--host 127.0.0.1]
             [--base-url URL] [--model ID] [--api-key KEY] [--theta 0.5]

Two more serving surfaces exist for decisions over a conversation — a gateway and an MCP server — configured with the same NOTJEV_BASE_URL / NOTJEV_MODEL:

notjev gateway --port 8789 &   # Chat Completions proxy + /notjev/decide, /notjev/context/*
notjev mcp                      # stdio: notjev_decide, notjev_context_put, notjev_context_drop

Engines & environment variables

Engine quickstarts

As a service

notjev serve --port 8788 &         # /v1/decide AND /v1/systemone, one process
curl -s localhost:8788/v1/systemone -H 'content-type: application/json' -d '{ … }'

Playground API

The Piko web app is a thin client over a small JSON API. It is handy for demos and internal tools, and it never holds a key of its own — it forwards to your engine.

{ "ok": true, "theta": 0.5,
  "engine": { "baseUrl": "http://127.0.0.1:8080", "model": "gemma-4-12b",
              "reachable": true, "served": ["gemma-4-12b"] } }

// in
{ "state": "…", "questions": [{ "id": "q", "type": "choice", "instructions": "…", "options": ["A","B"] }] }
// out
{ "ok": true, "prompts": { "q": "Choose the correct option. Reply with only its letter.\n\nContext:\n…" } }

{ "ok": true, "model": "…", "theta": 0.5, "ms": 74, "perQuestionMs": 24.6,
  "results": [ { "id": "q", "choice": "A", "p1": 0.99, "margin": 0.98, "band": "certain",
                 "coverage": 0.99, "undecided": false, "probabilities": { "A": 0.99, "B": 0.01 } } ] }

Piko sits on the project's readout library — no second model, no hosted key, no per-call cost. The benchmark numbers quoted here come from a production judge and are provenance, not a promise about your questions.