quantum-framework 0.9.0__py3-none-any.whl

quantum/runtime/executors/ai/agent_executor.py

@@ -0,0 +1,217 @@
+"""
+Agent Executor - Execute q:agent statements
+
+Handles AI agent execution with tool use capabilities.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import (
+    QuantumReturn,
+    HTMLNode, TextNode, DocTypeNode, CommentNode,
+)
+
+# Import from features module
+try:
+    from quantum.core.features.agents.src.ast_node import AgentNode
+except ImportError:
+    from quantum.core.features.agents.src import AgentNode
+
+_RENDER_ONLY_NODE_TYPES = (HTMLNode, TextNode, DocTypeNode, CommentNode)
+
+
+def build_tool_definitions(tool_nodes) -> List[Dict[str, Any]]:
+    """
+    Build the tool definitions AgentService actually consumes.
+
+    AgentService._build_tools_description() reads name/description/params
+    (a list of param dicts), and AgentService._execute_tool() reads
+    tool_def["body"] to hand the AST statements to tool_executor. The
+    JSON-Schema shape from AgentToolNode.get_schema() has neither, which is
+    why tools used to silently degrade to the "no handler" placeholder.
+    """
+    from quantum.runtime.agent_service import BUILTIN_TOOLS
+
+    tools = []
+    for tool in tool_nodes:
+        if tool.builtin:
+            builtin_def = BUILTIN_TOOLS.get(tool.name)
+            if builtin_def:
+                tools.append(dict(builtin_def))
+            continue
+
+        tools.append({
+            'name': tool.name,
+            'description': tool.description,
+            'params': [p.to_dict() for p in tool.params],
+            'body': tool.body,
+        })
+    return tools
+
+
+class AgentExecutor(BaseExecutor):
+    """
+    Executor for q:agent statements.
+
+    Supports:
+    - Multi-turn agent reasoning loop
+    - Tool calling and execution
+    - Multiple LLM providers (Ollama, OpenAI, Anthropic)
+    - Iteration limits and timeouts
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [AgentNode]
+
+    def execute(self, node: AgentNode, exec_context) -> Any:
+        """
+        Execute AI agent.
+
+        Args:
+            node: AgentNode with agent configuration
+            exec_context: Execution context
+
+        Returns:
+            Agent response dict with result and actions
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Resolve task from execute node
+            if not node.execute:
+                raise ExecutorError("Agent requires <q:execute> to run")
+
+            task = self.apply_databinding(node.execute.task, context)
+            task_context = ""
+            if node.execute.context:
+                task_context = self.apply_databinding(node.execute.context, context)
+
+            # Build instruction
+            instruction = ""
+            if node.instruction:
+                instruction = self.apply_databinding(node.instruction.content, context)
+
+            tools = build_tool_definitions(node.tools)
+
+            api_key = ""
+            if node.api_key:
+                api_key = self.apply_databinding(node.api_key, context)
+
+            endpoint = ""
+            if node.endpoint:
+                endpoint = self.apply_databinding(node.endpoint, context)
+
+            agent_result = self.services.agent.execute(
+                instruction=instruction,
+                tools=tools,
+                task=task,
+                context=task_context,
+                model=node.model,
+                endpoint=endpoint,
+                provider=node.provider,
+                api_key=api_key,
+                max_iterations=node.max_iterations,
+                timeout_ms=node.timeout,
+                tool_executor=build_tool_executor(self, exec_context, node.tools),
+            )
+
+            result = agent_result.to_dict()
+
+            # Store results
+            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 = {
+                '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}")
+
+
+def coerce_tool_args(params, tool_args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Coerce LLM-supplied tool arguments to their declared q:param types.
+
+    An LLM sends every argument as a string ({"a": "17"}), so a tool body
+    doing {a + b} would concatenate instead of adding. The declared
+    <q:param type="number"> is what tells us the intent.
+    """
+    by_name = {p.name: p for p in (params or [])}
+    coerced = {}
+
+    for key, value in (tool_args or {}).items():
+        param = by_name.get(key)
+        if param is None or not isinstance(value, str):
+            coerced[key] = value
+            continue
+
+        try:
+            if param.type in ('number', 'decimal'):
+                coerced[key] = float(value) if '.' in value else int(value)
+            elif param.type == 'integer':
+                coerced[key] = int(value)
+            elif param.type == 'boolean':
+                coerced[key] = value.strip().lower() in ('true', '1', 'yes', 'on')
+            elif param.type in ('array', 'object'):
+                import json
+                coerced[key] = json.loads(value)
+            else:
+                coerced[key] = value
+        except (ValueError, TypeError):
+            # Leave the raw value in place — the tool body may still handle it,
+            # and a hard failure here would be worse than a best-effort pass.
+            coerced[key] = value
+
+    return coerced
+
+
+def build_tool_executor(executor: BaseExecutor, exec_context, tool_nodes=None):
+    """
+    Build the tool_executor callable AgentService/AgentTeam expect:
+    tool_executor(tool_name, tool_args, body) -> Any
+
+    Runs the tool's AST body in a child context with the LLM-supplied
+    arguments coerced to their declared types and bound as local variables.
+    """
+    params_by_tool = {
+        tool.name: tool.params for tool in (tool_nodes or []) if not tool.builtin
+    }
+
+    def tool_executor(tool_name: str, tool_args: Dict[str, Any], body: List[Any]) -> Any:
+        child_context = exec_context.create_child_context()
+        args = coerce_tool_args(params_by_tool.get(tool_name), tool_args)
+        for key, value in args.items():
+            child_context.set_variable(key, value, scope="local")
+        return _run_tool_body(executor, body, child_context)
+
+    return tool_executor
+
+
+def _run_tool_body(executor: BaseExecutor, body: List[Any], child_context) -> Any:
+    """Execute a tool body, returning the first q:return value found."""
+    for statement in body or []:
+        if isinstance(statement, QuantumReturn):
+            return executor.resolve_value(statement.value, child_context.get_all_variables())
+
+        if isinstance(statement, _RENDER_ONLY_NODE_TYPES):
+            continue
+
+        # <q:tool> commonly wraps its implementation in a <q:function> —
+        # descend into it rather than registering it as a callable function.
+        if type(statement).__name__ == 'FunctionNode':
+            result = _run_tool_body(executor, getattr(statement, 'body', []), child_context)
+            if result is not None:
+                return result
+            continue
+
+        executor.runtime.executor_registry.execute(statement, child_context)
+
+    return None

