ryeos-engine 0.1.0__py3-none-any.whl

rye/__init__.py

@@ -0,0 +1,3 @@
+"""RYE OS - AI operating system on Lillux microkernel."""
+
+__version__ = "0.1.0"

rye/constants.py

@@ -0,0 +1,62 @@
+"""RYE Constants
+
+Centralized constants for the AI directory name, item types, and tool actions.
+"""
+
+# The name of the working directory used in all three spaces.
+# Every space follows: base_path / AI_DIR / {type_dir} / {item_id}
+AI_DIR = ".ai"
+
+
+class ItemType:
+    """Item type constants."""
+
+    DIRECTIVE = "directive"
+    TOOL = "tool"
+    KNOWLEDGE = "knowledge"
+
+    ALL = [DIRECTIVE, TOOL, KNOWLEDGE]
+
+    # Type directory mappings
+    TYPE_DIRS = {
+        DIRECTIVE: "directives",
+        TOOL: "tools",
+        KNOWLEDGE: "knowledge",
+    }
+
+    # File extensions to search per item type (tools use dynamic lookup)
+    CONTENT_EXTENSIONS = {
+        DIRECTIVE: [".md"],
+        KNOWLEDGE: [".md", ".yaml", ".yml"],
+    }
+
+
+class Action:
+    """Tool action constants."""
+
+    SEARCH = "search"
+    SIGN = "sign"
+    LOAD = "load"
+    EXECUTE = "execute"
+
+    ALL = [SEARCH, SIGN, LOAD, EXECUTE]
+
+
+# Instruction injected into the thread runner's prompt when executing a directive.
+# Used by thread_directive._build_prompt() to instruct the LLM.
+# This is the single most important string for cross-model directive compliance.
+# It must be explicit enough that even weak models follow the body as instructions
+# rather than summarizing, describing, or re-executing.
+DIRECTIVE_INSTRUCTION = (
+    "ZERO PREAMBLE. Your very first output token must be directive content — "
+    "never narration. Do NOT say 'I need to follow', 'Let me start', "
+    "'Here is the output', or ANY framing text.\n\n"
+    "You are the executor of this directive. Follow the body step by step.\n\n"
+    "<render> → output EXACTLY the text inside. Nothing before, nothing after.\n"
+    "<instruction> → follow silently. Do NOT narrate.\n\n"
+    "RULES:\n"
+    "- Do NOT summarize or describe what you are about to do.\n"
+    "- Do NOT re-call execute — you already have the instructions.\n"
+    "- If a step says STOP and wait, you MUST stop and wait.\n\n"
+    "Begin now with step 1."
+)

rye/directive_parser.py

