kubiya-control-plane-api 0.9.15__py3-none-any.whl

control_plane_api/app/lib/templating/__init__.py

@@ -0,0 +1,88 @@
+"""
+Template engine package for variable substitution in MCP configurations.
+
+This package provides a flexible, extensible template engine that supports
+multiple template syntaxes through a plugin-based parser system.
+
+Supported template syntaxes:
+- {{variable}} - Simple variable substitution
+- {{.secret.name}} - Secret from vault
+- {{.env.VAR}} - Environment variable
+
+Example usage:
+    from control_plane_api.app.lib.templating import TemplateEngine, TemplateContext, TemplateCompiler
+
+    # Parse and compile a template
+    engine = TemplateEngine()
+    context = TemplateContext(
+        secrets={"api_key": "secret-value"},
+        env_vars={"PORT": "8080"}
+    )
+
+    compiler = TemplateCompiler(engine)
+    result = compiler.compile("http://api.example.com:{{.env.PORT}}/{{.secret.api_key}}", context)
+    print(result.compiled)  # "http://api.example.com:8080/secret-value"
+"""
+
+# Core types
+from control_plane_api.app.lib.templating.types import (
+    TemplateVariableType,
+    TemplateVariable,
+    ValidationError,
+    ParseResult,
+    TemplateContext,
+    ValidationResult,
+    CompileResult,
+)
+
+# Main engine components
+from control_plane_api.app.lib.templating.engine import TemplateEngine, get_default_engine
+from control_plane_api.app.lib.templating.validator import TemplateValidator
+from control_plane_api.app.lib.templating.compiler import TemplateCompiler
+from control_plane_api.app.lib.templating.resolver import (
+    TemplateResolver,
+    TemplateResolutionError,
+    resolve_templates,
+    has_templates,
+    extract_all_variables,
+)
+
+# Parser infrastructure (for advanced usage)
+from control_plane_api.app.lib.templating.parsers import (
+    BaseParser,
+    SimpleVariableParser,
+    SecretVariableParser,
+    EnvVariableParser,
+    DEFAULT_PARSERS,
+)
+
+__all__ = [
+    # Types
+    "TemplateVariableType",
+    "TemplateVariable",
+    "ValidationError",
+    "ParseResult",
+    "TemplateContext",
+    "ValidationResult",
+    "CompileResult",
+    # Main components
+    "TemplateEngine",
+    "get_default_engine",
+    "TemplateValidator",
+    "TemplateCompiler",
+    "TemplateResolver",
+    "TemplateResolutionError",
+    # Convenience functions
+    "resolve_templates",
+    "has_templates",
+    "extract_all_variables",
+    # Parsers (advanced)
+    "BaseParser",
+    "SimpleVariableParser",
+    "SecretVariableParser",
+    "EnvVariableParser",
+    "DEFAULT_PARSERS",
+]
+
+# Version
+__version__ = "1.0.0"

control_plane_api/app/lib/templating/compiler.py

