@4djs/assistant 0.0.1 → 0.1.0

package/README.md

@@ -1,17 +1,13 @@
-# @4d/assistant
+# @4djs/assistant
 
-Embeddable React chat assistant with LLM tool-calling, streaming, markdown rendering, and optional fallback mode when no LLM is configured.
+Embeddable React chat assistant with LLM tool-calling, streaming, markdown rendering, and an in-app LLM settings panel. Connect any OpenAI-compatible provider — cloud APIs or a local server such as Ollama or LM Studio.
 
 ## Install
 
-This package lives in the monorepo as a workspace dependency:
-
-```json
-{
-  "dependencies": {
-    "@4d/assistant": "workspace:*"
-  }
-}
+```bash
+npm install @4djs/assistant
+# or
+bun add @4djs/assistant
 ```
 
 Peer dependencies: `react` and `react-dom` (^19).
@@ -19,7 +15,7 @@ Peer dependencies: `react` and `react-dom` (^19).
 Import styles once in your app entry (required for the UI):
 
 ```ts
-import "@4d/assistant/styles.css";
+import "@4djs/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.
@@ -29,15 +25,15 @@ The stylesheet uses CSS variables from your host app (`--brand`, `--surface-pane
 The simplest integration is `AssistantRoot`, which wires the provider, store bootstrap, and default panel UI:
 
 ```tsx
-import { AssistantRoot, type AssistantConfig } from "@4d/assistant";
+import { AssistantRoot, type AssistantConfig } from "@4djs/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…",
+    enabled: true,
+    baseUrl: import.meta.env.VITE_LLM_BASE_URL ?? "https://api.openai.com/v1",
+    apiKey: import.meta.env.VITE_LLM_KEY ?? null,
+    model: import.meta.env.VITE_LLM_MODEL ?? "gpt-4o-mini",
+    systemPrompt: "You are a helpful assistant with access to tools.",
   },
   storageKeys: {
     history: "my-app-chat-history",
@@ -47,8 +43,8 @@ const config: AssistantConfig = {
     id: "welcome",
     role: "assistant",
     content: llmEnabled
-      ? `Hello! Using **${model ?? "LLM"}**.`
-      : "Hello! LLM is disabled — try `/clear` or use fallback commands.",
+      ? `Hello! Using **${model ?? "LLM"}**. Ask me anything.`
+      : "Hello! Connect an LLM in **LLM settings** to start chatting.",
     timestamp: Date.now(),
   }),
   listTools: async () => myTools,
@@ -60,7 +56,7 @@ export function MyAssistant() {
 }
 ```
 
-See [`apps/web/src/assistant/config.ts`](../../apps/web/src/assistant/config.ts) for a full production example wired to the 4D tool registry.
+When no LLM is configured, chat input is disabled and the UI prompts users to open **LLM settings**. Settings and clear-chat remain available without a provider.
 
 ## Configuration
 
@@ -80,7 +76,6 @@ See [`apps/web/src/assistant/config.ts`](../../apps/web/src/assistant/config.ts)
 | --- | --- |
 | `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`). |
@@ -91,9 +86,9 @@ See [`apps/web/src/assistant/config.ts`](../../apps/web/src/assistant/config.ts)
 {
   header: {
     title: "Assistant",
-    subtitle: "Query and explore your datastore",
-    icon: Sparkles,           // lucide-react icon
-    showClearButton: true,    // footer toolbar (default: true)
+    subtitle: "Query and explore your data",
+    icon: Sparkles,              // lucide-react icon
+    showClearButton: true,       // footer toolbar (default: true)
     showSuggestionsButton: true, // footer toolbar when fetchSuggestedPrompts is set
   },
   emptyState: {
@@ -108,7 +103,7 @@ See [`apps/web/src/assistant/config.ts`](../../apps/web/src/assistant/config.ts)
     composerPlaceholder: "Ask the assistant…",
     showModelSelector: true,
     maxWidth: "56rem",
-    className: "panel",       // extra class on the root panel
+    className: "panel",            // extra class on the root panel
   },
 }
 ```
@@ -122,12 +117,12 @@ The assistant calls an **OpenAI-compatible** chat completions API directly from
 Pass `llm` on `AssistantConfig`:
 
 ```ts
-import type { AssistantLlmSettings } from "@4d/assistant/core";
+import type { AssistantLlmSettings } from "@4djs/assistant/core";
 
 const llm: AssistantLlmSettings = {
   enabled: true,
   baseUrl: "https://api.openai.com/v1",
-  apiKey: import.meta.env.LLM_KEY ?? null,
+  apiKey: process.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
@@ -136,9 +131,9 @@ const llm: AssistantLlmSettings = {
 
 | 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. |
+| `enabled` | When `false`, chat is disabled until the user configures a provider. |
+| `baseUrl` | Provider base URL (e.g. `https://api.openai.com/v1` or `http://127.0.0.1:11434/v1`). |
+| `apiKey` | Bearer token for remote providers. Optional for local servers on `localhost`, `127.0.0.1`, or `*.local`. |
 | `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. |
@@ -157,30 +152,32 @@ llm: async () => ({
 Configure globally outside React:
 
 ```ts