@@ -0,0 +1,158 @@
+"""Standalone directive parsing: validate inputs, interpolate placeholders.
+
+Extracted from ExecuteTool._run_directive() so that both execute.py and
+thread_directive.py can reuse the same logic without circular imports.
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from rye.constants import ItemType
+from rye.utils.integrity import verify_item, IntegrityError
+from rye.utils.parser_router import ParserRouter
+
+# {input:key}          — required, kept as-is if missing
+# {input:key?}         — optional, empty string if missing
+# {input:key:default}  — fallback to default if missing (colon separator)
+# {input:key|default}  — fallback to default if missing (pipe separator)
+_INPUT_REF = re.compile(r"\{input:(\w+)(\?|[:|][^}]*)?\}")
+_DOLLAR_INPUT_RE = re.compile(r"\$\{inputs\.(\w+)\}")
+
+# {env:VAR}            — required, kept as-is if missing
+# {env:VAR:default}    — fallback to default if env var not set
+_ENV_REF = re.compile(r"\{env:(\w+)(?::([^}]*))?\}")
+
+def _resolve_env_refs(value: str) -> str:
+    """Resolve {env:VAR} and {env:VAR:default} placeholders from os.environ."""
+
+    def _replace(m: re.Match) -> str:
+        var = m.group(1)
+        default = m.group(2)
+        env_val = os.environ.get(var)
+        if env_val is not None:
+            return env_val
+        if default is not None:
+            return default
+        return m.group(0)
+
+    return _ENV_REF.sub(_replace, value)
+
+
+def _resolve_input_refs(value: str, inputs: Dict[str, Any]) -> str:
+    """Resolve {input:name} and ${inputs.name} placeholders in a string."""
+
+    def _replace(m: re.Match) -> str:
+        key = m.group(1)
+        modifier = m.group(2)
+        if key in inputs:
+            return str(inputs[key])
+        if modifier == "?":
+            return ""
+        if modifier and modifier[0] in (":", "|"):
+            return modifier[1:]
+        return m.group(0)
+
+    result = _INPUT_REF.sub(_replace, value)
+    # Also resolve ${inputs.name} syntax
+    if "${inputs." in result:
+        result = _DOLLAR_INPUT_RE.sub(
+            lambda m: str(inputs[m.group(1)]) if m.group(1) in inputs else m.group(0),
+            result,
+        )
+    return result
+
+
+def _interpolate_parsed(parsed: Dict[str, Any], inputs: Dict[str, Any]) -> None:
+    """Interpolate {input:name} and {env:VAR} refs in body, actions, and content fields."""
+    for key in ("body", "content", "raw"):
+        if isinstance(parsed.get(key), str):
+            parsed[key] = _resolve_env_refs(parsed[key])
+            parsed[key] = _resolve_input_refs(parsed[key], inputs)
+
+    for action in parsed.get("actions", []):
+        for k, v in list(action.items()):
+            if isinstance(v, str):
+                action[k] = _resolve_input_refs(v, inputs)
+        for pk, pv in list(action.get("params", {}).items()):
+            if isinstance(pv, str):
+                action["params"][pk] = _resolve_input_refs(pv, inputs)
+
+
+def parse_and_validate_directive(
+    *,
+    file_path: Path,
+    item_id: str,
+    parameters: Dict[str, Any],
+    project_path: Optional[Path] = None,
+) -> Dict[str, Any]:
+    """Parse a directive file, validate inputs, and interpolate placeholders.
+
+    Returns a dict with ``status`` set to ``"success"`` or ``"error"``.
+
+    On success the dict also contains:
+        parsed          – the parsed directive data (with placeholders resolved)
+        inputs          – the final validated input values (params + defaults)
+        declared_inputs – the raw input declarations from the directive
+
+    On error the dict contains an ``error`` message and, where applicable,
+    ``item_id`` and ``declared_inputs`` for caller diagnostics.
+    """
+    # 1. Integrity check
+    try:
+        verify_item(file_path, ItemType.DIRECTIVE, project_path=project_path)
+    except IntegrityError as exc:
+        return {"status": "error", "error": str(exc), "item_id": item_id}
+
+    # 2. Read and parse
+    content = file_path.read_text(encoding="utf-8")
+    parsed = ParserRouter().parse("markdown/xml", content)
+
+    if "error" in parsed:
+        return {"status": "error", "error": parsed.get("error"), "item_id": item_id}
+
+    # 3. Input validation
+    inputs = dict(parameters)
+    declared_inputs: List[Dict] = parsed.get("inputs", [])
+    declared_names = {inp["name"] for inp in declared_inputs}
+
+    # Reject unknown parameters early so the caller can correct
+    unknown = [k for k in parameters if k not in declared_names]
+    if unknown and declared_inputs:
+        return {
+            "status": "error",
+            "error": f"Unknown parameters: {', '.join(unknown)}. "
+                     f"Valid inputs: {', '.join(declared_names)}",
+            "item_id": item_id,
+            "declared_inputs": declared_inputs,
+        }
+
+    # Apply defaults
+    for inp in declared_inputs:
+        if inp["name"] not in inputs and "default" in inp:
+            inputs[inp["name"]] = inp["default"]
+
+    # Check required inputs
+    missing = [
+        inp["name"]
+        for inp in declared_inputs
+        if inp.get("required") and inp["name"] not in inputs
+    ]
+    if missing:
+        return {
+            "status": "error",
+            "error": f"Missing required inputs: {', '.join(missing)}",
+            "item_id": item_id,
+            "declared_inputs": declared_inputs,
+        }
+
+    # 4. Interpolate placeholders
+    _interpolate_parsed(parsed, inputs)
+
+    return {
+        "status": "success",
+        "parsed": parsed,
+        "inputs": inputs,
+        "declared_inputs": declared_inputs,
+    }

rye/executor/__init__.py

@@ -0,0 +1,19 @@
+"""RYE Executor - Data-driven tool execution with chain resolution.
+
+Components:
+    - PrimitiveExecutor: Main executor routing tools to Lillux primitives
+    - ChainValidator: Validates tool execution chains
+    - LockfileResolver: Resolves lockfile paths with 3-tier precedence
+"""
+
+from rye.executor.primitive_executor import PrimitiveExecutor, ExecutionResult
+from rye.executor.chain_validator import ChainValidator, ChainValidationResult
+from rye.executor.lockfile_resolver import LockfileResolver
+
+__all__ = [
+    "PrimitiveExecutor",
+    "ExecutionResult",
+    "ChainValidator",
+    "ChainValidationResult",
+    "LockfileResolver",
+]

rye/executor/chain_validator.py

@@ -0,0 +1,305 @@
+"""ChainValidator - Validates tool execution chains before execution.
+
+Ensures:
+    - Space compatibility (lower precedence cannot depend on higher)
+    - I/O compatibility (child outputs match parent inputs)
+    - No circular dependencies
+    - Version constraints satisfaction
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from packaging import version
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ChainValidationResult:
+    """Result of chain validation."""
+    
+    valid: bool = True
+    issues: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    validated_pairs: int = 0
+
+
+class ChainValidator:
+    """Validates tool execution chains for integrity and compatibility.
+    
+    Validation rules:
+        1. Space compatibility: Tools can only depend on equal or higher precedence spaces
+        2. I/O compatibility: Child outputs must satisfy parent inputs
+        3. Version constraints: Parent's child_constraints must be satisfied
+        4. No circular dependencies (handled during chain building)
+    """
+    
+    # Space precedence (higher number = higher precedence)
+    SPACE_PRECEDENCE = {
+        "project": 3,
+        "user": 2,
+        "system": 1,
+    }
+    
+    def validate_chain(self, chain: List[Dict[str, Any]]) -> ChainValidationResult:
+        """Validate entire execution chain.
+        
+        Chain order: [tool, runtime, ..., primitive]
+        Each pair (chain[i], chain[i+1]) is validated.
+        
+        Args:
+            chain: List of chain element dicts with keys:
+                - item_id: Tool identifier
+                - space: "project", "user", or "system"
+                - tool_type: Type of tool
+                - executor_id: Delegation target (None for primitives)
+                - inputs: Optional list of input types
+                - outputs: Optional list of output types
+                - version: Optional version string
+                - child_constraints: Optional version constraints for dependencies
+                
+        Returns:
+            ChainValidationResult with validation details
+        """
+        result = ChainValidationResult()
+        
+        if not chain:
+            return result
+        
+        if len(chain) == 1:
+            # Single element chain (primitive) - no pairs to validate
+            return result
+        
+        # Validate each (child, parent) pair
+        # In chain order: child → parent (child delegates to parent)
+        for i in range(len(chain) - 1):
+            child = chain[i]
+            parent = chain[i + 1]
+            
+            self._validate_pair(child, parent, result)
+            result.validated_pairs += 1
+        
+        # Check for space consistency
+        self._validate_space_consistency(chain, result)
+        
+        return result
+    
+    def _validate_pair(
+        self,
+        child: Dict[str, Any],
+        parent: Dict[str, Any],
+        result: ChainValidationResult,
+    ) -> None:
+        """Validate a (child, parent) pair in the chain.
+        
+        Child delegates to parent via executor_id.
+        """
+        # 1. Validate space compatibility
+        self._validate_space_compatibility(child, parent, result)
+        
+        # 2. Validate I/O compatibility
+        self._validate_io_compatibility(child, parent, result)
+        
+        # 3. Validate version constraints
+        self._validate_version_constraints(child, parent, result)
+    
+    def _validate_space_compatibility(
+        self,
+        child: Dict[str, Any],
+        parent: Dict[str, Any],
+        result: ChainValidationResult,
+    ) -> None:
+        """Validate that tools from different spaces are compatible.
+        
+        Rule: A tool can depend on tools from equal or higher precedence spaces only.
+        
+        Valid:
+            - project → user (project has higher precedence)
+            - project → system
+            - user → system
+            - same space → same space
+            
+        Invalid:
+            - user → project (user cannot depend on project-specific tools)
+            - system → project/user (system is immutable)
+        """
+        child_space = child.get("space", "")
+        parent_space = parent.get("space", "")
+        
+        child_precedence = self.SPACE_PRECEDENCE.get(child_space, 0)
+        parent_precedence = self.SPACE_PRECEDENCE.get(parent_space, 0)
+        
+        # Lower precedence depending on higher precedence: Invalid
+        if child_precedence < parent_precedence:
+            result.issues.append(
+                f"Tool '{child.get('item_id')}' from {child_space} space cannot "
+                f"depend on '{parent.get('item_id')}' from {parent_space} space. "
+                f"Lower precedence spaces cannot depend on higher precedence spaces."
+            )
+            result.valid = False
+    
+    def _validate_io_compatibility(
+        self,
+        child: Dict[str, Any],
+        parent: Dict[str, Any],
+        result: ChainValidationResult,
+    ) -> None:
+        """Validate that child outputs match parent inputs.
+        
+        If both declare I/O types, ensure compatibility.
+        Missing declarations are treated as compatible (warnings only).
+        """
+        child_outputs = set(child.get("outputs", []))
+        parent_inputs = set(parent.get("inputs", []))
+        
+        # Skip if either side doesn't declare types
+        if not child_outputs or not parent_inputs:
+            return
+        
+        # Check if parent's required inputs are satisfied
+        missing = parent_inputs - child_outputs
+        
+        if missing:
+            result.issues.append(
+                f"I/O mismatch: '{parent.get('item_id')}' requires inputs "
+                f"{list(missing)} not provided by '{child.get('item_id')}' "
+                f"(outputs: {list(child_outputs)})"
+            )
+            result.valid = False
+    
+    def _validate_version_constraints(
+        self,
+        child: Dict[str, Any],
+        parent: Dict[str, Any],
+        result: ChainValidationResult,
+    ) -> None:
+        """Validate version constraints between parent and child.
+        
+        Parent can specify child_constraints with min_version/max_version.
+        """
+        parent_constraints = parent.get("child_constraints", {})
+        child_id = child.get("item_id", "")
+        child_version = child.get("version")
+        
+        if not parent_constraints or child_id not in parent_constraints:
+            return
+        
+        if not child_version:
+            result.warnings.append(
+                f"'{child_id}' has no version but '{parent.get('item_id')}' "
+                f"specifies version constraints"
+            )
+            return
+        
+        constraints = parent_constraints[child_id]
+        min_version = constraints.get("min_version")
+        max_version = constraints.get("max_version")
+        
+        if min_version and not self._version_satisfies(child_version, ">=", min_version):
+            result.issues.append(
+                f"Version constraint failed: '{child_id}' version {child_version} "
+                f"< minimum required {min_version}"
+            )
+            result.valid = False
+        
+        if max_version and not self._version_satisfies(child_version, "<=", max_version):
+            result.issues.append(
+                f"Version constraint failed: '{child_id}' version {child_version} "
+                f"> maximum allowed {max_version}"
+            )
+            result.valid = False
+    
+    def _version_satisfies(self, version_str: str, op: str, constraint: str) -> bool:
+         """Check if version satisfies constraint using proper semver.
+         
+         Supports:
+         - Standard semver: 1.0.0, 2.1.3
+         - Pre-releases: 1.0.0-alpha, 1.0.0-beta.2
+         - Build metadata: 1.0.0+build.123
+         """
+         try:
+             v = version.parse(version_str)
+             c = version.parse(constraint)
+             
+             if op == ">=":
+                 return v >= c
+             elif op == "<=":
+                 return v <= c
+             elif op == "==":
+                 return v == c
+             elif op == ">":
+                 return v > c
+             elif op == "<":
+                 return v < c
+             elif op == "!=":
+                 return v != c
+             else:
+                 logger.warning(f"Unknown version operator: {op}")
+                 return True
+         except version.InvalidVersion:
+             logger.warning(f"Invalid version format: {version_str} or {constraint}")
+             return True  # Invalid versions pass (warning logged)
+    
+    def _validate_space_consistency(
+        self,
+        chain: List[Dict[str, Any]],
+        result: ChainValidationResult,
+    ) -> None:
+        """Validate overall space consistency in the chain.
+        
+        Additional checks beyond pair validation.
+        """
+        # Check if system tools are in the middle of a mutable chain
+        spaces = [e.get("space") for e in chain]
+        
+        # Find transitions from system back to mutable
+        for i in range(len(spaces) - 1):
+            if (spaces[i] or "").startswith("system") and spaces[i + 1] in ("project", "user"):
+                result.issues.append(
+                    f"Invalid chain: system tool '{chain[i].get('item_id')}' "
+                    f"cannot delegate to mutable {spaces[i + 1]} tool "
+                    f"'{chain[i + 1].get('item_id')}'"
+                )
+                result.valid = False
+    
+    def validate_tool(self, tool: Dict[str, Any]) -> ChainValidationResult:
+        """Validate a single tool's metadata.
+        
+        Lightweight validation without chain context.
+        
+        Args:
+            tool: Tool metadata dict
+            
+        Returns:
+            ChainValidationResult
+        """
+        result = ChainValidationResult()
+        
+        # Check required fields
+        if not tool.get("item_id"):
+            result.issues.append("Missing required field: item_id")
+            result.valid = False
+        
+        # Check space is valid
+        space = tool.get("space")
+        if space and space not in self.SPACE_PRECEDENCE:
+            result.issues.append(f"Invalid space: {space}")
+            result.valid = False
+        
+        # Check executor_id is valid if present
+        executor_id = tool.get("executor_id")
+        tool_type = tool.get("tool_type")
+        
+        if tool_type == "primitive" and executor_id is not None:
+            result.warnings.append(
+                f"Primitive '{tool.get('item_id')}' has executor_id set (should be None)"
+            )
+        
+        if tool_type == "runtime" and executor_id is None:
+            result.warnings.append(
+                f"Runtime '{tool.get('item_id')}' has no executor_id (should delegate)"
+            )
+        
+        return result