wave-server (DEPRECATED)

This repository is superseded by wave-engine --serve. The wave-engine now includes a built-in OpenAI-compatible server that uses the training forward pass directly — eliminating the training/inference mismatch bugs that plagued this separate implementation. See wave-engine for the unified binary.

# New way (correct — uses training forward pass):
cargo build --release --features serve
wave-engine --serve --resume checkpoint.bin --bpe tokenizer.json --port 8080

# Old way (deprecated — reimplemented forward pass with known mismatches):
wave-server checkpoint.bin data/input.txt --port 8080

---

Historical README below for reference.

wave-server (historical)

OpenAI-compatible API server for wave-engine models. Load a trained checkpoint, serve it via HTTP, optionally accumulate wave memory across conversations. Any chat UI that speaks the OpenAI protocol connects without modification.

Part of the Wave Coherence as a Computational Primitive research project.

Quick Start

# Build
cargo build --release

# Serve a model (WCHK checkpoint — self-describing, no config flags needed)
wave-server checkpoint.bin data/input.txt --port 8080

# Serve with BPE tokenizer (no data file needed)
wave-server checkpoint.bin --bpe tokenizer.json --port 8080

# Serve with wave memory (accumulates experience across conversations)
wave-server checkpoint.bin data/input.txt --memory memory.kwmf --port 8080

# Serve with API key authentication
wave-server checkpoint.bin data/input.txt --port 8080 --api-key sk-your-secret-key

# Test
curl http://localhost:8080/health
curl http://localhost:8080/v1/models
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'

Examples

Step 1: Train a model with wave-engine

You need a trained checkpoint first. In the wave-engine repo:

cargo run --release -- data/input.txt --layers 4 --iters 200
# Produces: checkpoint.bin

Step 2: Serve it

# Character-level model (uses the same data file for vocabulary)
cargo run --release -- checkpoint.bin data/input.txt --port 8080

# BPE model (uses tokenizer.json instead of data file)
cargo run --release -- checkpoint.bin --bpe data/tokenizer.json --port 8080

The server reads the model architecture from the checkpoint header (WCHK format) — no need to specify layers, dimensions, or any config flags.

Step 3: Test it

# Health check
curl http://localhost:8080/health

# Generate text
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Tell me about the ocean"}],"max_tokens":100}'

# Stream tokens in real-time
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":64,"stream":true}'

Step 4: Connect a chat UI

Point any OpenAI-compatible chat application to http://localhost:8080/v1:

• LM Studio — Override Base URL → http://127.0.0.1:8080/v1
• Open WebUI — Settings → Connections → add http://127.0.0.1:8080/v1
• SillyTavern / continue.dev — API base URL → http://127.0.0.1:8080/v1

With API key protection

# Start server with auth
cargo run --release -- checkpoint.bin data/input.txt --port 8080 --api-key sk-my-secret-key

# Requests now require the key
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-my-secret-key" \
  -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'

With wave memory (experience accumulation)

# First run — creates fresh memory file
cargo run --release -- checkpoint.bin data/input.txt --memory memory.kwmf --port 8080

# Model accumulates experience across conversations.
# Stop and restart — memory persists in the .kwmf file.
# The model weights never change, only the memory file grows.

Features

