flowquery 1.0.46 → 1.0.48

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

@@ -1,170 +0,0 @@
-"""Factory for creating function instances by name."""
-
-from typing import Any, Callable, Dict, List, Optional
-
-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[..., Any]]:
-        """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) -> Any:
-        """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) -> Any:
-        """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) -> Any:
-        """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

@@ -1,148 +0,0 @@
-"""Function metadata and decorator for FlowQuery functions."""
-
-from dataclasses import dataclass
-from typing import Any, Callable, Dict, List, Optional, TypedDict, cast
-
-# 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=cast(OutputSchema, 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()  # type: ignore[misc]
-        cls._factories[registry_key] = lambda c=constructor: c()  # type: ignore[misc]
-
-    @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) -> Callable[[type], type]:
-    """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

@@ -1,67 +0,0 @@
-"""Functions introspection function."""
-
-from typing import Any
-
-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) -> None:
-        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/head.py

@@ -1,39 +0,0 @@
-"""Head function."""
-
-from typing import Any
-
-from .function import Function
-from .function_metadata import FunctionDef
-
-
-@FunctionDef({
-    "description": "Returns the first element of a list",
-    "category": "scalar",
-    "parameters": [
-        {"name": "list", "description": "The list to get the first element from", "type": "array"}
-    ],
-    "output": {"description": "The first element of the list", "type": "any", "example": "1"},
-    "examples": [
-        "RETURN head([1, 2, 3])",
-        "WITH ['a', 'b', 'c'] AS items RETURN head(items)"
-    ]
-})
-class Head(Function):
-    """Head function.
-
-    Returns the first element of a list.
-    """
-
-    def __init__(self) -> None:
-        super().__init__("head")
-        self._expected_parameter_count = 1
-
-    def value(self) -> Any:
-        val = self.get_children()[0].value()
-        if val is None:
-            return None
-        if not isinstance(val, list):
-            raise ValueError("head() expects a list")
-        if len(val) == 0:
-            return None
-        return val[0]

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

@@ -1,49 +0,0 @@
-"""Id function."""
-
-from typing import Any
-
-from .function import Function
-from .function_metadata import FunctionDef
-
-
-@FunctionDef({
-    "description": (
-        "Returns the id of a node or relationship. "
-        "For nodes, returns the id property. For relationships, returns the type."
-    ),
-    "category": "scalar",
-    "parameters": [
-        {"name": "entity", "description": "A node or relationship to get the id from", "type": "object"}
-    ],
-    "output": {"description": "The id of the entity", "type": "any", "example": "1"},
-    "examples": [
-        "MATCH (n:Person) RETURN id(n)",
-        "MATCH (a)-[r]->(b) RETURN id(r)"
-    ]
-})
-class Id(Function):
-    """Id function.
-
-    Returns the id of a node or relationship.
-    """
-
-    def __init__(self) -> None:
-        super().__init__("id")
-        self._expected_parameter_count = 1
-
-    def value(self) -> Any:
-        obj = self.get_children()[0].value()
-        if obj is None:
-            return None
-        if not isinstance(obj, dict):
-            raise ValueError("id() expects a node or relationship")
-
-        # If it's a RelationshipMatchRecord (has type, startNode, endNode, properties)
-        if all(k in obj for k in ("type", "startNode", "endNode", "properties")):
-            return obj["type"]
-
-        # If it's a node record (has id field)
-        if "id" in obj:
-            return obj["id"]
-
-        raise ValueError("id() expects a node or relationship")

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

@@ -1,49 +0,0 @@
-"""Join function."""
-
-from typing import Any, List
-
-from ..ast_node import ASTNode
-from ..expressions.string import String
-from .function import Function
-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) -> None:
-        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 array is None:
-            return None
-        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

@@ -1,34 +0,0 @@
-"""Keys function."""
-
-from typing import Any
-
-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) -> None:
-        super().__init__("keys")
-        self._expected_parameter_count = 1
-
-    def value(self) -> Any:
-        obj = self.get_children()[0].value()
-        if obj is None:
-            return None
-        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/last.py

@@ -1,39 +0,0 @@
-"""Last function."""
-
-from typing import Any
-
-from .function import Function
-from .function_metadata import FunctionDef
-
-
-@FunctionDef({
-    "description": "Returns the last element of a list",
-    "category": "scalar",
-    "parameters": [
-        {"name": "list", "description": "The list to get the last element from", "type": "array"}
-    ],
-    "output": {"description": "The last element of the list", "type": "any", "example": "3"},
-    "examples": [
-        "RETURN last([1, 2, 3])",
-        "WITH ['a', 'b', 'c'] AS items RETURN last(items)"
-    ]
-})
-class Last(Function):
-    """Last function.
-
-    Returns the last element of a list.
-    """
-
-    def __init__(self) -> None:
-        super().__init__("last")
-        self._expected_parameter_count = 1
-
-    def value(self) -> Any:
-        val = self.get_children()[0].value()
-        if val is None:
-            return None
-        if not isinstance(val, list):
-            raise ValueError("last() expects a list")
-        if len(val) == 0:
-            return None
-        return val[-1]

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

@@ -1,60 +0,0 @@
-"""Local datetime function."""
-
-from datetime import datetime
-from typing import Any
-
-from .function import Function
-from .function_metadata import FunctionDef
-from .temporal_utils import build_datetime_object, parse_temporal_arg
-
-
-@FunctionDef({
-    "description": (
-        "Returns a local datetime value (no timezone). With no arguments returns the current local datetime. "
-        "Accepts an ISO 8601 string or a map of components."
-    ),
-    "category": "scalar",
-    "parameters": [
-        {
-            "name": "input",
-            "description": "Optional. An ISO 8601 datetime string or a map of components.",
-            "type": "string",
-            "required": False,
-        },
-    ],
-    "output": {
-        "description": (
-            "A datetime object with properties: year, month, day, hour, minute, second, millisecond, "
-            "epochMillis, epochSeconds, dayOfWeek, dayOfYear, quarter, formatted"
-        ),
-        "type": "object",
-    },
-    "examples": [
-        "RETURN localdatetime() AS now",
-        "RETURN localdatetime('2025-06-15T12:30:00') AS dt",
-        "WITH localdatetime() AS dt RETURN dt.hour, dt.minute",
-    ],
-})
-class LocalDatetime(Function):
-    """Local datetime function.
-
-    Returns a local datetime value (date + time, no timezone offset).
-    When called with no arguments, returns the current local datetime.
-    When called with a string argument, parses it as an ISO 8601 datetime.
-    """
-
-    def __init__(self) -> None:
-        super().__init__("localdatetime")
-        self._expected_parameter_count = None
-
-    def value(self) -> Any:
-        children = self.get_children()
-        if len(children) > 1:
-            raise ValueError("localdatetime() accepts at most one argument")
-
-        if len(children) == 1:
-            d = parse_temporal_arg(children[0].value(), "localdatetime")
-        else:
-            d = datetime.now()
-
-        return build_datetime_object(d, utc=False)