tep 0.11.0

data/examples/experiments/app.rb

@@ -0,0 +1,225 @@
+# experiments -- mock training-run manager driven by MCP tools.
+#
+# The full agentic-driver surface: Claude Code (or OpenCode /
+# Gravity / any MCP client) discovers tools + resources via
+# /mcp, runs experiments, polls metrics, cancels runs -- all via
+# the natural agent-tool loop, no human-in-the-loop UI required.
+#
+# The runs are simulated (no actual ML). State lives in module-
+# level arrays. A real version would persist to SQLite via the
+# same exact tool/resource API.
+#
+# Run:
+#   bin/tep build examples/experiments/app.rb -o /tmp/experiments
+#   /tmp/experiments -p 4567
+#
+# Then point an MCP client at http://127.0.0.1:4567/mcp,
+# or for non-MCP agents: http://127.0.0.1:4567/openapi.json +
+# http://127.0.0.1:4567/llms.txt for discovery.
+require 'sinatra'
+
+# ---- mock experiment state ----
+
+# Parallel arrays per experiment so spinel sees typed slots
+# instead of an Array<Hash> with mixed value types.
+EXP_IDS         = [0]; EXP_IDS.delete_at(0)
+EXP_NAMES       = [""]; EXP_NAMES.delete_at(0)
+EXP_LRS         = [""]; EXP_LRS.delete_at(0)
+EXP_EPOCHS      = [0]; EXP_EPOCHS.delete_at(0)
+EXP_CUR_EPOCH   = [0]; EXP_CUR_EPOCH.delete_at(0)
+EXP_STATUS      = [""]; EXP_STATUS.delete_at(0)    # "queued" | "running" | "done" | "cancelled"
+EXP_LOSS        = [""]; EXP_LOSS.delete_at(0)      # serialized loss-per-epoch, comma-joined
+
+NEXT_ID = [0]
+
+# Allocate a new experiment id, append all defaults.
+def enqueue_experiment(name, lr_str, epochs)
+  NEXT_ID[0] = NEXT_ID[0] + 1
+  id = NEXT_ID[0]
+  EXP_IDS.push(id)
+  EXP_NAMES.push(name)
+  EXP_LRS.push(lr_str)
+  EXP_EPOCHS.push(epochs)
+  EXP_CUR_EPOCH.push(0)
+  EXP_STATUS.push("queued")
+  EXP_LOSS.push("")
+  id
+end
+
+# Linear scan -- O(n), fine for the demo since n stays small.
+# Returns the array index for id, or -1 if not found.
+def find_exp_index(id)
+  i = 0
+  while i < EXP_IDS.length
+    if EXP_IDS[i] == id
+      return i
+    end
+    i = i + 1
+  end
+  -1
+end
+
+# Format a single experiment as `id=N name=foo status=running lr=1e-3 epoch=3/10 loss=0.42,0.31`.
+def format_experiment(i)
+  "id="    + EXP_IDS[i].to_s +
+  " name=" + EXP_NAMES[i] +
+  " lr="   + EXP_LRS[i] +
+  " status=" + EXP_STATUS[i] +
+  " epoch=" + EXP_CUR_EPOCH[i].to_s + "/" + EXP_EPOCHS[i].to_s +
+  " loss=" + EXP_LOSS[i]
+end
+
+# Simulate one epoch of training -- bump cur_epoch + append a
+# synthetic loss value. When epoch == epochs, flip status to done.
+def step_experiment(i)
+  if EXP_STATUS[i] == "running"
+    EXP_CUR_EPOCH[i] = EXP_CUR_EPOCH[i] + 1
+    # Synthetic loss: starts around 1.0, decays ~10% per step.
+    base_x100 = 100 - (EXP_CUR_EPOCH[i] * 10)
+    if base_x100 < 1
+      base_x100 = 1
+    end
+    new_loss = "0." + base_x100.to_s
+    if EXP_LOSS[i].length > 0
+      EXP_LOSS[i] = EXP_LOSS[i] + "," + new_loss
+    else
+      EXP_LOSS[i] = new_loss
+    end
+    if EXP_CUR_EPOCH[i] >= EXP_EPOCHS[i]
+      EXP_STATUS[i] = "done"
+    end
+  end
+  0
+end
+
+# ---- MCP tools ----
+
+mcp_tool 'start_experiment', "Enqueue a new training run", caps: [:run_experiments] do
+  param :name,          String,  "experiment name (free-text label)"
+  param :learning_rate, String,  "learning rate as string (e.g. '1e-3', '0.001')"
+  param :epochs,        Integer, "number of training epochs"
+
+  on_call do |name:, learning_rate:, epochs:|
+    id = enqueue_experiment(name, learning_rate, epochs)
+    idx = find_exp_index(id)
+    # Auto-advance to running for the demo. A real runner would
+    # background this and update status as worker fibers progress.
+    EXP_STATUS[idx] = "running"
+    Tep::MCP.text("started experiment id=" + id.to_s + " (" + name + ")")
+  end
+end
+
+mcp_tool 'step_experiment', "Advance one experiment by one epoch" do
+  param :id, Integer, "experiment id to advance"
+
+  on_call do |id:|
+    idx = find_exp_index(id)
+    if idx < 0
+      Tep::MCP.error("no such experiment id=" + id.to_s)
+    else
+      step_experiment(idx)
+      Tep::MCP.text(format_experiment(idx))
+    end
+  end
+end
+
+mcp_tool 'list_experiments', "List all experiments + their current state" do
+  on_call do
+    if EXP_IDS.length == 0
+      Tep::MCP.text("no experiments yet")
+    else
+      out = ""
+      i = 0
+      while i < EXP_IDS.length
+        if i > 0
+          out = out + "\n"
+        end
+        out = out + format_experiment(i)
+        i = i + 1
+      end
+      Tep::MCP.text(out)
+    end
+  end
+end
+
+mcp_tool 'cancel_experiment', "Mark an experiment as cancelled", caps: [:run_experiments] do
+  param :id, Integer, "experiment id to cancel"
+
+  on_call do |id:|
+    idx = find_exp_index(id)
+    if idx < 0
+      Tep::MCP.error("no such experiment id=" + id.to_s)
+    else
+      EXP_STATUS[idx] = "cancelled"
+      Tep::MCP.text("cancelled id=" + id.to_s)
+    end
+  end
+end
+
+# ---- MCP resources ----
+
+mcp_resource 'experiments/all', "Snapshot of every experiment" do
+  on_read do
+    body = ""
+    i = 0
+    while i < EXP_IDS.length
+      if i > 0
+        body = body + "\n"
+      end
+      body = body + format_experiment(i)
+      i = i + 1
+    end
+    Tep::MCP.resource_text("experiments/all", body)
+  end
+end
+
+mcp_resource 'experiments/active', "Currently-running experiments" do
+  on_read do
+    body = ""
+    i = 0
+    while i < EXP_IDS.length
+      if EXP_STATUS[i] == "running"
+        if body.length > 0
+          body = body + "\n"
+        end
+        body = body + format_experiment(i)
+      end
+      i = i + 1
+    end
+    if body.length == 0
+      body = "no active experiments"
+    end
+    Tep::MCP.resource_text("experiments/active", body)
+  end
+end
+
+# Plain HTTP landing for humans poking around.
+get '/' do
+  res.headers["Content-Type"] = "text/plain; charset=utf-8"
+  "experiments demo (tep MCP battery)\n" +
+  "\n" +
+  "Catalog: /llms.txt\n" +
+  "OpenAPI: /openapi.json\n" +
+  "MCP:     POST /mcp (JSON-RPC 2.0)\n" +
+  "\n" +
+  "Tools:\n" +
+  "  POST /tools/start_experiment   (requires X-Test-Cap-Run header below)\n" +
+  "  POST /tools/step_experiment\n" +
+  "  POST /tools/list_experiments\n" +
+  "  POST /tools/cancel_experiment  (capped)\n" +
+  "\n" +
+  "Resources:\n" +
+  "  GET  /resources/experiments/all\n" +
+  "  GET  /resources/experiments/active\n"
+end
+
+# Caps shim for the demo: in a real app, an MCP client would
+# hand a Tep::AuthBearerToken JWT with the run_experiments cap
+# baked in. Here, accept an X-Demo-Cap-Run header as the
+# capability source so humans can drive the demo with curl.
+before do
+  if req.req_headers["x-demo-cap-run"].length > 0
+    req.identity = Tep::Identity.new(
+      "user:demo", nil, [:run_experiments])
+  end
+end

