quantum-framework 0.19.0__tar.gz → 0.20.0__tar.gz

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantum-framework
-Version: 0.19.0
+Version: 0.20.0
 Summary: Full-stack declarative framework for building web, desktop, and mobile applications
 Author-email: Daniel Gregorio <danielgregorio2611@gmail.com>
 License: MIT
@@ -94,7 +94,7 @@ and asks the model — in the markup. There is no Python file behind it.
 An agent with its own tools, same idea:
 
 ```xml
-<q:agent name="calc" model="phi3" max_iterations="4">
+<q:agent name="calc" model="phi3" maxIterations="4">
   <q:instruction>Use the add tool, then answer.</q:instruction>
 
   <q:tool name="add" description="Add two numbers">

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/README.md

@@ -44,7 +44,7 @@ and asks the model — in the markup. There is no Python file behind it.
 An agent with its own tools, same idea:
 
 ```xml
-<q:agent name="calc" model="phi3" max_iterations="4">
+<q:agent name="calc" model="phi3" maxIterations="4">
   <q:instruction>Use the add tool, then answer.</q:instruction>
 
   <q:tool name="add" description="Add two numbers">

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantum-framework"
-version = "0.19.0"
+version = "0.20.0"
 description = "Full-stack declarative framework for building web, desktop, and mobile applications"
 readme = "README.md"
 license = {text = "MIT"}

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/ast_nodes.py

@@ -699,6 +699,7 @@ class QueryNode(QuantumNode):
         self.paginate = False  # Enable automatic pagination
         self.page = None
         self.page_expr = None  # DB-9: page as an expression (default {query.page})
+        self.on_error = 'fail'  # IA-5: 'continue' hands a failure to <name>_result
         self.sortable = False  # UI-13: ORDER BY the URL's ?sort=/&dir=
         self.page_size = 20
         self.timeout = None
@@ -1478,6 +1479,10 @@ class LLMNode(QuantumNode):
         self.prompt = None              # Prompt text (with databinding)
         self.system = None              # System prompt (optional)
         self.messages: List[LLMMessageNode] = []  # Chat mode messages
+        self.on_error = 'fail'          # IA-5: 'continue' hands a failure to <name>_result
+        self.knowledge = None           # IA-6: answer from this knowledge base, citing sources
+        self.top = 4                    # IA-6: how many sources to retrieve
+        self.stream = False             # IA-7: stream the answer to <ui:stream> (web requests)
         self.temperature = None         # 0.0-2.0
         self.max_tokens = None          # Token limit
         self.response_format = None     # "text" or "json"

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/expression_stdlib.py

@@ -172,6 +172,12 @@ def verify_password(password: Any, hashed: Any) -> bool:
         return False
 
 