-import { configureAssistantLlm } from "@4d/assistant/core";
+import { configureAssistantLlm } from "@4djs/assistant/core";
 
 configureAssistantLlm({ enabled: true, baseUrl: "…", apiKey: "…", model: "…" });
 ```
 
-### Environment variables (4D web app)
+Users can override provider settings in the built-in **LLM settings** panel. Values are persisted under `storageKeys.llmSettings` (default: `assistant-llm-settings`).
 
-The playground reads these from `.env.local` (exposed to the client via Vite `envPrefix`):
+### Environment variables
+
+A typical Vite or Next.js app might expose provider defaults like this:
 
 | 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 |
+| `VITE_LLM_KEY` / `LLM_KEY` | API key for remote providers |
+| `VITE_LLM_BASE_URL` / `LLM_BASE_URL` | Provider URL (default: OpenAI) |
+| `VITE_LLM_MODEL` / `LLM_MODEL` | Default model |
+| `VITE_LLM_MODELS` / `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.
+**Security:** Calls are made directly to the provider from the client. Any API key in your bundle is visible to users. Use scoped keys for public apps, or proxy requests through your backend for production.
 
 ## Wiring tools
 
 Tools must match the shape expected by the LLM agent:
 
 ```ts
-import type { AssistantToolDefinition, AssistantToolResult } from "@4d/assistant";
+import type { AssistantToolDefinition, AssistantToolResult } from "@4djs/assistant";
 
 const tools: AssistantToolDefinition[] = [
   {
@@ -201,7 +198,6 @@ 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) }],
   };
@@ -229,27 +225,7 @@ Array<{
 }>
 ```
 
-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.
+Use `parseSuggestedPromptsResponse` from `@4djs/assistant/core` to validate LLM JSON output.
 
 ## Custom composition
 
@@ -262,7 +238,7 @@ import {
   Assistant,
   useAssistant,
   useAssistantActions,
-} from "@4d/assistant";
+} from "@4djs/assistant";
 
 function CustomShell() {
   const messages = useAssistant((s) => s.messages);
@@ -275,7 +251,7 @@ export function App() {
     <AssistantProvider config={config}>
       <AssistantBootstrap>
         <CustomShell />
-      </AssistantProvider>
+      </AssistantBootstrap>
     </AssistantProvider>
   );
 }
@@ -285,7 +261,7 @@ Exported building blocks include `ChatComposer`, `ChatMessageView`, `ChatEmptySt
 
 ## 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.
+The input supports slash commands (e.g. `/clear`). Extend commands via `runAssistantChatCommand` and related helpers from `@4djs/assistant/core`, or handle custom logic before `sendChat` in your host app.
 
 ## Core package
 
@@ -298,7 +274,8 @@ import {
   buildLlmHistory,
   fetchLlmStatus,
   runAssistantChatCommand,
-} from "@4d/assistant/core";
+  isLlmConfigured,
+} from "@4djs/assistant/core";
 ```
 
 Useful for server routes, tests, or a fully custom UI.
@@ -307,9 +284,11 @@ Useful for server routes, tests, or a fully custom UI.
 
 | Import | Contents |
 | --- | --- |
-| `@4d/assistant` | React components, hooks, types |
-| `@4d/assistant/core` | Store, LLM client, commands, interactive tools |
-| `@4d/assistant/styles.css` | Component styles |
+| `@4djs/assistant` | React components, hooks, types |
+| `@4djs/assistant/core` | Store, LLM client, commands, interactive tools |
+| `@4djs/assistant/styles.css` | Component styles |
+
+The published package ships compiled JavaScript and TypeScript declarations from `dist/`. Source is not included in the tarball.
 
 ## Features
 
@@ -317,6 +296,8 @@ Useful for server routes, tests, or a fully custom UI.
 - Interactive tool UI (confirmations, choices, reply suggestions)
 - Markdown + GFM + math (KaTeX) + Mermaid diagrams
 - Model selector with searchable dropdown
+- In-app LLM settings (cloud or local OpenAI-compatible endpoints)
 - 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
+- Structured error states with retry actions

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@4djs/assistant",
-	"version": "0.0.1",
+	"version": "0.1.0",
 	"type": "module",
 	"types": "./dist/react/index.d.ts",
 	"files": [