flowquery 1.0.16 → 1.0.17

package/flowquery-py/src/parsing/functions/function.py

@@ -0,0 +1,68 @@
+"""Base class for all functions in FlowQuery."""
+
+from typing import List, Optional, Any
+
+from ..ast_node import ASTNode
+
+
+class Function(ASTNode):
+    """Base class for all functions in FlowQuery.
+    
+    Functions can have parameters and may support the DISTINCT modifier.
+    Subclasses implement specific function logic.
+    
+    Example:
+        func = FunctionFactory.create("sum")
+        func.parameters = [expression1, expression2]
+    """
+
+    def __init__(self, name: Optional[str] = None):
+        """Creates a new Function with the given name.
+        
+        Args:
+            name: The function name
+        """
+        super().__init__()
+        self._name = name or self.__class__.__name__
+        self._expected_parameter_count: Optional[int] = None
+        self._supports_distinct: bool = False
+
+    @property
+    def parameters(self) -> List[ASTNode]:
+        """Gets the function parameters."""
+        return self.children
+
+    @parameters.setter
+    def parameters(self, nodes: List[ASTNode]) -> None:
+        """Sets the function parameters.
+        
+        Args:
+            nodes: Array of AST nodes representing the function arguments
+            
+        Raises:
+            ValueError: If the number of parameters doesn't match expected count
+        """
+        if self._expected_parameter_count is not None and self._expected_parameter_count != len(nodes):
+            raise ValueError(
+                f"Function {self._name} expected {self._expected_parameter_count} parameters, "
+                f"but got {len(nodes)}"
+            )
+        self.children = nodes
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def __str__(self) -> str:
+        return f"Function ({self._name})"
+
+    @property
+    def distinct(self) -> bool:
+        return self._supports_distinct
+
+    @distinct.setter
+    def distinct(self, value: bool) -> None:
+        if self._supports_distinct:
+            self._supports_distinct = value
+        else:
+            raise ValueError(f"Function {self._name} does not support distinct")

package/flowquery-py/src/parsing/functions/function_factory.py