+def _urlencode(v) -> str:
+    """EXPR-12: a value made safe to put in a URL — `q:redirect url="/?q={urlencode(q)}"`."""
+    from urllib.parse import quote_plus
+    return quote_plus('' if v is None else str(v))
+
+
 STDLIB = {
     # passwords
     'hashPassword': hash_password,
@@ -189,6 +195,7 @@ STDLIB = {
     'split': _split,
     'contains': _contains,
     'slugify': _slugify,
+    'urlencode': _urlencode,
     # collections
     'len': _len,
     'first': _first,

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/features/agents/src/ast_node.py

@@ -290,7 +290,7 @@ class AgentNode(QuantumNode):
 
     Example:
         <!-- Using Ollama (default) -->
-        <q:agent name="support" model="phi3" max_iterations="5">
+        <q:agent name="support" model="phi3" maxIterations="5">
             ...
         </q:agent>
 
@@ -319,6 +319,7 @@ class AgentNode(QuantumNode):
     api_key: str = ""  # For cloud providers
     max_iterations: int = 10
     timeout: int = 60000  # milliseconds
+    on_error: str = "fail"  # IA-5: "continue" hands a failure to the page
 
     instruction: Optional[AgentInstructionNode] = None
     tools: List[AgentToolNode] = field(default_factory=list)

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/features/knowledge_base/src/ast_node.py

@@ -82,6 +82,7 @@ class KnowledgeNode(QuantumNode):
     persist: bool = False                     # Persist ChromaDB to disk
     persist_path: Optional[str] = None        # ChromaDB persistence path
     rebuild: bool = False                     # Force reindex
+    on_error: str = 'fail'                    # IA-5: 'continue' hands a failure to <name>_info
 
     def add_source(self, source: KnowledgeSourceNode):
         self.sources.append(source)

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/features/ui_engine/src/ast_nodes.py

@@ -1896,6 +1896,21 @@ class UIPagerNode(QuantumNode, UILayoutMixin):
         return [] if self.for_query else ["ui:pager needs for="]
 
 
+class UIStreamNode(QuantumNode, UILayoutMixin):
+    """<ui:stream for="answer"> — a q:llm answer, arriving as it is written (IA-7)."""
+
+    def __init__(self):
+        self.for_llm: Optional[str] = None
+        self.children: List[QuantumNode] = []
+        self._init_layout_attrs()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"type": "ui_stream", "for": self.for_llm}
+
+    def validate(self) -> List[str]:
+        return []
+
+
 class UIHistoryNode(QuantumNode, UILayoutMixin):
     """<ui:history table="t" key="{row.id}" datasource="db"> — a row's change history (DB-11)."""
 
@@ -1926,6 +1941,6 @@ CORE_TAGS = frozenset({
     'window', 'hbox', 'vbox', 'grid', 'panel', 'section', 'scrollbox', 'spacer', 'rule',
     'header', 'footer', 'card', 'card-header', 'card-body', 'card-footer', 'tabpanel', 'tab',
     'text', 'badge', 'alert', 'link', 'image', 'progress',
-    'table', 'column', 'list', 'item', 'pager', 'history',
+    'table', 'column', 'list', 'item', 'pager', 'history', 'stream',
     'form', 'formitem', 'input', 'checkbox', 'switch', 'radio', 'select', 'option', 'button',
 })

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/features/ui_engine/src/parser.py

@@ -28,7 +28,7 @@ from .ast_nodes import (
     UIToastNode, UIToastContainerNode,
     UICarouselNode, UISlideNode,
     UIStepperNode, UIStepNode,
-    UICalendarNode, UIDatePickerNode, UIPagerNode, UIHistoryNode,
+    UICalendarNode, UIDatePickerNode, UIPagerNode, UIHistoryNode, UIStreamNode,
 )
 from quantum.core.features.theming.src import UIThemeNode, UIColorNode
 from quantum.core.ast_nodes import TextNode
@@ -83,6 +83,7 @@ class UIParser:
         'column': '_parse_ui_column',
         'pager': '_parse_ui_pager',
         'history': '_parse_ui_history',
+        'stream': '_parse_ui_stream',
         'list': '_parse_ui_list',
         'item': '_parse_ui_item',
         'image': '_parse_ui_image',
@@ -551,6 +552,14 @@ class UIParser:
         self._apply_layout_attrs(node, element)
         return node
 
+    def _parse_ui_stream(self, element: ET.Element) -> UIStreamNode:
+        node = UIStreamNode()
+        node.for_llm = element.get('for')
+        if not node.for_llm:
+            raise UIParseError('<ui:stream> needs for="<the q:llm name>"')
+        self._apply_layout_attrs(node, element)
+        return node
+
     def _parse_ui_history(self, element: ET.Element) -> UIHistoryNode:
         node = UIHistoryNode()
         node.table = element.get('table')

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/parser.py

@@ -480,7 +480,13 @@ class QuantumParser:
         A direct else child of a q:if is already the nested form and stays
         where it is. An else with no q:if right before it is an error.
         """
-        for parent in list(root.iter()):
+        parents = list(root.iter())
+        # IF-4 looks at the else children as written: before any sibling-form
+        # else is moved into its q:if below (which is not ambiguous).
+        for parent in parents:
+            if self._get_element_name(parent) == 'if':
+                self._check_dangling_else(parent)
+        for parent in parents:
             if self._get_element_name(parent) == 'if':
                 continue
             anterior = None
@@ -502,6 +508,27 @@ class QuantumParser:
                     continue
                 anterior = child if nome == 'if' and self._is_quantum_tag(child) else None
 
+    def _check_dangling_else(self, if_element: ET.Element) -> None:
+        """IF-4: inside a q:if, a q:else/q:elseif right after an inner </q:if> is ambiguous.
+
+        IF-1 gives it to the outer q:if (a direct child belongs to its if), but
+        written right after an inner if it reads as that if's else — the
+        sibling form. A page built that way drew the else branch of the inner
+        if when the OUTER condition was false. Refused, with both fixes."""
+        previous = None
+        for child in if_element:
+            if not isinstance(child.tag, str):
+                continue
+            name = self._get_element_name(child)
+            if (name in ('else', 'elseif') and self._is_quantum_tag(child) and previous is not None):
+                error = QuantumParseError(
+                    f"<q:{name}> right after an inner </q:if>, inside another <q:if>, is ambiguous "
+                    f"(IF-4): it would belong to the OUTER q:if (IF-1). If it is the inner q:if's, "
+                    f"write it inside that q:if; if it is the outer's, put it before the inner q:if.")
+                error.line = getattr(child, 'sourceline', None)
+                raise error
+            previous = child if name == 'if' and self._is_quantum_tag(child) else None
+
     # Tags that existed and were removed, with what to use instead.
     REMOVED_TAGS = {
         'persist': ('was removed in Quantum 0.16 (SET-2): it kept variables in the browser, '

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/parsers/ai/agent_parser.py

@@ -42,6 +42,15 @@ class AgentParser(BaseTagParser):
 
         if not name:
             raise ParserError("Agent requires 'name' attribute")
+        if element.get('max_iterations') is not None:
+            # The guide and the README wrote max_iterations; it was never read
+            # and every agent ran up to 10 steps.
+            raise ParserError(f'<q:agent name="{name}">: the attribute is maxIterations, '
+                              f'not max_iterations')
+        on_error = self.get_attr(element, 'onerror', 'fail')
+        if on_error not in ('fail', 'continue'):
+            raise ParserError(f'<q:agent name="{name}"> onerror must be "fail" or "continue", '
+                              f'not "{on_error}"')
 
         agent_node = AgentNode(
             name=name,
@@ -50,7 +59,8 @@ class AgentParser(BaseTagParser):
             provider=self.get_attr(element, 'provider', 'auto'),
             api_key=self.get_attr(element, 'apiKey', ''),
             max_iterations=self.get_int_attr(element, 'maxIterations', 10),
-            timeout=self.get_int_attr(element, 'timeout', 60000)
+            timeout=self.get_int_attr(element, 'timeout', 60000),
+            on_error=on_error,
         )
 
         # Parse children

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/parsers/ai/knowledge_parser.py

@@ -52,6 +52,11 @@ class KnowledgeParser(BaseTagParser):
             persist_path=self.get_attr(element, 'persistPath', './.quantum/knowledge'),
             rebuild=self.get_bool_attr(element, 'rebuild', False)
         )
+        # IA-5: a base that cannot be built stops the page unless the page handles it.
+        knowledge_node.on_error = self.get_attr(element, 'onerror', 'fail')
+        if knowledge_node.on_error not in ('fail', 'continue'):
+            raise ParserError(f'<q:knowledge name="{name}"> onerror must be "fail" or "continue", '
+                              f'not "{knowledge_node.on_error}"')
 
         # Parse sources
         for child in element:
@@ -66,6 +71,11 @@ class KnowledgeParser(BaseTagParser):
     def _parse_source(self, element: ET.Element) -> KnowledgeSourceNode:
         """Parse q:source within q:knowledge."""
         source_type = self.get_attr(element, 'type', 'text')
+        # IA-8: type="url" was accepted and read nothing (a log line said "not
+        # yet implemented"); an unknown type read nothing at all.
+        if source_type not in ('text', 'file', 'directory', 'query'):
+            raise ParserError(f'<q:source type="{source_type}">: use text, file, directory or query'
+                              + (' (url is not supported)' if source_type == 'url' else ''))
 
         source = KnowledgeSourceNode(
             source_type=source_type,

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/parsers/ai/llm_parser.py

@@ -60,7 +60,21 @@ class LLMParser(BaseTagParser):
         # same attributes now work on both tags.
         llm_node.provider = self.get_attr(element, 'provider')
         llm_node.api_key = self.get_attr(element, 'apiKey')
-        llm_node.timeout = self.get_int_attr(element, 'timeout', 30)
+        # Seconds to wait for the model; undeclared, the service default (60).
+        llm_node.timeout = self.get_int_attr(element, 'timeout', 0) or None
+        # M5 (IA-6): answer from a knowledge base, citing its sources.
+        llm_node.knowledge = self.get_attr(element, 'knowledge')
+        top = self.get_attr(element, 'top')
+        if top is not None and not str(top).isdigit():
+            raise ParserError(f'<q:llm name="{name}" top="{top}">: the number of sources to retrieve')
+        llm_node.top = int(top) if top is not None else 4
+        # IA-7: in a web request, the answer arrives as it is written (<ui:stream>).
+        llm_node.stream = self.get_bool_attr(element, 'stream', False)
+        # IA-5: a failure stops the page unless the page handles it.
+        llm_node.on_error = self.get_attr(element, 'onerror', 'fail')
+        if llm_node.on_error not in ('fail', 'continue'):
+            raise ParserError(f'<q:llm name="{name}"> onerror must be "fail" or "continue", '
+                              f'not "{llm_node.on_error}"')
 
         # Parse children
         for child in element:

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/core/parsers/data/query_parser.py

@@ -108,6 +108,12 @@ class QueryParser(BaseTagParser):
             or None
         )
         query_node.result = self.get_attr(element, 'result')
+        # IA-5 / DB: onerror="continue" hands a failure to the page as <name>_result.
+        query_node.on_error = self.get_attr(element, 'onerror', 'fail')
+        if query_node.on_error not in ('fail', 'continue'):
+            from quantum.core.parser import QuantumParseError
+            raise QuantumParseError(f'<q:query name="{name}"> onerror must be "fail" or "continue", '
+                                    f'not "{query_node.on_error}"')
 
         # RAG/Knowledge attributes
         query_node.mode = self.get_attr(element, 'mode')

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/runtime/agent_service.py

@@ -78,6 +78,8 @@ class ToolCall:
         return {
             "tool": self.tool,
             "args": self.args,
+            # IA-4: the call as a page shows it — low_stock(below=5)
+            "call": f"{self.tool}({', '.join(f'{k}={v}' for k, v in (self.args or {}).items())})",
             "result": self.result,
             "error": self.error,
             "duration_ms": self.duration_ms
@@ -271,7 +273,9 @@ IMPORTANT: Always respond with valid JSON in the format shown above. Nothing els
                     model=model,
                     endpoint=endpoint,
                     provider=provider,
-                    api_key=api_key
+                    api_key=api_key,
+                    # the model gets what is left of the agent's timeout, not a fixed 60s
+                    timeout=max(1, int((timeout_ms - elapsed_ms) / 1000)),
                 )
 
                 # Get assistant message
@@ -409,7 +413,8 @@ IMPORTANT: Always respond with valid JSON in the format shown above. Nothing els
         model: str,
         endpoint: str,
         provider: str = "auto",
-        api_key: str = ""
+        api_key: str = "",
+        timeout: Optional[int] = None
     ) -> Dict[str, Any]:
         """
         Call LLM with messages using multi-provider support.
@@ -433,6 +438,7 @@ IMPORTANT: Always respond with valid JSON in the format shown above. Nothing els
                 endpoint=endpoint if endpoint else None,
                 api_key=api_key if api_key else None,
                 temperature=0.1,  # Low temperature for deterministic tool use
+                timeout=timeout,
             )
 
             # Handle response format from MultiProviderLLMService

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/runtime/component.py

