quantum-framework 0.9.0__py3-none-any.whl

quantum/core/parser_registry.py

@@ -0,0 +1,213 @@
+"""
+Parser Registry - Central dispatch for tag parsing
+
+Replaces the large if-elif chain in parser.py with a tag-based lookup.
+Parsers register themselves for specific tag names, and the registry
+dispatches parsing to the correct parser.
+"""
+
+from typing import Dict, Optional, List, TYPE_CHECKING
+from xml.etree import ElementTree as ET
+import logging
+
+if TYPE_CHECKING:
+    from quantum.core.parsers.base import BaseTagParser
+    from quantum.core.ast_nodes import QuantumNode
+
+logger = logging.getLogger(__name__)
+
+
+class ParserNotFoundError(Exception):
+    """Raised when no parser is registered for a tag"""
+    pass
+
+
+class ParserRegistry:
+    """
+    Registry for tag parsers.
+
+    Maps XML tag names to their parsers and dispatches parsing.
+
+    Example:
+        registry = ParserRegistry()
+        registry.register(LoopParser(main_parser))
+        registry.register(IfParser(main_parser))
+
+        # Later, parse any element
+        node = registry.parse(element, 'loop')
+    """
+
+    def __init__(self):
+        """Initialize empty registry"""
+        self._parsers: Dict[str, 'BaseTagParser'] = {}
+        self._html_parser: Optional['BaseTagParser'] = None
+        self._component_call_parser: Optional['BaseTagParser'] = None
+
+    def register(self, parser: 'BaseTagParser') -> 'ParserRegistry':
+        """
+        Register a parser for its handled tags.
+
+        Args:
+            parser: Parser instance to register
+
+        Returns:
+            Self for chaining
+        """
+        for tag_name in parser.tag_names:
+            if tag_name in self._parsers:
+                logger.warning(
+                    f"Overwriting parser for '{tag_name}': "
+                    f"{self._parsers[tag_name].__class__.__name__} -> "
+                    f"{parser.__class__.__name__}"
+                )
+            self._parsers[tag_name] = parser
+            logger.debug(f"Registered {parser.__class__.__name__} for '{tag_name}'")
+
+        return self
+
+    def register_all(self, parsers: List['BaseTagParser']) -> 'ParserRegistry':
+        """
+        Register multiple parsers at once.
+
+        Args:
+            parsers: List of parser instances
+
+        Returns:
+            Self for chaining
+        """
+        for parser in parsers:
+            self.register(parser)
+        return self
+
+    def register_html_parser(self, parser: 'BaseTagParser') -> 'ParserRegistry':
+        """
+        Register the HTML element parser.
+
+        Args:
+            parser: HTML parser instance
+
+        Returns:
+            Self for chaining
+        """
+        self._html_parser = parser
+        logger.debug(f"Registered HTML parser: {parser.__class__.__name__}")
+        return self
+
+    def register_component_call_parser(self, parser: 'BaseTagParser') -> 'ParserRegistry':
+        """
+        Register the component call parser (for uppercase tags).
+
+        Args:
+            parser: Component call parser instance
+
+        Returns:
+            Self for chaining
+        """
+        self._component_call_parser = parser
+        logger.debug(f"Registered component call parser: {parser.__class__.__name__}")
+        return self
+
+    def get_parser(self, tag_name: str) -> Optional['BaseTagParser']:
+        """
+        Get the parser for a tag name.
+
+        Args:
+            tag_name: Tag name (without q: prefix)
+
+        Returns:
+            Parser instance or None if not found
+        """
+        return self._parsers.get(tag_name)
+
+    def has_parser(self, tag_name: str) -> bool:
+        """
+        Check if a parser is registered for a tag.
+
+        Args:
+            tag_name: Tag name
+
+        Returns:
+            True if parser exists
+        """
+        return tag_name in self._parsers
+
+    def parse(self, element: ET.Element, tag_name: str) -> Optional['QuantumNode']:
+        """
+        Parse an element using its registered parser.
+
+        Args:
+            element: XML element to parse
+            tag_name: Tag name (without q: prefix)
+
+        Returns:
+            AST node or None
+
+        Raises:
+            ParserNotFoundError: If no parser is registered for the tag
+        """
+        parser = self._parsers.get(tag_name)
+
+        if parser is not None:
+            # One-time notice if this tag is outside the supported surface
+            # (PRODUCTION_READINESS.md Fase 0). Experimental tags still parse
+            # and run; the operator just gets told, once, that they are
+            # leaning on something unsupported.
+            from quantum.core.tiers import warn_if_unsupported
+            warn_if_unsupported(tag_name)
+            return parser.parse(element)
+
+        return None
+
+    def parse_html(self, element: ET.Element) -> Optional['QuantumNode']:
+        """
+        Parse an HTML element.
+
+        Args:
+            element: HTML element to parse
+
+        Returns:
+            AST node or None
+        """
+        if self._html_parser is not None:
+            return self._html_parser.parse(element)
+        return None
+
+    def parse_component_call(self, element: ET.Element) -> Optional['QuantumNode']:
+        """
+        Parse a component call (uppercase tag).
+
+        Args:
+            element: Component call element
+
+        Returns:
+            AST node or None
+        """
+        if self._component_call_parser is not None:
+            return self._component_call_parser.parse(element)
+        return None
+
+    def is_uppercase(self, tag_name: str) -> bool:
+        """
+        Check if tag is a component call (uppercase first letter).
+
+        Args:
+            tag_name: Tag name
+
+        Returns:
+            True if uppercase
+        """
+        return bool(tag_name and tag_name[0].isupper())
+
+    @property
+    def registered_tags(self) -> List[str]:
+        """Get list of all registered tag names"""
+        return list(self._parsers.keys())
+
+    @property
+    def parser_count(self) -> int:
+        """Get number of registered parsers (unique)"""
+        return len(set(self._parsers.values()))
+
+    def __repr__(self) -> str:
+        tags = list(self._parsers.keys())
+        return f"ParserRegistry({len(tags)} tags: {tags[:5]}{'...' if len(tags) > 5 else ''})"

