planar 0.5.0__py3-none-any.whl

planar/rules/models.py

@@ -0,0 +1,355 @@
+from __future__ import annotations
+
+import json
+from typing import Annotated, Literal, Type
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from planar.modeling.field_helpers import JsonSchema
+from planar.object_config.object_config import (
+    ObjectConfigurationBase,
+)
+
+
+class Position(BaseModel):
+    """Represents the x,y coordinates of a node in the graph"""
+
+    x: int
+    y: int
+
+
+class InputOutputNodeContent(BaseModel):
+    """Content structure for input or output nodes containing JSON schema"""
+
+    schema_: str = Field(
+        alias="schema"
+    )  # JSON string representation of the input schema
+
+
+class RuleTableInput(BaseModel):
+    """Represents an input column in a decision table"""
+
+    id: str
+    field: str  # The field name from the input schema
+    name: str
+
+
+class RuleTableOutput(BaseModel):
+    """Represents an output column in a decision table"""
+
+    id: str
+    field: str  # The field name from the output schema
+    name: str
+
+
+class DecisionRule(BaseModel):
+    """Represents a single rule row in a decision table with dynamic values"""
+
+    rule_id: str = Field(
+        alias="_id"
+    )  # Using alias to maintain compatibility with _id field
+    # Note: Additional dynamic keys will be present based on input/output column IDs
+    # These are handled using model_extra="allow" configuration
+
+    model_config = {"extra": "allow", "populate_by_name": True}
+
+
+class DecisionTableNodeContent(BaseModel):
+    """Content structure for decision table nodes"""
+
+    hitPolicy: Literal["first"]  # Policy for rule evaluation
+    rules: list[DecisionRule]  # List of rule rows
+    inputs: list[RuleTableInput]  # Input column definitions
+    outputs: list[RuleTableOutput]  # Output column definitions
+
+    passThrough: bool | None = None  # Whether to pass through input data
+    passThorough: bool | None = (
+        None  # Note: typo preserved from original implementation, see https://github.com/gorules/jdm-editor/issues/186
+    )
+
+    inputField: str | None = None  # Field mapping for input (currently unused)
+    outputPath: str | None = None  # Path mapping for output (currently unused)
+    executionMode: Literal["single", "loop"] | None  # Execution mode for the table
+
+
+class InputNode(BaseModel):
+    """Represents an input node in the JDM graph"""
+
+    id: str
+    type: Literal["inputNode"]
+    name: str
+    content: InputOutputNodeContent
+    position: Position
+
+
+class DecisionTableNode(BaseModel):
+    """Represents a decision table node in the JDM graph"""
+
+    id: str
+    type: Literal["decisionTableNode"]
+    name: str
+    content: DecisionTableNodeContent
+    position: Position
+
+
+class OutputNode(BaseModel):
+    """Represents an output node in the JDM graph"""
+
+    id: str
+    type: Literal["outputNode"]
+    name: str
+    content: InputOutputNodeContent
+    position: Position
+
+
+class FunctionNodeContent(BaseModel):
+    """Content structure for a function node containing JavaScript source code."""
+
+    source: str
+
+
+class FunctionNode(BaseModel):
+    """Represents a JavaScript function node in the JDM graph."""
+
+    id: str
+    type: Literal["functionNode"]
+    name: str
+    content: FunctionNodeContent
+    position: Position
+
+
+# class LegacyFunctionNode(BaseModel):
+#     """Represents a legacy JavaScript function node in the JDM graph.
+#     The GoRules examples (such as https://editor.gorules.io/?template=shipping-fees use a legacy fn node)
+#     """
+
+#     id: str
+#     type: Literal["functionNode"]
+#     name: str
+#     content: str
+#     position: Position
+
+
+class SwitchStatement(BaseModel):
+    """Represents a statement in a switch node."""
+
+    id: str
+    condition: str
+
+
+class SwitchNodeContent(BaseModel):
+    """Content structure for a switch node."""
+
+    hitPolicy: Literal["collect", "first"]
+    statements: list[SwitchStatement]
+
+
+class SwitchNode(BaseModel):
+    """Represents a switch node in the JDM graph."""
+
+    id: str
+    type: Literal["switchNode"]
+    name: str
+    content: SwitchNodeContent
+    position: Position
+
+
+class Expression(BaseModel):
+    """Represents a single expression in an expression node."""
+
+    id: str
+    key: str
+    value: str
+
+
+class ExpressionNodeContent(BaseModel):
+    """Content structure for an expression node."""
+
+    expressions: list[Expression]
+    passThrough: bool | None = None  # Whether to pass through input data
+    inputField: str | None = None  # Field mapping for input (currently unused)
+    outputPath: str | None = None  # Path mapping for output (currently unused)
+    executionMode: Literal["single", "loop"] | None = (
+        None  # Execution mode for the node
+    )
+
+
+class ExpressionNode(BaseModel):
+    """Represents an expression node in the JDM graph."""
+
+    id: str
+    type: Literal["expressionNode"]
+    name: str
+    content: ExpressionNodeContent
+    position: Position
+
+
+JDMNode = (
+    InputNode
+    | DecisionTableNode
+    | OutputNode
+    | FunctionNode
+    # | LegacyFunctionNode
+    | SwitchNode
+    | ExpressionNode
+)
+
+JDMNodeWithType = Annotated[JDMNode, Field(discriminator="type")]
+
+
+class JDMEdge(BaseModel):
+    """Represents an edge connecting nodes in the JDM graph"""
+
+    id: str
+    type: Literal["edge"]
+    sourceId: str  # ID of the source node
+    targetId: str  # ID of the target node
+
+
+class JDMGraph(BaseModel):
+    """
+    Complete JDM (JSON Decision Model) graph structure.
+    This represents a GoRules decision flow with input, processing, and output nodes.
+    """
+
+    nodes: list[JDMNodeWithType]  # All nodes in the graph
+    edges: list[JDMEdge]  # All edges connecting the nodes
+
+
+def create_jdm_graph(rule: Rule) -> JDMGraph:
+    """
+    Create a JDM (JSON Decision Model) graph based on input and output JSON schemas.
+
+    Args:
+        rule: A Rule object containing input and output Pydantic models
+
+    Returns:
+        A dictionary representing the JDM graph with nodes and edges
+    """
+    # Get JSON schemas from the Pydantic models
+    input_json_schema = rule.input.model_json_schema()
+    output_json_schema = rule.output.model_json_schema()
+
+    # Generate UUIDs for nodes and edges
+    input_node_id = str(uuid4())
+    output_node_id = str(uuid4())
+    rule_table_node_id = str(uuid4())
+    input_to_table_edge_id = str(uuid4())
+    table_to_output_edge_id = str(uuid4())
+
+    # Create output columns for rule table based on output schema properties
+    output_columns = []
+    output_properties = output_json_schema.get("properties", {})
+
+    for field_name, field_info in output_properties.items():
+        column = {
+            "id": str(uuid4()),
+            "field": field_name,
+            "name": field_name,
+        }
+        output_columns.append(column)
+
+    # Create a rule with default values for each output field
+    rule_values = {}
+    input_column_id = str(uuid4())
+    rule_values[input_column_id] = ""
+
+    # Add values for each output column based on field type
+    for column in output_columns:
+        field_name = column["field"]
+        field_type = output_properties.get(field_name, {}).get("type")
+
+        if field_type == "string":
+            rule_values[column["id"]] = '"default value"'
+        elif field_type == "boolean":
+            rule_values[column["id"]] = "true"
+        elif field_type == "number":
+            rule_values[column["id"]] = "0"
+        elif field_type == "integer":
+            rule_values[column["id"]] = "0"
+        else:
+            rule_values[column["id"]] = '""'
+
+    # Create the JDM graph structure using Pydantic models
+    return JDMGraph(
+        nodes=[
+            InputNode(
+                id=input_node_id,
+                type="inputNode",
+                name="Input",
+                content=InputOutputNodeContent(schema=json.dumps(input_json_schema)),
+                position=Position(x=100, y=100),
+            ),
+            DecisionTableNode(
+                id=rule_table_node_id,
+                type="decisionTableNode",
+                name="decisionTable1",
+                content=DecisionTableNodeContent(
+                    hitPolicy="first",
+                    rules=[DecisionRule(_id=str(uuid4()), **rule_values)],
+                    inputs=[
+                        RuleTableInput(
+                            id=input_column_id,
+                            name="Input",
+                            field=next(
+                                iter(input_json_schema.get("properties", {})), ""
+                            ),
+                        )
+                    ],
+                    outputs=[RuleTableOutput(**col) for col in output_columns],
+                    passThrough=True,
+                    inputField=None,
+                    outputPath=None,
+                    executionMode="single",
+                    passThorough=False,  # Note: keeping the typo from original JS code
+                ),
+                position=Position(x=400, y=100),
+            ),
+            OutputNode(
+                id=output_node_id,
+                type="outputNode",
+                name="Output",
+                content=InputOutputNodeContent(schema=json.dumps(output_json_schema)),
+                position=Position(x=700, y=100),
+            ),
+        ],
+        edges=[
+            JDMEdge(
+                id=input_to_table_edge_id,
+                type="edge",
+                sourceId=input_node_id,
+                targetId=rule_table_node_id,
+            ),
+            JDMEdge(
+                id=table_to_output_edge_id,
+                type="edge",
+                sourceId=rule_table_node_id,
+                targetId=output_node_id,
+            ),
+        ],
+    )
+
+
+class RuleBase(BaseModel):
+    name: str
+    description: str
+
+
+class Rule(RuleBase):
+    input: Type[BaseModel]
+    output: Type[BaseModel]
+
+    def to_config(self) -> RuleEngineConfig:
+        jdm_graph = create_jdm_graph(self)
+        return RuleEngineConfig(jdm=jdm_graph)
+
+
+class RuleEngineConfig(BaseModel):
+    jdm: JDMGraph = Field()
+
+
+class RuleSerializeable(RuleBase):
+    input_schema: JsonSchema
+    output_schema: JsonSchema
+    configs: list[ObjectConfigurationBase[RuleEngineConfig]]