@@ -0,0 +1,173 @@
+"""Factory for creating function instances by name."""
+
+from typing import Any, Callable, Dict, List, Optional
+
+from .function import Function
+from .async_function import AsyncFunction
+from .predicate_function import PredicateFunction
+from .function_metadata import (
+    FunctionMetadata,
+    get_function_metadata,
+    get_registered_function_factory,
+    get_registered_function_metadata,
+)
+
+
+class FunctionFactory:
+    """Factory for creating function instances by name.
+    
+    All functions are registered via the @FunctionDef decorator.
+    Maps function names (case-insensitive) to their corresponding implementation classes.
+    Supports built-in functions like sum, avg, collect, range, split, join, etc.
+    
+    Example:
+        sum_func = FunctionFactory.create("sum")
+        avg_func = FunctionFactory.create("AVG")
+    """
+
+    @staticmethod
+    def get_async_provider(name: str) -> Optional[Callable]:
+        """Gets an async data provider by name.
+        
+        Args:
+            name: The function name (case-insensitive)
+            
+        Returns:
+            The async data provider, or None if not found
+        """
+        return get_registered_function_factory(name.lower())
+
+    @staticmethod
+    def is_async_provider(name: str) -> bool:
+        """Checks if a function name is registered as an async data provider.
+        
+        Args:
+            name: The function name (case-insensitive)
+            
+        Returns:
+            True if the function is an async data provider
+        """
+        return get_registered_function_factory(name.lower(), "async") is not None
+
+    @staticmethod
+    def get_metadata(name: str) -> Optional[FunctionMetadata]:
+        """Gets metadata for a specific function.
+        
+        Args:
+            name: The function name (case-insensitive)
+            
+        Returns:
+            The function metadata, or None if not found
+        """
+        return get_function_metadata(name.lower())
+
+    @staticmethod
+    def list_functions(
+        category: Optional[str] = None,
+        async_only: bool = False,
+        sync_only: bool = False
+    ) -> List[FunctionMetadata]:
+        """Lists all registered functions with their metadata.
+        
+        Args:
+            category: Optional category filter
+            async_only: If True, only return async functions
+            sync_only: If True, only return sync functions
+            
+        Returns:
+            Array of function metadata
+        """
+        result: List[FunctionMetadata] = []
+        
+        for meta in get_registered_function_metadata():
+            if category and meta.category != category:
+                continue
+            if async_only and meta.category != "async":
+                continue
+            if sync_only and meta.category == "async":
+                continue
+            result.append(meta)
+        
+        return result
+
+    @staticmethod
+    def list_function_names() -> List[str]:
+        """Lists all registered function names.
+        
+        Returns:
+            Array of function names
+        """
+        return [m.name for m in get_registered_function_metadata()]
+
+    @staticmethod
+    def to_json() -> Dict[str, Any]:
+        """Gets all function metadata as a JSON-serializable object for LLM consumption.
+        
+        Returns:
+            Object with functions grouped by category
+        """
+        functions = FunctionFactory.list_functions()
+        categories = list(set(f.category for f in functions if f.category))
+        return {"functions": functions, "categories": categories}
+
+    @staticmethod
+    def create(name: str) -> Function:
+        """Creates a function instance by name.
+        
+        Args:
+            name: The function name (case-insensitive)
+            
+        Returns:
+            A Function instance of the appropriate type
+            
+        Raises:
+            ValueError: If the function name is not registered
+        """
+        lower_name = name.lower()
+        
+        # Check decorator-registered functions
+        decorator_factory = get_registered_function_factory(lower_name)
+        if decorator_factory:
+            return decorator_factory()
+        
+        raise ValueError(f"Unknown function: {name}")
+
+    @staticmethod
+    def create_predicate(name: str) -> PredicateFunction:
+        """Creates a predicate function instance by name.
+        
+        Args:
+            name: The function name (case-insensitive)
+            
+        Returns:
+            A PredicateFunction instance of the appropriate type
+            
+        Raises:
+            ValueError: If the predicate function name is not registered
+        """
+        lower_name = name.lower()
+        
+        decorator_factory = get_registered_function_factory(lower_name, "predicate")
+        if decorator_factory:
+            return decorator_factory()
+        
+        raise ValueError(f"Unknown predicate function: {name}")
+
+    @staticmethod
+    def create_async(name: str) -> AsyncFunction:
+        """Creates an async function instance by name.
+        
+        Args:
+            name: The function name (case-insensitive)
+            
+        Returns:
+            An AsyncFunction instance of the appropriate type
+            
+        Raises:
+            ValueError: If the async function name is not registered
+        """
+        lower_name = name.lower()
+        decorator_factory = get_registered_function_factory(lower_name, "async")
+        if decorator_factory:
+            return decorator_factory()
+        raise ValueError(f"Unknown async function: {name}")

package/flowquery-py/src/parsing/functions/function_metadata.py