@@ -901,27 +901,12 @@ class ComponentRuntime:
             # Extract knowledge base name from datasource
             kb_name = query_node.datasource.replace('knowledge:', '', 1)
 
-            # Check if knowledge base failed to initialize - return empty results
+            # IA-5: a base that could not be built is an error here too — never an
+            # answer ("still loading", success=True) that the page shows as one.
             kb_meta = exec_context.get_variable(f"_knowledge_{kb_name}")
             if isinstance(kb_meta, dict) and kb_meta.get("_failed"):
-                from quantum.runtime.database_service import QueryResult as _QR
-                mode = query_node.mode
-                if mode == 'rag':
-                    empty_data = [{"answer": "Knowledge base is still loading. Please refresh the page.", "sources": "", "confidence": "0"}]
-                    result = _QR(data=empty_data, column_list=['answer', 'sources', 'confidence'], execution_time=0.0, record_count=1, success=True)
-                else:
-                    result = _QR(data=[], column_list=['content', 'relevance', 'source', 'chunk_index'], execution_time=0.0, record_count=0, success=True)
-                result_dict = result.to_dict()
-                exec_context.set_variable(query_node.name, result.data, scope="component")
-                exec_context.set_variable(f"{query_node.name}_result", result_dict, scope="component")
-                self.context[query_node.name] = result.data
-                self.context[f"{query_node.name}_result"] = result_dict
-                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"{query_node.name}.{field_name}"
-                        exec_context.set_variable(dotted_key, field_value, scope="component")
-                        self.context[dotted_key] = field_value
-                return result
+                raise KnowledgeError(f"knowledge base '{kb_name}' could not be built: "
+                                     f"{kb_meta.get('error', 'unknown error')}")
 
             # Get the search query from the first parameter value
             search_text = None

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/runtime/executors/ai/agent_executor.py

