@luzmo/analytics-components-kit 1.0.8 → 1.0.9-beta.1

package/components/ai-chat/stream/chunk-extractors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pure field extractors for raw stream chunks.
+ *
+ * These read assistant text, chart, dashboard, and conversation-id values out of
+ * the various shapes a chunk can take (inline fields, `aiMessageAssets`, or a
+ * nested `result.assistant_message`). They are side-effect free, except
+ * `applyConversationId`, which forwards the id through a callback.
+ */
+import type { AiPromptCustomItemInput, DashboardStatePayload } from '../ai-prompt-types';
+import type { StreamHandlerContext } from './types';
+export declare function extractInlineStreamText(chunk: Record<string, unknown>): string;
+export declare function extractStreamText(chunk: Record<string, unknown>): string;
+/**
+ * Authoritative assistant text from a terminal chunk's `result.assistant_message`.
+ *
+ * Unlike {@link extractStreamText}, this never falls back to inline delta fields, so
+ * it is safe to use when finalizing the message: it yields the full answer to *set*
+ * (not append), avoiding duplication when the same text was already streamed as deltas.
+ */
+export declare function extractResultAssistantText(chunk: Record<string, unknown>): string;
+export declare function isStreamDone(chunk: Record<string, unknown>): boolean;
+export declare function applyConversationId(chunk: Record<string, unknown>, ctx: StreamHandlerContext): void;
+export declare function extractChartFromChunk(chunk: Record<string, unknown>): Record<string, unknown> | null;
+export declare function extractDashboardName(assets: unknown[]): Record<string, string> | undefined;
+export declare function extractDashboardFromChunk(chunk: Record<string, unknown>): DashboardStatePayload | null;
+/** Collect dashboard name from whichever asset array the chunk exposes. */
+export declare function extractDashboardNameFromChunk(chunk: Record<string, unknown>): Record<string, string> | undefined;
+/** Reads custom-item drafts from top-level or terminal assistant-message assets. */
+export declare function extractCustomItemFromChunk(chunk: Record<string, unknown>): AiPromptCustomItemInput['value'] | null;

package/components/ai-chat/stream/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * AI chat streaming — public barrel for the stream pipeline.
+ *
+ * Orchestrated by `ai-chat-session.ts` when a prompt is submitted. The pipeline
+ * has three layers: transport (HTTP + line parsing), processing (chunk → state +
+ * events), and shared helpers (field extraction).
+ *
+ * ## End-to-end flow
+ *
+ * ```
+ * submit prompt
+ *   → createInitialProgress()              // "Thinking" progress tree in the UI
+ *   → fetchStreamingResponse()             // POST to aiprompt API (or custom fetchStreaming)
+ *   → readNdjsonStream(body, onChunk)      // decode NDJSON / SSE lines into JSON objects
+ *        → createStreamHandler(agent)      // bound processStreamChunk per agent
+ *             → processStreamChunk()       // map chunk → callbacks (onStep, onComplete, …)
+ *   → session applies callbacks            // updates messages, progress, chart/dashboard
+ * ```
+ *
+ * ## Modules
+ *
+ * | File                 | Responsibility                                              |
+ * | -------------------- | ----------------------------------------------------------- |
+ * | `transport`          | HTTP fetch + NDJSON/SSE line parsing                        |
+ * | `progress`           | Initial progress tree + progress-chunk detection           |
+ * | `registry`           | Agent wiring: `createStreamHandler`, initial stream state   |
+ * | `stream-processor`   | Chunk routing, asset buffering, step/complete event emission  |
+ * | `chunk-extractors`   | Chunk field extraction (text, chart, dashboard, conversation) |
+ * | `types`              | `StreamHandlerContext`, callbacks, per-chunk state            |
+ *
+ * ## Agent mapping (`registry.ts`)
+ *
+ * - **dashboard** — `dashboardAssetType: 'dashboard'`; emits layout/title/item steps.
+ * - **item** — `chartAssetType: 'item'`; final chart on `onComplete`.
+ * - **custom-item** — `customItemAssetType: 'custom-item'`; updated draft on `onComplete`.
+ * - **analyst** — text and progress only.
+ *
+ * ## Callbacks (`StreamHandlerCallbacks`)
+ *
+ * Each chunk drives incremental UI via `onStep` (typed stream events), `onProgress`,
+ * `onMessageUpdate`, and `onProgressCollapsed`. The stream ends with a single
+ * `onComplete` carrying the final message and optional chart/dashboard payload.
+ *
+ * See `stream-processor.ts` for the full chunk-handler priority order and mapping table.
+ */
+export type { StreamingRequestOptions, StreamingResponse } from './transport';
+export { fetchStreamingResponse, parseStreamLine, readNdjsonStream } from './transport';
+export { createInitialProgress, hasProgressChunk } from './progress';
+export type { StreamChunkProcessor } from './registry';
+export { createInitialStreamState, createStreamHandler, getAgentStreamDefinition } from './registry';
+export type { AgentStreamDefinition, StreamHandlerCallbacks, StreamHandlerContext, StreamHandlerState } from './types';
+export { applyConversationId, extractChartFromChunk, extractDashboardFromChunk, extractDashboardName, extractDashboardNameFromChunk, extractInlineStreamText, extractResultAssistantText, extractStreamText, isStreamDone } from './chunk-extractors';
+export { processStreamChunk } from './stream-processor';

