Skip to documentation
ALEXANDRONET

package

@stackline/ai-server 0.0.6 — installation and API

Fetch-compatible HTTP backend handler for Stackline AI.

Install @stackline/ai-server

npm install @stackline/[email protected]

Package version: 0.0.6. Metadata verified: 2026-11-06. This is separate from the framework version and demonstration runtime.

Node.js requirement
{"node": ">=18.17.0"}
Accepted peer dependencies (declared ranges)
{}

Tested environments are described in the versioned README and linked source checks. A declared peer range is not evidence that every version in it was tested.

Versioned reference

This reference comes from the published @stackline/[email protected] README. Its upstream attribution and license remain with the source. Benchmark and security statements describe the cited tests and advisories, not a guarantee for every application.

@stackline/ai-server

Fetch-compatible HTTP backend handler for Stackline AI.

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:

  • GET /api/ai/health
  • GET /api/ai/manifest
  • GET /api/ai/models
  • POST /api/ai/chat
  • OPTIONS /api/ai/*

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/[email protected]
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

  • Runtime: Node.js >=18.17.0.
  • A StacklineAIServer from @stackline/ai.
  • Web Fetch API Request and Response.

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

  • createStacklineAIHttpHandler(options)
  • StacklineAIHttpHandler
  • StacklineAIHttpHandlerOptions
  • StacklineAICorsOptions

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

  • Full tutorial: docs/getting-started/full-stack-tutorial.md
  • HTTP reference: docs/reference/http-api.md

Local Development

Clone the monorepo and run from its root. Repository tooling requires Node.js >=22.13.0 and [email protected]; 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.

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