@4djs/assistant 0.0.0

package/README.md

@@ -0,0 +1,322 @@
+# @4d/assistant
+
+Embeddable React chat assistant with LLM tool-calling, streaming, markdown rendering, and optional fallback mode when no LLM is configured.
+
+## Install
+
+This package lives in the monorepo as a workspace dependency:
+
+```json
+{
+  "dependencies": {
+    "@4d/assistant": "workspace:*"
+  }
+}
+```
+
+Peer dependencies: `react` and `react-dom` (^19).
+
+Import styles once in your app entry (required for the UI):
+
+```ts
+import "@4d/assistant/styles.css";
+```
+
+The stylesheet uses CSS variables from your host app (`--brand`, `--surface-panel`, `--text-heading`, etc.). Define those tokens in your global CSS so the assistant matches your design system.
+
+## Quick start
+
+The simplest integration is `AssistantRoot`, which wires the provider, store bootstrap, and default panel UI:
+
+```tsx
+import { AssistantRoot, type AssistantConfig } from "@4d/assistant";
+
+const config: AssistantConfig = {
+  llm: {
+    enabled: Boolean(import.meta.env.LLM_KEY),
+    baseUrl: import.meta.env.LLM_BASE_URL ?? "https://api.openai.com/v1",
+    apiKey: import.meta.env.LLM_KEY ?? null,
+    model: import.meta.env.LLM_MODEL ?? "gpt-4o-mini",
+    systemPrompt: "You are a helpful assistant…",
+  },
+  storageKeys: {
+    history: "my-app-chat-history",
+    llmSettings: "my-app-llm-settings",
+  },
+  welcomeMessage: ({ llmEnabled, model }) => ({
+    id: "welcome",
+    role: "assistant",
+    content: llmEnabled
+      ? `Hello! Using **${model ?? "LLM"}**.`
+      : "Hello! LLM is disabled — try `/clear` or use fallback commands.",
+    timestamp: Date.now(),
+  }),
+  listTools: async () => myTools,
+  invokeTool: async (name, args) => myToolRunner(name, args),
+};
+
+export function MyAssistant() {
+  return <AssistantRoot config={config} />;
+}
+```
+
+See [`apps/web/src/assistant/config.ts`](../../apps/web/src/assistant/config.ts) for a full production example wired to the 4D tool registry.
+
+## Configuration
+
+`AssistantConfig` extends the store dependencies with UI options.
+
+### Required store hooks
+
+| Option | Description |
+| --- | --- |
+| `welcomeMessage(ctx)` | Returns the initial assistant message. Called again when LLM status or model changes. |
+| `listTools()` | Returns OpenAI-style tool definitions (`name`, `description`, `inputSchema`). |
+| `invokeTool(name, args)` | Executes a tool and returns `{ content, isError?, structuredContent? }`. |
+
+### Optional store hooks
+
+| Option | Description |
+| --- | --- |
+| `llm` | OpenAI-compatible provider settings (see below). |
+| `storageKeys` | `localStorage` keys for chat history and LLM settings (including selected model). |
+| `fallbackHandler` | Called when LLM is disabled. Return an `AssistantMessage` or `null`. |
+| `onToolInvoked` | Side-effect hook after each tool completes (e.g. refresh app state). |
+| `fetchSuggestedPrompts` | Async hook to generate contextual starter prompts via LLM. |
+| `autoLoadLlmStatus` | Fetch LLM config on mount (default: `true`). |
+
+### UI options
+
+```ts
+{
+  header: {
+    title: "Assistant",
+    subtitle: "Query and explore your datastore",
+    icon: Sparkles,           // lucide-react icon
+    showClearButton: true,    // footer toolbar (default: true)
+    showSuggestionsButton: true, // footer toolbar when fetchSuggestedPrompts is set
+  },
+  emptyState: {
+    title: "Get started",
+    description: "Ask a question or pick a suggestion below.",
+    dynamicSuggestedPrompts: true,  // manual LLM fetch on welcome screen
+    suggestedPrompts: [             // static fallback when LLM is off
+      { id: "catalog", label: "Show catalog", prompt: "catalog", icon: Database },
+    ],
+  },
+  ui: {
+    composerPlaceholder: "Ask the assistant…",
+    showModelSelector: true,
+    maxWidth: "56rem",
+    className: "panel",       // extra class on the root panel
+  },
+}
+```
+
+Per-instance overrides are supported via `Assistant` / `AssistantRoot` props: `header`, `emptyState`, `ui`.
+
+## LLM provider
+
+The assistant calls an **OpenAI-compatible** chat completions API directly from the browser (or your host runtime). No proxy `/api/chat` routes are required.
+
+Pass `llm` on `AssistantConfig`:
+
+```ts
+import type { AssistantLlmSettings } from "@4d/assistant/core";
+
+const llm: AssistantLlmSettings = {
+  enabled: true,
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: import.meta.env.LLM_KEY ?? null,
+  model: "gpt-4o-mini",
+  systemPrompt: "You are a helpful assistant with access to tools.",
+  models: ["gpt-4o-mini", "gpt-4o"], // optional static list
+};
+```
+
+| Field | Description |
+| --- | --- |
+| `enabled` | When `false`, or when `apiKey` is missing, fallback mode is used. |
+| `baseUrl` | Provider base URL (e.g. `https://api.openai.com/v1`). |
+| `apiKey` | Bearer token for the provider. |
+| `model` | Default model when the user has not picked one. |
+| `models` | Optional static model list. When omitted, models are fetched from `{baseUrl}/models`. |
+| `systemPrompt` | Prepended system message for each completion. |
+
+You can also pass a resolver function for dynamic config:
+
+```ts
+llm: async () => ({
+  enabled: true,
+  baseUrl: "https://api.openai.com/v1",
+  apiKey: await getApiKeyFromSecureStorage(),
+  model: "gpt-4o-mini",
+}),
+```
+
+Configure globally outside React:
+
+```ts
+import { configureAssistantLlm } from "@4d/assistant/core";
+
+configureAssistantLlm({ enabled: true, baseUrl: "…", apiKey: "…", model: "…" });
+```
+
+### Environment variables (4D web app)
+
+The playground reads these from `.env.local` (exposed to the client via Vite `envPrefix`):
+
+| Variable | Description |
+| --- | --- |
+| `LLM_KEY` | API key (required to enable LLM) |
+| `LLM_BASE_URL` | Provider URL (default: OpenAI) |
+| `LLM_MODEL` | Default model |
+| `LLM_MODELS` | Comma-separated extra models for the selector |
+
+**Note:** Because calls are made directly to the provider, the API key is available to the client bundle. Use this pattern for local/dev playgrounds or when the key is scoped and acceptable in the browser.
+
+## Wiring tools
+
+Tools must match the shape expected by the LLM agent:
+
+```ts
+import type { AssistantToolDefinition, AssistantToolResult } from "@4d/assistant";
+
+const tools: AssistantToolDefinition[] = [
+  {
+    name: "query_entity",
+    description: "Query records from a dataclass",
+    inputSchema: {
+      type: "object",
+      properties: {
+        entity: { type: "string" },
+        filter: { type: "string" },
+      },
+      required: ["entity"],
+    },
+  },
+];
+
+async function invokeTool(
+  name: string,
+  args: Record<string, unknown>,
+): Promise<AssistantToolResult> {
+  // run tool, return text content for the model
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+  };
+}
+```
+
+The store passes `listTools` output to the LLM on each turn and calls `invokeTool` for each tool call in the response.
+
+## Suggested prompts
+
+Two modes:
+
+1. **Static** — set `emptyState.suggestedPrompts` with `label`, `hint`, `prompt`, and optional Lucide `icon`.
+2. **Dynamic** — implement `fetchSuggestedPrompts`. The UI does **not** auto-fetch; users click **Generate suggestions** on the welcome screen or the sparkles button in the composer footer.
+
+Dynamic fetch receives `{ llmEnabled, model, tools }` and should return:
+
+```ts
+Array<{
+  id: string;
+  label: string;
+  description?: string;
+  prompt: string;
+  icon?: string; // e.g. "database", "search", "sparkles"
+}>
+```
+
+Use `parseSuggestedPromptsResponse` from `@4d/assistant/core` to validate LLM JSON output.
+
+## Fallback mode (no LLM)
+
+When `configUrl` reports `enabled: false`, the assistant skips the LLM and calls `fallbackHandler` instead:
+
+```ts
+fallbackHandler: async ({ message, tools }) => {
+  if (message === "catalog") {
+    return {
+      id: crypto.randomUUID(),
+      role: "assistant",
+      content: "Here is your catalog…",
+      timestamp: Date.now(),
+    };
+  }
+  return null;
+},
+```
+
+Return `null` to show a generic “LLM disabled” message.
+
+## Custom composition
+
+Use lower-level exports to build your own layout:
+
+```tsx
+import {
+  AssistantProvider,
+  AssistantBootstrap,
+  Assistant,
+  useAssistant,
+  useAssistantActions,
+} from "@4d/assistant";
+
+function CustomShell() {
+  const messages = useAssistant((s) => s.messages);
+  const { sendChat } = useAssistantActions();
+  // render your own chrome around <Assistant /> or individual chat components
+}
+
+export function App() {
+  return (
+    <AssistantProvider config={config}>
+      <AssistantBootstrap>
+        <CustomShell />
+      </AssistantProvider>
+    </AssistantProvider>
+  );
+}
+```
+
+Exported building blocks include `ChatComposer`, `ChatMessageView`, `ChatEmptyState`, `ChatActivity`, `ModelSelector`, `MarkdownContent`, and `MermaidDiagram`.
+
+## Composer commands
+
+The input supports slash commands (e.g. `/clear`). Extend commands in `@4d/assistant/core` via `chat-commands.ts` or handle custom logic before `sendChat` in your host app.
+
+## Core package
+
+Import headless logic without React:
+
+```ts
+import {
+  createAssistantStore,
+  runLlmAgent,
+  buildLlmHistory,
+  fetchLlmStatus,
+  runAssistantChatCommand,
+} from "@4d/assistant/core";
+```
+
+Useful for server routes, tests, or a fully custom UI.
+
+## Package exports
+
+| Import | Contents |
+| --- | --- |
+| `@4d/assistant` | React components, hooks, types |
+| `@4d/assistant/core` | Store, LLM client, commands, interactive tools |
+| `@4d/assistant/styles.css` | Component styles |
+
+## Features
+
+- Streaming LLM responses with tool-call activity timeline
+- Interactive tool UI (confirmations, choices, reply suggestions)
+- Markdown + GFM + math (KaTeX) + Mermaid diagrams
+- Model selector with searchable dropdown
+- Persistent chat history and model preference (`localStorage`)
+- Welcome screen with static or LLM-generated starter prompts
+- Composer footer toolbar: model selector, generate suggestions, clear chat

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@4djs/assistant",
+	"version": "0.0.0",
+	"type": "module",
+	"exports": {
+		".": "./src/react/index.ts",
+		"./core": "./src/core/index.ts",
+		"./styles.css": "./src/styles/assistant.css"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"build": "bun run build:core && bun run build:react && bun run build:styles",
+		"build:core": "bun build ./src/core/index.ts --outdir ./dist/core --target node --format esm",
+		"build:react": "bun build ./src/react/index.ts --outdir ./dist --target browser --external react --external react-dom --format esm",
+		"build:styles": "mkdir -p dist && cp src/styles/assistant.css dist/styles.css",
+		"prepack": "bun run build"
+	},
+	"dependencies": {
+		"highlight.js": "11.11.1",
+		"katex": "0.17.0",
+		"lucide-react": "^0.511.0",
+		"mermaid": "11.15.0",
+		"react-markdown": "10.1.0",
+		"rehype-katex": "7.0.1",
+		"remark-gfm": "4.0.1",
+		"remark-math": "6.0.0",
+		"zustand": "^5.0.5"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0"
+	},
+	"devDependencies": {
+		"@4d/typescript-config": "workspace:*",
+		"@types/react": "^19.1.2",
+		"@types/react-dom": "^19.1.2",
+		"react": "^19.1.0",
+		"react-dom": "^19.1.0",
+		"typescript": "catalog:"
+	}
+}

