quantum-framework 0.18.0__py3-none-any.whl

quantum/core/features/invocation/src/ast_node.py

@@ -0,0 +1,147 @@
+"""
+Invocation Feature - AST Nodes
+Defines InvokeNode and InvokeHeaderNode for q:invoke
+"""
+
+from typing import List, Dict, Any
+from quantum.core.ast_nodes import QuantumNode, QuantumParam
+
+
+class InvokeNode(QuantumNode):
+    """Represents a <q:invoke> - Universal invocation for functions, components, HTTP, etc."""
+
+    def __init__(self, name: str):
+        self.name = name  # Variable name for result
+
+        # Invocation target (determines type)
+        self.function = None      # Local function name
+        self.component = None     # Local component name
+        self.url = None          # HTTP/REST endpoint
+        self.endpoint = None     # GraphQL/SOAP endpoint
+        self.service = None      # Service name (for service discovery)
+
+        # HTTP-specific
+        self.method = "GET"      # GET, POST, PUT, DELETE, PATCH
+        self.headers: List['InvokeHeaderNode'] = []
+        self.body = None         # Request body (for POST/PUT/PATCH)
+        self.content_type = "application/json"
+
+        # Authentication
+        self.auth_type = None    # bearer, apikey, basic, oauth2
+        self.auth_token = None   # Bearer token or API key
+        self.auth_header = None  # Header name for API key (default: Authorization)
+        self.auth_username = None  # Basic auth username
+        self.auth_password = None  # Basic auth password
+
+        # Parameters (query params for HTTP, args for functions/components)
+        self.params: List[QuantumParam] = []
+
+        # Timeouts and retries
+        self.timeout = 30000     # Default 30s
+        self.retry = 0           # Number of retries
+        self.retry_delay = 1000  # Delay between retries in ms
+
+        # Response handling
+        self.response_format = "auto"  # auto, json, text, xml, binary
+        self.transform = None    # Transformation expression
+        self.cache = False
+        self.ttl = None
+        self.result = None       # Variable name for metadata
+        self.on_error = 'fail'   # INV-2: 'fail' or 'continue'
+
+    def add_header(self, header: 'InvokeHeaderNode'):
+        """Add HTTP header"""
+        self.headers.append(header)
+
+    def add_param(self, param: QuantumParam):
+        """Add parameter"""
+        self.params.append(param)
+
+    def get_invocation_type(self) -> str:
+        """Determine invocation type based on attributes"""
+        if self.function:
+            return "function"
+        elif self.component:
+            return "component"
+        elif self.url:
+            return "http"
+        elif self.endpoint:
+            # Could be GraphQL, SOAP, etc. (Phase 2)
+            return "endpoint"
+        elif self.service:
+            # Service discovery (Phase 2)
+            return "service"
+        else:
+            return "unknown"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "invoke",
+            "name": self.name,
+            "invocation_type": self.get_invocation_type(),
+            "function": self.function,
+            "component": self.component,
+            "url": self.url,
+            "method": self.method,
+            "headers": [h.to_dict() for h in self.headers],
+            "params": [p.__dict__ for p in self.params],
+            "auth_type": self.auth_type,
+            "timeout": self.timeout,
+            "retry": self.retry,
+            "cache": self.cache
+        }
+
+    def validate(self) -> List[str]:
+        errors = []
+        # name is optional: fire-and-forget invocation has no result to bind.
+        # What actually matters is that there is something to invoke.
+
+        # Validate that at least one target is specified
+        targets = [self.function, self.component, self.url, self.endpoint, self.service]
+        if not any(targets):
+            errors.append("Invoke requires one of: function, component, url, endpoint, or service")
+
+        # Validate that only one target is specified
+        if sum(1 for t in targets if t is not None) > 1:
+            errors.append("Invoke can only specify one target (function, component, url, endpoint, or service)")
+
+        # Validate HTTP method
+        if self.method not in ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']:
+            errors.append(f"Invalid HTTP method: {self.method}")
+
+        # Validate auth_type
+        if self.auth_type and self.auth_type not in ['bearer', 'apikey', 'basic', 'oauth2']:
+            errors.append(f"Invalid auth_type: {self.auth_type}. Must be bearer, apikey, basic, or oauth2")
+
+        # Validate headers
+        for header in self.headers:
+            errors.extend(header.validate())
+
+        # Validate params
+        for param in self.params:
+            errors.extend(param.validate())
+
+        return errors
+
+
+class InvokeHeaderNode(QuantumNode):
+    """Represents a header in <q:invoke>"""
+
+    def __init__(self, name: str, value: str):
+        self.name = name
+        self.value = value
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "invokeHeader",
+            "name": self.name,
+            "value": self.value[:50] + "..." if len(str(self.value)) > 50 else self.value
+        }
+
+    def validate(self) -> List[str]:
+        errors = []
+        if not self.name:
+            errors.append("Header name is required")
+        if self.value is None:
+            errors.append(f"Header '{self.name}' value is required")
+        return errors