quantum/runtime/executors/ai/knowledge_executor.py

@@ -0,0 +1,114 @@
+"""
+Knowledge Executor - Execute q:knowledge statements
+
+Handles knowledge base creation and RAG operations.
+"""
+
+import copy
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+
+# Import from features module
+try:
+    from quantum.core.features.knowledge_base.src.ast_node import KnowledgeNode
+except ImportError:
+    from quantum.core.features.knowledge_base.src import KnowledgeNode
+
+
+class KnowledgeExecutor(BaseExecutor):
+    """
+    Executor for q:knowledge statements.
+
+    Supports:
+    - Multiple source types (text, file, directory, URL, query)
+    - Embedding generation
+    - Vector storage (ChromaDB)
+    - RAG queries via q:query knowledge="name"
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [KnowledgeNode]
+
+    def execute(self, node: KnowledgeNode, exec_context) -> Any:
+        """
+        Execute knowledge base creation.
+
+        Args:
+            node: KnowledgeNode with knowledge base configuration
+            exec_context: Execution context
+
+        Returns:
+            Knowledge base info dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # KnowledgeService.index_knowledge() expects KnowledgeSourceNode
+            # objects (attribute access: source.content, source.path, ...),
+            # not dicts — build resolved copies rather than a dict config.
+            sources = []
+            for source in node.sources:
+                resolved = copy.copy(source)
+
+                if source.source_type == 'text' and source.content:
+                    resolved.content = self.apply_databinding(source.content, context)
+                elif source.source_type in ('file', 'directory') and source.path:
+                    resolved.path = self.apply_databinding(source.path, context)
+                elif source.source_type == 'url' and source.url:
+                    resolved.url = self.apply_databinding(source.url, context)
+                elif source.source_type == 'query' and source.sql:
+                    resolved.sql = self.apply_databinding(source.sql, context)
+
+                sources.append(resolved)
+
+            # Index into the SAME KnowledgeService instance that
+            # q:query datasource="knowledge:..." searches later
+            # (runtime.knowledge_service — see component.py's
+            # _execute_knowledge_query). services.knowledge is a separate
+            # instance and indexing into it would leave searches empty.
+            knowledge_service = self.runtime.knowledge_service
+            knowledge_service.index_knowledge(
+                name=node.name,
+                sources=sources,
+                embed_model=node.embed_model,
+                chunk_size=node.chunk_size,
+                chunk_overlap=node.chunk_overlap,
+                persist=node.persist,
+                persist_path=node.persist_path,
+                rebuild=node.rebuild,
+                database_service=self.services.database,
+                exec_context=exec_context,
+            )
+
+            info = {
+                'success': True,
+                'name': node.name,
+                'model': node.model,
+                'embed_model': node.embed_model,
+            }
+
+            # Store knowledge base reference (name resolves via q:query
+            # datasource="knowledge:{name}", not by reading this variable)
+            exec_context.set_variable(node.name, info, scope="component")
+            exec_context.set_variable(f"{node.name}_info", info, scope="component")
+            exec_context.set_variable(f"_knowledge_{node.name}", {
+                'embed_model': node.embed_model,
+                'model': node.model,
+            }, scope="component")
+
+            return info
+
+        except Exception as e:
+            exec_context.set_variable(f"{node.name}_info", {
+                'success': False,
+                '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.
+            exec_context.set_variable(f"_knowledge_{node.name}", {
+                '_failed': True,
+            }, scope="component")
+            raise ExecutorError(f"Knowledge base creation error: {e}")

quantum/runtime/executors/ai/llm_executor.py

@@ -0,0 +1,153 @@
+"""
+LLM Executor - Execute q:llm statements
+
+Handles LLM invocation across providers (Ollama, OpenAI, Anthropic, LM Studio).
+"""
+
+import json
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.core.ast_nodes import LLMNode
+
+
+class LLMExecutor(BaseExecutor):
+    """
+    Executor for q:llm statements.
+
+    Supports:
+    - Completion mode (single prompt) and chat mode (messages array)
+    - Multiple providers via provider= / endpoint= / apiKey=
+    - JSON response format
+    - Temperature and token limits
+    - Response caching with TTL
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [LLMNode]
+
+    def execute(self, node: LLMNode, exec_context) -> Any:
+        """
+        Execute LLM invocation.
+
+        Args:
+            node: LLMNode with LLM configuration
+            exec_context: Execution context
+
+        Returns:
+            LLM response (text or parsed JSON)
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            model = node.model or 'phi3'
+            provider = node.provider or None
+            endpoint = self.apply_databinding(node.endpoint, context) if node.endpoint else None
+            api_key = self.apply_databinding(node.api_key, context) if node.api_key else None
+
+            system_text = None
+            if node.system:
+                system_text = self.apply_databinding(node.system, context)
+
+            # Chat mode - build the messages array. node.system prepends a
+            # system-role message (in addition to any explicit
+            # <q:message role="system"> already in node.messages).
+            messages = []
+            if node.messages:
+                if system_text:
+                    messages.append({'role': 'system', 'content': system_text})
+                for msg in node.messages:
+                    content = self.apply_databinding(msg.content, context)
+                    messages.append({'role': msg.role, 'content': content})
+
+            prompt_text = None
+            if not messages:
+                prompt_text = self.apply_databinding(node.prompt, context) if node.prompt else ''
+
+            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'
+
+            cache = self.services.llm_cache if node.cache else None
+            cache_key = None
+            if cache is not None:
+                cache_key = cache.build_key(
+                    provider=provider, model=model, endpoint=endpoint,
+                    messages=messages, prompt=prompt_text, system=system_text,
+                    temperature=temperature, max_tokens=max_tokens,
+                    response_format=response_format,
+                )
+                cached = cache.get(cache_key)
+                if cached is not None:
+                    return self._store(node, cached, exec_context, cached=True)
+
+            # MultiProviderLLMService is what q:agent has always used; q:llm
+            # was pinned to the Ollama-only LLMService, which is why
+            # "multi-provider" was only half true.
+            llm = self.services.multi_llm
+
+            if messages:
+                response = llm.chat(
+                    messages=messages,
+                    model=model,
+                    provider=provider,
+                    endpoint=endpoint,
+                    api_key=api_key,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    response_format=response_format,
+                )
+            else:
+                response = llm.generate(
+                    prompt=prompt_text,
+                    model=model,
+                    system=system_text,
+                    provider=provider,
+                    endpoint=endpoint,
+                    api_key=api_key,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    response_format=response_format,
+                )
+
+            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)
+
+        except Exception as e:
+            exec_context.set_variable(f"{node.name}_result", {
+                'success': False,
+                'error': str(e),
+                'model': node.model
+            }, scope="component")
+            raise ExecutorError(f"LLM execution error: {e}")
+
+    def _store(self, node: LLMNode, response: Dict[str, Any], exec_context, cached: bool) -> Any:
+        """Unpack a provider response, store it, and return the value."""
+        text = response.get('data', '')
+        value = text
+
+        # The provider layer returns raw text; JSON parsing is this executor's
+        # job (the single-provider service used to do it, the shared one does not).
+        if (node.response_format or 'text') == 'json':
+            parsed = response.get('parsed')
+            if parsed is None and isinstance(text, str) and text.strip():
+                try:
+                    parsed = json.loads(text)
+                except json.JSONDecodeError:
+                    parsed = None
+            if parsed is not None:
+                value = parsed
+
+        exec_context.set_variable(node.name, value, scope="component")
+        exec_context.set_variable(f"{node.name}_result", {
+            'success': response.get('success', True),
+            'response': value,
+            'model': response.get('model', node.model),
+            'provider': response.get('provider'),
+            'usage': response.get('usage'),
+            'cached': cached,
+        }, scope="component")
+
+        return value

quantum/runtime/executors/ai/team_executor.py

@@ -0,0 +1,171 @@
+"""
+Team Executor - Execute q:team statements
+
+Handles multi-agent team execution with handoffs.
+"""
+
+from typing import Any, List, Dict, Type
+from quantum.runtime.executors.base import BaseExecutor, ExecutorError
+from quantum.runtime.executors.ai.agent_executor import build_tool_definitions, build_tool_executor
+
+# Import from features module
+try:
+    from quantum.core.features.agents.src.ast_node import AgentTeamNode
+except ImportError:
+    from quantum.core.features.agents.src import AgentTeamNode
+
+
+
+# The tools that make a team a team. An agent inside <q:team> gets them
+# automatically.
+#
+# They used to require an explicit <q:tool name="handoff" builtin="true" /> on
+# every agent, and nobody wrote it — examples/multi_agent_support.q advertises
+# "Built-in handoff, readShared, writeShared, listAgents tools" in its header
+# and instructs the router to "use the handoff tool", while declaring none of
+# them. So the tool did not exist, the model could not call it, and the team
+# ended at its first agent reporting success. A q:team exists in order to hand
+# off; making that opt-in was boilerplate everyone forgets.
+#
+# An agent that declares a tool of the same name wins, so this cannot shadow a
+# deliberate override.
+_TEAM_BUILTINS = ('handoff', 'readShared', 'writeShared', 'listAgents')
+
+
+def _team_tools(agent):
+    """Explicit tools first, then any team builtin the agent did not define."""
+    from quantum.runtime.agent_service import BUILTIN_TOOLS
+
+    tools = build_tool_definitions(agent.tools)
+    declared = {t.get('name') for t in tools}
+    for name in _TEAM_BUILTINS:
+        if name not in declared and name in BUILTIN_TOOLS:
+            tools.append(dict(BUILTIN_TOOLS[name]))
+    return tools
+
+
+class TeamExecutor(BaseExecutor):
+    """
+    Executor for q:team statements.
+
+    Supports:
+    - Multi-agent orchestration
+    - Agent handoffs
+    - Shared team context
+    - Entry point routing
+    """
+
+    @property
+    def handles(self) -> List[Type]:
+        return [AgentTeamNode]
+
+    def execute(self, node: AgentTeamNode, exec_context) -> Any:
+        """
+        Execute agent team.
+
+        Args:
+            node: AgentTeamNode with team configuration
+            exec_context: Execution context
+
+        Returns:
+            Team execution result dict
+        """
+        try:
+            context = exec_context.get_all_variables()
+
+            # Resolve task from execute node
+            if not node.execute:
+                raise ExecutorError("Team requires <q:execute> to run")
+
+            task = self.apply_databinding(node.execute.task, context)
+
+            # Determine entry agent
+            entry_agent = node.execute.entry or node.supervisor
+            if not entry_agent and node.agents:
+                entry_agent = node.agents[0].name
+
+            # Initialize shared context
+            shared_context = {}
+            for set_node in node.shared:
+                if hasattr(set_node, 'name') and hasattr(set_node, 'value'):
+                    value = self.apply_databinding(set_node.value, context)
+                    shared_context[set_node.name] = value
+
+            # MultiAgentService.create_team() takes a {name: config} dict —
+            # not a list, and not the team_config dict this executor used to
+            # build. execute_team() also lives on services.multi_agent, not
+            # services.agent (which is the single-agent AgentService).
+            agents = {
+                agent.name: self._build_agent_config(agent, context)
+                for agent in node.agents
+            }
+
+            multi_agent = self.services.multi_agent
+            multi_agent.create_team(
+                name=node.name,
+                agents=agents,
+                shared=shared_context,
+                supervisor=node.supervisor or entry_agent,
+                max_handoffs=node.max_handoffs,
+                max_total_iterations=node.max_total_iterations,
+            )
+
+            team_result = multi_agent.execute_team(
+                name=node.name,
+                task=task,
+                entry_agent=entry_agent,
+                context="",
+                tool_executor=build_tool_executor(
+                    self, exec_context,
+                    [tool for agent in node.agents for tool in agent.tools],
+                ),
+            )
+
+            result = team_result.to_dict()
+
+            # Store results
+            exec_context.set_variable(node.name, result.get('finalResponse', ''), scope="component")
+            exec_context.set_variable(f"{node.name}_result", result, scope="component")
+
+            return result
+
+        except Exception as e:
+            error_result = {
+                'success': False,
+                'error': {'message': str(e)},
+                'finalResponse': '',
+                'handoffs': [],
+                'totalIterations': 0
+            }
+            exec_context.set_variable(f"{node.name}_result", error_result, scope="component")
+            raise ExecutorError(f"Team execution error: {e}")
+
+    def _build_agent_config(self, agent, context: Dict[str, Any]) -> Dict[str, Any]:
+        """Build agent configuration dict from AgentNode.
+
+        Key names must match what AgentTeam.execute() reads:
+        instruction/model/endpoint/provider/api_key/max_iterations/timeout/tools.
+        """
+        instruction = ""
+        if agent.instruction:
+            instruction = self.apply_databinding(agent.instruction.content, context)
+
+        api_key = ""
+        if agent.api_key:
+            api_key = self.apply_databinding(agent.api_key, context)
+
+        endpoint = ""
+        if agent.endpoint:
+            endpoint = self.apply_databinding(agent.endpoint, context)
+
+        return {
+            'name': agent.name,
+            'model': agent.model,
+            'provider': agent.provider,
+            'endpoint': endpoint,
+            'api_key': api_key,
+            'instruction': instruction,
+            'tools': _team_tools(agent),
+            'max_iterations': agent.max_iterations,
+            'timeout': agent.timeout,
+        }