lumma-fev

Run FrontiersMind Lumma-Fev decision models: give a document (the state) and typed questions, and get a probability distribution for every question in one forward pass. No text is generated, so there is nothing to parse.

• lumma_fev.load(): run a model locally (cuda, mps or cpu).
• lumma-fev-serve: a TypeSafe-compatible HTTP API (POST /v1/systemone), so existing TypeSafe clients work by changing their base URL.
• lumma_fev.Client: a small client for that API.

Models (pass the Hub id or the short size to load() and --model):

Install

pip install lumma-fev              # local inference and the client
pip install "lumma-fev[serve]"     # plus the API server
pip install "lumma-fev[large]"     # plus accelerate, for device_map="auto" (27B on several GPUs)
pip install "lumma-fev[images]"    # plus Pillow and torchvision, for image states (27B)

Run locally

import lumma_fev

model = lumma_fev.load()           # FrontiersMind/lumma-fev-0.1b; load("FrontiersMind/<repo>", revision=...) for others

answers = model.decide(
    state="I was charged twice for my March invoice. Please refund one of them.",
    questions={
        "billing": {"type": "noul", "instructions": "Is this about billing?"},
        "team": {"type": "choice", "instructions": "Which team should handle this?",
                 "criteria": {"billing": "Payments and refunds", "shipping": "Delivery problems", "technical": "Bugs and outages"}},
        "urgency": {"type": "score", "instructions": "How urgent is this?",
                    "criteria": ["can wait", "this week", "today"]},
    },
)
# {"billing": {"noul": 0.97}, "team": {"choice": "billing", "confidence": ..., "probabilities": {...}},
#  "urgency": {"score": ..., "confidence": ..., "legend": [...], "probabilities": {...}}}

load(model, revision=None, device=None, dtype=None, device_map=None) picks cuda, then mps, then cpu. The default dtype is fp32 on cpu (bf16 there is emulated: about 4x slower), bf16 on CUDA GPUs with native bf16 (compute capability 8.0+, e.g. A100, L4, H100) and on mps, and fp16 on older CUDA GPUs (T4, V100). Models over 10B parameters (27B) stay bf16 on cpu so they do not double in memory. The sizes up to 9B also load with transformers alone: AutoModel.from_pretrained("FrontiersMind/lumma-fev-0.1b", trust_remote_code=True).

Lumma-fev-27B

model = lumma_fev.load("27b")                        # one GPU with about 55 GB free (an 80 GB card)
model = lumma_fev.load("27b", device_map="auto")     # or spread over several GPUs (pip install "lumma-fev[large]")

model.decide("My integration keeps failing. Please help.",
             {"team": {"type": "choice", "instructions": "Which team should handle this request?",
                       "criteria": {"billing": "Charges and refunds", "support": "Technical integration errors",
                                    "sales": "Questions about buying a product"}}})
# {"team": {"type": "choice", "choice": "support", "confidence": 0.99..., "probabilities": {...}}}

model.decide("What is shown?", {"red": {"type": "noul", "instructions": "Is the product red?"}},
             images=["photo.png"])                   # paths, PIL images or data: URLs (pip install "lumma-fev[images]")

27B uses a different checkpoint format from the smaller sizes (a Qwen3.5 backbone plus a readout over answer codes); load() detects it from the repo's decision_config.json, and the call and the answers are the same. Its prompt follows the AutoJev reference code bundled in the repo, so probabilities match it. A question plus the state must fit in 8,192 tokens (nothing is truncated: longer input raises ValueError), and score questions need at least two levels. 27B was trained on noul and choice questions only, so check score answers on your own data. For speed, install the optional flash-linear-attention and causal-conv1d kernels; without them transformers falls back to slower PyTorch code.

Lumma-fev-0.1B-v2 (0.1b-v2, lumma-fev >= 0.4) uses the same readout format on the text-only Nandi-Mini-150M backbone: a plain-text prompt (no chat template, no images), causal attention, and a 2,048-token limit per question plus state. Its backbone ships custom modeling code, which load() runs with trust_remote_code=True.

Serve an API

lumma-fev-serve --model FrontiersMind/lumma-fev-0.1b --host 0.0.0.0 --port 8000
lumma-fev-serve --model 27b --host 0.0.0.0 --port 8000                 # add --device-map auto for several GPUs

Endpoints: POST /v1/systemone, GET /v1/models, GET /health. Requests run one at a time. With 27B, a request may also carry "images": [...], up to four base64 PNG, JPEG or WebP data: URLs.

curl -s localhost:8000/v1/systemone -H 'content-type: application/json' -d '{
  "state": "I was charged twice. Please fix this ASAP.",
  "questions": {"billing": {"type": "noul", "instructions": "Is this ticket about billing?"}}
}'
# {"model": "lumma-fev-latest", "answers": {"billing": {"noul": 0.98}}, "usage": {"input_tokens": 31, "output_tokens": 9}}

Call it from Python

from lumma_fev import Client

with Client("http://127.0.0.1:8000", api_key=None) as client:
    print(client.decide("I was charged twice.", {"billing": {"type": "noul", "instructions": "Is this about billing?"}}))
    print(client.models())

client.system_one(...) returns the full response (model, answers, usage); errors raise lumma_fev.LummaFevError with the HTTP status and detail.

The TypeSafe SDK works against the same server:

from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient(api_key="local", base_url="http://127.0.0.1:8000") as ts:
    result = ts.system_one(state="I was charged twice.", questions={"billing": Noul(instructions="Is this about billing?")})
    print(result.nouls["billing"].noul)

The SDK always sends an API key; any value works when the server has no --api-key.

Questions and answers

state and instructions can be text or any JSON value. Each question reads the state and its own instructions and options only, so questions never influence each other. Up to 9B, long states are truncated to the model's context (see the model card); 27B rejects input over 8,192 tokens instead.

License

Apache-2.0. See LICENSE and NOTICE.