quantum/core/features/invocation/src/runtime.py

@@ -0,0 +1,332 @@
+"""
+Invocation Feature - Runtime
+Handles execution of all invocation types (functions, components, HTTP, etc.)
+"""
+
+import time
+import json
+import requests
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass
+import base64
+
+
+@dataclass
+class InvocationResult:
+    """Result object for all invocations"""
+    success: bool
+    data: Any = None
+    error: Optional[Dict[str, Any]] = None
+    execution_time: float = 0.0
+    invocation_type: str = ""
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class InvocationService:
+    """Service to handle all types of invocations"""
+
+    def __init__(self):
+        self.cache: Dict[str, Any] = {}  # Simple in-memory cache
+
+    def invoke(
+        self,
+        invocation_type: str,
+        params: Dict[str, Any],
+        context: Any = None
+    ) -> InvocationResult:
+        """Main invocation dispatcher"""
+        start_time = time.time()
+
+        try:
+            if invocation_type == "function":
+                result = self._invoke_function(params, context)
+            elif invocation_type == "component":
+                result = self._invoke_component(params, context)
+            elif invocation_type == "http":
+                result = self._invoke_http(params)
+            else:
+                return InvocationResult(
+                    success=False,
+                    error={"message": f"Unknown invocation type: {invocation_type}"},
+                    invocation_type=invocation_type
+                )
+
+            execution_time = (time.time() - start_time) * 1000  # Convert to ms
+            result.execution_time = execution_time
+            result.invocation_type = invocation_type
+            return result
+
+        except Exception as e:
+            execution_time = (time.time() - start_time) * 1000
+            return InvocationResult(
+                success=False,
+                error={
+                    "message": str(e),
+                    "type": type(e).__name__
+                },
+                execution_time=execution_time,
+                invocation_type=invocation_type
+            )
+
+    def _invoke_function(self, params: Dict[str, Any], context: Any) -> InvocationResult:
+        """Invoke local function"""
+        function_name = params.get('function')
+        function_args = params.get('args', {})
+
+        if not context:
+            return InvocationResult(
+                success=False,
+                error={"message": "Context required for function invocation"}
+            )
+
+        # Get function from context (ComponentRuntime will handle this)
+        if not hasattr(context, 'get_function'):
+            return InvocationResult(
+                success=False,
+                error={"message": "Context does not support function invocation"}
+            )
+
+        func = context.get_function(function_name)
+        if not func:
+            return InvocationResult(
+                success=False,
+                error={"message": f"Function '{function_name}' not found"}
+            )
+
+        # Execute function
+        result = context.execute_function(function_name, function_args)
+
+        return InvocationResult(
+            success=result.get('success', False),
+            data=result.get('data'),
+            error=result.get('error'),
+            metadata=result
+        )
+
+    def _invoke_component(self, params: Dict[str, Any], context: Any) -> InvocationResult:
+        """Invoke local component"""
+        component_name = params.get('component')
+        component_args = params.get('args', {})
+
+        if not context:
+            return InvocationResult(
+                success=False,
+                error={"message": "Context required for component invocation"}
+            )
+
+        # Get component from context (ComponentRuntime will handle this)
+        if not hasattr(context, 'execute_component'):
+            return InvocationResult(
+                success=False,
+                error={"message": "Context does not support component invocation"}
+            )
+
+        result = context.execute_component(component_name, component_args)
+
+        return InvocationResult(
+            success=result.get('success', False),
+            data=result.get('data'),
+            error=result.get('error'),
+            metadata=result
+        )
+
+    def _invoke_http(self, params: Dict[str, Any]) -> InvocationResult:
+        """Invoke HTTP/REST endpoint"""
+        url = params.get('url')
+        method = params.get('method', 'GET').upper()
+        headers = params.get('headers', {})
+        query_params = params.get('params', {})
+        body = params.get('body')
+        auth_type = params.get('auth_type')
+        # `or`, not a get() default: the executor always passes these keys,
+        # with None when the attribute is absent — so get('timeout', 30000)
+        # returned None and `None / 1000` raised TypeError before any request
+        # was made. Every q:invoke url= without an explicit timeout failed
+        # with "unsupported operand type(s) for /: 'NoneType' and 'int'".
+        timeout_ms = params.get('timeout') or 30000
+        retry = params.get('retry') or 0
+        retry_delay = params.get('retry_delay') or 1000
+        response_format = params.get('response_format', 'auto')
+
+        if not url:
+            return InvocationResult(
+                success=False,
+                error={"message": "URL required for HTTP invocation"}
+            )
+
+        # Build authentication
+        headers = self._build_auth_headers(params, headers)
+
+        # Convert timeout to seconds for requests library
+        timeout_sec = timeout_ms / 1000
+
+        # Retry logic
+        last_error = None
+        for attempt in range(retry + 1):
+            try:
+                # Make HTTP request
+                response = requests.request(
+                    method=method,
+                    url=url,
+                    headers=headers,
+                    params=query_params,
+                    json=body if method in ['POST', 'PUT', 'PATCH'] and isinstance(body, dict) else None,
+                    data=body if method in ['POST', 'PUT', 'PATCH'] and isinstance(body, str) else None,
+                    timeout=timeout_sec
+                )
+
+                # Parse response based on format
+                data = self._parse_http_response(response, response_format)
+
+                # Build metadata
+                metadata = {
+                    "status_code": response.status_code,
+                    "status_text": response.reason,
+                    "headers": dict(response.headers),
+                    "url": response.url,
+                    "attempts": attempt + 1
+                }
+
+                # Check if response is successful
+                success = 200 <= response.status_code < 300
+
+                if not success:
+                    return InvocationResult(
+                        success=False,
+                        data=data,
+                        error={
+                            "message": f"HTTP {response.status_code}: {response.reason}",
+                            "status_code": response.status_code
+                        },
+                        metadata=metadata
+                    )
+
+                return InvocationResult(
+                    success=True,
+                    data=data,
+                    metadata=metadata
+                )
+
+            except requests.exceptions.Timeout as e:
+                last_error = InvocationResult(
+                    success=False,
+                    error={
+                        "message": f"Request timeout after {timeout_ms}ms",
+                        "type": "TimeoutError"
+                    },
+                    metadata={"attempts": attempt + 1}
+                )
+
+            except requests.exceptions.ConnectionError as e:
+                last_error = InvocationResult(
+                    success=False,
+                    error={
+                        "message": f"Connection error: {str(e)}",
+                        "type": "ConnectionError"
+                    },
+                    metadata={"attempts": attempt + 1}
+                )
+
+            except Exception as e:
+                last_error = InvocationResult(
+                    success=False,
+                    error={
+                        "message": str(e),
+                        "type": type(e).__name__
+                    },
+                    metadata={"attempts": attempt + 1}
+                )
+
+            # If we have more retries, wait before retrying
+            if attempt < retry:
+                time.sleep(retry_delay / 1000)  # Convert ms to seconds
+
+        # All retries exhausted, return last error
+        return last_error
+
+    def _build_auth_headers(self, params: Dict[str, Any], headers: Dict[str, str]) -> Dict[str, str]:
+        """Build authentication headers"""
+        auth_type = params.get('auth_type')
+        headers = headers.copy()  # Don't mutate original
+
+        if auth_type == 'bearer':
+            token = params.get('auth_token')
+            if token:
+                headers['Authorization'] = f'Bearer {token}'
+
+        elif auth_type == 'apikey':
+            token = params.get('auth_token')
+            header_name = params.get('auth_header', 'Authorization')
+            if token:
+                headers[header_name] = token
+
+        elif auth_type == 'basic':
+            username = params.get('auth_username')
+            password = params.get('auth_password')
+            if username and password:
+                credentials = f"{username}:{password}".encode('utf-8')
+                encoded = base64.b64encode(credentials).decode('utf-8')
+                headers['Authorization'] = f'Basic {encoded}'
+
+        return headers
+
+    def _parse_http_response(self, response: requests.Response, response_format: str) -> Any:
+        """Parse HTTP response based on format"""
+        if response_format == 'auto':
+            # Try to detect format from Content-Type header
+            content_type = response.headers.get('Content-Type', '').lower()
+
+            if 'application/json' in content_type:
+                try:
+                    return response.json()
+                except:
+                    return response.text
+
+            elif 'text/' in content_type or 'application/xml' in content_type:
+                return response.text
+
+            elif 'application/octet-stream' in content_type or 'image/' in content_type:
+                return {
+                    "binary": True,
+                    "content_type": content_type,
+                    "size": len(response.content)
+                }
+
+            else:
+                # Default to text
+                return response.text
+
+        elif response_format == 'json':
+            try:
+                return response.json()
+            except:
+                return {"error": "Failed to parse JSON response", "text": response.text}
+
+        elif response_format == 'text':
+            return response.text
+
+        elif response_format == 'xml':
+            return response.text
+
+        elif response_format == 'binary':
+            return {
+                "binary": True,
+                "content_type": response.headers.get('Content-Type'),
+                "size": len(response.content)
+            }
+
+        else:
+            return response.text
+
+    def get_from_cache(self, cache_key: str) -> Optional[Any]:
+        """Get value from cache"""
+        return self.cache.get(cache_key)
+
+    def put_in_cache(self, cache_key: str, value: Any, ttl: Optional[int] = None):
+        """Put value in cache"""
+        # Simple implementation - in production you'd use TTL properly
+        self.cache[cache_key] = value
+
+    def clear_cache(self):
+        """Clear all cache"""
+        self.cache.clear()