data/examples/geohash/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+ruby "3.3.0", engine: "spinel", engine_version: "0.0.0"
+
+# A real published gem, declared the normal way. spinel-compat vendor
+# (bundler-spinel, ../spinelgems) resolves it from Gemfile.lock into
+# vendor/spinel/. NOTE: pr_geohash's GeoHash.encode compiles under
+# spinel; its neighbors/decode use Array#flatten / #transpose, which
+# spinel doesn't support yet (matz/spinel#1078 / #1079) -- so this app
+# only exposes encode. Gem reuse is per-method; the Gemfile + the
+# spinelgems verdict are exactly how you find that out.
+gem "pr_geohash", "1.0.0"

data/examples/geohash/Gemfile.lock

@@ -0,0 +1,17 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    pr_geohash (1.0.0)
+
+PLATFORMS
+  aarch64-linux
+  ruby
+
+DEPENDENCIES
+  pr_geohash (= 1.0.0)
+
+RUBY VERSION
+   ruby 3.4.9p82
+
+BUNDLED WITH
+   2.6.9

data/examples/geohash/README.md

@@ -0,0 +1,58 @@
+# geohash — using a real published gem from a tep app (via a Gemfile)
+
+This example demonstrates something tep couldn't do before: **compile and
+run an app that depends on a published Ruby gem, declared in a `Gemfile`.**
+
+The gem is [`pr_geohash` 1.0.0](https://rubygems.org/gems/pr_geohash) (MIT),
+a pure-Ruby geohash encoder. It's declared in [`Gemfile`](Gemfile) and
+resolved by [`bundler-spinel`](https://github.com/OriPekelman/spinelgems)
+(`spinel-compat vendor`) — not hand-vendored.
+
+```ruby
+require_relative 'vendor/spinel/deps'   # generated from Gemfile.lock
+# ...
+get '/geohash' do
+  GeoHash.encode(params["lat"].to_f, params["lon"].to_f, 12)
+end
+```
+
+## How it works (the spinelgems convention)
+
+tep apps are AOT-compiled by spinel — no runtime gem loader, no gem load
+path. `spinel-compat vendor` reads `Gemfile.lock`, places each gem under
+`vendor/spinel/<name>/`, and writes `vendor/spinel/deps.rb` (a
+`require_relative` per gem). The app pulls them in with one
+`require_relative "vendor/spinel/deps"`, and `bin/tep build` inlines that
+chain recursively into the binary. `Gemfile`/`Gemfile.lock` are committed;
+`vendor/spinel/` is generated (gitignored).
+
+## Build + run
+
+```sh
+make vendor-examples           # spinel-compat vendor -> vendor/spinel/ (needs ../spinelgems)
+bin/tep build examples/geohash/app.rb -o /tmp/geohash
+/tmp/geohash -p 4979 &
+curl 'http://127.0.0.1:4979/geohash?lat=48.8584&lon=2.2945&precision=8'
+# => u09tunqu   (identical to CRuby's GeoHash.encode)
+```
+
+`test/test_geohash_example.rb` vendors, builds this app, and checks the
+output matches CRuby byte-for-byte.
+
+## What works, what doesn't (gem reuse is per-method)
+
+`GeoHash.encode` compiles and runs cleanly — it uses only `map`, `join`,
+integer bit-ops and Float comparisons, all of which spinel supports.
+
+`GeoHash.neighbors` and `GeoHash.decode` are deliberately **not** exposed:
+they rely on `Array#flatten` (on a string-element array) / `Array#transpose`,
+which spinel doesn't compile yet — tracked upstream as
+[matz/spinel#1078](https://github.com/matz/spinel/issues/1078) (flatten is
+specialized for int-element arrays only) and
+[matz/spinel#1079](https://github.com/matz/spinel/issues/1079) (transpose
+missing). That's the honest shape of gem reuse under tep today: the hot
+path of a well-behaved pure-Ruby gem drops straight in, while methods that
+reach for unsupported stdlib corners don't.
+
+For an example where the gem's **entire** API compiles — no caveats — see
+[`examples/maidenhead`](../maidenhead/README.md).

data/examples/geohash/app.rb

@@ -0,0 +1,33 @@
+require 'sinatra'
+
+# Use a REAL published Ruby gem -- pr_geohash 1.0.0 (MIT) -- from a tep
+# app, declared in a Gemfile and resolved by `spinel-compat vendor`
+# (bundler-spinel, ../spinelgems) into vendor/spinel/. The one require
+# below pulls in the generated deps.rb chain; bin/tep inlines it into the
+# AOT binary. Run `make vendor` (or see README.md) before building.
+require_relative 'vendor/spinel/deps'
+
+# GET /geohash?lat=..&lon=..&precision=..
+# Encodes a latitude/longitude into a geohash using GeoHash.encode from
+# the gem. Query params (not path segments) so the '-' and '.' in real
+# coordinates don't need escaping.
+get '/geohash' do
+  lat  = params["lat"].to_f
+  lon  = params["lon"].to_f
+  prec = params["precision"].to_i
+  if prec <= 0
+    prec = 12
+  end
+  GeoHash.encode(lat, lon, prec)
+end
+
+# NOTE: GeoHash.neighbors / GeoHash.decode are intentionally NOT exposed.
+# They lean on Array#flatten / Array#transpose, which spinel doesn't
+# compile yet (encode uses only map/join/bit-ops and works fine). A good
+# illustration that gem reuse is per-method: the hot path compiles, a
+# couple of helpers don't -- see README.md.
+
+get '/' do
+  "tep + pr_geohash 1.0.0 (a real, unmodified published gem)\n" +
+  "try: /geohash?lat=48.8584&lon=2.2945&precision=8\n"
+end

data/examples/hello.rb

@@ -0,0 +1,120 @@
+# Tep "hello" demo -- exercises the full v0.1 surface.
+require_relative "../lib/tep"
+
+class Root < Tep::Handler
+  def handle(req, res)
+    "<!doctype html><html><head><title>tep " + Tep::VERSION + "</title>" +
+    "<link rel=\"stylesheet\" href=\"/style.css\">" +
+    "</head><body>" +
+    "<h1>tep " + Tep::VERSION + "</h1>" +
+    "<p>Sinatra-flavoured framework, AOT-compiled by Spinel.</p>" +
+    "<ul>" +
+    "<li><a href=\"/hi/world\">/hi/:name</a> -- path params</li>" +
+    "<li><a href=\"/search?q=ruby&page=2\">/search?q=...&page=...</a> -- query string</li>" +
+    "<li><a href=\"/square/12\">/square/:n</a> -- typed path param</li>" +
+    "<li><a href=\"/about\">/about</a> -- custom Content-Type</li>" +
+    "<li><a href=\"/old\">/old</a> -- 302 redirect</li>" +
+    "<li><a href=\"/secret\">/secret</a> -- 401 halt</li>" +
+    "<li><a href=\"/hello.txt\">/hello.txt</a> -- static file from public/</li>" +
+    "<li><a href=\"/style.css\">/style.css</a> -- static CSS</li>" +
+    "<li><a href=\"/missing\">/missing</a> -- custom 404</li>" +
+    "<li>POST /echo (form-urlencoded body)</li>" +
+    "</ul></body></html>"
+  end
+end
+
+class Hi < Tep::Handler
+  def handle(req, res)
+    "<p>hi, " + req.params["name"] + "!</p>\n"
+  end
+end
+
+class Search < Tep::Handler
+  def handle(req, res)
+    "<p>q=" + req.params["q"] + " page=" + req.params["page"] + "</p>\n"
+  end
+end
+
+class Square < Tep::Handler
+  def handle(req, res)
+    n = req.params["n"].to_i
+    "<p>" + n.to_s + "<sup>2</sup> = " + (n * n).to_s + "</p>\n"
+  end
+end
+
+class About < Tep::Handler
+  def handle(req, res)
+    res.headers["Content-Type"] = "text/plain; charset=utf-8"
+    "tep " + Tep::VERSION + " -- spinel-compiled Sinatra-flavoured framework\n"
+  end
+end
+
+class Old < Tep::Handler
+  def handle(req, res)
+    res.set_status(302)
+    res.headers["Location"] = "/"
+    ""
+  end
+end
+
+class Secret < Tep::Handler
+  def handle(req, res)
+    res.set_status(401)
+    res.headers["WWW-Authenticate"] = "Basic realm=\"tep\""
+    "<h1>401</h1><p>nothing here for you.</p>\n"
+  end
+end
+
+class Echo < Tep::Handler
+  def handle(req, res)
+    res.headers["Content-Type"] = "text/plain; charset=utf-8"
+    "verb=" + req.verb + "\n" +
+    "path=" + req.path + "\n" +
+    "name=" + req.params["name"] + "\n" +
+    "body=" + req.raw_body + "\n"
+  end
+end
+
+class CustomNotFound < Tep::Handler
+  def handle(req, res)
+    res.headers["Content-Type"] = "text/html; charset=utf-8"
+    "<h1>nope -- " + req.path + "</h1>" +
+    "<p>this is a custom 404 page from Tep.not_found</p>\n"
+  end
+end
+
+class LoggerFilter < Tep::Filter
+  def before(req, res)
+    puts "[" + req.verb + "] " + req.path
+    0
+  end
+end
+
+class TimerFilter < Tep::Filter
+  def after(req, res)
+    res.headers["X-Tep-Powered-By"] = "spinel-aot"
+    0
+  end
+end
+
+# ---- registrations ----
+
+# Spinel doesn't have `__dir__` at compile time, so the path
+# substituted here has to be absolute *or* relative to the binary's
+# CWD at runtime. Adjust to suit your deployment.
+Tep.public_dir "./public"
+Tep.before     LoggerFilter.new
+Tep.after      TimerFilter.new
+Tep.not_found  CustomNotFound.new
+
+Tep.get  "/",            Root.new
+Tep.get  "/hi/:name",    Hi.new
+Tep.get  "/search",      Search.new
+Tep.get  "/square/:n",   Square.new
+Tep.get  "/about",       About.new
+Tep.get  "/old",         Old.new
+Tep.get  "/secret",      Secret.new
+Tep.post "/echo",        Echo.new
+
+# port, workers, quiet
+Tep.run!(4567, 1, false)

data/examples/llm_gateway/README.md

@@ -0,0 +1,73 @@
+# llm_gateway — an LLM API gateway on `Tep::Proxy`
+
+Fronts a remote OpenAI-compatible upstream and adds, in ~40 lines of
+Ruby, the three things a gateway exists for:
+
+1. **Credential swap** — strips the client's `Authorization`, attaches
+   the server-side key (`before`). The upstream only ever sees the
+   gateway's key.
+2. **Transparent streaming** — `stream: true` requests are forwarded
+   over a held-open connection and the SSE events pass straight back
+   to the client, unbuffered (`stream_request?` + `on_stream_chunk`).
+3. **Per-request telemetry** — exactly one toy/v1 `inference` event
+   per request, emitted at end-of-stream (`on_stream_end` +
+   `Tep::Events`) — the right cardinality (one per request, not per
+   chunk), with token counts + latency.
+
+This is the showcase for proxy battery chunk 6.2 (streaming +
+`on_stream_end`) composed with `Tep::Events`. It uses the **block-form
+proxy DSL** (`gw.before do … end`), which `bin/tep` lowers to a
+`Tep::Proxy` subclass.
+
+## Run
+
+```sh
+UPSTREAM=https://api.openai.com \
+OPENAI_KEY=sk-... \
+EVENTS_JSONL=/tmp/gateway.events.jsonl \
+  bin/tep build examples/llm_gateway/app.rb -o /tmp/gw && /tmp/gw -p 4567
+```
+
+(Points at any OpenAI-compatible server — a local `ollama`, vLLM,
+llama.cpp's server, or the real OpenAI API. `EVENTS_JSONL` unset
+disables emission with zero overhead.)
+
+```sh
+# streaming chat completion — SSE passthrough + one inference event
+curl -s localhost:4567/v1/chat/completions \
+  -H 'content-type: application/json' \
+  -d '{"model":"gpt-4o-mini","stream":true,
+       "messages":[{"role":"user","content":"hi"}]}'
+
+tail -1 /tmp/gateway.events.jsonl
+# {"kind":"inference","phase":"serve","t":3,"model":"gpt-4o-mini",
+#  "prompt_tokens":0,"completion_tokens":42,"wall_us":3000000,
+#  "extra":{"request_id":"...","principal_id":"anonymous"}}
+```
+
+The events stream is the toy/v1 envelope, so a research-lab
+orchestrator (or any consumer of training/serving events) ingests it
+the same way it ingests a training run.
+
+## Notes / limits
+
+- **Streaming requires the scheduled server** (`set :scheduler,
+  :scheduled`) — the pump parks on `io_wait`, same as WebSocket.
+- **Token counts are approximate at the proxy:** `completion_tokens`
+  is the SSE-event count (no tokenizer here); `prompt_tokens` is left
+  0. A real gateway parses `delta.content` / the request `messages`.
+  The origin-server battery (`Tep::Llm::OpenAI::Server`) reports exact
+  counts from the backend.
+- **`wall_us` is second-resolution** (`Time.now` exposes only integer
+  epoch seconds; LLM requests are seconds-scale, so latency is still
+  meaningful). Sub-second timing would need a µs-clock primitive.
+- **Auth/capabilities** flow through `req.identity` like any tep
+  route — gate the gateway with `req.identity.may?(:call_upstream)` in
+  `before` if you want per-principal access control.
+
+## See also
+
+- [`docs/PROXY-BATTERY.md`](../../docs/PROXY-BATTERY.md) — the battery.
+- `lib/tep/events.rb` — the toy/v1 emitter.
+- `examples/api_gateway` — the non-streaming sibling (auth-attach +
+  observability), 6.3's other half.

data/examples/llm_gateway/app.rb

@@ -0,0 +1,91 @@
+# examples/llm_gateway -- an LLM API gateway built on Tep::Proxy.
+#
+# Fronts a remote OpenAI-compatible upstream: swaps the client's
+# credential for the server-side key, streams the SSE response back
+# unchanged, and emits ONE toy/v1 serving event (kind:eval,
+# phase:serve, name:request) per request at end-of-stream (via
+# Tep::Events#inference). This is the payoff of
+# the proxy streaming battery (chunk 6.2) + the events emitter --
+# token-count + latency telemetry with the right cardinality (one
+# event per request, not per chunk), using on_stream_end as the
+# one-shot finalizer.
+#
+# Run:
+#   UPSTREAM=https://api.openai.com OPENAI_KEY=sk-... \
+#   EVENTS_JSONL=/tmp/gateway.events.jsonl \
+#     bin/tep build examples/llm_gateway/app.rb -o /tmp/gw && /tmp/gw -p 4567
+#
+#   # streaming chat completion -> SSE passthrough + one serving event
+#   curl -s localhost:4567/v1/chat/completions -H 'content-type: application/json' \
+#     -d '{"model":"gpt-4o-mini","stream":true,"messages":[{"role":"user","content":"hi"}]}'
+#   tail -1 /tmp/gateway.events.jsonl
+#   # {"kind":"eval","phase":"serve","t":3,"name":"request","extra":{
+#   #   "model":"gpt-4o-mini","prompt_tokens":0,"completion_tokens":42,
+#   #   "latency_us":3000000, ...}}
+require 'sinatra'
+
+# Streaming proxying needs the cooperative server (the pump parks on
+# io_wait); same constraint as WebSocket.
+set :scheduler, :scheduled
+set :workers, 1
+
+UPSTREAM     = ENV["UPSTREAM"]   || "http://127.0.0.1:11434"   # e.g. a local ollama
+OPENAI_KEY   = ENV["OPENAI_KEY"] || ""
+EVENTS       = Tep::Events.new(ENV["EVENTS_JSONL"] || "")      # "" disables emission
+
+on_start do
+  EVENTS.run_start("gateway", "proxy", "upstream", UPSTREAM,
+                   "{\"server\":\"tep-llm-gateway\"}")
+end
+
+# Block-form proxy DSL (lowered to a Tep::Proxy subclass by bin/tep).
+gw = Tep::Proxy.new(UPSTREAM)
+
+# Swap the credential: strip whatever the client sent, attach the
+# server-side key. Also stamp a coarse start time for the latency
+# measurement in on_stream_end (req.ivars is per-request state).
+gw.before do |req, res, ureq|
+  if OPENAI_KEY.length > 0
+    ureq.set_header("Authorization", "Bearer " + OPENAI_KEY)
+  end
+  req.ivars["t0"] = Time.now.to_i.to_s
+  false
+end
+
+# Stream when the client asked for it. OpenAI signals streaming with
+# `"stream": true` in the JSON body; Tep::Json has no bool getter, so
+# we match the literal (with or without the space).
+gw.stream_request? do |req|
+  b = req.raw_body
+  b.include?("\"stream\":true") || b.include?("\"stream\": true")
+end
+
+# Pass each SSE event straight through. The framework's StreamStats
+# tracks chunk_count / byte_count for us (chunk_count ~ completion
+# tokens for this demo; a real gateway would parse delta.content).
+gw.on_stream_chunk do |chunk, out, stats|
+  out.write(chunk.chunk_text)
+  0
+end
+
+# One inference event at end-of-stream -- the right cardinality.
+gw.on_stream_end do |req, out, stats|
+  model = Tep::Json.get_str(req.raw_body, "model")
+  t0    = req.ivars["t0"].to_i
+  wall  = Time.now.to_i - t0
+  if wall < 0
+    wall = 0
+  end
+  extra = "{" +
+    Tep::Json.encode_pair_str("request_id", req.req_headers["x-request-id"]) + "," +
+    Tep::Json.encode_pair_str("principal_id", req.identity.principal_id) +
+  "}"
+  # prompt_tokens unknown at the proxy (no tokenizer); completion_tokens
+  # approximated by the SSE event count. wall_us is second-resolution
+  # (no µs clock) -- fine for seconds-scale LLM latency.
+  EVENTS.inference(model, 0, stats.chunk_count, wall * 1000000, extra)
+  0
+end
+
+Tep.get  "/v1/models",           gw
+Tep.post "/v1/chat/completions", gw

data/examples/maidenhead/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+ruby "3.3.0", engine: "spinel", engine_version: "0.0.0"
+
+# A real published gem, declared the normal way. bundler-spinel
+# (spinel-compat vendor) resolves it from the lockfile and places its
+# source under vendor/spinel/ where tep's build will follow it.
+gem "maidenhead", "1.0.1"

data/examples/maidenhead/Gemfile.lock

@@ -0,0 +1,17 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    maidenhead (1.0.1)
+
+PLATFORMS
+  aarch64-linux
+  ruby
+
+DEPENDENCIES
+  maidenhead (= 1.0.1)
+
+RUBY VERSION
+   ruby 3.4.9p82
+
+BUNDLED WITH
+   2.6.9