quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/executors/data/invoke_executor.py

@@ -0,0 +1,228 @@
+"""
+Invoke Executor - Execute q:invoke statements
+
+Handles function, component, and HTTP invocations with caching.
+"""
+
+from typing import Any, List, Dict, Type
+import json
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.features.invocation.src.ast_node import InvokeNode
+
+
+class InvokeExecutor(BaseExecutor):
+    """
+    Executor for q:invoke statements.
+
+    Supports:
+    - Function invocation (local functions)
+    - Component invocation (other .q components)
+    - HTTP invocation (REST APIs)
+    - Response caching with TTL
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [InvokeNode]
+
+    def execute(self, node: InvokeNode, exec_context) -> Any:
+        """
+        Execute invocation.
+
+        Args:
+            node: InvokeNode with invocation configuration
+            exec_context: Execution context
+
+        Returns:
+            None (stores result in context)
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            invocation_type = node.get_invocation_type()
+
+            if invocation_type == "unknown":
+                raise ExecutorError(
+                    f"Invoke '{node.name}' requires one of: function, component, url or service"
+                )
+
+            # Build parameters based on type
+            if invocation_type == "function":
+                params = self._build_function_params(node, context)
+            elif invocation_type == "component":
+                params = self._build_component_params(node, context)
+            elif invocation_type == "http":
+                params = self._build_http_params(node, context)
+            elif invocation_type == "service":
+                result = self._invoke_service(node, context)
+                self._store_result(node, result, exec_context)
+                params = None
+            else:
+                raise ExecutorError(f"Unsupported invocation type: {invocation_type}")
+
+            # Check cache
+            if params is None:
+                pass
+            elif node.cache:
+                cache_key = f"invoke_{node.name}_{hash(str(params))}"
+                cached = self.services.invocation.get_from_cache(cache_key)
+                if cached is not None:
+                    self._store_result(node, cached, exec_context)
+                    return
+
+            if params is not None:
+                # Execute invocation
+                result = self.services.invocation.invoke(
+                    invocation_type,
+                    params,
+                    context=self.runtime
+                )
+
+                # Cache result
+                if node.cache and result.success:
+                    cache_key = f"invoke_{node.name}_{hash(str(params))}"
+                    self.services.invocation.put_in_cache(cache_key, result, node.ttl)
+
+                # Store result
+                self._store_result(node, result, exec_context)
+
+        except Exception as e:
+            raise ExecutorError(f"Invoke execution error in '{node.name}': {e}")
+
+        # INV-2: same rule as q:data and q:query — a failure stops the
+        # component, unless onerror="continue" says the program handles it.
+        if not result.success and getattr(node, 'on_error', 'fail') != 'continue':
+            erro = result.error
+            motivo = erro.get('message', 'unknown error') if isinstance(erro, dict) else str(erro)
+            raise ExecutorError(
+                f"q:invoke '{node.name}' failed: {motivo}. "
+                f"Add onerror=\"continue\" to handle it with {node.name}_result instead.")
+
+    def _invoke_service(self, node: InvokeNode, context: Dict[str, Any]):
+        """q:invoke service="name" (SVC-3): call a function declared with @service.
+
+        The q:param children are the keyword arguments, converted by their
+        type= like any other q:param. It was parsed since the first version
+        ("Service discovery (Phase 2)") and failed at runtime with
+        "Unsupported invocation type: service".
+        """
+        import time
+        from quantum import services
+        from quantum.core.features.invocation.src.runtime import InvocationResult
+        from quantum.runtime import param_validation
+
+        services.load(self.services.config.get('services') or [])
+        func = services.get(node.service)
+
+        args = self._param_args(node, context)
+        for param in node.params:
+            if param.name in args and getattr(param, 'type', None):
+                valor, erro = param_validation.coerce(param, args[param.name])
+                if erro:
+                    raise ExecutorError(erro)
+                args[param.name] = valor
+
+        inicio = time.time()
+        try:
+            data = func(**args)
+        except TypeError as exc:
+            return InvocationResult(success=False, invocation_type='service',
+                                    error={'message': f"service '{node.service}': {exc}"})
+        except Exception as exc:  # noqa: BLE001 — the service's own failure (INV-2)
+            return InvocationResult(success=False, invocation_type='service',
+                                    error={'message': f"service '{node.service}' failed: {exc}",
+                                           'type': type(exc).__name__})
+        return InvocationResult(success=True, data=data, invocation_type='service',
+                                execution_time=(time.time() - inicio) * 1000)
+
+    def _param_args(self, node: InvokeNode, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Resolve <q:param> children into call arguments.
+
+        This used to read `param.default`, but the invoke parser stores the
+        value= attribute on `param.value` — `default` is only the fallback.
+        So every argument arrived as the empty string and
+        <q:param name="n" value="21" /> passed ''.
+        """
+        args = {}
+        for param in node.params:
+            raw = getattr(param, 'value', None)
+            if raw is None:
+                raw = param.default
+            args[param.name] = self.apply_databinding(raw if raw is not None else "", context)
+        return args
+
+    def _build_function_params(self, node: InvokeNode, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Build parameters for function invocation"""
+        args = self._param_args(node, context)
+        return {
+            'function': node.function,
+            'args': args
+        }
+
+    def _build_component_params(self, node: InvokeNode, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Build parameters for component invocation"""
+        args = self._param_args(node, context)
+        return {
+            'component': node.component,
+            'args': args
+        }
+
+    def _build_http_params(self, node: InvokeNode, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Build parameters for HTTP invocation"""
+        url = self.apply_databinding(node.url, context)
+
+        headers = {}
+        for header_node in node.headers:
+            header_value = self.apply_databinding(header_node.value, context)
+            headers[header_node.name] = header_value
+
+        if 'Content-Type' not in headers and 'content-type' not in headers:
+            headers['Content-Type'] = node.content_type
+
+        # Same value=/default fallback as function and component calls: this
+        # read only `default`, so <q:param name="q" value="x"/> sent q=''.
+        query_params = self._param_args(node, context)
+
+        body = None
+        if node.body:
+            body = self.apply_databinding(node.body, context)
+            if isinstance(body, str) and 'json' in node.content_type.lower():
+                try:
+                    body = json.loads(body)
+                except:
+                    pass
+
+        return {
+            'url': url,
+            'method': node.method,
+            'headers': headers,
+            'params': query_params,
+            'body': body,
+            'auth_type': node.auth_type,
+            'auth_token': self.apply_databinding(node.auth_token, context) if node.auth_token else None,
+            'auth_header': node.auth_header,
+            'auth_username': self.apply_databinding(node.auth_username, context) if node.auth_username else None,
+            'auth_password': self.apply_databinding(node.auth_password, context) if node.auth_password else None,
+            'timeout': node.timeout,
+            'retry': node.retry,
+            'retry_delay': node.retry_delay,
+            'response_format': node.response_format
+        }
+
+    def _store_result(self, node: InvokeNode, result, exec_context):
+        """Store invocation result in context"""
+        exec_context.set_variable(node.name, result.data, scope="component")
+
+        result_dict = {
+            'success': result.success,
+            'data': result.data,
+            'error': result.error,
+            'executionTime': result.execution_time,
+            'invocationType': result.invocation_type,
+            'metadata': result.metadata
+        }
+
+        exec_context.set_variable(f"{node.name}_result", result_dict, scope="component")
+
+        if node.result:
+            exec_context.set_variable(node.result, result_dict, scope="component")

quantum/runtime/executors/data/query_executor.py

@@ -0,0 +1,290 @@
+"""
+Query Executor - Execute q:query statements
+
+Handles database queries with parameter validation, pagination, and Query of Queries.
+"""
+
+from typing import Any, List, Dict, Type
+import sqlite3
+import time
+import re
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import QueryNode
+
+
+class QueryExecutor(BaseExecutor):
+    """
+    Executor for q:query statements.
+
+    Supports:
+    - Database queries with parameterized SQL
+    - Pagination with automatic COUNT
+    - Query of Queries (in-memory SQL on result sets)
+    - Knowledge base queries (virtual datasource)
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [QueryNode]
+
+    def execute(self, node: QueryNode, exec_context) -> Any:
+        """
+        Execute database query.
+
+        Args:
+            node: QueryNode with query configuration
+            exec_context: Execution context
+
+        Returns:
+            QueryResult with data and metadata
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Resolve and validate parameters
+            resolved_params = self._resolve_params(node, context)
+
+            # Check for knowledge base query
+            if node.datasource and node.datasource.startswith('knowledge:'):
+                return self._execute_knowledge_query(node, resolved_params, exec_context)
+
+            # Check for Query of Queries
+            if node.source:
+                return self._execute_query_of_queries(node, context, resolved_params, exec_context)
+
+            # Execute standard database query
+            return self._execute_database_query(node, resolved_params, exec_context)
+
+        except Exception as e:
+            raise ExecutorError(f"Query execution error in '{node.name}': {e}")
+
+    def _resolve_params(self, node: QueryNode, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Resolve and validate query parameters"""
+        from quantum.runtime.query_validators import QueryValidator, QueryValidationError
+
+        resolved_params = {}
+        for param_node in node.params:
+            param_value = self.apply_databinding(param_node.value, context)
+
+            attributes = {
+                'null': param_node.null,
+                'max_length': param_node.max_length,
+                'scale': param_node.scale
+            }
+
+            try:
+                validated_value = QueryValidator.validate_param(
+                    param_value,
+                    param_node.param_type,
+                    attributes
+                )
+                resolved_params[param_node.name] = validated_value
+            except QueryValidationError as e:
+                raise ExecutorError(f"Parameter '{param_node.name}' validation failed: {e}")
+
+        return resolved_params
+
+    def _execute_database_query(self, node: QueryNode, params: Dict[str, Any], exec_context) -> Any:
+        """Execute standard database query"""
+        from quantum.runtime.query_validators import QueryValidator
+
+        # Sanitize SQL
+        QueryValidator.sanitize_sql(node.sql)
+
+        # Handle pagination
+        pagination_metadata = None
+        sql_to_execute = self._sorted_sql(node, params, exec_context)     # UI-13
+
+        if node.paginate:
+            pagination_metadata, sql_to_execute = self._handle_pagination(
+                node, params, exec_context, base_sql=sql_to_execute)
+
+        # Execute query
+        result = self.services.database.execute_query(
+            node.datasource,
+            sql_to_execute,
+            params
+        )
+
+        # Store results
+        self._store_query_result(node, result, pagination_metadata, exec_context)
+
+        return result
+
+    def _sorted_sql(self, node: QueryNode, params: Dict[str, Any], exec_context) -> str:
+        """UI-13: a sortable query orders by the URL's ?sort= (and ?dir=asc|desc).
+
+        The column must be one the query returns — found with LIMIT 0, never
+        taken from the URL otherwise; an unknown one leaves the order as
+        written (a URL is not an error)."""
+        if not getattr(node, 'sortable', False):
+            return node.sql
+        try:
+            consulta = exec_context.get_variable('query') if exec_context is not None else None
+        except Exception:
+            consulta = None
+        consulta = consulta if isinstance(consulta, dict) else {}
+        coluna = str(consulta.get('sort') or '').strip()
+        direcao = 'DESC' if str(consulta.get('dir') or '').lower() == 'desc' else 'ASC'
+        if not coluna:
+            return node.sql
+        base = node.sql.strip().rstrip(';')
+        sonda = self.services.database.execute_query(
+            node.datasource, f'SELECT * FROM ({base}) AS quantum_ordenada LIMIT 0', params)
+        if coluna not in (sonda.column_list or []):
+            return node.sql
+        return f'SELECT * FROM ({base}) AS quantum_ordenada ORDER BY "{coluna}" {direcao}'
+
+    def _handle_pagination(self, node: QueryNode, params: Dict[str, Any], exec_context=None,
+                           base_sql: str = None):
+        """Handle query pagination"""
+        count_sql = self._generate_count_query(node.sql)
+        count_result = self.services.database.execute_query(
+            node.datasource,
+            count_sql,
+            params
+        )
+
+        total_records = count_result.data[0]['count'] if count_result.data else 0
+
+        page = node.page if node.page is not None else 1
+        if getattr(node, 'page_expr', None):
+            # DB-9: from the URL, so never an error — ?page=abc or ?page=-3 is page 1.
+            variaveis = exec_context.get_all_variables() if exec_context is not None else None
+            bruto = self.apply_databinding(node.page_expr, variaveis)
+            try:
+                page = max(1, int(str(bruto).strip()))
+            except (TypeError, ValueError):
+                page = 1
+        # paginate="true" without a page size is a config error, not a
+        # reason to crash on None arithmetic further down.
+        page_size = node.page_size or 10
+        total_pages = (total_records + page_size - 1) // page_size
+
+        offset = (page - 1) * page_size
+        sql_to_execute = f"{base_sql or node.sql}\nLIMIT {page_size} OFFSET {offset}"
+
+        pagination_metadata = {
+            'totalRecords': total_records,
+            'totalPages': total_pages,
+            'currentPage': page,
+            'pageSize': page_size,
+            'hasNextPage': page < total_pages,
+            'hasPreviousPage': page > 1,
+            'startRecord': offset + 1 if total_records > 0 else 0,
+            'endRecord': min(offset + page_size, total_records)
+        }
+
+        return pagination_metadata, sql_to_execute
+
+    def _generate_count_query(self, original_sql: str) -> str:
+        """Generate COUNT(*) query from original SQL"""
+        sql = ' '.join(original_sql.split())
+        sql = re.sub(r'\s+ORDER\s+BY\s+[^;]+?(?=\s+(?:LIMIT|OFFSET|FOR\s+UPDATE)|$)', '', sql, flags=re.IGNORECASE)
+        sql = re.sub(r'\s+LIMIT\s+\d+', '', sql, flags=re.IGNORECASE)
+        sql = re.sub(r'\s+OFFSET\s+\d+', '', sql, flags=re.IGNORECASE)
+        return f"SELECT COUNT(*) as count FROM ({sql}) AS count_query"
+
+    def _execute_query_of_queries(self, node: QueryNode, context: Dict[str, Any],
+                                   params: Dict[str, Any], exec_context) -> Any:
+        """Execute Query of Queries - SQL on in-memory result sets"""
+        from quantum.runtime.database_service import QueryResult
+
+        source_name = node.source
+        source_data = context.get(source_name) or exec_context.get_variable(source_name)
+
+        if source_data is None:
+            raise ExecutorError(f"Source query '{source_name}' not found")
+
+        if not isinstance(source_data, list):
+            raise ExecutorError(f"Source '{source_name}' is not a query result")
+
+        if not source_data:
+            result = QueryResult(
+                success=True, data=[], record_count=0,
+                column_list=[], execution_time=0, sql=node.sql
+            )
+            self._store_query_result(node, result, None, exec_context)
+            return result
+
+        # Create in-memory SQLite database
+        conn = sqlite3.connect(':memory:')
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+
+        try:
+            first_row = source_data[0]
+            if not isinstance(first_row, dict):
+                raise ExecutorError("Source data must be list of dictionaries")
+
+            columns = list(first_row.keys())
+            column_defs = ', '.join([f'"{col}" TEXT' for col in columns])
+            cursor.execute(f'CREATE TABLE source_table ({column_defs})')
+
+            placeholders = ', '.join(['?' for _ in columns])
+            for row in source_data:
+                values = [row.get(col) for col in columns]
+                cursor.execute(f'INSERT INTO source_table VALUES ({placeholders})', values)
+
+            sql = node.sql.replace(f'FROM {source_name}', 'FROM source_table')
+            sql = sql.replace(f'FROM {{{source_name}}}', 'FROM source_table')
+
+            for param_name in params:
+                sql = sql.replace(f':{param_name}', '?')
+
+            start_time = time.time()
+            cursor.execute(sql, list(params.values()) if params else [])
+            result_rows = cursor.fetchall()
+            execution_time = (time.time() - start_time) * 1000
+
+            result_data = []
+            column_names = []
+            if result_rows:
+                column_names = [desc[0] for desc in cursor.description]
+                for row in result_rows:
+                    result_data.append(dict(zip(column_names, row)))
+
+            conn.close()
+
+            result = QueryResult(
+                success=True,
+                data=result_data,
+                record_count=len(result_data),
+                column_list=column_names,
+                execution_time=int(execution_time),
+                sql=node.sql
+            )
+
+            self._store_query_result(node, result, None, exec_context)
+            return result
+
+        except sqlite3.Error as e:
+            conn.close()
+            raise ExecutorError(f"Query of Queries SQL error: {e}")
+
+    def _execute_knowledge_query(self, node: QueryNode, params: Dict[str, Any], exec_context) -> Any:
+        """Execute knowledge base query (RAG)"""
+        # Delegate to runtime's knowledge query handler
+        return self.runtime._execute_knowledge_query(node, params, exec_context)
+
+    def _store_query_result(self, node: QueryNode, result, pagination_metadata, exec_context):
+        """Store query result in context"""
+        result_dict = result.to_dict()
+
+        if pagination_metadata:
+            result_dict['pagination'] = pagination_metadata
+
+        # Store data as array
+        exec_context.set_variable(node.name, result.data, scope="component")
+
+        # Store full result with metadata
+        exec_context.set_variable(f"{node.name}_result", result_dict, scope="component")
+
+        # Single-row field exposure
+        if result.data and len(result.data) == 1 and isinstance(result.data[0], dict):
+            for field_name, field_value in result.data[0].items():
+                dotted_key = f"{node.name}.{field_name}"
+                exec_context.set_variable(dotted_key, field_value, scope="component")
+
+        if node.result:
+            exec_context.set_variable(node.result, result_dict, scope="component")

quantum/runtime/executors/data/transaction_executor.py

@@ -0,0 +1,91 @@
+"""
+Transaction Executor - Execute q:transaction statements
+
+Handles database transactions with atomic commit/rollback.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import TransactionNode, QueryNode
+
+
+class TransactionExecutor(BaseExecutor):
+    """
+    Executor for q:transaction statements.
+
+    Supports:
+    - Atomic transaction execution
+    - Automatic rollback on failure
+    - Multiple isolation levels
+    - Nested statement execution
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [TransactionNode]
+
+    def execute(self, node: TransactionNode, exec_context) -> Any:
+        """
+        Execute database transaction.
+
+        Args:
+            node: TransactionNode with statements to execute
+            exec_context: Execution context
+
+        Returns:
+            Transaction result dict with success status
+        """
+        try:
+            # Determine datasource
+            datasource_name = self._get_datasource(node)
+
+            # Begin transaction
+            transaction_context = self.services.database.begin_transaction(datasource_name)
+
+            results = []
+            try:
+                # Execute all statements
+                for statement in node.statements:
+                    result = self.execute_child(statement, exec_context)
+                    results.append(result)
+
+                # Commit transaction
+                success = self.services.database.commit_transaction(transaction_context)
+
+                transaction_result = {
+                    'success': success,
+                    'committed': True,
+                    'isolation_level': node.isolation_level,
+                    'statement_count': len(node.statements),
+                    'results': results
+                }
+
+            except Exception as stmt_error:
+                # Rollback on failure
+                self.services.database.rollback_transaction(transaction_context)
+
+                transaction_result = {
+                    'success': False,
+                    'rolled_back': True,
+                    'error': str(stmt_error),
+                    'isolation_level': node.isolation_level
+                }
+
+                raise ExecutorError(f"Transaction failed and was rolled back: {stmt_error}")
+
+            # Store result
+            exec_context.set_variable('_transaction_result', transaction_result, scope="component")
+
+            return transaction_result
+
+        except ExecutorError:
+            raise
+        except Exception as e:
+            raise ExecutorError(f"Transaction execution error: {e}")
+
+    def _get_datasource(self, node: TransactionNode) -> str:
+        """Get datasource from first query in transaction"""
+        for stmt in node.statements:
+            if isinstance(stmt, QueryNode) and stmt.datasource:
+                return stmt.datasource
+        return "default"

quantum/runtime/executors/jobs/__init__.py

@@ -0,0 +1,11 @@
+"""
+Jobs Executors
+
+Executors for job/scheduling operations: schedule, thread, job.
+"""
+
+from .schedule_executor import ScheduleExecutor
+from .thread_executor import ThreadExecutor
+from .job_executor import JobExecutor
+
+__all__ = ['ScheduleExecutor', 'ThreadExecutor', 'JobExecutor']