Alexandro.Net

Download README · GitHub release

@stackline/ai-server

Fetch-compatible HTTP backend handler for Stackline AI.

npm version license GitHub repository Docs Reddit community

Documentation | npm | Issues | Repository

Current package version: 0.0.6

Why this package?

@stackline/ai-server gives the browser one safe backend API without exposing provider keys, Ollama targets, SQL, or memory paths. It is Fetch-compatible by design and can be adapted to Node HTTP, Express, or other runtimes that can create Web Request and Response objects.

What This Package Does

This package turns a StacklineAIServer from @stackline/ai into HTTP routes:

It expects Web Fetch API Request objects and returns Web Fetch API Response objects.

It is not an Express middleware by itself.

When To Use

Use this package when a browser UI needs one safe backend API for health, manifest, model listing, and chat.

Compatibility

Item Value
Package @stackline/ai-server@0.0.6
Supported Node.js >=18.17.0
Module entry dist/index.js (ES modules)
Types dist/index.d.ts
Runtime dependencies 1 direct dependency

Status

Initial public API, ESM-only, TypeScript declarations included.

Requirements

When Not To Use

Do not pass this handler directly to Express as app.use(handleAI). Express uses req/res, while this package expects Web Request and returns Web Response.

Limitations

The current chat response is non-streaming. Request bodies are consumed as a bounded stream, so maxBodyBytes stops oversized input before the complete payload is buffered.

Installation

Install By Situation

HTTP Handler With A Custom Provider

npm init -y
npm pkg set type=module
npm install @stackline/ai @stackline/ai-server

HTTP API With Ollama

npm init -y
npm pkg set type=module
npm install @stackline/ai @stackline/ai-server @stackline/ai-ollama

HTTP API With Ollama And Browser UI

npm init -y
npm pkg set type=module
npm install @stackline/ai @stackline/ai-server @stackline/ai-ollama @stackline/ai-ui
npm install -D vite
mkdir -p src

Express Backend

npm init -y
npm pkg set type=module
npm install express @stackline/ai @stackline/ai-server @stackline/ai-ollama

Add @stackline/ai-ui and vite only if this Express backend also serves a browser app.

Usage

Complete Node HTTP Example

import { createServer } from "node:http";
import { createStacklineAIServer } from "@stackline/ai/server";
import { createStacklineAIHttpHandler } from "@stackline/ai-server";
import { ollamaProvider } from "@stackline/ai-ollama";

async function requestFromNode(req) {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  return new Request(`http://${req.headers.host || "localhost"}${req.url}`, {
    method: req.method,
    headers: req.headers,
    body: chunks.length ? Buffer.concat(chunks) : undefined,
  });
}

async function writeNodeResponse(res, response) {
  res.statusCode = response.status;
  response.headers.forEach((value, key) => res.setHeader(key, value));
  res.end(Buffer.from(await response.arrayBuffer()));
}

const model = process.env.OLLAMA_MODEL || "auto";
if (!model.trim()) throw new Error("OLLAMA_MODEL is empty.");

const ai = createStacklineAIServer({
  provider: ollamaProvider({
    target: process.env.OLLAMA_TARGET || "http://127.0.0.1:11434",
    model,
  }),
  rag: false,
  memory: false,
});

const handleAI = createStacklineAIHttpHandler({
  server: ai,
  basePath: "/api/ai",
  allowedModels: process.env.STACKLINE_AI_ALLOWED_MODELS
    ? process.env.STACKLINE_AI_ALLOWED_MODELS.split(",").map((item) => item.trim()).filter(Boolean)
    : undefined,
  maxBodyBytes: 256 * 1024,
  cors: {
    origins: [process.env.WEB_ORIGIN || "http://localhost:4623"],
  },
});

const server = createServer(async (req, res) => {
  try {
    const response = await handleAI(await requestFromNode(req));
    await writeNodeResponse(res, response);
  } catch (cause) {
    const message = cause instanceof Error ? cause.message : "Unexpected server error.";
    res.writeHead(500, { "content-type": "application/json; charset=utf-8" });
    res.end(JSON.stringify({ error: { message, status: 500 } }));
  }
});

server.listen(Number(process.env.PORT || 8787), () => {
  console.log("Stackline AI API: http://127.0.0.1:8787/api/ai");
});

Express Adapter

Use an adapter that converts Express req/res to Web Request/Response. Do not run express.json() before this route, because the Stackline handler reads the request body.