@@ -0,0 +1,149 @@
+"""Function metadata and decorator for FlowQuery functions."""
+
+from typing import Any, Callable, Dict, List, Optional, TypedDict, Union
+from dataclasses import dataclass
+
+
+# Type definitions
+FunctionCategory = str  # "scalar" | "aggregate" | "predicate" | "async" | string
+
+
+class ParameterSchema(TypedDict, total=False):
+    """Schema definition for function arguments."""
+    name: str
+    description: str
+    type: str  # "string" | "number" | "boolean" | "object" | "array" | "null"
+    required: bool
+    default: Any
+    items: Dict[str, Any]
+    properties: Dict[str, Any]
+    enum: List[Any]
+    example: Any
+
+
+class OutputSchema(TypedDict, total=False):
+    """Schema definition for function output."""
+    description: str
+    type: str
+    items: Dict[str, Any]
+    properties: Dict[str, Any]
+    example: Any
+
+
+@dataclass
+class FunctionMetadata:
+    """Metadata for a registered function, designed for LLM consumption."""
+    name: str
+    description: str
+    category: FunctionCategory
+    parameters: List[ParameterSchema]
+    output: OutputSchema
+    examples: Optional[List[str]] = None
+    notes: Optional[str] = None
+
+
+class FunctionDefOptions(TypedDict, total=False):
+    """Decorator options - metadata without the name (derived from class)."""
+    description: str
+    category: FunctionCategory
+    parameters: List[ParameterSchema]
+    output: OutputSchema
+    examples: List[str]
+    notes: str
+
+
+class FunctionRegistry:
+    """Centralized registry for function metadata, factories, and async providers."""
+    
+    _metadata: Dict[str, FunctionMetadata] = {}
+    _factories: Dict[str, Callable[[], Any]] = {}
+
+    @classmethod
+    def register(cls, constructor: type, options: FunctionDefOptions) -> None:
+        """Registers a regular function class."""
+        instance = constructor()
+        display_name = getattr(instance, 'name', constructor.__name__).lower()
+        category = options.get('category', '')
+        registry_key = f"{display_name}:{category}" if category else display_name
+
+        metadata = FunctionMetadata(
+            name=display_name,
+            description=options.get('description', ''),
+            category=options.get('category', 'scalar'),
+            parameters=options.get('parameters', []),
+            output=options.get('output', {'description': '', 'type': 'any'}),
+            examples=options.get('examples'),
+            notes=options.get('notes'),
+        )
+        cls._metadata[registry_key] = metadata
+
+        if category != 'predicate':
+            cls._factories[display_name] = lambda c=constructor: c()
+        cls._factories[registry_key] = lambda c=constructor: c()
+
+    @classmethod
+    def get_all_metadata(cls) -> List[FunctionMetadata]:
+        return list(cls._metadata.values())
+
+    @classmethod
+    def get_metadata(cls, name: str, category: Optional[str] = None) -> Optional[FunctionMetadata]:
+        lower_name = name.lower()
+        if category:
+            return cls._metadata.get(f"{lower_name}:{category}")
+        for meta in cls._metadata.values():
+            if meta.name.lower() == lower_name:
+                return meta
+        return None
+
+    @classmethod
+    def get_factory(cls, name: str, category: Optional[str] = None) -> Optional[Callable[[], Any]]:
+        lower_name = name.lower()
+        if category:
+            return cls._factories.get(f"{lower_name}:{category}")
+        return cls._factories.get(lower_name)
+
+
+def FunctionDef(options: FunctionDefOptions):
+    """Class decorator that registers function metadata.
+    
+    The function name is derived from the class's constructor.
+    
+    Args:
+        options: Function metadata (excluding name)
+        
+    Returns:
+        Class decorator
+        
+    Example:
+        @FunctionDef({
+            'description': "Adds two numbers",
+            'category': "scalar",
+            'parameters': [
+                {'name': "a", 'description': "First number", 'type': "number"},
+                {'name': "b", 'description': "Second number", 'type': "number"}
+            ],
+            'output': {'description': "Sum of a and b", 'type': "number"},
+        })
+        class AddFunction(Function):
+            def __init__(self):
+                super().__init__("add")
+    """
+    def decorator(cls: type) -> type:
+        FunctionRegistry.register(cls, options)
+        return cls
+    return decorator
+
+
+def get_registered_function_metadata() -> List[FunctionMetadata]:
+    """Gets all registered function metadata from decorators."""
+    return FunctionRegistry.get_all_metadata()
+
+
+def get_registered_function_factory(name: str, category: Optional[str] = None) -> Optional[Callable[[], Any]]:
+    """Gets a registered function factory by name."""
+    return FunctionRegistry.get_factory(name, category)
+
+
+def get_function_metadata(name: str, category: Optional[str] = None) -> Optional[FunctionMetadata]:
+    """Gets metadata for a specific function by name."""
+    return FunctionRegistry.get_metadata(name, category)

package/flowquery-py/src/parsing/functions/functions.py

