@magemetrics/ai 0.11.0 → 0.11.3

package/dist/react/index.d.ts

@@ -94,6 +94,46 @@ export declare interface ChatContextValue {
     enableSpeechToText?: boolean;
 }
 
+/**
+ * Optional provider that allows the host application to pass dynamic runtime hints
+ * to the chat. The hints are sent with every message and injected ephemerally into
+ * the LLM prompt — they are not persisted or shown in the UI.
+ * Place this anywhere inside `MageMetricsContextProvider` and around the `Chat` component.
+ * When the `value` prop changes, the next message sent will carry the updated hints.
+ * If this provider is not used, no hints are sent — everything works as before.
+ * @param props - The provider props
+ * @param props.value - The chat hints value to provide
+ * @param props.children - The child components
+ * @returns The provider component wrapping children
+ */
+export declare const ChatHintsProvider: default_2.FC<ChatHintsProviderProps>;
+
+declare interface ChatHintsProviderProps {
+    /**
+     * Arbitrary key-value hints from the host application.
+     * These are sent alongside every chat message and injected into the LLM prompt.
+     * @example
+     * ```tsx
+     * <ChatHintsProvider value={{
+     *   selectedLocation: { lat: 48.8566, lng: 2.3522, name: "Paris" },
+     *   activeFilters: ["revenue > 1M"],
+     * }}>
+     *   <Chat flowId="..." />
+     * </ChatHintsProvider>
+     * ```
+     */
+    value: ChatHintsValue;
+    children: default_2.ReactNode;
+}
+
+/**
+ * The value type for chat hints — a free-form key-value object
+ * that the host application can use to pass runtime information to the LLM.
+ * These hints are injected ephemerally into each chat message (not persisted)
+ * so the LLM is aware of the host application's current state.
+ */
+export declare type ChatHintsValue = Record<string, unknown>;
+
 export declare interface ChatInputContextValue {
     flowId: string | undefined;
     isLoading: boolean;
@@ -293,8 +333,8 @@ declare const FrontendReportSchema: z.ZodObject<{
             avg_length: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$loose>>;
     }, z.core.$loose>;
-    is_removed: z.ZodBoolean;
     flow_id: z.ZodString;
+    is_removed: z.ZodBoolean;
     is_materialized: z.ZodNullable<z.ZodBoolean>;
     last_materialized_at: z.ZodNullable<z.ZodString>;
     materialized_error_message: z.ZodNullable<z.ZodString>;
@@ -350,7 +390,6 @@ declare const FrontendVisualizationSchema: z.ZodObject<{
         type: z.ZodLiteral<"pie">;
     }, z.core.$strip>], "type">;
     created_at: z.ZodString;
-    flow_data_id: z.ZodNumber;
     flow_data: z.ZodOptional<z.ZodObject<{
         is_materialized: z.ZodNullable<z.ZodBoolean>;
         last_materialized_at: z.ZodNullable<z.ZodString>;
@@ -361,6 +400,7 @@ declare const FrontendVisualizationSchema: z.ZodObject<{
             running: "running";
         }>>;
     }, z.core.$strip>>;
