flowquery 1.0.12 → 1.0.14

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

@@ -10,13 +10,15 @@
 import FlowQuery from 'flowquery';
 import { FunctionMetadata } from 'flowquery/extensibility';
 
-// Import loader classes - the @FunctionDef decorator auto-registers them with FlowQuery
+// Import plugin classes - the @FunctionDef decorator auto-registers them with FlowQuery
+// This step is essential to ensure decorators are executed so that plugins are registered with FlowQuery
 import './loaders/FetchJson';
 import './loaders/CatFacts';
 import './loaders/MockData';
 import './loaders/Llm';
 import './loaders/Table';
 import './loaders/Form';
+import './loaders/Weather';
 
 /**
  * Initialize plugins.

package/misc/apps/RAG/src/plugins/loaders/CatFacts.ts

@@ -6,12 +6,12 @@
  *   RETURN fact.text
  */
 
-import { FunctionDef } from 'flowquery/extensibility';
+import { FunctionDef, AsyncFunction } from 'flowquery/extensibility';
 
 const CAT_FACTS_API = 'https://catfact.ninja/facts';
 
 /**
- * CatFacts loader class - fetches random cat facts from the Cat Facts API.
+ * CatFacts class - fetches random cat facts from the Cat Facts API.
  */
 @FunctionDef({
     description: 'Fetches random cat facts from the Cat Facts API (catfact.ninja)',
@@ -38,10 +38,11 @@ const CAT_FACTS_API = 'https://catfact.ninja/facts';
         "LOAD JSON FROM catFacts(5) AS fact RETURN fact.text, fact.length AS length"
     ]
 })
