ZooWork - Instinct model

An open decision-model family from the ZooWork team at Serendipity One Inc.

Models on Hugging Face · Hosted API · API documentation

Instinct turns shared context and typed questions into distributions over fixed candidates. It supports binary judgments, categorical choices and ordered scores without generating text. All three models are open on Hugging Face, share the same typed API, and return zero generated output tokens.

Model family

The first two models use unchanged Qwen weights and add inference-time decision readouts. instinct-tuned-4b publishes ZooWork's fine-tuned checkpoint. This GitHub repository provides the shared request contract, reference runtime, examples and serving utilities.

Capabilities

• Noul — a yes/no proposition returned as P(yes) in [0, 1].
• Choice — a distribution over 2–16 named candidates, plus the selected candidate and confidence.
• Score — a distribution over 2–16 ordered levels and their probability-weighted expected level.
• Shared state — ask several independent questions about the same string, object or array in one request.
• Zero text generation — responses contain structured answers and report output_tokens: 0.
• Inspectable outputs — the lower-level API exposes probabilities, predictions, raw candidate logits and prompt-token counts.

Measured results

Reporting-only results on all 231 published JevBench tasks:

All reported runs completed 231/231 items. These are public-set diagnostics—not held-out scores, official full-suite ranks, or full JevBench Intelligence and Calibration scores. The public subset has no judge tier and was consulted during development.

Latency is warmed, serial serving latency excluding public Internet, TLS and gateway overhead; the 27B and dual-4B values pool three complete passes, while tuned-4B's p95 is an estimate from its measured 62 ms direct-upstream p50 and observed end-to-end tail spread, not an SLO.

For the open tuned model, the split is easy 48/48, standard 69/72 and hard 81/111. See its release notes and the 27B recipe notes for artifact-specific conditions.

Installation

Python 3.10 or newer and a CUDA GPU with BF16 support (Ampere or newer) are required for inference. instinct-tuned-4b downloads about 8.5 GB of weights from Hugging Face on first use and runs on a single 24 GB GPU; the 27B reference needs about 54 GB (see reference/qwen3.8-27b). The flash-linear-attention Triton kernels are compiled on first use, so the environment also needs a C compiler; slim images without gcc (for example the pytorch/pytorch:*-runtime tags) install fine but fail on the first forward pass with Failed to find C compiler.

The simplest environment is an NGC PyTorch container, which ships a matched torch, CUDA and compiler. Install on top of it and keep its torch: the gpu extra accepts NGC's 2.8.0a0 builds, so pip leaves them in place.

docker run --gpus all --shm-size=8g -it \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  nvcr.io/nvidia/pytorch:25.06-py3

git clone https://github.com/SerendipityOneInc/instinct.git
cd instinct
pip install -e ".[gpu]"

Layer execution is pinned to transformers==5.16.1. The runtime refuses other versions unless INSTINCT_ALLOW_UNVERIFIED_TRANSFORMERS=1 is set. flash-linear-attention==0.5.2 and fla-core==0.5.2 provide the Qwen3.5 linear-attention kernels.

Local inference

CLI

instinct-decide --model instinct-tuned-4b \
  models/instinct-tuned-4b/examples/request.json

To reproduce the frozen 27B instinct recipe locally:

instinct-decide --model reference-qwen3.8-27b \
  reference/qwen3.8-27b/examples/request.json

The first run downloads the weights; later runs load them from the Hugging Face cache. The output for the example request is checked in as examples/expected.json, produced on an H200. Other GPUs give the same choices with probabilities that can differ in the second decimal place (see the canary note in the model README).

Use --weights <local-directory-or-hf-repo> to override the recipe's weight location.

Python

from instinct import InstinctModel, answer

model = InstinctModel.from_pretrained("instinct-tuned-4b")
result = answer(model, {
    "state": {"customer": "My package says delivered but it is not here."},
    "questions": {
        "escalate": {
            "type": "noul",
            "instructions": "Is human support required?",
        },
        "urgency": {
            "type": "score",
            "instructions": "How urgent is this?",
            "criteria": ["Not urgent", "Somewhat urgent", "Urgent", "Critical"],
        },
    },
})

print(result["answers"])

Reference HTTP server

