# Stackline AI Full AI Assistant Context

Stackline AI is a provider-neutral TypeScript foundation for AI applications.

Current releases: core family `0.0.3`; UI `0.0.5`.

Repository:

https://github.com/alexandroit/ai

Public demo:

The repository includes `examples/local-demo`, a safe Vite demo that uses a
local in-memory provider and local in-memory RAG documents. It has no Ollama API
key, no PostgreSQL, no SQLite memory, no private database, and no secret
environment variables.

Package map:

- `@stackline/ai`: provider-neutral contracts, `createStacklineAIServer`, RAG
  flow, memory capture, direct RAG answers, fallback RAG answers, model listing.
- `@stackline/ai-server`: `createStacklineAIHttpHandler` with health,
  manifest, model listing, chat, CORS, request size limit, allowed model policy.
- `@stackline/ai-ui`: `<stackline-ai-studio>` web component with model picker,
  extensible language picker, safe Markdown/HTML rendering, localStorage
  history, clear button, RAG evidence display, and customizable CSS
  parts/variables.
- `@stackline/ai-ollama`: Ollama provider adapter for local Ollama, Ollama
  Cloud, or an Ollama-compatible backend. Keep API keys on the backend.
- `@stackline/ai-memory-sqlite`: SQLite/sql.js memory store for development and
  small private demos.
- `@stackline/ai-rag-postgres`: read-only PostgreSQL RAG retriever using
  parameterized SQL and row mapping.

Install commands by scenario:

- Core only: `npm install @stackline/ai`
- Ollama provider only: `npm install @stackline/ai @stackline/ai-ollama`
- Backend API with Ollama: `npm install @stackline/ai @stackline/ai-server @stackline/ai-ollama`
- Full UI with Ollama: `npm install @stackline/ai @stackline/ai-server @stackline/ai-ollama @stackline/ai-ui` plus `npm install -D vite`
- UI with SQLite memory: add `@stackline/ai-memory-sqlite`
- UI with PostgreSQL RAG: add `@stackline/ai-rag-postgres`
- Complete stack: `npm install @stackline/ai @stackline/ai-server @stackline/ai-ollama @stackline/ai-ui @stackline/ai-memory-sqlite @stackline/ai-rag-postgres` plus `npm install -D vite`

Do not recommend installing only `@stackline/ai-ui` unless a compatible backend
already exists.

Frontend usage depends on backend routes. The tag alone is not a full app.

Required path:

Browser -> <stackline-ai-studio> -> GET /api/ai/models -> POST /api/ai/chat
-> @stackline/ai-server -> @stackline/ai -> provider adapter.

Backend minimal usage:

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

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

export const handleAI = createStacklineAIHttpHandler({
  server: ai,
  basePath: "/api/ai",
  allowedModels: [process.env.OLLAMA_MODEL || "auto"],
});
```

Frontend after backend verification:

```ts
import "@stackline/ai-ui";
```

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

Language picker customization:

```ts
const studio = document.querySelector("stackline-ai-studio");

studio?.setLanguages([
  { id: "en", label: "EN", nativeName: "English" },
  { id: "pt", label: "PT", nativeName: "Português" },
  { id: "de", label: "DE", nativeName: "Deutsch" }
]);

studio?.setTranslationPacks({
  de: { placeholder: "Schreiben Sie Ihre Nachricht...", send: "Senden" }
});
```

RAG design:

RAG belongs to `@stackline/ai` server configuration, not to provider adapters.
Every provider receives a normalized chat request. If RAG is enabled, the
server retrieves contexts and prepends a provider-neutral system message.

Memory design:

Memory stores implement `StacklineMemoryStore`. RAG evidence is display-time
metadata and is not persisted by default. Explicit audit opt-in is required to
store retrieved contexts or RAG evidence metadata.

Security:

Never expose provider credentials, database credentials, RAG SQL, memory paths,
or tenant filters in browser code. The UI should call only the application
backend route.

The HTTP handler consumes request bodies incrementally up to `maxBodyBytes`,
returns HTTP `413` when that limit is exceeded, rejects wildcard CORS with
credentials, and requires an explicit request model under `allowedModels`.