quantum/core/parsers/__init__.py

@@ -0,0 +1,76 @@
+"""
+Quantum Parsers Package
+
+Modular parsers for XML tag parsing. Each parser handles specific tag types.
+
+Categories:
+- control_flow: if, loop, set
+- data: query, invoke, data, transaction
+- services: log, dump, file, mail
+- ai: llm, agent, team, knowledge
+- messaging: websocket, message, subscribe, queue
+- jobs: schedule, thread, job
+- scripting: python, pyimport, pyclass
+"""
+
+from .base import BaseTagParser, ParserError
+
+# Control flow parsers
+from .control_flow import IfParser, LoopParser, SetParser
+
+# Data parsers
+from .data import QueryParser, InvokeParser, DataParser, TransactionParser
+
+# Service parsers
+from .services import LogParser, DumpParser, FileParser, MailParser
+
+# AI parsers
+from .ai import LLMParser, AgentParser, TeamParser, KnowledgeParser
+
+# Messaging parsers
+from .messaging import (
+    WebSocketParser, WebSocketSendParser, WebSocketCloseParser,
+    MessageParser, SubscribeParser, QueueParser
+)
+
+# Jobs parsers
+from .jobs import ScheduleParser, ThreadParser, JobParser
+
+# Scripting parsers
+from .scripting import PythonParser, PyImportParser, PyClassParser
+
+# HTML parsers
+from .html import HTMLParser, ComponentCallParser
+
+
+__all__ = [
+    # Base
+    'BaseTagParser', 'ParserError',
+
+    # Control flow
+    'IfParser', 'LoopParser', 'SetParser',
+
+    # Data
+    'QueryParser', 'InvokeParser', 'DataParser', 'TransactionParser',
+
+    # Services
+    'LogParser', 'DumpParser', 'FileParser', 'MailParser',
+
+    # AI
+    'LLMParser', 'AgentParser', 'TeamParser', 'KnowledgeParser',
+
+    # Messaging
+    'WebSocketParser', 'WebSocketSendParser', 'WebSocketCloseParser',
+    'MessageParser', 'SubscribeParser', 'QueueParser',
+
+    # Jobs
+    'ScheduleParser', 'ThreadParser', 'JobParser',
+
+    # Scripting
+    'PythonParser', 'PyImportParser', 'PyClassParser',
+
+    # HTML
+    'HTMLParser', 'ComponentCallParser',
+]
+
+__version__ = '1.0.0'

quantum/core/parsers/ai/__init__.py

@@ -0,0 +1,12 @@
+"""
+AI Parsers
+
+Parsers for AI operations: llm, agent, team, knowledge.
+"""
+
+from .llm_parser import LLMParser
+from .agent_parser import AgentParser
+from .team_parser import TeamParser
+from .knowledge_parser import KnowledgeParser
+
+__all__ = ['LLMParser', 'AgentParser', 'TeamParser', 'KnowledgeParser']

quantum/core/parsers/ai/agent_parser.py

