"""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)