instinct-serve --model instinct-tuned-4b --port 8008
curl -s http://127.0.0.1:8008/v1/systemone \
  -H 'Content-Type: application/json' \
  --data @models/instinct-tuned-4b/examples/request.json

The local server exposes POST /v1/systemone and GET /health, binds to 127.0.0.1 by default, and serves one model request at a time. It is a reference server without authentication, TLS or rate limiting; do not expose it directly to an untrusted network. Request bodies are limited to 8 MiB and 64 questions.

Hosted API

ZooWork operates the production Instinct API. Create an API key and explore the model family at instinct.zoowork.ai; the current authentication, model and usage contract is documented at instinct.zoowork.ai/docs.

Hosted API pricing

These are serving prices for ZooWork's managed API, not licenses or usage fees for the open weights. Running the models yourself does not use the hosted API billing plan.

export INSTINCT_API_KEY='your-key'

curl https://api.zoowork.ai/v1/systemone \
  -H "Authorization: Bearer ${INSTINCT_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "instinct-tuned-4b",
    "state": "The payment service is down for all customers.",
    "questions": {
      "outage": {
        "type": "noul",
        "instructions": "Is the payment service experiencing an outage?"
      },
      "team": {
        "type": "choice",
        "instructions": "Which team should respond?",
        "criteria": {
          "engineering": "Technical service failures",
          "billing": "Invoice questions"
        }
      }
    }
  }'

The hosted product offers all three model IDs behind the same typed API. The repository artifacts currently cover tuned-4B and the frozen 27B recipe as described above; consult the live API documentation for current availability and pricing.

Request and response contract

Request

Criteria by question type:

• noul: optional {"true": "...", "false": "..."} descriptions;
• choice: an object mapping 2–16 candidate IDs to descriptions;
• score: a list of 2–16 ordered level descriptions.

Unknown request or question fields are rejected.

Response

{
  "answers": {
    "outage": {
      "type": "noul",
      "noul": 0.98
    },
    "team": {
      "type": "choice",
      "choice": "engineering",
      "probabilities": {
        "engineering": 0.97,
        "billing": 0.03
      },
      "confidence": 0.81
    }
  },
  "usage": {
    "input_tokens": 312,
    "output_tokens": 0
  }
}

The values above illustrate the response shape; exact probabilities and token counts depend on the request and runtime. Noul returns P(yes). Choice returns the arg-max candidate, the complete candidate distribution and confidence. Score returns the level distribution and its expected zero-based level. Probabilities are rounded to six decimal places.

How it works

For each question, the selected recipe:

1. renders the shared state, instructions and candidate rubric into a deterministic prompt;
2. assigns one single-token label (A, B, …) to each candidate;
3. runs the model once per configured option order;
4. reads the candidate-label logits at the final prompt position;
5. applies the recipe temperature (per question type when the recipe sets temperature_by_type) and a softmax;
6. maps probabilities back to the caller's candidate IDs and averages configured orders.

instinct-tuned-4b uses one option order and applies only the candidate LM-head rows to the full-depth, final-norm hidden state. Its temperature is 2.80 for choice and score and 0.50 for noul; the lower noul temperature sharpens P(yes) without changing any prediction. The prompt bytes are part of the trained model contract: changing instinct/prompt.py can change the model's output.

Testing and contributing

pip install -e ".[test]"
pytest -q

Issues and pull requests are welcome; see CONTRIBUTING.md. Changes to prompt rendering require matching canary evidence. Report security issues privately through GitHub security advisories; see SECURITY.md.

Citation

@software{instinct2026,
  title   = {Instinct: An Open Decision-Model Family},
  author  = {{ZooWork Team, Serendipity One Inc.}},
  year    = {2026},
  version = {0.1.0},
  url     = {https://github.com/SerendipityOneInc/instinct},
  note    = {Models: instinct, instinct-dual-4b, instinct-tuned-4b}
}

License

The code in this repository is released under the Apache License 2.0. Copyright 2026 Serendipity One Inc. See NOTICE.

The vLLM-derived serving files are also Apache-2.0; see serving/vllm/LICENSE and serving/vllm/NOTICE. Model weights are distributed separately under the license stated on their respective model cards.

References

• Reflex — an open implementation of typed, candidate-scored decision models.
• JevBench — the public benchmark used for the diagnostic results above.
• Qwen — the open model family behind the Instinct models.
• vLLM — the serving engine used by the optional optimized path.