@@ -122,18 +122,24 @@ class AgentExecutor(BaseExecutor):
             exec_context.set_variable(node.name, result.get('result', ''), scope="component")
             exec_context.set_variable(f"{node.name}_result", result, scope="component")
 
-            return result
-
         except Exception as e:
-            error_result = {
+            result = {
                 'success': False,
                 'error': {'message': str(e)},
                 'result': '',
                 'iterations': 0,
                 'actions': []
             }
-            exec_context.set_variable(f"{node.name}_result", error_result, scope="component")
-            raise ExecutorError(f"Agent execution error: {e}")
+            exec_context.set_variable(node.name, '', scope="component")
+            exec_context.set_variable(f"{node.name}_result", result, scope="component")
+
+        # IA-5: an agent that did not finish used to leave success=false and an
+        # empty answer on a page that went on as if nothing happened.
+        if not result.get('success') and getattr(node, 'on_error', 'fail') != 'continue':
+            message = (result.get('error') or {}).get('message') or 'the agent did not finish'
+            raise ExecutorError(f'Agent "{node.name}" failed: {message}. Add onerror="continue" to '
+                                f'handle it on the page ({node.name}_result.success is false).')
+        return result
 
 
 def coerce_tool_args(params, tool_args: Dict[str, Any]) -> Dict[str, Any]:

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/runtime/executors/ai/knowledge_executor.py

@@ -105,10 +105,12 @@ class KnowledgeExecutor(BaseExecutor):
                 'error': str(e),
                 'name': node.name
             }, scope="component")