+    flow_data_id: z.ZodNumber;
 }, z.core.$strip>;
 
 declare const InputContainer: default_2.FC<{
@@ -625,6 +665,12 @@ is_public: boolean;
 
 export declare const useChatContext: () => ChatContextValue;
 
+/**
+ * Returns the current chat hints value, or `null` if no `ChatHintsProvider` is present.
+ * @returns The current chat hints value or null
+ */
+export declare const useChatHints: () => ChatHintsValue | null;
+
 export declare const useChatInputContext: () => ChatInputContextValue;
 
 export declare const useCreateFlow: (options?: UseMutationOptions<{
@@ -746,7 +792,7 @@ export declare const useCreateFlow: (options?: UseMutationOptions<{
 };
 
 export declare const useDataReportColumnValue: (reportId: number, filters: ReportDataFilters) => UseQueryResult<    {
-[key: string]: unknown;
+[x: string]: unknown;
 }[], Error>;
 
 export declare const useDataTableContext: () => {
@@ -777,26 +823,26 @@ export declare const useDataTableContext: () => {
                 avg_length?: number | null | undefined;
             }>;
         };
-        is_removed: boolean;
         flow_id: string;
+        is_removed: boolean;
         is_materialized: boolean | null;
         last_materialized_at: string | null;
         materialized_error_message: string | null;
         materialized_status: "completed" | "running" | "failed" | null;
     };
     fetchNextPage: (options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult<InfiniteData<    {
-    [key: string]: unknown;
+    [x: string]: unknown;
     }[], unknown>, Error>>;
     pages: {
-        [key: string]: unknown;
+        [x: string]: unknown;
     }[][] | undefined;
     columns: {
         name: string;
         data_type: string;
         dataType: string;
-        renderType?: string;
-        unit?: string;
-        canonicalDataType?: "numeric" | "boolean" | "datetime" | "text" | "array" | "json" | "other";
+        renderType?: string | undefined;
+        unit?: string | undefined;
+        canonicalDataType?: "numeric" | "boolean" | "datetime" | "text" | "array" | "json" | "other" | undefined;
     }[] | undefined;
     isPendingColumns: boolean;
     hasMoreData: boolean;
@@ -905,29 +951,27 @@ export declare const useReport: (reportId: number) => {
         title: string;
         request: string | null;
         data_summary: {
+            [x: string]: unknown;
             columns: {
-                [key: string]: {
-                    position?: number;
+                [x: string]: {
+                    [x: string]: unknown;
+                    position?: number | undefined;
                     data_type: string;
                     null_count: number | null;
                     unique_count: number | null;
                     unique_percentage: number | null;
-                    min_value?: number | null;
-                    max_value?: number | null;
-                    avg_value?: number | null;
-                    median_value?: number | null;
-                    std_value?: number | null;
-                    min_date?: string | null;
-                    max_date?: string | null;
-                    min_length?: number | null;
-                    max_length?: number | null;
-                    avg_length?: number | null;
-                } & {
-                    [key: string]: unknown;
+                    min_value?: number | null | undefined;
+                    max_value?: number | null | undefined;
+                    avg_value?: number | null | undefined;
+                    median_value?: number | null | undefined;
+                    std_value?: number | null | undefined;
+                    min_date?: string | null | undefined;
+                    max_date?: string | null | undefined;
+                    min_length?: number | null | undefined;
+                    max_length?: number | null | undefined;
+                    avg_length?: number | null | undefined;
                 };
             };
-        } & {
-            [key: string]: unknown;
         };
         status: string | null;
         is_removed: boolean;
@@ -947,29 +991,27 @@ export declare const useReport: (reportId: number) => {
     title: string;
     request: string | null;
     data_summary: {
+    [x: string]: unknown;
     columns: {
-    [key: string]: {
-    position?: number;
+    [x: string]: {
+    [x: string]: unknown;
+    position?: number | undefined;
     data_type: string;
     null_count: number | null;
     unique_count: number | null;
     unique_percentage: number | null;
-    min_value?: number | null;
-    max_value?: number | null;
-    avg_value?: number | null;
-    median_value?: number | null;
-    std_value?: number | null;
-    min_date?: string | null;
-    max_date?: string | null;
-    min_length?: number | null;
-    max_length?: number | null;
-    avg_length?: number | null;
-    } & {
-    [key: string]: unknown;
+    min_value?: number | null | undefined;
+    max_value?: number | null | undefined;
+    avg_value?: number | null | undefined;
+    median_value?: number | null | undefined;
+    std_value?: number | null | undefined;
+    min_date?: string | null | undefined;
+    max_date?: string | null | undefined;
+    min_length?: number | null | undefined;
+    max_length?: number | null | undefined;
+    avg_length?: number | null | undefined;
     };
     };
-    } & {
-    [key: string]: unknown;
     };
     status: string | null;
     is_removed: boolean;
@@ -1022,7 +1064,6 @@ declare const V1FrontendVisualizationSchema: z.ZodObject<{
         type: z.ZodLiteral<"pie">;
     }, z.core.$strip>], "type">;
     created_at: z.ZodString;
-    flow_data_id: z.ZodNumber;
     flow_data: z.ZodOptional<z.ZodObject<{
         is_materialized: z.ZodNullable<z.ZodBoolean>;
         last_materialized_at: z.ZodNullable<z.ZodString>;
@@ -1033,6 +1074,7 @@ declare const V1FrontendVisualizationSchema: z.ZodObject<{
             running: "running";
         }>>;
     }, z.core.$strip>>;
+    flow_data_id: z.ZodNumber;
 }, z.core.$strip>;
 
 export declare const Visualization: ForwardRefExoticComponent<    {

package/dist/web-component/index.d.ts

@@ -94,6 +94,46 @@ export declare interface ChatContextValue {
     enableSpeechToText?: boolean;
 }
 
+/**
+ * Optional provider that allows the host application to pass dynamic runtime hints
+ * to the chat. The hints are sent with every message and injected ephemerally into
+ * the LLM prompt — they are not persisted or shown in the UI.
+ * Place this anywhere inside `MageMetricsContextProvider` and around the `Chat` component.
+ * When the `value` prop changes, the next message sent will carry the updated hints.
+ * If this provider is not used, no hints are sent — everything works as before.
+ * @param props - The provider props
+ * @param props.value - The chat hints value to provide
+ * @param props.children - The child components
+ * @returns The provider component wrapping children
+ */
+export declare const ChatHintsProvider: default_2.FC<ChatHintsProviderProps>;
+
+declare interface ChatHintsProviderProps {
+    /**
+     * Arbitrary key-value hints from the host application.
+     * These are sent alongside every chat message and injected into the LLM prompt.
+     * @example
+     * ```tsx
+     * <ChatHintsProvider value={{
+     *   selectedLocation: { lat: 48.8566, lng: 2.3522, name: "Paris" },
+     *   activeFilters: ["revenue > 1M"],
+     * }}>
+     *   <Chat flowId="..." />
+     * </ChatHintsProvider>
+     * ```
+     */
+    value: ChatHintsValue;
+    children: default_2.ReactNode;
+}
+
+/**
+ * The value type for chat hints — a free-form key-value object
+ * that the host application can use to pass runtime information to the LLM.
+ * These hints are injected ephemerally into each chat message (not persisted)
+ * so the LLM is aware of the host application's current state.
+ */
+export declare type ChatHintsValue = Record<string, unknown>;
+
 export declare interface ChatInputContextValue {
     flowId: string | undefined;
     isLoading: boolean;
@@ -293,8 +333,8 @@ declare const FrontendReportSchema: z.ZodObject<{
             avg_length: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$loose>>;
     }, z.core.$loose>;
-    is_removed: z.ZodBoolean;
     flow_id: z.ZodString;
+    is_removed: z.ZodBoolean;
     is_materialized: z.ZodNullable<z.ZodBoolean>;
     last_materialized_at: z.ZodNullable<z.ZodString>;
     materialized_error_message: z.ZodNullable<z.ZodString>;
@@ -350,7 +390,6 @@ declare const FrontendVisualizationSchema: z.ZodObject<{
         type: z.ZodLiteral<"pie">;
     }, z.core.$strip>], "type">;
     created_at: z.ZodString;
-    flow_data_id: z.ZodNumber;
     flow_data: z.ZodOptional<z.ZodObject<{
         is_materialized: z.ZodNullable<z.ZodBoolean>;
         last_materialized_at: z.ZodNullable<z.ZodString>;
@@ -361,6 +400,7 @@ declare const FrontendVisualizationSchema: z.ZodObject<{
             running: "running";
         }>>;
     }, z.core.$strip>>;
+    flow_data_id: z.ZodNumber;
 }, z.core.$strip>;
 
 declare const InputContainer: default_2.FC<{
@@ -625,6 +665,12 @@ export declare const useCanvas: (canvasId: string | undefined | null, options?:
 
 export declare const useChatContext: () => ChatContextValue;
 
+/**
+ * Returns the current chat hints value, or `null` if no `ChatHintsProvider` is present.
+ * @returns The current chat hints value or null
+ */
+export declare const useChatHints: () => ChatHintsValue | null;
+
 export declare const useChatInputContext: () => ChatInputContextValue;
 
 export declare const useCreateFlow: (options?: UseMutationOptions<{
@@ -746,7 +792,7 @@ export declare const useCreateFlow: (options?: UseMutationOptions<{
 };
 
 export declare const useDataReportColumnValue: (reportId: number, filters: ReportDataFilters) => UseQueryResult<    {
-    [key: string]: unknown;
+    [x: string]: unknown;
 }[], Error>;
 
 export declare const useDataTableContext: () => {
@@ -777,26 +823,26 @@ export declare const useDataTableContext: () => {
                 avg_length?: number | null | undefined;
             }>;
         };
-        is_removed: boolean;
         flow_id: string;
+        is_removed: boolean;
         is_materialized: boolean | null;
         last_materialized_at: string | null;
         materialized_error_message: string | null;
         materialized_status: "completed" | "running" | "failed" | null;
     };
     fetchNextPage: (options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult<InfiniteData<    {
-        [key: string]: unknown;
+        [x: string]: unknown;
     }[], unknown>, Error>>;
     pages: {
-        [key: string]: unknown;
+        [x: string]: unknown;
     }[][] | undefined;
     columns: {
         name: string;
         data_type: string;
         dataType: string;
-        renderType?: string;
-        unit?: string;
-        canonicalDataType?: "numeric" | "boolean" | "datetime" | "text" | "array" | "json" | "other";
+        renderType?: string | undefined;
+        unit?: string | undefined;
+        canonicalDataType?: "numeric" | "boolean" | "datetime" | "text" | "array" | "json" | "other" | undefined;
     }[] | undefined;
     isPendingColumns: boolean;
     hasMoreData: boolean;
@@ -905,29 +951,27 @@ export declare const useReport: (reportId: number) => {
         title: string;
         request: string | null;
         data_summary: {
+            [x: string]: unknown;
             columns: {
-                [key: string]: {
-                    position?: number;
+                [x: string]: {
+                    [x: string]: unknown;
+                    position?: number | undefined;
                     data_type: string;
                     null_count: number | null;
                     unique_count: number | null;
                     unique_percentage: number | null;
-                    min_value?: number | null;
-                    max_value?: number | null;
-                    avg_value?: number | null;
-                    median_value?: number | null;
-                    std_value?: number | null;
-                    min_date?: string | null;
-                    max_date?: string | null;
-                    min_length?: number | null;
-                    max_length?: number | null;
-                    avg_length?: number | null;
-                } & {
-                    [key: string]: unknown;
+                    min_value?: number | null | undefined;
+                    max_value?: number | null | undefined;
+                    avg_value?: number | null | undefined;
+                    median_value?: number | null | undefined;
+                    std_value?: number | null | undefined;
+                    min_date?: string | null | undefined;
+                    max_date?: string | null | undefined;
+                    min_length?: number | null | undefined;
+                    max_length?: number | null | undefined;
+                    avg_length?: number | null | undefined;
                 };
             };
-        } & {
-            [key: string]: unknown;
         };
         status: string | null;
         is_removed: boolean;
@@ -947,29 +991,27 @@ export declare const useReport: (reportId: number) => {
         title: string;
         request: string | null;
         data_summary: {
+            [x: string]: unknown;
             columns: {
-                [key: string]: {
-                    position?: number;
+                [x: string]: {
+                    [x: string]: unknown;
+                    position?: number | undefined;
                     data_type: string;
                     null_count: number | null;
                     unique_count: number | null;
                     unique_percentage: number | null;
-                    min_value?: number | null;
-                    max_value?: number | null;
-                    avg_value?: number | null;
-                    median_value?: number | null;
-                    std_value?: number | null;
-                    min_date?: string | null;
-                    max_date?: string | null;
-                    min_length?: number | null;
-                    max_length?: number | null;
-                    avg_length?: number | null;
-                } & {
-                    [key: string]: unknown;
+                    min_value?: number | null | undefined;
+                    max_value?: number | null | undefined;
+                    avg_value?: number | null | undefined;
+                    median_value?: number | null | undefined;
+                    std_value?: number | null | undefined;
+                    min_date?: string | null | undefined;
+                    max_date?: string | null | undefined;
+                    min_length?: number | null | undefined;
+                    max_length?: number | null | undefined;
+                    avg_length?: number | null | undefined;
                 };
             };
-        } & {
-            [key: string]: unknown;
         };
         status: string | null;
         is_removed: boolean;
@@ -1022,7 +1064,6 @@ declare const V1FrontendVisualizationSchema: z.ZodObject<{
         type: z.ZodLiteral<"pie">;
     }, z.core.$strip>], "type">;
     created_at: z.ZodString;
-    flow_data_id: z.ZodNumber;
     flow_data: z.ZodOptional<z.ZodObject<{
         is_materialized: z.ZodNullable<z.ZodBoolean>;
         last_materialized_at: z.ZodNullable<z.ZodString>;
@@ -1033,6 +1074,7 @@ declare const V1FrontendVisualizationSchema: z.ZodObject<{
             running: "running";
         }>>;
     }, z.core.$strip>>;
+    flow_data_id: z.ZodNumber;
 }, z.core.$strip>;
 
 export declare const Visualization: ForwardRefExoticComponent<    {