@stackline/ai-ollama

Ollama provider adapter for Stackline AI.

Documentation | npm | Issues | Repository

Current package version: 0.0.6

Why this package?

@stackline/ai-ollama keeps Ollama behind your backend while still giving Stackline UI and HTTP packages a provider-neutral interface. It documents the full model path because Ollama /api/chat requires a real model name.

What This Package Does

This package adapts local Ollama, Ollama Cloud, or an Ollama-compatible API to the provider contract from @stackline/ai.

It is backend code. Do not put Ollama Cloud keys in browser code.

When To Use

Use this package when Stackline AI should call local Ollama, Ollama Cloud, or an Ollama-compatible backend.

Compatibility

Item	Value
Package	`@stackline/ai-ollama@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

Runtime: Node.js >=18.17.0.
Ollama or an Ollama-compatible API.
At least one installed chat model, unless every request supplies a valid explicit model.

When Not To Use

Do not import this package in the browser for private deployments. It belongs behind @stackline/ai-server.

Limitations

The adapter sends stream: false. Provider capabilities report streaming, but the current HTTP package does not expose streaming routes.

Installation

Install By Situation

Ollama Provider Only

Use this when backend code calls ai.chat() directly and you do not need HTTP or UI yet.

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

Ollama Through HTTP Routes

Use this when you need /api/ai/models and /api/ai/chat.

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

Ollama With The Browser Studio UI

Use this when you want <stackline-ai-studio> to work.

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

Usage

Step 1: Validate Ollama Before Stackline

ollama --version
ollama list
ollama pull llama3.1
curl http://127.0.0.1:11434/api/tags

Direct chat test:

curl http://127.0.0.1:11434/api/chat \
  -H 'content-type: application/json' \
  -d '{
    "model": "llama3.1",
    "messages": [
      { "role": "user", "content": "Reply with one short sentence." }
    ],
    "stream": false
  }'

If llama3.1 is not installed, use the exact NAME shown by ollama list.

Step 2: Use An Explicit Model First

Explicit models are the safest first deployment because they make failures obvious.

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

const model = process.env.OLLAMA_MODEL || "llama3.1";
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",
    apiKey: process.env.OLLAMA_API_KEY,
    model,
  }),
  rag: false,
  memory: false,
});

const response = await ai.chat({
  model,
  messages: [{ role: "user", content: "Say hello." }],
});

console.log(response.content);

Step 3: Expose It Through The Server

import { createStacklineAIHttpHandler } from "@stackline/ai-server";

const handleAI = createStacklineAIHttpHandler({
  server: ai,
  basePath: "/api/ai",
  allowedModels: [model],
});

Then the browser UI can call:

<stackline-ai-studio
  endpoint="/api/ai/chat"
  models-endpoint="/api/ai/models"
  model="llama3.1"
></stackline-ai-studio>

`model: "auto"`

The provider also supports:

ollamaProvider({
  target: "http://127.0.0.1:11434",
  model: "auto",
});

Auto mode calls /api/tags, skips model names that look like image, embedding, rerank, or vision-only models, and caches the first likely chat model. If no model can be resolved, chat throws:

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

Use explicit models when debugging a first install. Use auto when you want the backend to select the first installed chat-like model.

Features

Feature	Supported
Local Ollama target	✅
Ollama-compatible API target	✅
Optional API key header	✅
Explicit model selection	✅
`model: "auto"` fallback	✅
`/api/tags` model listing	✅
Non-chat model filtering for auto mode	✅
TypeScript declarations	✅

Security

Keep apiKey on the backend. Use model allow-lists in @stackline/ai-server when exposing a public app.

API Surface

Public API

ollamaProvider(options?: OllamaProviderOptions)
OllamaProviderOptions

Options

target: defaults to http://127.0.0.1:11434.
apiKey: optional bearer token.
model: explicit model or "auto".
fetch: optional fetch implementation for tests or custom runtimes.

Model Empty Troubleshooting

Symptom:

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

Cause:

request.model was empty;
provider options.model was empty;
or model: "auto" could not resolve an installed model from /api/tags.

Fix:

ollama list

Copy the exact NAME, then set:

OLLAMA_MODEL=llama3.1

Use the same value in UI markup when you want the browser to send it:

<stackline-ai-studio model="llama3.1"></stackline-ai-studio>

Error Handling

Non-OK Ollama responses include the upstream error text when possible.

Integration

Use with:

@stackline/ai for provider-neutral orchestration;
@stackline/ai-server for safe backend HTTP routes;
@stackline/ai-ui for the browser Studio component.

Documentation

Full tutorial: docs/getting-started/full-stack-tutorial.md
Package reference: docs/reference/packages.md

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-ollama build
pnpm --filter @stackline/ai-ollama test
pnpm run check

Consumer Smoke Test

Test The Example

pnpm --filter stackline-ai-example-ollama-minimal 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.

Update the package manifest, changelog, workspace references, and documentation together.
Run the workspace checks plus pnpm audit and pnpm audit --prod.
Use publish.yml and confirm expected_manifest_sha512 against the reviewed SHA512SUMS file.
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

Stackline.
Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

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.