package/components/ai-chat/stream/progress.d.ts

@@ -0,0 +1,3 @@
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+export declare function createInitialProgress(): ProgressTreeNode;
+export declare function hasProgressChunk(value: Record<string, unknown>): boolean;

package/components/ai-chat/stream/registry.d.ts

@@ -0,0 +1,6 @@
+import type { AiPromptAgent } from '../ai-prompt-types';
+import type { AgentStreamDefinition, StreamHandlerContext } from './types';
+export type StreamChunkProcessor = (chunk: Record<string, unknown>, ctx: StreamHandlerContext) => void;
+export declare function getAgentStreamDefinition(agent: AiPromptAgent): AgentStreamDefinition;
+export declare function createStreamHandler(agent: AiPromptAgent): StreamChunkProcessor;
+export declare function createInitialStreamState(): StreamHandlerContext['state'];

package/components/ai-chat/stream/stream-processor.d.ts

@@ -0,0 +1,2 @@
+import type { AgentStreamDefinition, StreamHandlerContext } from './types';
+export declare function processStreamChunk(chunk: Record<string, unknown>, ctx: StreamHandlerContext, def: AgentStreamDefinition): void;

package/components/ai-chat/stream/transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Transport layer for AI chat streaming.
+ *
+ * Owns the HTTP request to the aiprompt API and the wire-format decoding of the
+ * response body. Knows nothing about chunk semantics — it produces raw JSON
+ * objects that `stream-processor.ts` interprets.
+ *
+ * Supports both plain NDJSON (`{"type":"progress",...}`) and SSE (`data: {...}`).
+ */
+export interface StreamingRequestOptions {
+    url: string;
+    body: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface StreamingResponse {
+    body: ReadableStream<Uint8Array>;
+    conversationId: string | null;
+}
+export declare function fetchStreamingResponse(options: StreamingRequestOptions): Promise<StreamingResponse>;
+/**
+ * Parse one line from an aiprompt response stream.
+ * Supports plain NDJSON (`{"type":"progress",...}`) and SSE (`data: {...}`).
+ */
+export declare function parseStreamLine(line: string): Record<string, unknown> | null;
+/** Read NDJSON or SSE (`data:`) chunks from a streaming aiprompt response body. */
+export declare function readNdjsonStream(body: ReadableStream<Uint8Array>, onChunk: (chunk: Record<string, unknown>) => void): Promise<void>;

package/components/ai-chat/stream/types.d.ts

@@ -0,0 +1,59 @@
+import type { ProgressTreeNode } from '@luzmo/lucero/progress-steps';
+import type { ChatMessage } from '../../../types';
+import type { AiChatCompleteEvent, AiChatStepEvent } from '../ai-chat-events';
+import type { AiPromptAgent, AiPromptCustomItemInput, DashboardStatePayload } from '../ai-prompt-types';
+export interface StreamHandlerCallbacks {
+    onConversationIdChange: (conversationId: string) => void;
+    onProgress: (progress: ProgressTreeNode) => void;
+    onProgressCollapsed: (collapsed: boolean) => void;
+    onMessageUpdate: (message: ChatMessage) => void;
+    getConversationId: () => string | null;
+    /** Fired for every incremental, assembled stream event. */
+    onStep: (event: AiChatStepEvent) => void;
+    /** Fired exactly once with the authoritative final result (or error). */
+    onComplete: (event: AiChatCompleteEvent) => void;
+}
+/** Per-asset accumulation buffer for the ASSET_START/DELTA/END channel. */
+export interface StreamAssetBuffer {
+    assetType: string;
+    snapshot: Record<string, unknown>;
+}
+export interface StreamHandlerState {
+    progressCollapsed: boolean;
+    /** Accumulated assistant text streamed so far. */
+    accumulatedText: string;
+    /** Latest classifier decision routed from the progress root node. */
+    decision: 'create' | 'edit' | 'question' | null;
+    /** In-flight asset buffers keyed by asset id (or asset type as fallback). */
+    assets: Record<string, StreamAssetBuffer>;
+    /** Authoritative dashboard snapshot (dashboard agent). */
+    dashboardSnapshot: DashboardStatePayload | null;
+    /** Dashboard name keyed by locale (dashboard agent). */
+    dashboardName: Record<string, string> | undefined;
+    /** Authoritative chart snapshot (item agent). */
+    chartSnapshot: Record<string, unknown> | null;
+    /** Authoritative custom item draft (custom-item agent). */
+    customItemSnapshot: AiPromptCustomItemInput['value'] | null;
+    /** Pending clarification question, when the agent interrupted. */
+    interruptQuestion: string | null;
+    /** Guards against firing {@link StreamHandlerCallbacks.onComplete} more than once. */
+    completed: boolean;
+}
+export interface StreamHandlerContext {
+    aiMessage: ChatMessage;
+    callbacks: StreamHandlerCallbacks;
+    state: StreamHandlerState;
+}
+/**
+ * Per-agent stream definition. The shared processor owns the envelope/emit logic;
+ * the agent only declares which final `asset_type`s map to its authoritative result.
+ */
+export interface AgentStreamDefinition {
+    agent: AiPromptAgent;
+    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.chart}. */
+    chartAssetType?: string;
+    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.dashboard}. */
+    dashboardAssetType?: string;
+    /** Final asset type whose payload becomes {@link AiChatCompleteEvent.customItem}. */
+    customItemAssetType?: string;
+}

package/components/ai-chat/types.d.ts

@@ -0,0 +1,24 @@
+import type { LuzmoChart } from '../../types';
+import type { AiPromptCustomItemInput, AiPromptItemTask, AiPromptScreenMode, DashboardStatePayload } from './ai-prompt-types';
+/** Configuration for one built-in agent. Omitted context preserves the same agent's context; null clears it. */
+export type AiChatAgentConfig = {
+    type: 'item';
+    context?: {
+        chart?: LuzmoChart | null;
+        task?: AiPromptItemTask;
+    } | null;
+} | {
+    type: 'dashboard';
+    context?: {
+        dashboard?: DashboardStatePayload | null;
+        currentScreenMode?: AiPromptScreenMode;
+    } | null;
+} | {
+    type: 'custom-item';
+    context?: {
+        customItem?: AiPromptCustomItemInput['value'] | null;
+    } | null;
+} | {
+    type: 'analyst';
+    context?: null;
+};