@stackline/ai-ollama

Ollama provider adapter for Stackline AI, supporting local Ollama, Ollama-compatible APIs, explicit model selection, model: "auto", model listing, and backend-only provider credentials.

Documentation & Live Demos | npm | Issues | Repository | Community Discussions

Latest tested package release: 0.0.2

Credits: Stackline AI package architecture, publishing, and documentation by Alexandro Paixao Marques.

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.

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 | ✅ |

Table of Contents

1. Why this package?
2. Features
3. Status
4. What This Package Does
5. Install By Situation
6. Step 1: Validate Ollama Before Stackline
7. Step 2: Use An Explicit Model First
8. Step 3: Expose It Through The Server
9. model: "auto"
10. Model Empty Troubleshooting
11. Security

Status

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

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.

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

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 To Use

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

When Not To Use

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

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.

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.

Test The Example

pnpm --filter stackline-ai-example-ollama-minimal smoke

Security

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

Limitations

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

Versioning

Use the same release line as @stackline/ai.

License

MIT

Documentation

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