Feature	Status	Description
OpenAI-compatible API	✓	/v1/chat/completions, /v1/models, /health
SSE streaming	✓	Real-time token-by-token streaming
KV-cache	✓	Cached phase angles and value projections for harmonic attention
BPE tokenizer	✓	HuggingFace tokenizer.json format
Wave memory	✓	Persistent experience accumulation across conversations (.kwmf)
Bearer token auth	✓	Optional --api-key for /v1/* endpoints
GPU acceleration	✓	Optional --features gpu for wgpu matmul acceleration
WCHK + KCHK checkpoints	✓	Native wave-engine format + legacy kerr-engine compatibility
LM Studio verified	✓	Tested with LM Studio 0.4.6

Usage

wave-server <checkpoint> [data] [options]

Arguments:
  <checkpoint>      Path to checkpoint file (.bin) trained by wave-engine
  [data]            Path to training data (for vocabulary — optional with --bpe)

Tokenizer (one required):
  [data]            Character/word vocab extracted from training data
  --bpe FILE        BPE tokenizer from HuggingFace tokenizer.json
  --word            Word-level tokenizer (requires data file)

Server:
  --port N          Listen port (default: 8080)
  --host ADDR       Bind address (default: 127.0.0.1, use 0.0.0.0 for LAN)
  --model-name S    Model name in API responses (default: wave-engine)
  --api-key KEY     Require bearer token auth on /v1/* endpoints
  --gpu             Enable GPU acceleration (requires --features gpu build)

Wave Memory:
  --memory FILE     Load/create a .kwmf wave memory file. Injects into
                    ODE initial conditions. Accumulates across conversations.

Architecture (WCHK v1 checkpoints only — v2 self-describes):
  --n-bands N       Harmonic frequency bands (default: 384)
  --n-head N        Attention heads (default: 12)
  --n-layers N      Parallel blocks (default: 24)
  --maestro-dim N   Maestro bottleneck width (default: 16)
  --block-size N    Max sequence length (default: 256)
  --rk4-steps N     ODE integration steps (default: 16)

Endpoints

Endpoint	Method	Auth	Description
/v1/chat/completions	POST	Yes	OpenAI-compatible chat completion
/v1/models	GET	Yes	List available models
/health	GET	No	Server health check with model info

POST /v1/chat/completions — Accepts messages (required), temperature, top_p, max_tokens, stream, top_k, repetition_penalty. Non-streaming returns JSON. Streaming ("stream": true) returns Server-Sent Events ending with data: [DONE]\n\n.

Auth — When --api-key is set, all /v1/* endpoints require Authorization: Bearer <key> header. /health is always open for load balancers and monitoring.

Checkpoint Formats

WCHK (recommended) — Wave-engine native format. Self-describing header contains the full model config. No architecture flags needed.

wave-server checkpoint.bin data/input.txt --port 8080

KCHK (legacy) — Kerr-engine format. Loaded with best-effort compatibility. Architecture flags may be needed if the model doesn't match defaults.

wave-server legacy_checkpoint.bin data/input.txt --n-bands 64 --n-head 4 --n-layers 4

Connecting Chat UIs

Any chat application that supports OpenAI-compatible endpoints can connect.

LM Studio (verified with 0.4.6) — In the chat panel, set "Override Base URL" to http://127.0.0.1:8080/v1. Select any model from the dropdown — the server uses its loaded model regardless. Put your API key in the "OpenAI API Key" field (or any string if auth is disabled).

Open WebUI — Settings → Connections → add http://127.0.0.1:8080/v1 as an OpenAI endpoint.

SillyTavern / continue.dev / any OpenAI client — Point the API base URL to http://127.0.0.1:8080/v1. Set the API key if auth is enabled.

curl —

curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-key" \
  -d '{
    "model": "wave-engine",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 64,
    "temperature": 0.8,
    "stream": true
  }'

Wave Memory

The --memory flag enables persistent experience accumulation across conversations. The model weights never change — a separate file (typically 1-2KB) shifts the Kerr-ODE's starting position on the unit circle.

# First conversation — creates fresh memory file
wave-server checkpoint.bin data/input.txt --memory memory.kwmf

# Subsequent conversations — loads and accumulates
wave-server checkpoint.bin data/input.txt --memory memory.kwmf

# Inspect what accumulated
kerr-memory census memory.kwmf

During inference, memory offsets add to the ODE initial conditions: Z_k = input_k + α · memory_k. After each conversation, the ODE final states feed an exponential moving average that merges into the persistent file. The Kerr dynamics amplify resonant memories and damp unreinforced ones.

The memory system is model-agnostic — it stores per-band oscillator states and works with any model that uses the Kerr-ODE. See kerr-memory for the library and full investigation results.

Architecture

The server implements the wave-engine forward pass for inference. The architecture matches the training engine exactly — parallel blocks with harmonic coherence attention and dual-maestro Kerr-ODE FFN.

Block structure (GPT-J parallel formulation):

x = x + attention(LN(x)) + FFN(LN(x))

Attention — Harmonic coherence scoring: cos(n × Δφ) where n is a learned harmonic number and Δφ is the phase difference between positions. Frozen during training, frozen during inference. KV-cache stores phase angles (scalars) and value projections per head — simpler than standard transformer KV-cache because phases are scalars and frozen weights never invalidate the cache.

FFN — Dual-maestro Kerr-ODE: input → maestro_in (768→16→768) → ODE (RK4) → maestro_out (768→16→768) → out_proj (768→768).

~1,500 lines across 12 modules. Self-contained — the forward pass is built in, no wave-engine dependency at runtime.

src/
├── main.rs          CLI, startup, config
├── server.rs        Axum router, auth middleware, graceful shutdown
├── handlers.rs      Request handlers, SSE streaming, memory accumulation
├── api_types.rs     OpenAI protocol types (serde structs)
├── model.rs         Forward pass, weight structs, KV-cache, Kerr-ODE with memory
├── checkpoint.rs    Checkpoint loader (WCHK and legacy KCHK)
├── inference.rs     Token generation with temperature/top-k/top-p sampling
├── prompt.rs        Vocabulary, text encode/decode, chat message formatting
├── data.rs          Character and word tokenizers
├── bpe.rs           BPE tokenizer (HuggingFace tokenizer.json)
├── rng.rs           Deterministic PRNG for sampling
├── gpu.rs           GPU matvec accelerator (optional, wgpu)
└── gpu_forward.rs   GPU-accelerated forward pass (optional)

Known Limitations

GPU forward pass needs updating — The gpu_forward.rs module references the old kerr-server architecture (sequential blocks, single maestro, QKV attention). It needs rewriting to match the current wave-engine architecture (parallel blocks, dual maestro, harmonic coherence attention). CPU inference works correctly. GPU inference with --features gpu may not compile against the current model structs.

No concurrent requests — The server handles one request at a time. Sequential inference. Batched dispatch using the engine's existing batch patterns would allow serving multiple users simultaneously.

Dependencies

• kerr-memory — Wave memory state management (for --memory flag)
• axum 0.8 — HTTP framework
• tokio — Async runtime
• serde, serde_json, uuid, tokio-stream
• wgpu, bytemuck, pollster (optional, for --features gpu)

No wave-engine dependency at runtime. The forward pass is built into the server.

Requirements

• Rust (edition 2024)
• kerr-memory repo at ../kerr-memory (path dependency for wave memory support)

# Default build (CPU inference)
cargo build --release

# With GPU acceleration
cargo build --release --features gpu

Contributing

The maintainer (Marco Da Cunha) is an IT systems administrator, not a programmer. The server was built through collaboration with AI — Claude Desktop for architecture, Claude Code for implementation. This is stated openly.

Contribution process:

• Fork the repo, create a branch, submit a PR.
• Every PR must demonstrate that the four endpoints still work: health, models, non-streaming chat, and SSE streaming.
• The maintainer merges based on testing and description, not code review. Be clear about what you changed and why.

Known targets for contributors:

Target	Impact	Difficulty
Fix gpu_forward.rs for wave-engine architecture	GPU inference at 768-dim+	Medium
Batched GPU dispatch	Use engine's batch patterns for multi-position inference	Medium
Vocab embedded in checkpoint	Eliminate data file requirement at serve time	Small
Streaming memory accumulation	Currently only non-streaming updates memory	Small
Concurrent request handling	Multi-user serving via batched dispatch	Medium
Model hot-reload	Swap models without server restart	Medium

Related

• wave-engine — Training engine that produces the checkpoints this server serves (public, Apache 2.0)
• kerr-memory — Wave memory library used by the --memory flag (public, Apache 2.0)
• Wave Coherence as a Computational Primitive — The parent research project (public, MIT)

License

Apache 2.0. See LICENSE.

Credits

• Marco Da Cunha — Architecture, direction, pattern recognition
• Claude Desktop (Opus) — Architecture design, documentation
• Claude Code — Implementation, testing