openai-server

OpenAI-compatible HTTP surface for hum

A bee that puts an OpenAI-shaped /v1/chat/completions server in front of hum’s local thrum socket. Any tool, agent framework, or client library that speaks OpenAI’s chat-completions API can drive a hum daemon without knowing thrum exists.

Propensity

statefulness	richness	wire shape	hides
convention-stateful	medium	OpenAI `/v1/chat/completions` SSE	pulse, breath, drone, perf-mark, tendril, permission-ask, tool-meta

Convention-stateful: no server-side hum tracking; the OpenAI user field is treated as a session continuation hint.

What it does

client                           openai-server                       humd
  │                                   │                                │
  │  POST /v1/chat/completions        │                                │
  ├──────────────────────────────────►│                                │
  │   { messages, model, stream }     │                                │
  │                                   │  chi:"hello"                   │
  │                                   ├───────────────────────────────►│
  │                                   │  chi:"prompt"                  │
  │                                   ├───────────────────────────────►│
  │                                   │  chi:"chunk" (text fragments)  │
  │                                   │◄───────────────────────────────┤
  │   data: {...}\n\n (SSE)           │                                │
  │◄──────────────────────────────────┤                                │
  │                                   │  chi:"finish"                  │
  │                                   │◄───────────────────────────────┤
  │   data: [DONE]\n\n                │                                │
  │◄──────────────────────────────────┤                                │

Configure

env	default	what
`OPENAI_SERVER_PORT`	`14620`	HTTP listen port
`OPENAI_SERVER_HOST`	`127.0.0.1`	HTTP listen host
`OPENAI_SERVER_API_KEY`	(unset → no auth)	bearer token required on requests
`HUM_THRUM_SOCK`	`$XDG_RUNTIME_DIR/hum/thrum.sock`	humd’s NDJSON socket

The bee’s own kind (openai-server) is its env namespace — HUM_* is reserved for hum-side knobs like HUM_THRUM_SOCK.

Config file (optional)

Also reads ~/.config/hum/hives/openai-server.json if present:

{ "host": "127.0.0.1", "port": 14620, "apiKey": "secret" }

Resolution precedence: env > config file > built-in defaults.

Run

npm install
npm run build
npm start

Or in dev:

npx tsx src/index.ts

Use

curl http://localhost:14620/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonnet",
    "stream": true,
    "messages": [{ "role": "user", "content": "ping" }]
  }'

Drop-in for the OpenAI SDK:

import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "http://localhost:14620/v1",
  apiKey:  "anything",
});
const r = await client.chat.completions.create({
  model: "sonnet",
  messages: [{ role: "user", content: "ping" }],
});

Status

Reference implementation. Tools / function-calling map onto thrum’s chi:"tool-call" / chi:"tool-result" pair; lots of OpenAI surface (images, audio, fine-tuning) is intentionally not implemented — file an issue if you need a specific endpoint.