package/src/core/chat-activity.ts

@@ -0,0 +1,107 @@
+export type ChatActivityStatus = "active" | "done" | "error";
+
+export interface ChatActivityStep {
+	id: string;
+	kind: "tool";
+	name: string;
+	args: Record<string, unknown>;
+	callId?: string;
+	status: ChatActivityStatus;
+	result?: unknown;
+	error?: string;
+}
+
+export function summarizeActivityResult(result: unknown): unknown {
+	if (result === undefined || result === null) return result;
+	if (typeof result !== "object") return result;
+
+	const value = result as Record<string, unknown>;
+	if ("structuredContent" in value) {
+		return value.structuredContent ?? value;
+	}
+	if ("content" in value && Array.isArray(value.content)) {
+		return value.content;
+	}
+	return result;
+}
+
+export function chatActivityStepLabel(step: ChatActivityStep): string {
+	if (step.status === "active") {
+		if (step.name === "request_confirmation")
+			return "Waiting for confirmation…";
+		if (step.name === "request_choices") return "Waiting for your choice…";
+		if (step.name === "suggest_replies") return "Suggesting replies…";
+		return `Running ${step.name}…`;
+	}
+	if (step.status === "error") return `${step.name} failed`;
+	if (step.name === "request_confirmation") return "Confirmation answered";
+	if (step.name === "request_choices") return "Choice submitted";
+	if (step.name === "suggest_replies") return "Reply suggestions shown";
+	return `Ran ${step.name}`;
+}
+
+export function formatJsonIfLarge(raw: string): string {
+	const trimmed = raw.trim();
+	const JSON_PRETTY_MIN_LENGTH = 80;
+
+	if (trimmed.length < JSON_PRETTY_MIN_LENGTH) {
+		return trimmed;
+	}
+
+	try {
+		return JSON.stringify(JSON.parse(trimmed), null, 2);
+	} catch {
+		return trimmed;
+	}
+}
+
+export function formatActivityJson(raw?: string): string | null {
+	if (!raw?.trim()) return null;
+
+	try {
+		return JSON.stringify(JSON.parse(raw), null, 2);
+	} catch {
+		return raw;
+	}
+}
+
+export function formatActivityJsonValue(value: unknown): string | null {
+	if (value === undefined || value === null) return null;
+	if (typeof value === "string") return formatActivityJson(value);
+	try {
+		return JSON.stringify(value, null, 2);
+	} catch {
+		return String(value);
+	}
+}
+
+export function isEmptyActivityJson(value: unknown): boolean {
+	if (value === undefined || value === null) return true;
+
+	if (typeof value === "object" && !Array.isArray(value)) {
+		return Object.keys(value as Record<string, unknown>).length === 0;
+	}
+
+	if (typeof value === "string") {
+		if (!value.trim()) return true;
+		try {
+			const parsed = JSON.parse(value) as unknown;
+			return (
+				(typeof parsed === "object" &&
+					parsed !== null &&
+					Object.keys(parsed).length === 0) ||
+				parsed === null
+			);
+		} catch {
+			return false;
+		}
+	}
+
+	return false;
+}
+
+export function stepHasDetails(step: ChatActivityStep): boolean {
+	if (step.error?.trim()) return true;
+	if (step.result !== undefined && step.result !== null) return true;
+	return !isEmptyActivityJson(step.args);
+}