@@ -0,0 +1,278 @@
+"""
+Template compilation logic.
+
+Compiles templates by substituting variables with their values from a context.
+"""
+
+import json
+import os
+import structlog
+import httpx
+from typing import Any, Dict, Optional
+from control_plane_api.app.lib.templating.types import (
+    TemplateContext,
+    TemplateVariableType,
+    CompileResult,
+)
+from control_plane_api.app.lib.templating.engine import TemplateEngine, get_default_engine
+from control_plane_api.app.lib.templating.validator import TemplateValidator
+
+logger = structlog.get_logger()
+
+
+class TemplateCompiler:
+    """
+    Compiles templates by substituting variables with values from a context.
+
+    The compiler:
+    1. Validates the template
+    2. Substitutes variables with their values
+    3. Returns the compiled string
+    """
+
+    def __init__(self, engine: TemplateEngine = None):
+        """
+        Initialize the compiler with a template engine.
+
+        Args:
+            engine: Template engine to use. If None, uses default engine.
+        """
+        self.engine = engine if engine is not None else get_default_engine()
+        self.validator = TemplateValidator(self.engine)
+
+    def compile(self, template: str, context: TemplateContext) -> CompileResult:
+        """
+        Compile a template by substituting all variables with their values.
+
+        Process:
+        1. Parse the template to extract variables
+        2. Validate that all variables exist in context
+        3. Substitute variables with their values (in reverse order to preserve positions)
+
+        Args:
+            template: Template string to compile
+            context: Template context with variable values
+
+        Returns:
+            CompileResult with compiled string or error
+        """
+        try:
+            # Parse the template
+            parse_result = self.engine.parse(template)
+
+            # Check for syntax errors
+            if not parse_result.is_valid:
+                error_messages = [err.message for err in parse_result.errors]
+                error_str = "; ".join(error_messages)
+                logger.warning("template_syntax_errors", errors=error_messages)
+                return CompileResult(
+                    compiled="",
+                    success=False,
+                    error=f"Template syntax errors: {error_str}"
+                )
+
+            # Validate against context
+            validation_result = self.validator.validate(template, context)
+            if not validation_result.valid:
+                error_messages = [err.message for err in validation_result.errors]
+                error_str = "; ".join(error_messages)
+                logger.warning("template_validation_errors", errors=error_messages)
+                return CompileResult(
+                    compiled="",
+                    success=False,
+                    error=f"Template validation errors: {error_str}"
+                )
+
+            # Substitute variables (process in reverse order to preserve positions)
+            result = template
+            for var in sorted(parse_result.variables, key=lambda v: v.start, reverse=True):
+                try:
+                    # Get the value based on variable type
+                    value = self._get_variable_value(var.type, var, context)
+
+                    # Convert to string
+                    value_str = str(value) if value is not None else ""
+
+                    # Substitute
+                    result = result[:var.start] + value_str + result[var.end:]
+
+                    logger.debug(
+                        "variable_substituted",
+                        variable_name=var.name,
+                        variable_type=var.type.value,
+                        has_value=bool(value),
+                        value_length=len(value_str)
+                    )
+
+                except KeyError as e:
+                    # This shouldn't happen if validation passed, but handle it gracefully
+                    logger.error(
+                        "variable_not_found_during_compilation",
+                        variable_name=var.name,
+                        error=str(e)
+                    )
+                    # Preserve the original error message (especially for graph node API errors)
+                    error_msg = str(e) if str(e) else f"Variable '{var.name}' not found in context"
+                    return CompileResult(
+                        compiled="",
+                        success=False,
+                        error=error_msg
+                    )
+
+            logger.info(
+                "template_compiled_successfully",
+                original_length=len(template),
+                compiled_length=len(result),
+                variable_count=len(parse_result.variables)
+            )
+
+            return CompileResult(
+                compiled=result,
+                success=True
+            )
+
+        except Exception as e:
+            logger.error("template_compilation_failed", error=str(e), exc_info=True)
+            return CompileResult(
+                compiled="",
+                success=False,
+                error=f"Compilation failed: {str(e)}"
+            )
+
+    def _get_variable_value(
+        self,
+        var_type: TemplateVariableType,
+        var,
+        context: TemplateContext
+    ) -> Any:
+        """
+        Get the value for a variable from the context.
+
+        Args:
+            var_type: Type of variable
+            var: TemplateVariable object
+            context: Template context
+
+        Returns:
+            Variable value
+
+        Raises:
+            KeyError: If variable not found in context
+        """
+        if var_type == TemplateVariableType.SECRET:
+            return context.secrets[var.display_name]
+        elif var_type == TemplateVariableType.ENV:
+            return context.env_vars[var.display_name]
+        elif var_type == TemplateVariableType.GRAPH:
+            return self._get_graph_node_value(var.display_name, context)
+        else:  # SIMPLE
+            return context.variables[var.name]
+
+    def _get_graph_node_value(
+        self,
+        node_id: str,
+        context: TemplateContext
+    ) -> str:
+        """
+        Get graph node data from context or fetch from API.
+
+        Args:
+            node_id: The node ID to fetch
+            context: Template context with graph configuration
+
+        Returns:
+            Formatted node data as JSON string
+
+        Raises:
+            KeyError: If node not found or API configuration missing
+        """
+        # Check if node is already in context
+        if context.graph_nodes and node_id in context.graph_nodes:
+            node_data = context.graph_nodes[node_id]
+            return json.dumps(node_data, indent=2)
+
+        # Need to fetch from API - validate configuration
+        if not context.graph_api_base:
+            raise KeyError(
+                f"Context graph API base URL not configured for node '{node_id}'"
+            )
+        if not context.graph_api_key:
+            raise KeyError(
+                f"Context graph API key not configured for node '{node_id}'"
+            )
+
+        # Fetch node from API
+        try:
+            node_data = self._fetch_graph_node(
+                node_id=node_id,
+                api_base=context.graph_api_base,
+                api_key=context.graph_api_key,
+                org_id=context.graph_org_id
+            )
+
+            # Cache in context for subsequent requests
+            if context.graph_nodes is None:
+                context.graph_nodes = {}
+            context.graph_nodes[node_id] = node_data
+
+            return json.dumps(node_data, indent=2)
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                raise KeyError(f"Graph node '{node_id}' not found")
+            else:
+                raise KeyError(
+                    f"Failed to fetch graph node '{node_id}': "
+                    f"HTTP {e.response.status_code}"
+                )
+        except Exception as e:
+            raise KeyError(f"Failed to fetch graph node '{node_id}': {str(e)}")
+
+    def _fetch_graph_node(
+        self,
+        node_id: str,
+        api_base: str,
+        api_key: str,
+        org_id: Optional[str] = None,
+        timeout: int = 30
+    ) -> Dict[str, Any]:
+        """
+        Fetch a node from the context graph API.
+
+        Args:
+            node_id: The node ID to fetch
+            api_base: Context graph API base URL
+            api_key: API key for authentication
+            org_id: Optional organization ID
+            timeout: Request timeout in seconds
+
+        Returns:
+            Node data dictionary
+
+        Raises:
+            httpx.HTTPStatusError: If request fails (including 404)
+            Exception: If request fails for other reasons
+        """
+        url = f"{api_base.rstrip('/')}/api/v1/graph/nodes/{node_id}"
+
+        headers = {
+            "Authorization": f"UserKey {api_key}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "X-Kubiya-Client": "agent-runtime-template-compiler",
+        }
+
+        if org_id:
+            headers["X-Organization-ID"] = org_id
+
+        logger.debug(
+            "fetching_graph_node",
+            node_id=node_id,
+            api_base=api_base,
+            has_org_id=bool(org_id)
+        )
+
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(url, headers=headers)
+            response.raise_for_status()
+            return response.json()