@@ -0,0 +1,106 @@
+"""
+Agent Parser - Parse q:agent statements
+
+Handles AI agent configuration with tools.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.features.agents.src.ast_node import (
+    AgentNode, AgentToolNode, AgentToolParamNode,
+    AgentInstructionNode, AgentExecuteNode
+)
+
+
+class AgentParser(BaseTagParser):
+    """
+    Parser for q:agent statements.
+
+    Supports:
+    - Tool definitions
+    - System instructions
+    - Execute configuration
+    - Multiple providers
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['agent']
+
+    def parse(self, element: ET.Element) -> AgentNode:
+        """
+        Parse q:agent statement.
+
+        Args:
+            element: XML element for q:agent
+
+        Returns:
+            AgentNode AST node
+        """
+        name = self.get_attr(element, 'name')
+
+        if not name:
+            raise ParserError("Agent requires 'name' attribute")
+
+        agent_node = AgentNode(
+            name=name,
+            model=self.get_attr(element, 'model', 'phi3'),
+            endpoint=self.get_attr(element, 'endpoint', ''),
+            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)
+        )
+
+        # Parse children
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'instruction':
+                agent_node.instruction = AgentInstructionNode(
+                    content=self.get_text(child)
+                )
+            elif child_type == 'tool':
+                tool = self._parse_tool(child)
+                agent_node.tools.append(tool)
+            elif child_type == 'execute':
+                agent_node.execute = AgentExecuteNode(
+                    task=self.get_attr(child, 'task', self.get_text(child)),
+                    context=self.get_attr(child, 'context', ''),
+                    entry=self.get_attr(child, 'entry', '')
+                )
+
+        return agent_node
+
+    def _parse_tool(self, element: ET.Element) -> AgentToolNode:
+        """Parse q:tool within q:agent."""
+        name = self.get_attr(element, 'name')
+        description = self.get_attr(element, 'description', '')
+        builtin = self.get_bool_attr(element, 'builtin', False)
+
+        tool = AgentToolNode(
+            name=name,
+            description=description,
+            builtin=builtin
+        )
+
+        # Parse params and body
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'param':
+                param = AgentToolParamNode(
+                    name=self.get_attr(child, 'name', ''),
+                    type=self.get_attr(child, 'type', 'string'),
+                    required=self.get_bool_attr(child, 'required', False),
+                    description=self.get_attr(child, 'description', '')
+                )
+                tool.params.append(param)
+            else:
+                # Tool body statement
+                statement = self.parse_statement(child)
+                if statement:
+                    tool.body.append(statement)
+
+        return tool

quantum/core/parsers/ai/knowledge_parser.py

@@ -0,0 +1,86 @@
+"""
+Knowledge Parser - Parse q:knowledge statements
+
+Handles knowledge base configuration for RAG.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.features.knowledge_base.src.ast_node import KnowledgeNode, KnowledgeSourceNode
+
+
+class KnowledgeParser(BaseTagParser):
+    """
+    Parser for q:knowledge statements.
+
+    Supports:
+    - Multiple source types
+    - Embedding configuration
+    - Persistence options
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['knowledge']
+
+    def parse(self, element: ET.Element) -> KnowledgeNode:
+        """
+        Parse q:knowledge statement.
+
+        Args:
+            element: XML element for q:knowledge
+
+        Returns:
+            KnowledgeNode AST node
+        """
+        name = self.get_attr(element, 'name')
+
+        if not name:
+            raise ParserError("Knowledge requires 'name' attribute")
+
+        knowledge_node = KnowledgeNode(
+            name=name,
+            model=self.get_attr(element, 'model'),
+            embed_model=self.get_attr(element, 'embedModel', 'nomic-embed-text'),
+            chunk_size=self.get_int_attr(element, 'chunkSize', 500),
+            chunk_overlap=self.get_int_attr(element, 'chunkOverlap', 50),
+            # Persist by default: re-embedding an unchanged corpus on every
+            # boot costs minutes of API calls and buys nothing. Opt out with
+            # persist="false" for throwaway/in-memory bases.
+            persist=self.get_bool_attr(element, 'persist', True),
+            persist_path=self.get_attr(element, 'persistPath', './.quantum/knowledge'),
+            rebuild=self.get_bool_attr(element, 'rebuild', False)
+        )
+
+        # Parse sources
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'source':
+                source = self._parse_source(child)
+                knowledge_node.add_source(source)
+
+        return knowledge_node
+
+    def _parse_source(self, element: ET.Element) -> KnowledgeSourceNode:
+        """Parse q:source within q:knowledge."""
+        source_type = self.get_attr(element, 'type', 'text')
+
+        source = KnowledgeSourceNode(
+            source_type=source_type,
+            path=self.get_attr(element, 'path'),
+            pattern=self.get_attr(element, 'pattern'),
+            url=self.get_attr(element, 'url'),
+            datasource=self.get_attr(element, 'datasource'),
+            chunk_size=self.get_int_attr(element, 'chunkSize', 0) or None,
+            chunk_overlap=self.get_int_attr(element, 'chunkOverlap', 0) or None
+        )
+
+        # Get content for text source
+        if source_type == 'text':
+            source.content = self.get_text(element)
+        elif source_type == 'query':
+            source.sql = self.get_text(element)
+
+        return source

quantum/core/parsers/ai/llm_parser.py

