AI Chat

ai v0.1.0 react, svelte, web

Headless AI chat core (OpenAI-compatible streaming, model fallback, token estimation, function calling with human-in-the-loop confirmation, local/backend history) with React, Svelte, and framework-free Web adapters. BYOK — the API key always comes from your app's config, never hardcoded.

Variables de entorno

Clave	Requerida	Descripción
`OPENROUTER_API_KEY`	No	API key for OpenRouter, the default OpenAI-compatible provider (baseURL https://openrouter.ai/api/v1). BYOK — passed by your app into ChatConfig.apiKey, never hardcoded in this component.
`OPENAI_API_KEY`	No	API key used only if you set LLM_BASE_URL to point at OpenAI directly instead of OpenRouter.
`LLM_BASE_URL`	No	Optional override for ChatConfig.baseURL. Defaults to OpenRouter; set to any OpenAI-compatible /chat/completions endpoint (OpenAI, LiteLLM, self-hosted gateway).

Instalación manual

Descarga el tarball y copia cada archivo listado abajo a su ruta destino:

curl -L -o ai-chat.tar.gz https://TU_HOST/registry/ai-chat.tar.gz
tar -xzf ai-chat.tar.gz

Origen	Destino en tu proyecto
`core/client.ts`	`src/modularcore/ai-chat/core/client.ts`
`core/stream.ts`	`src/modularcore/ai-chat/core/stream.ts`
`core/chat.ts`	`src/modularcore/ai-chat/core/chat.ts`
`core/fallback.ts`	`src/modularcore/ai-chat/core/fallback.ts`
`core/tokens.ts`	`src/modularcore/ai-chat/core/tokens.ts`
`core/tools.ts`	`src/modularcore/ai-chat/core/tools.ts`
`core/history/types.ts`	`src/modularcore/ai-chat/core/history/types.ts`
`core/history/local.ts`	`src/modularcore/ai-chat/core/history/local.ts`
`core/history/backend.ts`	`src/modularcore/ai-chat/core/history/backend.ts`
`ui/markdown.ts`	`src/modularcore/ai-chat/ui/markdown.ts`
`adapters/react/use-chat.ts`	`src/modularcore/ai-chat/adapters/react/use-chat.ts`
`adapters/svelte/create-chat.svelte.ts`	`src/modularcore/ai-chat/adapters/svelte/create-chat.svelte.ts`
`adapters/web/chat-element.ts`	`src/modularcore/ai-chat/adapters/web/chat-element.ts`

Instalación con CLI

modularcore add ai-chat

Documentación

# @modularcore/ai-chat

Headless AI chat core — OpenAI-compatible streaming, model fallback, token usage tracking,
function calling with human-in-the-loop confirmation, and local/backend history — with thin
React, Svelte, and framework-free Web adapters on top.

BYOK (Bring Your Own Key). The core never hardcodes or reads an API key from the
environment itself: your app passes apiKey (and optionally baseURL) into ChatConfig. This
lets you point at OpenRouter (the default), OpenAI directly, or any other OpenAI-compatible
/chat/completions endpoint — including your own server-side proxy, so the key never reaches
the browser.

## What's in this package

- core/client.ts — thin fetch-based OpenAI-compatible client (requestChatCompletionStream).
- core/stream.ts — real SSE parser over the raw ReadableStream<Uint8Array> fetch returns.
- core/chat.ts — Chat, the headless orchestrator (streaming, tool-call loop, history).
- core/fallback.ts — tries an ordered list of models, falling back on failure.
- core/tokens.ts — parses provider usage payloads.
- core/tools.ts — function-calling registry + human-in-the-loop dispatch.
- core/history/* — pluggable conversation history (local storage or your own backend).
- ui/markdown.ts — dependency-free Markdown → HTML renderer that escapes all untrusted text
before adding any formatting markup, so its output is safe to assign to innerHTML/{@html}.
- adapters/react, adapters/svelte, adapters/web — thin bindings over Chat for each
framework (Svelte adapter uses Svelte 5 runes).

## Basic usage (Svelte 5)

import { createChat } from '@modularcore/ai-chat/svelte';

const chat = createChat({
  apiKey: import.meta.env.VITE_OPENROUTER_API_KEY, // or proxy through your own backend
  models: ['openai/gpt-4o-mini'],
});

await chat.send('Hello!');

For a public-facing playground, never ship a real key to the client — proxy requests through a
server-side endpoint that injects the key (see apps/web/src/routes/api/chat/+server.ts in this
monorepo for a hardened example: rate limiting, a model allowlist, a max-tokens cap, tools
disabled, and real streaming passthrough).

## More docs

- [docs/backend-history-contract.md](./docs/backend-history-contract.md) — the contract your
backend must implement if you use core/history/backend.ts instead of local storage.