rsnarsna
feat(lab): implement Phase 2 project structure and inventory integrity test suite
e06cbf7
Raw History Blame Contribute Delete
7.94 kB
"""Pydantic schemas and contracts for ALLI Node Validation Lab.
Phase 2: Project Structure & Inventory Integrity.
Provides canonical contract definitions, status enums, and integrity report models.
"""
from enum import Enum
from typing import Any, Dict, List, Optional
from pydantic import BaseModel, Field, model_validator
class ValidationStatus(str, Enum):
"""Authoritative validation result status for nodes and capabilities."""
PASS = "PASS"
FAIL = "FAIL"
UNSUPPORTED = "UNSUPPORTED"
NOT_TESTED = "NOT_TESTED"
class RegistrationStatus(str, Enum):
"""Cross-tier registration parity status between frontend and backend."""
FULL_PARITY = "FULL_PARITY"
SCHEMA_MISMATCH = "SCHEMA_MISMATCH"
FRONTEND_ONLY = "FRONTEND_ONLY"
BACKEND_ONLY = "BACKEND_ONLY"
class DualTierField(BaseModel):
"""Captures dual-tier value comparison between frontend and backend."""
fe: Optional[str] = None
be: Optional[str] = None
match: bool = False
class PortDefinition(BaseModel):
"""Definition of an input or output port in the contract."""
id: str
name: Optional[str] = None
type: Optional[str] = None
required: Optional[bool] = None
default: Optional[Any] = None
default_value: Optional[Any] = None
kind: Optional[str] = None
description: Optional[str] = None
multiple: Optional[bool] = None
is_var_positional: Optional[bool] = None
is_var_keyword: Optional[bool] = None
keyword_key: Optional[str] = None
class NodePortsContract(BaseModel):
"""Port definitions and mismatch diagnostics for a node."""
inputs: Dict[str, List[PortDefinition]] = Field(default_factory=dict)
outputs: Dict[str, List[PortDefinition]] = Field(default_factory=dict)
input_mismatches: List[str] = Field(default_factory=list)
output_mismatches: List[str] = Field(default_factory=list)
class ParameterDefinition(BaseModel):
"""Parameter definition for static or configurable properties on a node."""
id: str
name: Optional[str] = None
type: Optional[str] = None
default: Optional[Any] = None
options: Optional[Any] = None
min: Optional[Any] = None
max: Optional[Any] = None
min_value: Optional[Any] = None
max_value: Optional[Any] = None
step: Optional[Any] = None
precision: Optional[Any] = None
regex: Optional[Any] = None
enum_values: Optional[Any] = None
is_identifier: Optional[bool] = None
widget: Optional[str] = None
required: Optional[bool] = None
description: Optional[str] = None
class NodeParametersContract(BaseModel):
"""Parameters contract and mismatch tracking across tiers."""
frontend: List[ParameterDefinition] = Field(default_factory=list)
backend: List[ParameterDefinition] = Field(default_factory=list)
mismatches: List[str] = Field(default_factory=list)
class NodeCapabilitiesContract(BaseModel):
"""Explicitly decoupled runtime and codegen capabilities across tiers."""
backend_execution: ValidationStatus = ValidationStatus.NOT_TESTED
backend_codegen: ValidationStatus = ValidationStatus.NOT_TESTED
frontend_execution: ValidationStatus = ValidationStatus.NOT_TESTED
frontend_codegen: ValidationStatus = ValidationStatus.NOT_TESTED
class NodeValidationContract(BaseModel):
"""Authoritative validation contract for a single canonical node in ALLI."""
type: str = Field(description="Canonical unique node type identifier, e.g. 'math.sqrt'")
canonical_node_type: Optional[str] = Field(
default=None, description="Explicit canonical type alias"
)
is_frontend_registered: bool = Field(
default=True, description="Whether node is registered in frontend schema"
)
is_backend_registered: bool = Field(
default=False, description="Whether node is registered in backend registry"
)
status: str = Field(
default="SCHEMA_MISMATCH",
description="Parity classification: FULL_PARITY, SCHEMA_MISMATCH, FRONTEND_ONLY, BACKEND_ONLY",
)
label: Optional[DualTierField] = None
category: Optional[DualTierField] = None
description: Optional[str] = None
icon: Optional[str] = None
aliases: List[str] = Field(default_factory=list)
ports: Optional[NodePortsContract] = None
parameters: Optional[NodeParametersContract] = None
capabilities: NodeCapabilitiesContract
validation_status: ValidationStatus = ValidationStatus.PASS
failure_reason: Optional[str] = None
unsupported_reason: Optional[str] = None
evidence: Dict[str, Any] = Field(
default_factory=dict, description="Diagnostics, port counts, and discrepancy evidence"
)
gap_notes: List[str] = Field(default_factory=list)
studio_palette_bindings: List[Dict[str, Any]] = Field(default_factory=list)
is_primitive_spec: bool = False
@model_validator(mode="before")
@classmethod
def populate_contract_metadata(cls, values: Any) -> Any:
"""Hydrate canonical metadata, tier registration flags, and evidence."""
if isinstance(values, dict):
# Ensure canonical_node_type is always synchronized with type
if not values.get("canonical_node_type"):
values["canonical_node_type"] = values.get("type")
status = values.get("status", "")
values["is_frontend_registered"] = status in (
"FULL_PARITY",
"SCHEMA_MISMATCH",
"FRONTEND_ONLY",
)
values["is_backend_registered"] = status in ("FULL_PARITY", "SCHEMA_MISMATCH")
caps = values.get("capabilities", {})
if isinstance(caps, dict):
be_exec = caps.get("backend_execution")
if be_exec == "UNSUPPORTED":
values.setdefault(
"unsupported_reason",
"Execution unsupported or air-gapped/guarded for this execution tier.",
)
elif be_exec == "FAIL":
values.setdefault(
"failure_reason", "Execution failed backend contract check."
)
# Collect diagnostics evidence
evidence = values.get("evidence") or {}
ports = values.get("ports") or {}
params = values.get("parameters") or {}
if isinstance(ports, dict):
evidence["input_mismatches_count"] = len(ports.get("input_mismatches", []))
evidence["output_mismatches_count"] = len(ports.get("output_mismatches", []))
if isinstance(params, dict):
evidence["parameter_mismatches_count"] = len(params.get("mismatches", []))
evidence["gap_notes_count"] = len(values.get("gap_notes", []))
values["evidence"] = evidence
return values
class InventorySummaryCounts(BaseModel):
"""Aggregate counts of node inventory and validation matrix."""
total_unique_node_types: int = 59
backend_registered_count: int = 47
frontend_canonical_count: int = 59
full_parity_nodes: int = 15
schema_mismatch_nodes: int = 32
frontend_only_nodes: int = 12
backend_only_nodes: int = 0
guarded_unsupported_nodes: int = 6
backend_exec_pass_count: int = 47
backend_codegen_pass_count: int = 58
frontend_exec_pass_count: int = 51
frontend_codegen_pass_count: int = 59
class InventoryIntegrityReport(BaseModel):
"""Comprehensive machine-readable report generated for Node Validation Lab."""
timestamp: str
phase: str = "Phase 2: Project Structure & Inventory Integrity"
description: str = (
"Authoritative node inventory integrity and verification report for ALLI Studio."
)
summary_counts: InventorySummaryCounts
integrity_checks: Dict[str, bool]
nodes: List[NodeValidationContract]
metadata: Dict[str, Any] = Field(default_factory=dict)