@@ -0,0 +1,78 @@
+"""
+LLM Parser - Parse q:llm statements
+
+Handles LLM invocation configuration.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.ast_nodes import LLMNode, LLMMessageNode
+
+
+class LLMParser(BaseTagParser):
+    """
+    Parser for q:llm statements.
+
+    Supports:
+    - Completion mode (prompt)
+    - Chat mode (messages)
+    - Temperature/token configuration
+    - Response formatting
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['llm']
+
+    def parse(self, element: ET.Element) -> LLMNode:
+        """
+        Parse q:llm statement.
+
+        Args:
+            element: XML element for q:llm
+
+        Returns:
+            LLMNode AST node
+        """
+        name = self.get_attr(element, 'name')
+
+        if not name:
+            raise ParserError("LLM requires 'name' attribute")
+
+        llm_node = LLMNode(name)
+        llm_node.model = self.get_attr(element, 'model')
+        llm_node.endpoint = self.get_attr(element, 'endpoint')
+
+        # Temperature and tokens
+        temp = self.get_attr(element, 'temperature')
+        if temp:
+            try:
+                llm_node.temperature = float(temp)
+            except ValueError:
+                pass
+
+        llm_node.max_tokens = self.get_int_attr(element, 'maxTokens', 0) or None
+        llm_node.response_format = self.get_attr(element, 'responseFormat')
+        llm_node.cache = self.get_bool_attr(element, 'cache', False)
+        llm_node.ttl = self.get_int_attr(element, 'ttl', 0) or None
+        # q:llm spoke only Ollama while q:agent was already multi-provider;
+        # 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)
+
+        # Parse children
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'prompt':
+                llm_node.prompt = self.get_text(child)
+            elif child_type == 'system':
+                llm_node.system = self.get_text(child)
+            elif child_type == 'message':
+                role = self.get_attr(child, 'role', 'user')
+                content = self.get_text(child)
+                llm_node.messages.append(LLMMessageNode(role, content))
+
+        return llm_node

quantum/core/parsers/ai/team_parser.py

@@ -0,0 +1,88 @@
+"""
+Team Parser - Parse q:team statements
+
+Handles multi-agent team configuration.
+"""
+
+from typing import List
+from xml.etree import ElementTree as ET
+from quantum.core.parsers.base import BaseTagParser, ParserError
+from quantum.core.features.agents.src.ast_node import AgentTeamNode, AgentExecuteNode
+
+
+class TeamParser(BaseTagParser):
+    """
+    Parser for q:team statements.
+
+    Supports:
+    - Multiple agent definitions
+    - Shared context
+    - Supervisor/entry configuration
+    """
+
+    @property
+    def tag_names(self) -> List[str]:
+        return ['team']
+
+    def parse(self, element: ET.Element) -> AgentTeamNode:
+        """
+        Parse q:team statement.
+
+        Args:
+            element: XML element for q:team
+
+        Returns:
+            AgentTeamNode AST node
+        """
+        name = self.get_attr(element, 'name')
+
+        if not name:
+            raise ParserError("Team requires 'name' attribute")
+
+        # Create team node with defaults (matching legacy behavior)
+        team_node = AgentTeamNode(name=name)
+
+        # Parse attributes (support both snake_case and camelCase)
+        team_node.supervisor = self.get_attr(element, 'supervisor', '')
+
+        max_handoffs = self.get_attr(element, 'max_handoffs') or self.get_attr(element, 'maxHandoffs')
+        if max_handoffs:
+            try:
+                team_node.max_handoffs = int(max_handoffs)
+            except ValueError:
+                pass
+
+        max_iterations = self.get_attr(element, 'max_total_iterations') or self.get_attr(element, 'maxTotalIterations')
+        if max_iterations:
+            try:
+                team_node.max_total_iterations = int(max_iterations)
+            except ValueError:
+                pass
+
+        # Parse children
+        for child in element:
+            child_type = self.get_element_name(child)
+
+            if child_type == 'shared':
+                # Parse shared context (q:set nodes)
+                for shared_child in child:
+                    statement = self.parse_statement(shared_child)
+                    if statement:
+                        team_node.shared.append(statement)
+            elif child_type == 'agent':
+                # Parse agent using main parser
+                agent = self.parse_statement(child)
+                if agent:
+                    # Team members are driven by the team's <q:execute>, not
+                    # one of their own — mark them so validate() doesn't
+                    # reject the whole component.
+                    agent.in_team = True
+                    team_node.agents.append(agent)
+            elif child_type == 'execute':
+                team_node.execute = AgentExecuteNode(
+                    task=self.get_attr(child, 'task', self.get_text(child)),
+                    context=self.get_attr(child, 'context', ''),
+                    entry=self.get_attr(child, 'entry', '')
+                )
+
+        return team_node