planar/rules/rule_configuration.py

@@ -0,0 +1,191 @@
+import json
+from typing import Any
+
+from planar.object_config import ConfigurableObjectType, ObjectConfigurationIO
+from planar.object_config.models import (
+    ConfigDiagnosticIssue,
+    ConfigDiagnostics,
+    DiffErrorCode,
+)
+from planar.object_registry import ObjectRegistry
+from planar.rules.models import JDMGraph, JDMNode, RuleEngineConfig, create_jdm_graph
+
+
+def node_diff(
+    reference: JDMNode | dict,
+    current: JDMNode | dict,
+    for_object: str,
+    path: str = "",
+) -> list[ConfigDiagnosticIssue]:
+    """
+    Recursively compare two dictionaries and return a list of diagnostics.
+
+    Args:
+        reference: The reference dictionary to compare against
+        current: The current dictionary being validated
+        path: The current field path (used for nested objects)
+
+    Returns:
+        List of DiffDiagnostic objects describing the differences found
+    """
+    diagnostics = []
+
+    reference_dict = (
+        reference.model_dump() if isinstance(reference, JDMNode) else reference
+    )
+    current_dict = current.model_dump() if isinstance(current, JDMNode) else current
+
+    # First pass: Check reference against current
+    for key, ref_value in reference_dict.items():
+        current_path = f"{path}.{key}" if path else key
+
+        if key not in current_dict:
+            # Missing field in current
+            diagnostics.append(
+                ConfigDiagnosticIssue.model_validate(
+                    {
+                        "error_code": DiffErrorCode.MISSING_FIELD,
+                        "field_path": current_path,
+                        "message": f"Field '{current_path}' is missing in current node",
+                        "reference_value": ref_value,
+                        "current_value": None,
+                        "for_object": for_object,
+                    }
+                )
+            )
+        else:
+            current_value = current_dict[key]
+
+            # Both are dictionaries - recurse
+            if (isinstance(ref_value, dict) and isinstance(current_value, dict)) or (
+                isinstance(ref_value, JDMNode) and isinstance(current_value, JDMNode)
+            ):
+                nested_diagnostics = node_diff(
+                    ref_value,
+                    current_value,
+                    for_object,
+                    current_path,
+                )
+                diagnostics.extend(nested_diagnostics)
+
+            # Values are different (and not both dicts)
+            elif ref_value != current_value:
+                diagnostics.append(
+                    ConfigDiagnosticIssue.model_validate(
+                        {
+                            "error_code": DiffErrorCode.VALUE_MISMATCH,
+                            "field_path": current_path,
+                            "message": f"Value mismatch at '{current_path}': expected {ref_value}, got {current_value}",
+                            "reference_value": ref_value,
+                            "current_value": current_value,
+                            "for_object": for_object,
+                        }
+                    )
+                )
+
+    # Second pass: Check current for extra fields not in reference
+    for key, current_value in current_dict.items():
+        current_path = f"{path}.{key}" if path else key
+
+        if key not in reference_dict:
+            diagnostics.append(
+                ConfigDiagnosticIssue.model_validate(
+                    {
+                        "error_code": DiffErrorCode.EXTRA_FIELD,
+                        "field_path": current_path,
+                        "message": f"Extra field '{current_path}' found in current node",
+                        "reference_value": None,
+                        "current_value": current_value,
+                        "for_object": for_object,
+                    }
+                )
+            )
+
+    return diagnostics
+
+
+def get_input_and_output_node_schemas(
+    jdm: JDMGraph,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    nodes = jdm.nodes
+
+    input_node = next((node for node in nodes if node.type == "inputNode"), None)
+    output_node = next((node for node in nodes if node.type == "outputNode"), None)
+
+    # if a jdm graph was uploaded from a 3rd party site such as https://editor.gorules.io/?template=shipping-fees
+    # then the schema will just be "", and json.loads will raise an error trying to parse an empty string
+    input_schema = (
+        json.loads(input_node.content.schema_)
+        if input_node and input_node.content.schema_
+        else {}
+    )
+    output_schema = (
+        json.loads(output_node.content.schema_)
+        if output_node and output_node.content.schema_
+        else {}
+    )
+
+    return input_schema, output_schema
+
+
+def validate_config(
+    name: str,
+    config: RuleEngineConfig,
+) -> ConfigDiagnostics:
+    """
+    Validate a configuration against a default configuration using JDM nodes comparison.
+
+    Args:
+        config: The configuration to validate
+        default: The default/reference configuration
+
+    Returns:
+        True if configuration is valid, False otherwise
+    """
+
+    rules = ObjectRegistry.get_instance().get_rules()
+    rule = next((rule for rule in rules if rule.name == name), None)
+
+    if rule is None:
+        raise ValueError(f"Rule with name {name} not found")
+
+    rule_input_schema = rule.input.model_json_schema()
+    rule_output_schema = rule.output.model_json_schema()
+
+    config_input_node_schema, config_output_node_schema = (
+        get_input_and_output_node_schemas(config.jdm)
+    )
+
+    input_node_diagnostics = node_diff(
+        rule_input_schema.get("properties", {}),
+        config_input_node_schema.get("properties", {}),
+        "inputNode",
+    )
+    output_node_diagnostics = node_diff(
+        rule_output_schema.get("properties", {}),
+        config_output_node_schema.get("properties", {}),
+        "outputNode",
+    )
+
+    if len(input_node_diagnostics) > 0 or len(output_node_diagnostics) > 0:
+        return ConfigDiagnostics.model_validate(
+            {
+                "is_valid": False,
+                "suggested_fix": RuleEngineConfig(jdm=create_jdm_graph(rule)),
+                "issues": input_node_diagnostics + output_node_diagnostics,
+            }
+        )
+
+    return ConfigDiagnostics.model_validate(
+        {
+            "is_valid": True,
+            "issues": [],
+        }
+    )
+
+
+rule_configuration = ObjectConfigurationIO(
+    RuleEngineConfig,
+    ConfigurableObjectType.RULE,
+    validate_config=validate_config,
+)

planar/rules/runner.py

@@ -0,0 +1,64 @@
+import json
+from typing import Any, Literal, TypeVar, cast
+
+from pydantic import BaseModel
+from zen import ZenDecisionContent, ZenEngine
+
+from planar.logging import get_logger
+from planar.rules.models import JDMGraph
+
+T = TypeVar("T", bound=BaseModel)
+
+logger = get_logger(__name__)
+
+
+class EvaluateResponse(BaseModel):
+    success: Literal[True]
+    performance: str
+    result: dict
+    trace: dict | None
+
+
+class EvaluateError(BaseModel):
+    success: Literal[False]
+    title: str
+    message: dict
+    data: dict
+
+
+def evaluate_rule(
+    jdm: JDMGraph, input: dict[str, Any]
+) -> EvaluateResponse | EvaluateError:
+    logger.debug(
+        "evaluating rule",
+        input_keys=list(input.keys()),
+        node_count=len(jdm.nodes),
+    )
+    engine = ZenEngine()
+    zen_decision = engine.create_decision(cast(ZenDecisionContent, jdm.model_dump()))
+    try:
+        result = zen_decision.evaluate(input, {"trace": True})
+        logger.info("rule evaluation successful")
+        return EvaluateResponse.model_validate(
+            {
+                "success": True,
+                "performance": result["performance"],
+                "result": result["result"],
+                "trace": result.get("trace", None),
+            }
+        )
+    except RuntimeError as e:
+        logger.exception("rule evaluation failed")
+        error_data = json.loads(str(e))
+        message = json.loads(error_data["source"])
+
+        return EvaluateError.model_validate(
+            {
+                "success": False,
+                "title": error_data["type"],
+                "message": message,
+                "data": {
+                    "nodeId": error_data["nodeId"],
+                },
+            }
+        )