import express from "express";
import { createStacklineAIServer } from "@stackline/ai/server";
import { createStacklineAIHttpHandler } from "@stackline/ai-server";
import { ollamaProvider } from "@stackline/ai-ollama";

async function requestFromExpress(req) {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  return new Request(`${req.protocol}://${req.get("host")}${req.originalUrl}`, {
    method: req.method,
    headers: req.headers,
    body: chunks.length ? Buffer.concat(chunks) : undefined,
  });
}

async function writeExpressResponse(res, response) {
  res.status(response.status);
  response.headers.forEach((value, key) => res.setHeader(key, value));
  res.send(Buffer.from(await response.arrayBuffer()));
}

const ai = createStacklineAIServer({
  provider: ollamaProvider({
    target: process.env.OLLAMA_TARGET || "http://127.0.0.1:11434",
    model: process.env.OLLAMA_MODEL || "auto",
  }),
  rag: false,
  memory: false,
});

const handleAI = createStacklineAIHttpHandler({
  server: ai,
  basePath: "",
});

const app = express();

app.use("/api/ai", async (req, res, next) => {
  try {
    const response = await handleAI(await requestFromExpress(req));
    await writeExpressResponse(res, response);
  } catch (error) {
    next(error);
  }
});

app.listen(8788, () => {
  console.log("Express API: http://127.0.0.1:8788/api/ai");
});

Verify The Routes

curl http://127.0.0.1:8787/api/ai/health
curl http://127.0.0.1:8787/api/ai/manifest
curl http://127.0.0.1:8787/api/ai/models
curl -i -X OPTIONS http://127.0.0.1:8787/api/ai/chat \
  -H 'origin: http://localhost:4623' \
  -H 'access-control-request-method: POST'
curl http://127.0.0.1:8787/api/ai/chat \
  -H 'content-type: application/json' \
  -d '{"model":"llama3.1","messages":[{"role":"user","content":"Hello"}]}'

Features

Feature Supported
GET /health ✅
GET /manifest ✅
GET /models ✅
POST /chat ✅
CORS handling ✅
Request body limit ✅
Allowed model policy ✅
Fetch-compatible handler ✅
Express adapter example ✅

Security

Add authentication, authorization, rate limiting, restrictive CORS, body limits, and model allow-lists in production.

API Surface

Public API

Configuration

createStacklineAIHttpHandler({
  server: ai,
  basePath: "/api/ai",
  allowedModels: ["llama3.1"],
  maxBodyBytes: 256 * 1024,
  cors: {
    origins: ["https://app.example.com"],
    credentials: true,
  },
});

Request And Response Schemas

POST /chat accepts:

{
  "model": "llama3.1",
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "temperature": 0.2,
  "metadata": {
    "sessionId": "demo-session",
    "userId": "user-1"
  }
}

POST /chat returns:

{
  "message": {
    "role": "assistant",
    "content": "Hello.",
    "model": "llama3.1"
  },
  "content": "Hello.",
  "model": "llama3.1"
}

Error Handling

Errors are JSON:

{ "error": { "message": "messages must be an array.", "status": 400 } }

Oversized bodies return 413, model allow-list failures return 403, and other validation/provider failures return 400. When allowedModels is set, the client must send an explicit model value.

The common Ollama model error:

Ollama chat requires a model. Use a model name or model: "auto".

means the request model and provider model were empty, or auto could not find an installed model from Ollama /api/tags.

Documentation

Local Development

Clone the monorepo and run from its root. Repository tooling requires Node.js >=22.13.0 and pnpm@11.22.0; release archives use official Node.js 24.20.0 and npm 11.19.0.

pnpm install --frozen-lockfile
pnpm --filter @stackline/ai-server build
pnpm --filter @stackline/ai-server test
pnpm run check

Consumer Smoke Test

Test The Example

pnpm --filter stackline-ai-example-express-adapter smoke

Pack the release family and validate a fresh consumer, including runtime exports and TypeScript declarations:

pnpm run pack:release
node scripts/consumer-smoke.mjs release-artifacts

Release Checklist

Versioning

Use the same release line as @stackline/ai.

  1. Update the package manifest, changelog, workspace references, and documentation together.
  2. Run the workspace checks plus pnpm audit and pnpm audit --prod.
  3. Use publish.yml and confirm expected_manifest_sha512 against the reviewed SHA512SUMS file.
  4. Verify each public package's exact bytes and GitHub Actions provenance.

License

MIT. Copyright notices and the credits above are retained.

Credits and original authors

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.