@@ -0,0 +1,59 @@
+"""Functions introspection function."""
+
+from typing import Any, Dict, List, Optional
+
+from .function import Function
+from .function_factory import FunctionFactory
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Lists all registered functions with their metadata. Useful for discovering available functions and their documentation.",
+    "category": "scalar",
+    "parameters": [
+        {"name": "category", "description": "Optional category to filter by (e.g., 'aggregation', 'string', 'math')", "type": "string", "required": False}
+    ],
+    "output": {
+        "description": "Array of function metadata objects",
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+                "name": {"description": "Function name", "type": "string"},
+                "description": {"description": "What the function does", "type": "string"},
+                "category": {"description": "Function category", "type": "string"},
+                "parameters": {"description": "Array of parameter definitions", "type": "array"},
+                "output": {"description": "Output schema", "type": "object"},
+                "examples": {"description": "Usage examples", "type": "array"}
+            }
+        }
+    },
+    "examples": [
+        "WITH functions() AS funcs RETURN funcs",
+        "WITH functions('aggregation') AS funcs UNWIND funcs AS f RETURN f.name, f.description"
+    ]
+})
+class Functions(Function):
+    """Functions introspection function.
+    
+    Lists all registered functions with their metadata.
+    """
+
+    def __init__(self):
+        super().__init__("functions")
+        self._expected_parameter_count = None  # 0 or 1 parameter
+
+    def value(self) -> Any:
+        children = self.get_children()
+        
+        if len(children) == 0:
+            # Return all functions
+            return FunctionFactory.list_functions()
+        elif len(children) == 1:
+            # Filter by category
+            category = children[0].value()
+            if isinstance(category, str):
+                return FunctionFactory.list_functions(category=category)
+            raise ValueError("functions() category parameter must be a string")
+        else:
+            raise ValueError("functions() takes 0 or 1 parameters")

package/flowquery-py/src/parsing/functions/join.py

@@ -0,0 +1,47 @@
+"""Join function."""
+
+from typing import Any, List
+
+from .function import Function
+from ..ast_node import ASTNode
+from ..expressions.string import String
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Joins an array of strings with a delimiter",
+    "category": "scalar",
+    "parameters": [
+        {"name": "array", "description": "Array of values to join", "type": "array"},
+        {"name": "delimiter", "description": "Delimiter to join with", "type": "string"}
+    ],
+    "output": {"description": "Joined string", "type": "string", "example": "a,b,c"},
+    "examples": ["WITH ['a', 'b', 'c'] AS arr RETURN join(arr, ',')"]
+})
+class Join(Function):
+    """Join function.
+    
+    Joins an array of strings with a delimiter.
+    """
+
+    def __init__(self):
+        super().__init__("join")
+        self._expected_parameter_count = 2
+
+    @property
+    def parameters(self) -> List[ASTNode]:
+        return self.get_children()
+
+    @parameters.setter
+    def parameters(self, nodes: List[ASTNode]) -> None:
+        if len(nodes) == 1:
+            nodes.append(String(""))
+        for node in nodes:
+            self.add_child(node)
+
+    def value(self) -> Any:
+        array = self.get_children()[0].value()
+        delimiter = self.get_children()[1].value()
+        if not isinstance(array, list) or not isinstance(delimiter, str):
+            raise ValueError("Invalid arguments for join function")
+        return delimiter.join(str(item) for item in array)

package/flowquery-py/src/parsing/functions/keys.py

@@ -0,0 +1,34 @@
+"""Keys function."""
+
+from typing import Any, List
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Returns the keys of an object (associative array) as an array",
+    "category": "scalar",
+    "parameters": [
+        {"name": "object", "description": "Object to extract keys from", "type": "object"}
+    ],
+    "output": {"description": "Array of keys", "type": "array", "example": ["name", "age"]},
+    "examples": ["WITH { name: 'Alice', age: 30 } AS obj RETURN keys(obj)"]
+})
+class Keys(Function):
+    """Keys function.
+    
+    Returns the keys of an object (associative array) as an array.
+    """
+
+    def __init__(self):
+        super().__init__("keys")
+        self._expected_parameter_count = 1
+
+    def value(self) -> Any:
+        obj = self.get_children()[0].value()
+        if obj is None:
+            return []
+        if not isinstance(obj, dict):
+            raise ValueError("keys() expects an object, not an array or primitive")
+        return list(obj.keys())

package/flowquery-py/src/parsing/functions/predicate_function.py

@@ -0,0 +1,46 @@
+"""Base class for predicate functions in FlowQuery."""
+
+from typing import Any, Optional
+
+from ..ast_node import ASTNode
+from ..expressions.expression import Expression
+from ..expressions.reference import Reference
+from .value_holder import ValueHolder
+
+
+class PredicateFunction(ASTNode):
+    """Base class for predicate functions."""
+
+    def __init__(self, name: Optional[str] = None):
+        super().__init__()
+        self._name = name or self.__class__.__name__
+        self._value_holder = ValueHolder()
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def reference(self) -> Reference:
+        return self.first_child()
+
+    @property
+    def array(self) -> ASTNode:
+        return self.get_children()[1].first_child()
+
+    @property
+    def _return(self) -> Expression:
+        return self.get_children()[2]
+
+    @property
+    def where(self) -> Optional['Where']:
+        from ..operations.where import Where
+        if len(self.get_children()) == 4:
+            return self.get_children()[3]
+        return None
+
+    def value(self) -> Any:
+        raise NotImplementedError("Method not implemented.")
+
+    def __str__(self) -> str:
+        return f"PredicateFunction ({self._name})"