package/src/core/chat-commands.ts

@@ -0,0 +1,173 @@
+export type ChatCommandSurface = "assistant";
+
+export type ChatCommandRunResult = {
+	handled: boolean;
+	clearInput?: boolean;
+	error?: string;
+};
+
+export type AssistantCommandDeps = {
+	clearMessages: () => void;
+	setError: (error: string | null) => void;
+	streaming: boolean;
+};
+
+const CHAT_COMMANDS = [
+	{
+		name: "clear",
+		description: "Clear the current conversation",
+		surfaces: ["assistant"] as const,
+		run: async (args: string, deps: AssistantCommandDeps) => {
+			if (args) {
+				throw new Error("The /clear command does not accept arguments.");
+			}
+			if (deps.streaming) {
+				throw new Error("Wait for the assistant to finish before clearing.");
+			}
+			deps.clearMessages();
+			deps.setError(null);
+		},
+	},
+] satisfies Array<{
+	name: string;
+	description: string;
+	surfaces: readonly ChatCommandSurface[];
+	run: (args: string, deps: AssistantCommandDeps) => void | Promise<void>;
+}>;
+
+export type ChatCommandSuggestion = {
+	name: string;
+	description: string;
+	usage: string;
+};
+
+export function getChatCommandSuggestions(
+	surface: ChatCommandSurface,
+): ChatCommandSuggestion[] {
+	return CHAT_COMMANDS.filter((command) =>
+		command.surfaces.includes(surface),
+	).map(({ name, description }) => ({
+		name,
+		description,
+		usage: `/${name}`,
+	}));
+}
+
+export function isChatCommandInput(value: string): boolean {
+	return value.trimStart().startsWith("/");
+}
+
+export function filterChatCommands(
+	value: string,
+	surface: ChatCommandSurface,
+): ChatCommandSuggestion[] {
+	if (!isChatCommandInput(value)) {
+		return [];
+	}
+
+	const query = value.trimStart().slice(1).toLowerCase();
+	const commands = getChatCommandSuggestions(surface);
+
+	if (!query) {
+		return commands;
+	}
+
+	return commands.filter(
+		(command) =>
+			command.name.startsWith(query) ||
+			command.usage.toLowerCase().startsWith(`/${query}`),
+	);
+}
+
+export function shouldShowChatCommandMenu(
+	value: string,
+	surface: ChatCommandSurface,
+): boolean {
+	if (!isChatCommandInput(value) || value.includes("\n")) {
+		return false;
+	}
+
+	const trimmed = value.trimStart();
+	if (trimmed.includes(" ")) {
+		return false;
+	}
+
+	return filterChatCommands(value, surface).length > 0;
+}
+
+export function completionForChatCommand(
+	command: ChatCommandSuggestion,
+): string {
+	return `${command.usage} `;
+}
+
+export function listChatCommands(surface?: ChatCommandSurface): Array<{
+	name: string;
+	description: string;
+}> {
+	return CHAT_COMMANDS.filter(
+		(command) => !surface || command.surfaces.includes(surface),
+	).map(({ name, description }) => ({ name, description }));
+}
+
+export function parseChatCommand(
+	input: string,
+): { name: string; args: string } | null {
+	const trimmed = input.trim();
+	const match = /^\/([a-z][a-z0-9_-]*)(?:\s+([\s\S]*))?$/i.exec(trimmed);
+	if (!match) {
+		return null;
+	}
+
+	const name = match[1];
+	if (!name) {
+		return null;
+	}
+
+	return {
+		name: name.toLowerCase(),
+		args: (match[2] ?? "").trim(),
+	};
+}
+
+async function executeCommand(
+	parsed: { name: string; args: string },
+	deps: AssistantCommandDeps,
+): Promise<ChatCommandRunResult> {
+	const command = CHAT_COMMANDS.find((entry) => entry.name === parsed.name);
+	if (!command?.surfaces.includes("assistant")) {
+		return {
+			handled: true,
+			clearInput: true,
+			error: `Unknown command: /${parsed.name}`,
+		};
+	}
+
+	try {
+		await command.run(parsed.args, deps);
+		return { handled: true, clearInput: true };
+	} catch (error) {
+		return {
+			handled: true,
+			clearInput: true,
+			error: error instanceof Error ? error.message : "Command failed",
+		};
+	}
+}
+
+export async function runAssistantChatCommand(
+	input: string,
+	deps: AssistantCommandDeps,
+): Promise<ChatCommandRunResult> {
+	const parsed = parseChatCommand(input);
+	if (!parsed) {
+		return { handled: false };
+	}
+
+	return executeCommand(parsed, deps);
+}
+
+/** @deprecated Use runAssistantChatCommand instead */
+export function isClearCommand(text: string): boolean {
+	return parseChatCommand(text)?.name === "clear";
+}