quantum/core/features/knowledge_base/src/__init__.py

@@ -0,0 +1,6 @@
+"""Knowledge Base feature - RAG with virtual knowledge bases."""
+
+from .ast_node import KnowledgeNode, KnowledgeSourceNode
+from .parser import parse_knowledge
+
+__all__ = ['KnowledgeNode', 'KnowledgeSourceNode', 'parse_knowledge']

quantum/core/features/knowledge_base/src/ast_node.py

@@ -0,0 +1,113 @@
+"""AST nodes for q:knowledge and q:source."""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+from quantum.core.ast_nodes import QuantumNode
+
+
+@dataclass
+class KnowledgeSourceNode(QuantumNode):
+    """
+    Represents <q:source> inside <q:knowledge>.
+
+    Examples:
+      <q:source type="text">Quantum Framework allows...</q:source>
+      <q:source type="file" path="./docs/guide.md" />
+      <q:source type="directory" path="./docs/" pattern="*.md" />
+      <q:source type="query" datasource="mydb">
+          SELECT title, content FROM articles
+      </q:source>
+    """
+    source_type: str = "text"          # text, file, directory, url, query
+    content: Optional[str] = None      # Inline text content
+    path: Optional[str] = None         # File or directory path
+    pattern: Optional[str] = None      # Glob pattern for directory type
+    url: Optional[str] = None          # URL for url type
+    datasource: Optional[str] = None   # Datasource for query type
+    sql: Optional[str] = None          # SQL for query type
+    chunk_size: Optional[int] = None   # Override parent chunk_size
+    chunk_overlap: Optional[int] = None  # Override parent chunk_overlap
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "knowledge_source",
+            "source_type": self.source_type,
+            "content": self.content[:50] + "..." if self.content and len(self.content) > 50 else self.content,
+            "path": self.path,
+            "pattern": self.pattern,
+            "url": self.url,
+            "datasource": self.datasource,
+        }
+
+    def validate(self) -> List[str]:
+        errors = []
+        valid_types = ['text', 'file', 'directory', 'url', 'query']
+        if self.source_type not in valid_types:
+            errors.append(f"Invalid source type: {self.source_type}. Must be one of {valid_types}")
+
+        if self.source_type == 'text' and not self.content:
+            errors.append("Text source requires content")
+        if self.source_type == 'file' and not self.path:
+            errors.append("File source requires 'path' attribute")
+        if self.source_type == 'directory' and not self.path:
+            errors.append("Directory source requires 'path' attribute")
+        if self.source_type == 'url' and not self.url:
+            errors.append("URL source requires 'url' attribute")
+        if self.source_type == 'query' and not self.datasource:
+            errors.append("Query source requires 'datasource' attribute")
+
+        return errors
+
+    def __repr__(self):
+        return f'<KnowledgeSourceNode type={self.source_type}>'
+
+
+@dataclass
+class KnowledgeNode(QuantumNode):
+    """
+    Represents <q:knowledge> - defines a virtual knowledge base.
+
+    Examples:
+      <q:knowledge name="docs" model="phi3" embedModel="nomic-embed-text">
+          <q:source type="text">Quantum Framework allows...</q:source>
+          <q:source type="file" path="./docs/guide.md" />
+      </q:knowledge>
+    """
+    name: str = ""
+    model: Optional[str] = None              # LLM model for RAG
+    embed_model: str = "nomic-embed-text"     # Embedding model
+    chunk_size: int = 500                     # Characters per chunk
+    chunk_overlap: int = 50                   # Overlap between chunks
+    sources: List[KnowledgeSourceNode] = field(default_factory=list)
+    persist: bool = False                     # Persist ChromaDB to disk
+    persist_path: Optional[str] = None        # ChromaDB persistence path
+    rebuild: bool = False                     # Force reindex
+
+    def add_source(self, source: KnowledgeSourceNode):
+        self.sources.append(source)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "type": "knowledge",
+            "name": self.name,
+            "model": self.model,
+            "embed_model": self.embed_model,
+            "chunk_size": self.chunk_size,
+            "chunk_overlap": self.chunk_overlap,
+            "sources": [s.to_dict() for s in self.sources],
+            "persist": self.persist,
+            "rebuild": self.rebuild,
+        }
+
+    def validate(self) -> List[str]:
+        errors = []
+        if not self.name:
+            errors.append("Knowledge base name is required")
+        if not self.sources:
+            errors.append("Knowledge base requires at least one <q:source>")
+        for source in self.sources:
+            errors.extend(source.validate())
+        return errors
+
+    def __repr__(self):
+        return f'<KnowledgeNode name={self.name} sources={len(self.sources)}>'

