flowquery 1.0.5 → 1.0.7

package/misc/apps/RAG/src/components/FlowQueryRunner.css

@@ -0,0 +1,104 @@
+.flowquery-runner-surface {
+    max-width: 800px;
+    width: 90vw;
+}
+
+.flowquery-runner-content {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    padding-top: 16px;
+}
+
+.flowquery-input-container {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.flowquery-textarea {
+    width: 100%;
+    min-height: 120px;
+    font-family: 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+    font-size: 13px;
+    resize: vertical;
+}
+
+.flowquery-actions {
+    display: flex;
+    gap: 8px;
+    align-items: center;
+}
+
+.flowquery-execution-time {
+    margin-left: auto;
+    font-size: 12px;
+    color: #666;
+}
+
+.flowquery-results-container {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.flowquery-results-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+}
+
+.flowquery-results-count {
+    font-size: 12px;
+    color: #666;
+}
+
+.flowquery-results {
+    max-height: 300px;
+    overflow: auto;
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+    background-color: #f8f8f8;
+}
+
+.flowquery-results-content {
+    padding: 12px;
+    font-family: 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+    font-size: 12px;
+    white-space: pre-wrap;
+    word-break: break-word;
+    margin: 0;
+}
+
+.flowquery-error {
+    color: #c50f1f;
+    padding: 12px;
+    margin: 0;
+}
+
+.flowquery-no-results {
+    color: #666;
+    font-style: italic;
+    padding: 12px;
+}
+
+.flowquery-loading {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 12px;
+    color: #666;
+}
+
+.flowquery-examples-list {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+}
+
+.flowquery-example-button {
+    text-align: left;
+    justify-content: flex-start;
+    font-family: 'Cascadia Code', 'Fira Code', 'Consolas', monospace;
+    font-size: 12px;
+}

package/misc/apps/RAG/src/components/FlowQueryRunner.tsx

@@ -0,0 +1,332 @@
+/**
+ * FlowQuery Runner Component
+ * 
+ * A popup dialog that allows users to run FlowQuery statements directly
+ * and see the results in the dialog.
+ */
+
+import React, { Component } from 'react';
+import {
+    Dialog,
+    DialogTrigger,
+    DialogSurface,
+    DialogTitle,
+    DialogBody,
+    DialogActions,
+    DialogContent,
+    Button,
+    Textarea,
+    Label,
+    Field,
+    Spinner,
+    Tooltip,
+} from '@fluentui/react-components';
+import { 
+    Play24Regular, 
+    Code24Regular, 
+    Dismiss24Regular,
+    Copy24Regular,
+    ArrowClockwise24Regular,
+    Checkmark24Regular,
+} from '@fluentui/react-icons';
+import { FlowQueryExecutor, FlowQueryExecutionResult } from '../utils/FlowQueryExecutor';
+import './FlowQueryRunner.css';
+
+const flowQueryExecutor = new FlowQueryExecutor();
+
+interface FlowQueryRunnerProps {
+    /** Initial query to pre-populate the input */
+    initialQuery?: string;
+    /** Controlled open state - if provided, the component becomes controlled */
+    open?: boolean;
+    /** Callback when open state changes (for controlled mode) */
+    onOpenChange?: (open: boolean) => void;
+    /** Callback when the dialog is closed (deprecated, use onOpenChange) */
+    onClose?: () => void;
+    /** Custom trigger element. If not provided, a default button is shown. Not used in controlled mode. */
+    trigger?: React.ReactElement;
+}
+
+interface FlowQueryRunnerState {
+    open: boolean;
+    query: string;
+    isExecuting: boolean;
+    result: FlowQueryExecutionResult | null;
+    copied: boolean;
+}
+
+export class FlowQueryRunner extends Component<FlowQueryRunnerProps, FlowQueryRunnerState> {
+    constructor(props: FlowQueryRunnerProps) {
+        super(props);
+        this.state = {
+            open: props.open ?? false,
+            query: props.initialQuery || '',
+            isExecuting: false,
+            result: null,
+            copied: false,
+        };
+    }
+
+    componentDidUpdate(prevProps: FlowQueryRunnerProps): void {
+        // Handle controlled mode: sync open state from props
+        if (this.props.open !== undefined && this.props.open !== prevProps.open) {
+            this.setState({ open: this.props.open });
+            // If opening with a new initial query, update the query
+            if (this.props.open && this.props.initialQuery !== prevProps.initialQuery) {
+                this.setState({ query: this.props.initialQuery || '', result: null });
+            }
+        }
+        // Handle initialQuery changes when opening
+        if (this.props.initialQuery !== prevProps.initialQuery && this.props.open) {
+            this.setState({ query: this.props.initialQuery || '', result: null });
+        }
+    }
+
+    /**
+     * Check if the component is in controlled mode
+     */
+    isControlled = (): boolean => {
+        return this.props.open !== undefined;
+    };
+
+    handleOpenChange = (_: unknown, data: { open: boolean }): void => {
+        if (this.isControlled()) {
+            // In controlled mode, notify parent
+            this.props.onOpenChange?.(data.open);
+        } else {
+            // In uncontrolled mode, manage state internally
+            this.setState({ open: data.open });
+        }
+        
+        if (!data.open && this.props.onClose) {
+            this.props.onClose();
+        }
+    };
+
+    handleClose = (): void => {
+        if (this.isControlled()) {
+            this.props.onOpenChange?.(false);
+        } else {
+            this.setState({ open: false });
+        }
+        this.props.onClose?.();
+    };
+
+    handleQueryChange = (_: unknown, data: { value: string }): void => {
+        this.setState({ query: data.value });
+    };
+
+    handleExecute = async (): Promise<void> => {
+        const { query } = this.state;
+        
+        if (!query.trim()) {
+            return;
+        }
+
+        this.setState({ isExecuting: true, result: null });
+
+        try {
+            const result = await flowQueryExecutor.execute(query);
+            this.setState({ result, isExecuting: false });
+        } catch (error) {
+            this.setState({
+                result: {
+                    success: false,
+                    query,
+                    error: error instanceof Error ? error.message : String(error),
+                    executionTime: 0,
+                },
+                isExecuting: false,
+            });
+        }
+    };
+
+    handleClear = (): void => {
+        this.setState({ query: '', result: null });
+    };
+
+    handleCopyResults = (): void => {
+        const { result } = this.state;
+        if (result?.success && result.results) {
+            navigator.clipboard.writeText(JSON.stringify(result.results, null, 2));
+            this.setState({ copied: true });
+            setTimeout(() => this.setState({ copied: false }), 2000);
+        }
+    };
+
+    handleKeyDown = (event: React.KeyboardEvent): void => {
+        // Execute on Ctrl+Enter or Cmd+Enter
+        if ((event.ctrlKey || event.metaKey) && event.key === 'Enter') {
+            event.preventDefault();
+            this.handleExecute();
+        }
+    };
+
+    renderResults(): React.ReactNode {
+        const { result, isExecuting, copied } = this.state;
+
+        if (isExecuting) {
+            return (
+                <div className="flowquery-loading">
+                    <Spinner size="tiny" />
+                    <span>Executing query...</span>
+                </div>
+            );
+        }
+
+        if (!result) {
+            return (
+                <div className="flowquery-no-results">
+                    Enter a FlowQuery statement and click Run to see results.
+                </div>
+            );
+        }
+
+        if (!result.success) {
+            return (
+                <pre className="flowquery-error">
+                    Error: {result.error}
+                </pre>
+            );
+        }
+
+        const resultCount = result.results?.length || 0;
+        const resultsJson = JSON.stringify(result.results, null, 2);
+
+        return (
+            <div className="flowquery-results-container">
+                <div className="flowquery-results-header">
+                    <span className="flowquery-results-count">
+                        {resultCount} result{resultCount !== 1 ? 's' : ''} 
+                        {' • '}
+                        {result.executionTime.toFixed(2)}ms
+                    </span>
+                    <Tooltip 
+                        content={copied ? "Copied!" : "Copy results"} 
+                        relationship="label"
+                    >
+                        <Button
+                            appearance="subtle"
+                            icon={copied ? <Checkmark24Regular /> : <Copy24Regular />}
+                            size="small"
+                            onClick={this.handleCopyResults}
+                            disabled={!result.results?.length}
+                        />
+                    </Tooltip>
+                </div>
+                <div className="flowquery-results">
+                    <pre className="flowquery-results-content">
+                        {resultsJson}
+                    </pre>
+                </div>
+            </div>
+        );
+    }
+
+    renderDialogSurface(): React.JSX.Element {
+        const { query, isExecuting } = this.state;
+
+        return (
+            <DialogSurface className="flowquery-runner-surface">
+                <DialogBody>
+                    <DialogTitle
+                        action={
+                            <Button
+                                appearance="subtle"
+                                icon={<Dismiss24Regular />}
+                                onClick={this.handleClose}
+                            />
+                        }
+                    >
+                        FlowQuery Runner
+                    </DialogTitle>
+                    <DialogContent className="flowquery-runner-content">
+                        <div className="flowquery-input-container">
+                            <Field label="FlowQuery Statement">
+                                <Textarea
+                                    value={query}
+                                    onChange={this.handleQueryChange}
+                                    onKeyDown={this.handleKeyDown}
+                                    placeholder="Enter your FlowQuery statement here..."
+                                    className="flowquery-textarea"
+                                    resize="vertical"
+                                />
+                            </Field>
+                            <div className="flowquery-actions">
+                                <Tooltip content="Run query (Ctrl+Enter)" relationship="label">
+                                    <Button
+                                        appearance="primary"
+                                        icon={<Play24Regular />}
+                                        onClick={this.handleExecute}
+                                        disabled={isExecuting || !query.trim()}
+                                    >
+                                        Run
+                                    </Button>
+                                </Tooltip>
+                                <Tooltip content="Clear query and results" relationship="label">
+                                    <Button
+                                        appearance="subtle"
+                                        icon={<ArrowClockwise24Regular />}
+                                        onClick={this.handleClear}
+                                        disabled={isExecuting}
+                                    >
+                                        Clear
+                                    </Button>
+                                </Tooltip>
+                            </div>
+                        </div>
+
+                        <Field label="Results">
+                            <div className="flowquery-results">
+                                {this.renderResults()}
+                            </div>
+                        </Field>
+                    </DialogContent>
+                    <DialogActions>
+                        <Button 
+                            appearance="secondary" 
+                            onClick={this.handleClose}
+                        >
+                            Close
+                        </Button>
+                    </DialogActions>
+                </DialogBody>
+            </DialogSurface>
+        );
+    }
+
+    render(): React.ReactNode {
+        const { open } = this.state;
+        const { trigger } = this.props;
+        const isControlled = this.isControlled();
+
+        // In controlled mode, render dialog without trigger
+        if (isControlled) {
+            return (
+                <Dialog open={open} onOpenChange={this.handleOpenChange}>
+                    {this.renderDialogSurface()}
+                </Dialog>
+            );
+        }
+
+        // In uncontrolled mode, render with trigger
+        return (
+            <Dialog open={open} onOpenChange={this.handleOpenChange}>
+                <DialogTrigger disableButtonEnhancement>
+                    {trigger || (
+                        <Button
+                            appearance="subtle"
+                            icon={<Code24Regular />}
+                            title="FlowQuery Runner"
+                        >
+                            FlowQuery
+                        </Button>
+                    )}
+                </DialogTrigger>
+                {this.renderDialogSurface()}
+            </Dialog>
+        );
+    }
+}
+
+export default FlowQueryRunner;

package/misc/apps/RAG/src/components/index.ts

@@ -0,0 +1,15 @@
+// Chat components exports
+export { ChatContainer } from './ChatContainer';
+export { ChatMessage } from './ChatMessage';
+export { ChatInput } from './ChatInput';
+export { ApiKeySettings } from './ApiKeySettings';
+
+// FlowQuery Runner
+export { FlowQueryRunner } from './FlowQueryRunner';
+
+// FlowQuery Agent
+export { processQuery, processQueryStream } from './FlowQueryAgent';
+export type { AgentStep, AgentResult, FlowQueryAgentOptions, AgentStreamCallback } from './FlowQueryAgent';
+
+// Types
+export type { Message } from './ChatMessage';

package/misc/apps/RAG/src/index.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import { initializePlugins } from './plugins';
+
+// Initialize FlowQuery plugins before rendering
+initializePlugins();
+
+const container = document.getElementById('root');
+if (container) {
+    const root = createRoot(container);
+    root.render(
+        <React.StrictMode>
+            <App />
+        </React.StrictMode>
+    );
+}

package/misc/apps/RAG/src/plugins/README.md

@@ -0,0 +1,139 @@
+# FlowQuery Plugin System
+
+This folder contains the plugin system for adding async data loader functions to FlowQuery.
+
+## Quick Start
+
+1. Create a new file in `loaders/` (e.g., `my-api.ts`)
+2. Define your plugin following the `AsyncLoaderPlugin` interface
+3. Import and add it to the `allPlugins` array in `index.ts`
+
+## Creating a Plugin
+
+### Basic Plugin Structure
+
+```typescript
+import { AsyncLoaderPlugin } from '../types';
+
+// Your async data provider function
+async function* myDataProvider(arg1: string, arg2?: number): AsyncGenerator<any, void, unknown> {
+    const response = await fetch(`https://api.example.com/${arg1}`);
+    const data = await response.json();
+    
+    // Yield items one at a time (for arrays)
+    if (Array.isArray(data)) {
+        for (const item of data) {
+            yield item;
+        }
+    } else {
+        yield data;
+    }
+}
+
+// Export the plugin definition
+export const myPlugin: AsyncLoaderPlugin = {
+    name: 'myData',  // Function name in FlowQuery
+    provider: myDataProvider,
+    metadata: {
+        description: 'Fetches data from My API',
+        category: 'data',
+        parameters: [
+            { name: 'arg1', description: 'First argument', type: 'string', required: true },
+            { name: 'arg2', description: 'Optional second arg', type: 'number', required: false }
+        ],
+        output: {
+            description: 'Data item',
+            type: 'object',
+            properties: {
+                id: { description: 'Item ID', type: 'number' },
+                value: { description: 'Item value', type: 'string' }
+            }
+        },
+        examples: [
+            "LOAD JSON FROM myData('users') AS item RETURN item.id, item.value"
+        ]
+    }
+};
+
+export default myPlugin;
+```
+
+### Register the Plugin
+
+Add your plugin to `index.ts`:
+
+```typescript
+import myPlugin from './loaders/my-api';
+
+const allPlugins: AsyncLoaderPlugin[] = [
+    // ... existing plugins
+    myPlugin,
+];
+```
+
+## Using Plugins in FlowQuery
+
+Once registered, use your plugin in FlowQuery queries:
+
+```sql
+-- Fetch data from your custom source
+LOAD JSON FROM myData('users') AS user
+WHERE user.active = true
+RETURN user.name, user.email
+
+-- Combine with filtering and ordering
+LOAD JSON FROM myData('products', 50) AS product
+WHERE product.price > 10
+ORDER BY product.name ASC
+RETURN product.name, product.price
+```
+
+## Available Built-in Plugins
+
+| Plugin | Description | Example |
+|--------|-------------|---------|
+| `fetchJson` | Fetch JSON from any URL | `fetchJson('https://api.example.com/data')` |
+
+> **Note**: Additional plugins may be registered. Check `index.ts` for the current list of available plugins.
+
+## Plugin Types
+
+### AsyncLoaderPlugin
+
+```typescript
+interface AsyncLoaderPlugin {
+    name: string;                    // Function name (lowercased when registered)
+    provider: AsyncDataProvider;     // The async generator/function
+    metadata?: PluginMetadata;       // Optional metadata for LLM consumption
+}
+```
+
+### AsyncDataProvider
+
+```typescript
+type AsyncDataProvider = (...args: any[]) => AsyncGenerator<any, void, unknown> | Promise<any>;
+```
+
+Plugins can return either:
+- An `AsyncGenerator` that yields items one at a time
+- A `Promise` that resolves to an array or single value
+
+### PluginMetadata
+
+```typescript
+interface PluginMetadata {
+    name: string;
+    description: string;
+    category?: string;
+    parameters?: ParameterSchema[];
+    output?: OutputSchema;
+    examples?: string[];
+}
+```
+
+## Tips
+
+1. **Use generators for large datasets** - Yield items one at a time to avoid memory issues
+2. **Add comprehensive metadata** - This helps LLMs understand and use your functions
+3. **Handle errors gracefully** - Throw descriptive errors for API failures
+4. **Include examples** - Show users how to use your plugin in FlowQuery

package/misc/apps/RAG/src/plugins/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Plugin loader - automatically discovers and loads all plugins.
+ * 
+ * To add a new plugin:
+ * 1. Create a new file in the `loaders/` directory
+ * 2. Add the @AsyncProviderDef decorator to your loader class
+ * 3. Import the class in this file (the decorator auto-registers with FlowQuery)
+ */
+
+import FlowQuery from 'flowquery';
+import { FunctionMetadata } from 'flowquery/extensibility';
+
+// Import loader classes - the @AsyncProviderDef decorator auto-registers them with FlowQuery
+import './loaders/FetchJson';
+import './loaders/CatFacts';
+import './loaders/MockData';
+import './loaders/Llm';
+
+/**
+ * Initialize plugins.
+ * Plugins are auto-registered via @AsyncProviderDef decorators when imported.
+ * This function just logs the registered plugins for debugging.
+ */
+export function initializePlugins(): void {
+    const plugins = getLoadedPluginNames();
+    console.log(`FlowQuery plugins loaded: ${plugins.join(', ')}`);
+}
+
+/**
+ * Get the list of loaded plugin names.
+ * Uses FlowQuery's introspection to discover registered async providers.
+ */
+export function getLoadedPluginNames(): string[] {
+    return FlowQuery.listFunctions({ asyncOnly: true }).map(f => f.name);
+}
+
+/**
+ * Get metadata for all loaded plugins.
+ * Uses FlowQuery's functions() introspection as the single source of truth.
+ */
+export function getAllPluginMetadata(): FunctionMetadata[] {
+    return FlowQuery.listFunctions({ asyncOnly: true });
+}
+
+/**
+ * Get all available async loader plugins by querying FlowQuery directly.
+ * This is the preferred async method that uses functions() introspection.
+ * 
+ * @returns Promise resolving to array of plugin metadata
+ */
+export async function getAvailableLoaders(): Promise<FunctionMetadata[]> {
+    const runner = new FlowQuery(`
+        WITH functions() AS funcs 
+        UNWIND funcs AS f 
+        WHERE f.isAsyncProvider = true
+        RETURN f
+    `);
+    await runner.run();
+    return runner.results.map((r: any) => r.expr0 as FunctionMetadata);
+}
+
+// Re-export types for external use
+export type { FunctionMetadata, FunctionDefOptions, ParameterSchema, OutputSchema, AsyncDataProvider } from 'flowquery/extensibility';
+export { FunctionDef } from 'flowquery/extensibility';
+
+// Re-export standalone loader functions for use outside of FlowQuery
+export { llm, llmStream, extractContent } from './loaders/Llm';
+export type { LlmOptions, LlmResponse } from './loaders/Llm';