package/flowquery-py/src/parsing/functions/predicate_sum.py

@@ -0,0 +1,47 @@
+"""PredicateSum function."""
+
+from typing import Any, List, Optional
+
+from .predicate_function import PredicateFunction
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Calculates the sum of values in an array with optional filtering. Uses list comprehension syntax: sum(variable IN array [WHERE condition] | expression)",
+    "category": "predicate",
+    "parameters": [
+        {"name": "variable", "description": "Variable name to bind each element", "type": "string"},
+        {"name": "array", "description": "Array to iterate over", "type": "array"},
+        {"name": "expression", "description": "Expression to sum for each element", "type": "any"},
+        {"name": "where", "description": "Optional filter condition", "type": "boolean", "required": False}
+    ],
+    "output": {"description": "Sum of the evaluated expressions", "type": "number", "example": 6},
+    "examples": [
+        "WITH [1, 2, 3] AS nums RETURN sum(n IN nums | n)",
+        "WITH [1, 2, 3, 4] AS nums RETURN sum(n IN nums WHERE n > 1 | n * 2)"
+    ]
+})
+class PredicateSum(PredicateFunction):
+    """PredicateSum function.
+    
+    Calculates the sum of values in an array with optional filtering.
+    """
+
+    def __init__(self):
+        super().__init__("sum")
+
+    def value(self) -> Any:
+        self.reference.referred = self._value_holder
+        array = self.array.value()
+        if array is None or not isinstance(array, list):
+            raise ValueError("Invalid array for sum function")
+        
+        _sum: Optional[Any] = None
+        for item in array:
+            self._value_holder.holder = item
+            if self.where is None or self.where.value():
+                if _sum is None:
+                    _sum = self._return.value()
+                else:
+                    _sum += self._return.value()
+        return _sum

package/flowquery-py/src/parsing/functions/rand.py

@@ -0,0 +1,28 @@
+"""Rand function."""
+
+import random
+from typing import Any
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Generates a random number between 0 and 1",
+    "category": "scalar",
+    "parameters": [],
+    "output": {"description": "Random number between 0 and 1", "type": "number", "example": 0.7234},
+    "examples": ["WITH rand() AS r RETURN r"]
+})
+class Rand(Function):
+    """Rand function.
+    
+    Generates a random number between 0 and 1.
+    """
+
+    def __init__(self):
+        super().__init__("rand")
+        self._expected_parameter_count = 0
+
+    def value(self) -> Any:
+        return random.random()

package/flowquery-py/src/parsing/functions/range_.py

@@ -0,0 +1,34 @@
+"""Range function."""
+
+from typing import Any, List
+
+from .function import Function
+from .function_metadata import FunctionDef
+
+
+@FunctionDef({
+    "description": "Generates an array of sequential integers",
+    "category": "scalar",
+    "parameters": [
+        {"name": "start", "description": "Starting number (inclusive)", "type": "number"},
+        {"name": "end", "description": "Ending number (inclusive)", "type": "number"}
+    ],
+    "output": {"description": "Array of integers from start to end", "type": "array", "items": {"type": "number"}, "example": [1, 2, 3, 4, 5]},
+    "examples": ["WITH range(1, 5) AS nums RETURN nums"]
+})
+class Range(Function):
+    """Range function.
+    
+    Generates an array of sequential integers.
+    """
+
+    def __init__(self):
+        super().__init__("range")
+        self._expected_parameter_count = 2
+
+    def value(self) -> Any:
+        start = self.get_children()[0].value()
+        end = self.get_children()[1].value()
+        if not isinstance(start, (int, float)) or not isinstance(end, (int, float)):
+            raise ValueError("Invalid arguments for range function")
+        return list(range(int(start), int(end) + 1))