-            # _execute_knowledge_query() (component.py) checks this marker to
-            # return a graceful "still loading" result instead of raising
-            # KnowledgeError("not found") on the next q:query for this KB.
+            # IA-5: a q:query on this base then fails with this reason (it used
+            # to answer "Knowledge base is still loading" as if that were the
+            # answer, with success=True).
             exec_context.set_variable(f"_knowledge_{node.name}", {
-                '_failed': True,
+                '_failed': True, 'error': str(e),
             }, scope="component")
+            if getattr(node, 'on_error', 'fail') == 'continue':
+                return None
             raise ExecutorError(f"Knowledge base creation error: {e}")

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/runtime/executors/ai/llm_executor.py

@@ -5,6 +5,7 @@ Handles LLM invocation across providers (Ollama, OpenAI, Anthropic, LM Studio).
 """
 
 import json
+import re
 from typing import Any, List, Dict, Type
 from quantum.runtime.executors.base import BaseExecutor, ExecutorError
 from quantum.core.ast_nodes import LLMNode
@@ -64,10 +65,49 @@ class LLMExecutor(BaseExecutor):
             if not messages:
                 prompt_text = self.apply_databinding(node.prompt, context) if node.prompt else ''
 
+            sources = None
+            if getattr(node, 'knowledge', None):
+                # IA-6 (M5): answer from the knowledge base, citing its sources.
+                question = next((m['content'] for m in reversed(messages) if m['role'] == 'user'), prompt_text)
+                sources = self._retrieve(node, question or '', exec_context)
+                if not sources:
+                    # Nothing to answer from: the model is not asked (it would
+                    # answer from memory, uncited). The page sees found=false.
+                    return self._store(node, {'data': '', 'success': True, 'model': model}, exec_context,
+                                       cached=False, extra={'found': False, 'sources': [], 'cited': []})
+                grounding = self._grounding(sources)
+                # Small models follow the last instruction best: repeat it with the question.
+                reminder = ' (Answer from the sources and cite them like [1].)'
+                if messages and messages[-1]['role'] == 'user':
+                    messages[-1] = {'role': 'user', 'content': messages[-1]['content'] + reminder}
+                elif prompt_text is not None:
+                    prompt_text += reminder
+                system_text = f'{grounding}\n\n{system_text}' if system_text else grounding
+                if messages:
+                    if messages[0]['role'] == 'system':
+                        messages[0] = {'role': 'system', 'content': f"{grounding}\n\n{messages[0]['content']}"}
+                    else:
+                        messages.insert(0, {'role': 'system', 'content': grounding})
+
             temperature = float(node.temperature) if node.temperature is not None else None
             max_tokens = int(node.max_tokens) if node.max_tokens is not None else None
             response_format = node.response_format or 'text'
 
+            if getattr(node, 'stream', False) and self._in_web_request():
+                # IA-7: the page renders now; <ui:stream> reads the answer from /_stream/<token>.
+                from quantum.runtime import llm_stream
+                chat = messages or ([{'role': 'system', 'content': system_text}] if system_text else []) +                     [{'role': 'user', 'content': prompt_text or ''}]
+                token = llm_stream.register({
+                    'messages': chat, 'model': model, 'provider': provider, 'endpoint': endpoint,
+                    'api_key': api_key, 'temperature': temperature, 'max_tokens': max_tokens,
+                    'timeout': node.timeout,
+                }, exec_context.session_vars)
+                extra = {'stream': f'/_stream/{token}'}
+                if sources is not None:
+                    extra.update({'found': True, 'sources': sources, 'cited': []})
+                return self._store(node, {'data': '', 'success': True, 'model': model}, exec_context,
+                                   cached=False, extra=extra)
+
             cache = self.services.llm_cache if node.cache else None
             cache_key = None
             if cache is not None:
@@ -96,6 +136,7 @@ class LLMExecutor(BaseExecutor):
                     temperature=temperature,
                     max_tokens=max_tokens,
                     response_format=response_format,
+                    timeout=node.timeout,
                 )
             else:
                 response = llm.generate(
@@ -108,22 +149,74 @@ class LLMExecutor(BaseExecutor):
                     temperature=temperature,
                     max_tokens=max_tokens,
                     response_format=response_format,
+                    timeout=node.timeout,
                 )
 
             if cache is not None and response.get('success', True):
                 cache.set(cache_key, response, ttl=node.ttl)
 
-            return self._store(node, response, exec_context, cached=False)
+            extra = None
+            if sources is not None:
+                extra = {'found': True, 'sources': sources,
+                         'cited': self._cited(str(response.get('data', '')), len(sources))}
+            return self._store(node, response, exec_context, cached=False, extra=extra)
 
         except Exception as e:
+            # IA-5: same shape as q:invoke (INV-2): <name>_result.error.message.
             exec_context.set_variable(f"{node.name}_result", {
                 'success': False,
-                'error': str(e),
+                'error': {'message': str(e)},
                 'model': node.model
             }, scope="component")
-            raise ExecutorError(f"LLM execution error: {e}")
+            if getattr(node, 'on_error', 'fail') == 'continue':
+                exec_context.set_variable(node.name, '', scope="component")
+                return None
+            raise ExecutorError(f"LLM execution error: {e}. Add onerror=\"continue\" to handle it "
+                                f"with {node.name}_result instead.")
+
+    @staticmethod
+    def _in_web_request() -> bool:
+        """IA-7: streaming needs a browser (or the console) to read /_stream; `quantum run` waits."""
+        try:
+            from flask import has_request_context
+            return has_request_context()
+        except ImportError:
+            return False
 
-    def _store(self, node: LLMNode, response: Dict[str, Any], exec_context, cached: bool) -> Any:
+    # -- IA-6: answers grounded in a knowledge base --------------------------------
+
+    def _retrieve(self, node: LLMNode, question: str, exec_context) -> list:
+        """The top chunks for the question, numbered as the model will cite them."""
+        name = node.knowledge
+        try:
+            meta = exec_context.get_variable(f'_knowledge_{name}')
+        except Exception:
+            meta = None
+        if not isinstance(meta, dict):
+            raise ExecutorError(f'<q:llm knowledge="{name}">: there is no <q:knowledge name="{name}"> '
+                                f'on this page')
+        if meta.get('_failed'):
+            raise ExecutorError(f"knowledge base '{name}' could not be built: {meta.get('error')}")
+        hits = self.runtime.knowledge_service.search(
+            name, question, int(getattr(node, 'top', 4) or 4), meta.get('embed_model', 'nomic-embed-text'))
+        from pathlib import PurePath
+        return [{'n': i + 1, 'source': h.get('source') or 'unknown',
+                 'name': PurePath(str(h.get('source') or 'unknown').replace('\\', '/')).name,
+                 'text': h.get('content', ''), 'relevance': h.get('relevance')} for i, h in enumerate(hits)]
+
+    @staticmethod
+    def _grounding(sources: list) -> str:
+        numbered = '\n\n'.join(f"[{s['n']}] ({s['name']})\n{s['text']}" for s in sources)
+        return ('Answer using only the sources below. After each statement, cite the source it '
+                'comes from by its number in brackets, like [1]. If the sources do not contain '
+                'the answer, say that you do not know.\n\nSources:\n' + numbered)
+
+    @staticmethod
+    def _cited(text: str, count: int) -> list:
+        return sorted({int(n) for n in re.findall(r'\[(\d+)\]', text) if 1 <= int(n) <= count})
+
+    def _store(self, node: LLMNode, response: Dict[str, Any], exec_context, cached: bool,
+               extra: Dict[str, Any] = None) -> Any:
         """Unpack a provider response, store it, and return the value."""
         text = response.get('data', '')
         value = text
@@ -148,6 +241,7 @@ class LLMExecutor(BaseExecutor):
             'provider': response.get('provider'),
             'usage': response.get('usage'),
             'cached': cached,
+            **(extra or {}),
         }, scope="component")
 
         return value

{quantum_framework-0.19.0 → quantum_framework-0.20.0}/quantum/runtime/executors/data/query_executor.py

@@ -56,6 +56,13 @@ class QueryExecutor(BaseExecutor):
             return self._execute_database_query(node, resolved_params, exec_context)
 
         except Exception as e:
+            if getattr(node, 'on_error', 'fail') == 'continue':
+                # IA-5: the page handles it — no rows, and why.
+                exec_context.set_variable(node.name, [], scope="component")
+                exec_context.set_variable(f"{node.name}_result", {
+                    'success': False, 'error': {'message': str(e)}, 'recordCount': 0, 'data': [],
+                }, scope="component")
+                return None
             raise ExecutorError(f"Query execution error in '{node.name}': {e}")
 
     def _resolve_params(self, node: QueryNode, context: Dict[str, Any]) -> Dict[str, Any]: