semif-api

An HTTP API around SemIf (consumed as a library — no fork), with two serving backends, plus a browser UI with self-learning game demos: an agent plays a platformer and a puzzle room by asking the model to decide, and rewrites its own rules from a transcript of failures.

Two ways to score a decision:

• torch — loads an HF causal LM (ROCm build); the softmax over your declared options is read from logits. No decoding.
• llama — talks to llama-server hosting a GGUF; same readout over the server's candidate probabilities. This backend also serves /plan.

Quickstart

nix develop            # ROCm torch (gfx1151), transformers, fastapi, uvicorn

# torch (default model Qwen/Qwen3.5-4B):
.venv/bin/python -m uvicorn semif_api.app:app --host 127.0.0.1 --port 8321

# or llama (default server http://127.0.0.1:8080, alias Qwen3.5-4B):
SEMIF_BACKEND=llama .venv/bin/python -m uvicorn semif_api.app:app --host 127.0.0.1 --port 8321

Open http://127.0.0.1:8321/ui/ — a request builder for /decide and /decide-batch, plus four demo tabs (platformer and puzzle room, each in ruled and self-learning variants).

Layout

• semif-api/ — the FastAPI package (endpoints, web UI as package data)
• docs/usage.md — API walkthrough · docs/games.md — demo design · docs/llama-backend.md — GGUF backend configuration
• examples/ — decision fixtures and reference outputs
• tests/ — offline suites (JS prompt/game tests, Python backend tests)
• scripts/validate.sh — full GPU-host validation (upstream tests, CLI scoring, drift compare, HTTP parity)
• flake.nix — builds upstream semif, semif-api, a dev shell, and a nixosModule

Tests

node --test "tests/**/*.cjs"
.venv/bin/python -m unittest discover -s tests -p 'test_llama*.py'

NixOS module

services.semif-api = {
  enable = true;
  backend = "llama";          # or "torch"
  llamaUrl = "http://127.0.0.1:8080";
  llamaModel = "Qwen3.5-4B";  # any alias served by llama-server
};

Options: backend, host (127.0.0.1), port (8321), model, revision, user, openFirewall, maxTokens, and the llama* settings in docs/llama-backend.md.

Notes

• Developed and measured on an AMD Strix Halo APU (gfx1151); the nixpkgs pin reflects where prebuilt gfx1151 torch is available.
• Batch shape changes bf16 results (upstream-documented); GPU work serializes per request and only batches within /decide-batch.