control_plane_api/app/lib/templating/engine.py

@@ -0,0 +1,178 @@
+"""
+Main template engine orchestrator.
+
+Coordinates multiple parsers to extract, validate, and compile templates.
+"""
+
+import structlog
+from typing import List, Set
+from control_plane_api.app.lib.templating.types import (
+    TemplateVariable,
+    ParseResult,
+    ValidationError,
+)
+from control_plane_api.app.lib.templating.parsers import BaseParser, DEFAULT_PARSERS
+
+logger = structlog.get_logger()
+
+
+class TemplateEngine:
+    """
+    Main template engine that coordinates multiple parsers.
+
+    This engine uses a plugin-based architecture where different parsers
+    can be registered to handle different template syntaxes.
+    """
+
+    def __init__(self, parsers: List[BaseParser] = None):
+        """
+        Initialize the template engine with a list of parsers.
+
+        Args:
+            parsers: List of parsers to use. If None, uses DEFAULT_PARSERS.
+        """
+        self.parsers = parsers if parsers is not None else DEFAULT_PARSERS.copy()
+        logger.debug("template_engine_initialized", parser_count=len(self.parsers))
+
+    def parse(self, template: str) -> ParseResult:
+        """
+        Parse a template string using all registered parsers.
+
+        Args:
+            template: Template string to parse
+
+        Returns:
+            ParseResult with all variables found and any syntax errors
+        """
+        if not template:
+            return ParseResult(template="", variables=[], errors=[])
+
+        variables: List[TemplateVariable] = []
+        errors: List[ValidationError] = []
+        processed_positions: Set[int] = set()
+
+        # Run each parser
+        for parser in self.parsers:
+            try:
+                parser_variables = parser.parse(template)
+
+                # Filter out variables at already-processed positions
+                # This prevents conflicts between parsers (e.g., {{var}} matching as both simple and secret)
+                for var in parser_variables:
+                    if var.start not in processed_positions:
+                        variables.append(var)
+                        processed_positions.add(var.start)
+                        logger.debug(
+                            "variable_parsed",
+                            variable_name=var.name,
+                            variable_type=var.type.value,
+                            position=var.start
+                        )
+
+            except Exception as e:
+                logger.error(
+                    "parser_error",
+                    parser=parser.__class__.__name__,
+                    error=str(e)
+                )
+                errors.append(ValidationError(
+                    message=f"Parser error ({parser.__class__.__name__}): {str(e)}",
+                    code="PARSER_ERROR"
+                ))
+
+        # Check for unrecognized template patterns
+        # Find all {{ }} that weren't matched by any parser
+        import re
+        all_braces = re.finditer(r"\{\{([^}]+)\}\}", template)
+        for match in all_braces:
+            start = match.start()
+            if start not in processed_positions:
+                raw = match.group(0)
+                errors.append(ValidationError(
+                    message=f"Unrecognized template syntax: '{raw}'. Expected {{{{variable}}}}, {{{{.secret.name}}}}, or {{{{.env.VAR}}}}",
+                    position=start,
+                    code="INVALID_SYNTAX"
+                ))
+                logger.warning(
+                    "unrecognized_template_syntax",
+                    raw=raw,
+                    position=start
+                )
+
+        # Sort variables by position for consistent ordering
+        variables.sort(key=lambda v: v.start)
+
+        return ParseResult(
+            template=template,
+            variables=variables,
+            errors=errors
+        )
+
+    def extract_variables(self, template: str) -> List[TemplateVariable]:
+        """
+        Extract all variables from a template without full parsing.
+
+        Args:
+            template: Template string
+
+        Returns:
+            List of TemplateVariable objects
+        """
+        parse_result = self.parse(template)
+        return parse_result.variables
+
+    def get_required_secrets(self, template: str) -> List[str]:
+        """
+        Get list of required secret names from a template.
+
+        Args:
+            template: Template string
+
+        Returns:
+            List of secret names (without .secret prefix)
+        """
+        parse_result = self.parse(template)
+        return [var.display_name for var in parse_result.secret_variables]
+
+    def get_required_env_vars(self, template: str) -> List[str]:
+        """
+        Get list of required environment variable names from a template.
+
+        Args:
+            template: Template string
+
+        Returns:
+            List of environment variable names (without .env prefix)
+        """
+        parse_result = self.parse(template)
+        return [var.display_name for var in parse_result.env_variables]
+
+    def get_required_simple_vars(self, template: str) -> List[str]:
+        """
+        Get list of required simple variable names from a template.
+
+        Args:
+            template: Template string
+
+        Returns:
+            List of simple variable names
+        """
+        parse_result = self.parse(template)
+        return [var.name for var in parse_result.simple_variables]
+
+
+# Global default engine instance
+_default_engine = None
+
+
+def get_default_engine() -> TemplateEngine:
+    """
+    Get the default global template engine instance.
+
+    Returns:
+        TemplateEngine instance
+    """
+    global _default_engine
+    if _default_engine is None:
+        _default_engine = TemplateEngine()
+    return _default_engine

