rsnarsna
feat(alli-backend): Wave-1 standardization, standalone sys.env node & vault crypto, and DEC-014 security hardening
8628c98 Download language_core/node_definition.py from Rsnarsna/auto: direct link, hf CLI and curl.
- Browser
- Download file 13.3 kB
-
https://huggingface.co/spaces/Rsnarsna/auto/resolve/main/language_core/node_definition.py
- Command line
-
hf download hf://spaces/Rsnarsna/auto/language_core/node_definition.py
-
curl -L -o node_definition.py https://huggingface.co/spaces/Rsnarsna/auto/resolve/main/language_core/node_definition.py
13.3 kB
| """ | |
| ALLI Standard Node Definition & Metadata Contracts (Node Standard v1). | |
| Defines NodeDefinition along with documentation, verification, execution, and codegen metadata. | |
| """ | |
| import re | |
| from typing import Any, Dict, List, Optional | |
| from pydantic import BaseModel, Field, field_validator, model_validator | |
| from language_core.schema_types import ParameterDefinition, PortDefinition | |
| class PossibleException(BaseModel): | |
| """Step 2.6: Documented runtime exception with triggering conditions and severity.""" | |
| type: str = Field(..., description="Exception class name (e.g. 'ValueError', 'ZeroDivisionError')") | |
| condition: str = Field(..., description="Trigger condition explanation") | |
| severity: str = Field(default="error", description="Severity ('error' or 'warning')") | |
| def validate_exception_name(cls, v: str) -> str: | |
| if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", v): | |
| raise ValueError(f"Exception type '{v}' must be a valid Python identifier.") | |
| return v | |
| class DocumentationExample(BaseModel): | |
| """Example usage for documentation and deterministic verification.""" | |
| title: str = Field(..., description="Summary title of the test case") | |
| inputs: Dict[str, Any] = Field(default_factory=dict, description="Sample input socket values") | |
| parameters: Dict[str, Any] = Field(default_factory=dict, description="Sample parameter configurations") | |
| expected_output: Dict[str, Any] = Field(default_factory=dict, description="Expected output socket values") | |
| code_snippet: str = Field(default="", description="Generated Python syntax snippet") | |
| class DocumentationMetadata(BaseModel): | |
| """Step 2.6: Comprehensive documentation contract for node introspection and education.""" | |
| summary: str = Field(..., description="Concise explanation of the node's function") | |
| description: Optional[str] = Field(default=None, description="Detailed behavioral specification") | |
| doc_url: Optional[str] = Field(default=None, description="Official documentation URL") | |
| examples: List[DocumentationExample] = Field(default_factory=list, description="Working test examples") | |
| complexity: str = Field(default="O(1)", description="Algorithmic runtime time complexity string (Big-O)") | |
| time_complexity: Optional[str] = Field(default=None, description="Detailed time complexity in Big-O notation") | |
| space_complexity: Optional[str] = Field(default="O(1)", description="Space complexity in Big-O notation") | |
| complexity_assumptions: Optional[str] = Field(default=None, description="Assumptions for complexity analysis") | |
| exceptions: List[str] = Field(default_factory=list, description="Possible runtime exception names") | |
| possible_exceptions: List[PossibleException] = Field(default_factory=list, description="Structured exceptions") | |
| since_version: str = Field(default="1.0.0", description="Schema specification version") | |
| def validate_docs(self) -> "DocumentationMetadata": | |
| if not self.time_complexity: | |
| self.time_complexity = self.complexity | |
| if self.possible_exceptions and not self.exceptions: | |
| self.exceptions = [e.type for e in self.possible_exceptions] | |
| elif self.exceptions and not self.possible_exceptions: | |
| self.possible_exceptions = [ | |
| PossibleException(type=t, condition=f"Raised when operation encounters invalid state ({t})") | |
| for t in self.exceptions | |
| ] | |
| if self.doc_url is not None and self.doc_url.strip(): | |
| url = self.doc_url.strip() | |
| if not (url.startswith("http://") or url.startswith("https://")): | |
| raise ValueError(f"Documentation doc_url '{self.doc_url}' must start with 'http://' or 'https://'.") | |
| comp = self.complexity.strip() | |
| if comp not in ("N/A", "unknown", "O(1)") and not re.match(r"^O\([a-zA-Z0-9_*^ /+-]+\)$", comp): | |
| raise ValueError(f"Complexity '{self.complexity}' must follow standard Big-O notation (e.g. 'O(1)', 'O(n)').") | |
| return self | |
| class VerificationMetadata(BaseModel): | |
| """Step 2.6: Declarative verification metadata for deterministic node validation and testing.""" | |
| node_kind: str = Field(default="value_producer", description="'value_producer', 'effect_only', or 'control_flow'") | |
| is_deterministic: bool = Field(default=True, description="Whether node execution is deterministic") | |
| side_effects: List[str] = Field(default_factory=list, description="List of side effects (e.g. ['stdout'])") | |
| minimal_config: Dict[str, Any] = Field(default_factory=dict, description="Valid minimal parameter configuration") | |
| test_inputs: Dict[str, Any] = Field(default_factory=dict, description="Representative test input socket values") | |
| expected_outputs: Dict[str, Any] = Field(default_factory=dict, description="Expected output socket values") | |
| expected_errors: Optional[Dict[str, Any]] = Field(default=None, description="Expected error mappings") | |
| capability_states: Dict[str, bool] = Field( | |
| default_factory=lambda: { | |
| "extracted": True, | |
| "node_generated": True, | |
| "runtime_supported": True, | |
| "codegen_supported": True, | |
| }, | |
| description="Explicit 4-part capability state", | |
| ) | |
| def validate_kind(cls, v: str) -> str: | |
| if v not in ("value_producer", "effect_only", "control_flow"): | |
| raise ValueError(f"node_kind '{v}' must be 'value_producer', 'effect_only', or 'control_flow'.") | |
| return v | |
| class ExecutionHandlerDefinition(BaseModel): | |
| """Step 2.5: Execution metadata defining runtime dispatch and code generator.""" | |
| handler_type: str = Field(default="builtin", description="Execution strategy ('builtin', 'pure_python', 'sandbox')") | |
| callable_path: Optional[str] = Field(default=None, description="Importable python callable path") | |
| code_template: Optional[str] = Field(default=None, description="AST code formatting template") | |
| class NodeSettingsDefinition(BaseModel): | |
| """Execution and runtime settings for node execution.""" | |
| timeout_seconds: Optional[float] = Field(default=None, description="Maximum execution duration in seconds") | |
| retry_count: int = Field(default=0, ge=0, description="Number of execution retries upon error") | |
| fallback_on_error: Optional[Any] = Field(default=None, description="Fallback output value if node fails") | |
| cache_policy: str = Field(default="session", description="Caching policy: 'always', 'never', 'session'") | |
| continue_on_error: bool = Field(default=False, description="Whether to continue despite error") | |
| execute_once: bool = Field(default=False, description="Whether to execute node only once per workflow") | |
| class NodeValidationDefinition(BaseModel): | |
| """Declarative validation rules for node parameters and connections.""" | |
| required_parameters: List[str] = Field(default_factory=list, description="IDs of mandatory parameters") | |
| min_inputs: int = Field(default=0, ge=0, description="Minimum number of connected input sockets") | |
| max_inputs: Optional[int] = Field(default=None, description="Maximum number of connected input sockets") | |
| custom_rules: List[str] = Field(default_factory=list, description="Declarative custom rule codes") | |
| class NodeCodegenDefinition(BaseModel): | |
| """AST code generation metadata for pure Python synthesis.""" | |
| template: Optional[str] = Field(default=None, description="AST code formatting template") | |
| imports: List[str] = Field(default_factory=list, description="Required Python module imports") | |
| requirements: List[str] = Field(default_factory=list, description="External PyPI pip requirements") | |
| variable_prefix: Optional[str] = Field(default=None, description="Custom prefix for output variable") | |
| class NodeDefinition(BaseModel): | |
| """Standard Node Schema Definition -- Single Source of Truth across ALLI (Node Standard v1).""" | |
| id: Optional[str] = Field(default=None, description="Unique node type identifier") | |
| type: str = Field(..., description="Globally unique namespaced type identifier (e.g. 'math.sqrt')") | |
| label: str = Field(..., description="Human-readable node display label") | |
| category: str = Field(..., description="Primary category group") | |
| version: str = Field(default="1.0.0", description="Semver specification version") | |
| description: str = Field(..., description="Clear explanation of what the node computes") | |
| icon: str = Field(default="Activity", description="Lucide icon identifier name") | |
| inputs: List[PortDefinition] = Field(default_factory=list, description="Input data sockets") | |
| parameters: List[ParameterDefinition] = Field(default_factory=list, description="Internal parameters") | |
| outputs: List[PortDefinition] = Field(default_factory=list, description="Output data sockets") | |
| settings: Optional[NodeSettingsDefinition] = Field(default=None, description="Execution and retry settings") | |
| validation: Optional[NodeValidationDefinition] = Field(default=None, description="Declarative validation rules") | |
| execution: Optional[ExecutionHandlerDefinition] = Field(default=None, description="Execution metadata") | |
| codegen: Optional[NodeCodegenDefinition] = Field(default=None, description="AST code generation metadata") | |
| dependencies: List[str] = Field(default_factory=list, description="Required PyPI packages") | |
| docs: Optional[DocumentationMetadata] = Field(default=None, description="Documentation metadata") | |
| verification: Optional[VerificationMetadata] = Field(default=None, description="Verification metadata") | |
| capability_states: Optional[Dict[str, bool]] = Field(default=None, description="4-part capability state") | |
| allow_var_positional: bool = Field(default=False, description="Whether node accepts *args") | |
| allow_var_keyword: bool = Field(default=False, description="Whether node accepts **kwargs") | |
| var_positional_name: str = Field(default="args", description="Identifier name for *args parameter") | |
| var_keyword_name: str = Field(default="kwargs", description="Identifier name for **kwargs parameter") | |
| def add_var_positional_port( | |
| self, port_id: Optional[str] = None, name: Optional[str] = None, type_hint: str = "any" | |
| ) -> PortDefinition: | |
| """Dynamically appends a positional argument socket (*args).""" | |
| if not self.allow_var_positional: | |
| raise ValueError(f"Node '{self.type}' does not accept variable positional arguments (*args).") | |
| idx = sum(1 for p in self.inputs if p.is_var_positional) | |
| port = PortDefinition( | |
| id=port_id or f"arg_{idx}", | |
| name=name or f"arg[{idx}]", | |
| type=type_hint, | |
| required=False, | |
| is_var_positional=True, | |
| description=f"Dynamic positional argument {idx} (*{self.var_positional_name})", | |
| ) | |
| self.inputs.append(port) | |
| return port | |
| def add_var_keyword_port( | |
| self, keyword_key: str, port_id: Optional[str] = None, name: Optional[str] = None, type_hint: str = "any" | |
| ) -> PortDefinition: | |
| """Dynamically appends a keyword argument socket (**kwargs).""" | |
| if not self.allow_var_keyword: | |
| raise ValueError(f"Node '{self.type}' does not accept variable keyword arguments (**kwargs).") | |
| clean_key = re.sub(r"[^a-zA-Z0-9_]", "_", keyword_key).strip("_") or "kw" | |
| port = PortDefinition( | |
| id=port_id or f"kw_{clean_key}", | |
| name=name or clean_key, | |
| type=type_hint, | |
| required=False, | |
| is_var_keyword=True, | |
| keyword_key=clean_key, | |
| description=f"Dynamic keyword argument {clean_key}=value (**{self.var_keyword_name})", | |
| ) | |
| self.inputs.append(port) | |
| return port | |
| def remove_dynamic_port(self, port_id: str) -> bool: | |
| """Removes a dynamic argument socket by identifier.""" | |
| initial_len = len(self.inputs) | |
| self.inputs = [ | |
| p for p in self.inputs | |
| if p.id != port_id or (not p.is_var_positional and not p.is_var_keyword) | |
| ] | |
| return len(self.inputs) < initial_len | |
| def validate_node_integrity(self) -> "NodeDefinition": | |
| if not self.id: | |
| self.id = self.type | |
| elif self.id != self.type: | |
| raise ValueError(f"Node id '{self.id}' must match node type '{self.type}'.") | |
| if not re.match(r"^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)+$", self.type): | |
| raise ValueError( | |
| f"Node type '{self.type}' must be namespaced with at least one dot (e.g. 'math.sqrt', 'core.variable')." | |
| ) | |
| in_ids = [p.id for p in self.inputs] | |
| if len(in_ids) != len(set(in_ids)): | |
| raise ValueError(f"Duplicate input port IDs detected in node '{self.type}': {in_ids}") | |
| param_ids = [p.id for p in self.parameters] | |
| if len(param_ids) != len(set(param_ids)): | |
| raise ValueError(f"Duplicate parameter IDs detected in node '{self.type}': {param_ids}") | |
| out_ids = [p.id for p in self.outputs] | |
| if len(out_ids) != len(set(out_ids)): | |
| raise ValueError(f"Duplicate output port IDs detected in node '{self.type}': {out_ids}") | |
| return self | |