-export class CatFactsLoader {
+export class CatFacts extends AsyncFunction {
     private readonly apiUrl: string;
 
     constructor(apiUrl: string = CAT_FACTS_API) {
+        super();
         this.apiUrl = apiUrl;
     }
 
@@ -50,7 +51,7 @@ export class CatFactsLoader {
      * 
      * @param count - Number of cat facts to fetch (default: 1)
      */
-    async *fetch(count: number = 1): AsyncGenerator<any, void, unknown> {
+    async *generate(count: number = 1): AsyncGenerator<any, void, unknown> {
         const url = `${this.apiUrl}?limit=${count}`;
         const response = await fetch(url);
         
@@ -71,4 +72,4 @@ export class CatFactsLoader {
     }
 }
 
-export default CatFactsLoader;
+export default CatFacts;

package/misc/apps/RAG/src/plugins/loaders/Form.ts

@@ -1,10 +1,10 @@
 /**
- * Form loader plugin - transforms configuration into Adaptive Card form format.
+ * Form plugin - transforms configuration into Adaptive Card form format.
  * 
  * Adaptive Cards are platform-agnostic UI snippets that can be rendered in
  * Microsoft Teams, Outlook, Windows, and other applications.
  * 
- * This loader creates customizable forms with various input types including:
+ * This plugin creates customizable forms with various input types including:
  * - Text inputs (single and multi-line)
  * - Number inputs
  * - Date and time pickers
@@ -22,7 +22,7 @@
  *   RETURN form
  */
 
-import { FunctionDef } from 'flowquery/extensibility';
+import { FunctionDef, AsyncFunction } from 'flowquery/extensibility';
 
 /**
  * Interface for Adaptive Card structure
@@ -118,7 +118,7 @@ interface FormConfig {
 }
 
 /**
- * Form loader - creates customizable Adaptive Card forms.
+ * Form class - creates customizable Adaptive Card forms.
  */
 @FunctionDef({
     description: 'Creates a customizable Adaptive Card form with various input types',
@@ -159,7 +159,7 @@ interface FormConfig {
         "LOAD JSON FROM form('Survey', [{ id: 'rating', type: 'dropdown', label: 'Rating', choices: ['1', '2', '3', '4', '5'] }, { id: 'subscribe', type: 'toggle', label: 'Subscribe', toggleTitle: 'Yes, send me updates' }], { submitButton: { title: 'Submit Survey', style: 'positive' } }) AS form RETURN form"
     ]
 })
-export class FormLoader {
+export class Form extends AsyncFunction {
     /**
      * Creates an Adaptive Card form with the specified fields and configuration.
      * 
@@ -167,7 +167,7 @@ export class FormLoader {
      * @param fields - Array of field configurations
      * @param config - Optional form configuration
      */
-    async *fetch(
+    async *generate(
         title: string,
         fields: FormFieldConfig[],
         config?: FormConfig
@@ -575,4 +575,4 @@ export class FormLoader {
     }
 }
 
-export { FormLoader as default };
+export { Form as default };

package/misc/apps/RAG/src/plugins/loaders/Llm.ts

@@ -9,10 +9,10 @@
  *   LOAD JSON FROM llm('Translate to French: Hello', { model: 'gpt-4o', temperature: 0.3 }) AS response
  *   RETURN response.choices[0].message.content
  * 
- * This loader can also be used standalone outside of FlowQuery:
- *   import { LlmLoader } from './plugins/loaders/Llm';
- *   const loader = new LlmLoader();
- *   const response = await loader.complete('What is 2+2?');
+ * This class can also be used standalone outside of FlowQuery:
+ *   import { Llm } from './plugins/loaders/Llm';
+ *   const llmInstance = new Llm();
+ *   const response = await llmInstance.complete('What is 2+2?');
  *   console.log(response.choices[0].message.content);
  */
 
@@ -78,7 +78,7 @@ export interface LlmResponse {
 }
 
 /**
- * LLM Loader class - calls OpenAI-compatible APIs for chat completions.
+ * Llm class - calls OpenAI-compatible APIs for chat completions.
  */
 @FunctionDef({
     description: 'Calls OpenAI-compatible chat completion APIs. Supports GPT models and any OpenAI-compatible endpoint.',
@@ -132,7 +132,7 @@ export interface LlmResponse {
     ],
     notes: 'Requires API key configured in Settings or passed as apiKey option. Works with any OpenAI-compatible API by setting the apiUrl option.'
 })
-export class LlmLoader {
+export class Llm {
     private readonly defaultOptions: Partial<LlmOptions>;
 
     constructor(defaultOptions: Partial<LlmOptions> = {}) {
@@ -243,8 +243,8 @@ export class LlmLoader {
      * 
      * @example
      * ```typescript
-     * const loader = new LlmLoader();
-     * const response = await loader.complete('What is the capital of France?');
+     * const llmInstance = new Llm();
+     * const response = await llmInstance.complete('What is the capital of France?');
      * console.log(response.choices[0].message.content);
      * ```
      */
@@ -281,8 +281,8 @@ export class LlmLoader {
      * 
      * @example
      * ```typescript
-     * const loader = new LlmLoader();
-     * for await (const chunk of loader.stream('Tell me a story')) {
+     * const llmInstance = new Llm();
+     * for await (const chunk of llmInstance.stream('Tell me a story')) {
      *   if (chunk.choices?.[0]?.delta?.content) {
      *     process.stdout.write(chunk.choices[0].delta.content);
      *   }
@@ -396,7 +396,7 @@ export class LlmLoader {
  * ```
  */
 export async function llm(prompt: string, options?: LlmOptions): Promise<LlmResponse> {
-    return new LlmLoader().complete(prompt, options);
+    return new Llm().complete(prompt, options);
 }
 
 /**
@@ -419,7 +419,7 @@ export async function llm(prompt: string, options?: LlmOptions): Promise<LlmResp
  * ```
  */
 export async function* llmStream(prompt: string, options?: LlmOptions): AsyncGenerator<any, void, unknown> {
-    yield* new LlmLoader().stream(prompt, options);
+    yield* new Llm().stream(prompt, options);
 }
 
 /**
@@ -430,7 +430,7 @@ export async function* llmStream(prompt: string, options?: LlmOptions): AsyncGen
  * @returns The text content from the first choice
  */
 export function extractContent(response: LlmResponse): string {
-    return LlmLoader.extractContent(response);
+    return Llm.extractContent(response);
 }
 
-export default LlmLoader;
+export default Llm;

package/misc/apps/RAG/src/plugins/loaders/MockData.ts

@@ -9,7 +9,7 @@
 import { FunctionDef } from 'flowquery/extensibility';
 
 /**
- * MockUsers loader class - generates mock user data for testing.
+ * MockUsers class - generates mock user data for testing.
  */
 @FunctionDef({
     description: 'Generates mock user data for testing purposes',
@@ -39,7 +39,7 @@ import { FunctionDef } from 'flowquery/extensibility';
         "LOAD JSON FROM mockUsers(20) AS user RETURN user WHERE user.active = true"
     ]
 })
-export class MockUsersLoader {
+export class MockUsers {
     private readonly firstNames: string[];
     private readonly lastNames: string[];
     private readonly domains: string[];
@@ -77,7 +77,7 @@ export class MockUsersLoader {
 }
 
 /**
- * MockProducts loader class - generates mock product data for testing.
+ * MockProducts class - generates mock product data for testing.
  */
 @FunctionDef({
     description: 'Generates mock product data for testing purposes',
@@ -108,7 +108,7 @@ export class MockUsersLoader {
         "LOAD JSON FROM mockProducts(50) AS p RETURN p WHERE p.category = 'Electronics'"
     ]
 })
-export class MockProductsLoader {
+export class MockProducts {
     private readonly categories: string[];
     private readonly adjectives: string[];
     private readonly nouns: string[];
@@ -146,4 +146,4 @@ export class MockProductsLoader {
     }
 }
 
-export { MockUsersLoader as default };
+export { MockUsers as default };

package/misc/apps/RAG/src/plugins/loaders/Table.ts

@@ -1,5 +1,5 @@
 /**
- * Table loader plugin - transforms tabular data into Adaptive Card format.
+ * Table plugin - transforms tabular data into Adaptive Card format.
  * 
  * Adaptive Cards are platform-agnostic UI snippets that can be rendered in
  * Microsoft Teams, Outlook, Windows, and other applications.
@@ -42,7 +42,7 @@ interface TableRow {
 }
 
 /**
- * Table loader - transforms tabular data into an Adaptive Card table format.
+ * Table class - transforms tabular data into an Adaptive Card table format.
  */
 @FunctionDef({
     description: 'Transforms tabular data into an Adaptive Card JSON format with a table layout',
@@ -90,7 +90,7 @@ interface TableRow {
         "LOAD JSON FROM mockProducts(10) AS p WITH collect(p) AS products LOAD JSON FROM table(products, 'Products', ['name', 'price', 'category']) AS card RETURN card"
     ]
 })
-export class TableLoader {
+export class Table {
     /**
      * Transforms data into an Adaptive Card with table layout.
      * 
@@ -268,4 +268,4 @@ export class TableLoader {
     }
 }
 
-export { TableLoader as default };
+export { Table as default };

package/misc/apps/RAG/src/plugins/loaders/Weather.ts

@@ -0,0 +1,126 @@
+/**
+ * Example plugin: Fetch weather forecast for a location.
+ * 
+ * Usage in FlowQuery:
+ *   LOAD JSON FROM weather('Oslo') AS forecast
+ *   RETURN forecast
+ */
+
+import { FunctionDef } from 'flowquery/extensibility';
+
+const GEOCODING_API = 'https://geocoding-api.open-meteo.com/v1/search';
+const WEATHER_API = 'https://api.met.no/weatherapi/locationforecast/2.0/compact';
+
+/**
+ * Weather class - fetches weather forecast for a given location.
+ */
+@FunctionDef({
+    description: 'Fetches weather forecast for a location using Open-Meteo geocoding and MET Norway weather API',
+    category: 'async',
+    parameters: [
+        {
+            name: 'location',
+            description: 'The name of the location to get weather for (e.g., "Oslo", "New York")',
+            type: 'string',
+            required: true
+        }
+    ],
+    output: {
+        description: 'Weather forecast data point with location and weather parameters',
+        type: 'object',
+        properties: {
+            date: { description: 'ISO 8601 timestamp in UTC', type: 'string' },
+            location: { description: 'Name of the location', type: 'string' },
+            lat: { description: 'Latitude in decimal degrees', type: 'number' },
+            lon: { description: 'Longitude in decimal degrees', type: 'number' },
+            temperature: { description: 'Air temperature in celsius', type: 'number' },
+            humidity: { description: 'Relative humidity in %', type: 'number' },
+            pressure: { description: 'Air pressure at sea level in hPa', type: 'number' },
+            cloud_cover: { description: 'Total cloud cover in %', type: 'number' },
+            wind_speed: { description: 'Wind speed in m/s', type: 'number' },
+            wind_direction: { description: 'Wind direction in degrees (0=N, 90=E, 180=S, 270=W)', type: 'number' },
+            precipitation: { description: 'Expected precipitation in mm (next hour if available)', type: 'number' },
+            symbol: { description: 'Weather symbol code (e.g., "partlycloudy_day", "rain")', type: 'string' }
+        }
+    },
+    examples: [
+        "LOAD JSON FROM weather('Oslo') AS forecast RETURN forecast",
+        "LOAD JSON FROM weather('London') AS forecast RETURN forecast[0]"
+    ]
+})
+export class Weather {
+    private readonly geocodingApiUrl: string;
+    private readonly weatherApiUrl: string;
+
+    constructor(geocodingApiUrl: string = GEOCODING_API, weatherApiUrl: string = WEATHER_API) {
+        this.geocodingApiUrl = geocodingApiUrl;
+        this.weatherApiUrl = weatherApiUrl;
+    }
+
+    /**
+     * Fetches weather forecast for a given location.
+     * 
+     * @param location - The name of the location to get weather for
+     */
+    async *fetch(location: string): AsyncGenerator<any, void, unknown> {
+        // Step 1: Geocode the location name to get lat/lon
+        const geocodeUrl = `${this.geocodingApiUrl}?name=${encodeURIComponent(location)}`;
+        const geocodeResponse = await fetch(geocodeUrl);
+
+        if (!geocodeResponse.ok) {
+            throw new Error(`Failed to geocode location: ${geocodeResponse.statusText}`);
+        }
+
+        const geocodeData = await geocodeResponse.json();
+
+        if (!geocodeData.results || geocodeData.results.length === 0) {
+            throw new Error(`Location not found: ${location}`);
+        }
+
+        const firstResult = geocodeData.results[0];
+        const lat = firstResult.latitude;
+        const lon = firstResult.longitude;
+
+        // Step 2: Fetch weather forecast using lat/lon
+        const weatherUrl = `${this.weatherApiUrl}?lat=${lat}&lon=${lon}`;
+        const weatherResponse = await fetch(weatherUrl, {
+            headers: {
+                // MET Norway API requires a User-Agent header
+                'User-Agent': 'FlowQuery-RAG/1.0'
+            }
+        });
+
+        if (!weatherResponse.ok) {
+            throw new Error(`Failed to fetch weather: ${weatherResponse.statusText}`);
+        }
+
+        const weatherData = await weatherResponse.json();
+
+        // Transform timeseries into simplified flat records and yield row by row
+        const locationName = firstResult.name;
+        const timeseries = weatherData.properties?.timeseries || [];
+
+        for (const entry of timeseries) {
+            const instant = entry.data?.instant?.details || {};
+            const next1h = entry.data?.next_1_hours || {};
+            const next6h = entry.data?.next_6_hours || {};
+
+            yield {
+                date: entry.time,
+                location: locationName,
+                lat,
+                lon,
+                temperature: instant.air_temperature,
+                humidity: instant.relative_humidity,
+                pressure: instant.air_pressure_at_sea_level,
+                cloud_cover: instant.cloud_area_fraction,
+                wind_speed: instant.wind_speed,
+                wind_direction: instant.wind_from_direction,
+                precipitation: next1h.details?.precipitation_amount ?? next6h.details?.precipitation_amount ?? null,
+                symbol: next1h.summary?.symbol_code ?? next6h.summary?.symbol_code ?? null
+            };
+        }
+    }
+}
+
+export default Weather;

package/misc/apps/RAG/src/prompts/FlowQuerySystemPrompt.ts

@@ -287,6 +287,10 @@ When the user asks a question that doesn't require data fetching (e.g., asking a
 - Use meaningful aliases in RETURN statements for better readability
 - Generate the simplest query that fulfills the user's request
 - If you cannot determine what the user needs, ask clarifying questions (with [NO_QUERY_NEEDED])
+- Do not use order by or coalesce
+- Do not use list comprehension [i for i in ...]
+- Do not use substring function
+- Do not use limit or skip
 
 ${FLOWQUERY_LANGUAGE_REFERENCE}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowquery",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "A declarative query language for data processing pipelines.",
   "main": "dist/index.node.js",
   "types": "dist/index.node.d.ts",

package/src/parsing/functions/aggregate_function.ts

@@ -21,7 +21,7 @@ class AggregateFunction extends Function {
      * 
      * @param name - The function name
      */
-    constructor(name: string) {
+    constructor(name?: string) {
         super(name);
     }
     

package/src/parsing/functions/async_function.ts

@@ -1,5 +1,5 @@
 import ASTNode from "../ast_node";
-import FunctionFactory from "./function_factory";
+import Function from "./function";
 
 /**
  * Represents an async data provider function call for use in LOAD operations.
@@ -17,26 +17,7 @@ import FunctionFactory from "./function_factory";
  * }
  * ```
  */
-class AsyncFunction extends ASTNode {
-    private _name: string;
-
-    /**
-     * Creates a new AsyncFunction with the given name.
-     * 
-     * @param name - The function name (must be registered as an async provider)
-     */
-    constructor(name: string) {
-        super();
-        this._name = name;
-    }
-
-    /**
-     * Gets the function name.
-     */
-    public get name(): string {
-        return this._name;
-    }
-
+class AsyncFunction extends Function {
     /**
      * Sets the function parameters.
      * 
@@ -48,47 +29,35 @@ class AsyncFunction extends ASTNode {
 
     /**
      * Evaluates all parameters and returns their values.
+     * Used by the framework to pass arguments to generate().
      * 
      * @returns Array of parameter values
      */
-    private getArguments(): any[] {
+    public getArguments(): any[] {
         return this.children.map(child => child.value());
     }
 
     /**
-     * Executes the async data provider function and yields results.
+     * Generates the async data provider function results.
      * 
+     * Subclasses override this method with their own typed parameters.
+     * The framework automatically evaluates the AST children and spreads
+     * them as arguments when calling this method.
+     * 
+     * @param args - Arguments passed from the query (e.g., myFunc(arg1, arg2))
      * @yields Data items from the async provider
      * @throws {Error} If the function is not registered as an async provider
+     * 
+     * @example
+     * ```typescript
+     * // Subclass with typed parameters:
+     * async *generate(count: number = 1, filter?: string): AsyncGenerator<any> {
+     *     // Implementation
+     * }
+     * ```
      */
-    public async *execute(): AsyncGenerator<any, void, unknown> {
-        const provider = FunctionFactory.getAsyncProvider(this._name);
-        if (!provider) {
-            throw new Error(`Async data provider '${this._name}' is not registered`);
-        }
-
-        const args = this.getArguments();
-        const result = provider(...args);
-
-        // Check if result is an async generator or a promise
-        if (result && typeof (result as AsyncGenerator).next === 'function') {
-            // It's an async generator
-            yield* result as AsyncGenerator<any, void, unknown>;
-        } else {
-            // It's a promise - await and yield the result
-            const data = await result;
-            if (Array.isArray(data)) {
-                for (const item of data) {
-                    yield item;
-                }
-            } else {
-                yield data;
-            }
-        }
-    }
-
-    public toString(): string {
-        return `AsyncFunction (${this._name})`;
+    public async *generate(...args: any[]): AsyncGenerator<any, void, unknown> {
+        throw new Error("Not implemented: generate method must be overridden in subclasses.");
     }
 }
 

package/src/parsing/functions/function.ts

@@ -22,9 +22,9 @@ class Function extends ASTNode {
      * 
      * @param name - The function name
      */
-    constructor(name: string) {
+    constructor(name?: string) {
         super();
-        this._name = name;
+        this._name = name || this.constructor.name;
     }
 
     /**

package/src/parsing/functions/function_factory.ts

@@ -22,9 +22,10 @@ import {
     getRegisteredFunctionMetadata,
     getFunctionMetadata,
     getRegisteredFunctionFactory,
-    getRegisteredAsyncProvider,
     AsyncDataProvider
 } from "./function_metadata";
+import AsyncFunction from "./async_function";
+import { get } from "node:http";
 
 // Re-export AsyncDataProvider for backwards compatibility
 export { AsyncDataProvider };
@@ -50,7 +51,7 @@ class FunctionFactory {
      * @returns The async data provider, or undefined if not found
      */
     public static getAsyncProvider(name: string): AsyncDataProvider | undefined {
-        return getRegisteredAsyncProvider(name.toLowerCase());
+        return getRegisteredFunctionFactory(name.toLowerCase());
     }
 
     /**
@@ -60,7 +61,7 @@ class FunctionFactory {
      * @returns True if the function is an async data provider
      */
     public static isAsyncProvider(name: string): boolean {
-        return getRegisteredAsyncProvider(name.toLowerCase()) !== undefined;
+        return getRegisteredFunctionFactory(name.toLowerCase(), "async") !== undefined;
     }
 
     /**
@@ -123,7 +124,7 @@ class FunctionFactory {
      * @returns A Function instance of the appropriate type
      */
     public static create(name: string): Function {
-        const lowerName = name.toLowerCase();
+        const lowerName: string = name.toLowerCase();
         
         // Check decorator-registered functions (built-ins use @FunctionDef)
         const decoratorFactory = getRegisteredFunctionFactory(lowerName);
@@ -131,8 +132,7 @@ class FunctionFactory {
             return decoratorFactory();
         }
 
-        // Unknown function - return generic Function instance
-        return new Function(name);
+        throw new Error(`Unknown function: ${name}`);
     }
 
     /**
@@ -143,7 +143,7 @@ class FunctionFactory {
      * @returns A PredicateFunction instance of the appropriate type
      */
     public static createPredicate(name: string): PredicateFunction {
-        const lowerName = name.toLowerCase();
+        const lowerName: string = name.toLowerCase();
         
         // Check decorator-registered predicate functions
         const decoratorFactory = getRegisteredFunctionFactory(lowerName, 'predicate');
@@ -151,9 +151,18 @@ class FunctionFactory {
             return decoratorFactory();
         }
 
-        // Unknown predicate function - return generic PredicateFunction instance
-        return new PredicateFunction(name);
+        throw new Error(`Unknown predicate function: ${name}`);
     }
+
+    public static createAsync(name: string): AsyncFunction {
+        const lowerName: string = name.toLowerCase();
+        const decoratorFactory = getRegisteredFunctionFactory(lowerName, 'async');
+        if (decoratorFactory) {
+            return decoratorFactory() as AsyncFunction;
+        }
+        throw new Error(`Unknown async function: ${name}`);
+    }
+
 }
 
 export default FunctionFactory;