control_plane_api/app/lib/templating/parsers/__init__.py

@@ -0,0 +1,29 @@
+"""
+Template parsers package.
+
+Exports all available template variable parsers.
+"""
+
+from control_plane_api.app.lib.templating.parsers.base import BaseParser
+from control_plane_api.app.lib.templating.parsers.simple import SimpleVariableParser
+from control_plane_api.app.lib.templating.parsers.secret import SecretVariableParser
+from control_plane_api.app.lib.templating.parsers.env import EnvVariableParser
+from control_plane_api.app.lib.templating.parsers.graph import GraphNodeParser
+
+# Default list of parsers to use in the template engine
+# Order matters: more specific patterns should come first to avoid conflicts
+DEFAULT_PARSERS = [
+    SecretVariableParser(),    # {{.secret.name}} - most specific
+    EnvVariableParser(),       # {{.env.VAR}} - specific
+    GraphNodeParser(),         # {{.graph.node-id}} - specific
+    SimpleVariableParser(),    # {{variable}} - most general (must be last)
+]
+
+__all__ = [
+    "BaseParser",
+    "SimpleVariableParser",
+    "SecretVariableParser",
+    "EnvVariableParser",
+    "GraphNodeParser",
+    "DEFAULT_PARSERS",
+]

control_plane_api/app/lib/templating/parsers/base.py

@@ -0,0 +1,96 @@
+"""
+Base parser interface for template variable parsers.
+
+This module defines the abstract base class that all template parsers must implement.
+"""
+
+import re
+from abc import ABC, abstractmethod
+from typing import List, Optional
+from control_plane_api.app.lib.templating.types import TemplateVariable, TemplateVariableType
+
+
+class BaseParser(ABC):
+    """
+    Abstract base class for template variable parsers.
+
+    Each parser is responsible for:
+    - Defining a regex pattern to match its template syntax
+    - Parsing matches into TemplateVariable objects
+    - Validating variable names according to its rules
+    """
+
+    @property
+    @abstractmethod
+    def pattern(self) -> re.Pattern:
+        """
+        Regular expression pattern to match this parser's template syntax.
+
+        Returns:
+            Compiled regex pattern
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def variable_type(self) -> TemplateVariableType:
+        """
+        Type of variables this parser handles.
+
+        Returns:
+            TemplateVariableType enum value
+        """
+        pass
+
+    @abstractmethod
+    def parse_match(self, match: re.Match, template: str) -> Optional[TemplateVariable]:
+        """
+        Parse a regex match into a TemplateVariable.
+
+        Args:
+            match: Regex match object
+            template: Full template string (for context)
+
+        Returns:
+            TemplateVariable if valid, None if invalid
+        """
+        pass
+
+    @abstractmethod
+    def validate_name(self, name: str) -> bool:
+        """
+        Validate that a variable name follows this parser's rules.
+
+        Args:
+            name: Variable name to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        pass
+
+    def parse(self, template: str) -> List[TemplateVariable]:
+        """
+        Parse a template string and extract all variables of this parser's type.
+
+        Args:
+            template: Template string to parse
+
+        Returns:
+            List of TemplateVariable objects found
+        """
+        if not template:
+            return []
+
+        variables: List[TemplateVariable] = []
+
+        for match in self.pattern.finditer(template):
+            variable = self.parse_match(match, template)
+            if variable:
+                variables.append(variable)
+
+        return variables
+
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return f"{self.__class__.__name__}(type={self.variable_type.value})"