quantum/core/features/knowledge_base/src/parser.py

@@ -0,0 +1,82 @@
+"""Parser for q:knowledge and q:source elements."""
+
+from xml.etree import ElementTree as ET
+from .ast_node import KnowledgeNode, KnowledgeSourceNode
+
+
+def parse_knowledge(element: ET.Element) -> KnowledgeNode:
+    """
+    Parse <q:knowledge> element into KnowledgeNode.
+
+    Args:
+        element: XML element representing <q:knowledge>
+
+    Returns:
+        KnowledgeNode with parsed sources
+    """
+    name = element.get('name', '')
+    node = KnowledgeNode(name=name)
+
+    # Parse attributes
+    node.model = element.get('model')
+    node.embed_model = element.get('embedModel', 'nomic-embed-text')
+
+    chunk_size = element.get('chunkSize')
+    if chunk_size:
+        try:
+            node.chunk_size = int(chunk_size)
+        except ValueError:
+            pass
+
+    chunk_overlap = element.get('chunkOverlap')
+    if chunk_overlap:
+        try:
+            node.chunk_overlap = int(chunk_overlap)
+        except ValueError:
+            pass
+
+    node.persist = element.get('persist', 'false').lower() in ('true', '1', 'yes')
+    node.persist_path = element.get('persistPath')
+    node.rebuild = element.get('rebuild', 'false').lower() in ('true', '1', 'yes')
+
+    # Parse <q:source> children
+    for child in element:
+        local_name = child.tag.split('}')[-1] if '}' in child.tag else child.tag.split(':')[-1]
+        if local_name == 'source':
+            source = _parse_source(child)
+            node.add_source(source)
+
+    return node
+
+
+def _parse_source(element: ET.Element) -> KnowledgeSourceNode:
+    """Parse <q:source> element into KnowledgeSourceNode."""
+    source = KnowledgeSourceNode()
+    source.source_type = element.get('type', 'text')
+    source.path = element.get('path')
+    source.pattern = element.get('pattern', '*.md')
+    source.url = element.get('url')
+    source.datasource = element.get('datasource')
+
+    chunk_size = element.get('chunkSize')
+    if chunk_size:
+        try:
+            source.chunk_size = int(chunk_size)
+        except ValueError:
+            pass
+
+    chunk_overlap = element.get('chunkOverlap')
+    if chunk_overlap:
+        try:
+            source.chunk_overlap = int(chunk_overlap)
+        except ValueError:
+            pass
+
+    # Text content (inline or SQL for query type)
+    text = (element.text or '').strip()
+    if source.source_type == 'query':
+        source.sql = text
+    elif source.source_type == 'text':
+        source.content = text
+
+    return source