structured2graph 0.1.1__py3-none-any.whl

core/hygm/models/llm_models.py

@@ -0,0 +1,229 @@
+"""
+LLM-specific models for Hypothetical Graph Modeling (HyGM).
+
+These models define the structure for LLM input/output and interactive
+operations.
+"""
+
+from enum import Enum
+from typing import List, Literal, TYPE_CHECKING
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from .graph_models import GraphModel
+
+
+class GraphModelingStrategy(Enum):
+    """Graph modeling strategies available."""
+
+    DETERMINISTIC = "deterministic"  # Rule-based graph creation
+    LLM_POWERED = "llm_powered"  # LLM generates the graph model
+
+
+class ModelingMode(Enum):
+    """Modeling modes available."""
+
+    AUTOMATIC = "automatic"  # Generate model without user interaction
+    INTERACTIVE = "interactive"  # Interactive mode with user feedback
+
+
+# Structured output models for LLM graph generation
+class LLMGraphNode(BaseModel):
+    """Node definition for LLM-generated graph models."""
+
+    name: str = Field(description="Unique identifier for the node")
+    labels: List[str] = Field(
+        description="Cypher labels for the node (e.g., ['User'], ['Product'])"
+    )
+    properties: List[str] = Field(
+        description="List of properties to include from source table"
+    )
+    primary_key: str = Field(description="Primary key property name")
+    indexes: List[str] = Field(description="Properties that should have indexes")
+    constraints: List[str] = Field(
+        description="Properties that should have uniqueness constraints"
+    )
+    source_table: str = Field(description="Source SQL table name")
+
+    class Config:
+        """Pydantic config for OpenAI structured output compatibility."""
+
+        extra = "forbid"
+
+
+class LLMGraphRelationship(BaseModel):
+    """Relationship definition for LLM-generated graph models."""
+
+    name: str = Field(description="Relationship type name (e.g., 'OWNS', 'BELONGS_TO')")
+    type: Literal["one_to_many", "many_to_many", "one_to_one"] = Field(
+        description="Cardinality of the relationship"
+    )
+    from_node: str = Field(description="Source node name")
+    to_node: str = Field(description="Target node name")
+    properties: List[str] = Field(
+        description="Properties to include on the relationship (if any)", default=[]
+    )
+    directionality: Literal["directed", "undirected"] = Field(
+        description="Whether the relationship has direction"
+    )
+
+    class Config:
+        """Pydantic config for OpenAI structured output compatibility."""
+
+        extra = "forbid"
+
+
+class LLMGraphModel(BaseModel):
+    """Complete graph model structure for LLM generation."""
+
+    nodes: List[LLMGraphNode] = Field(description="All nodes in the graph model")
+    relationships: List[LLMGraphRelationship] = Field(
+        description="All relationships in the graph model"
+    )
+
+    class Config:
+        """Pydantic config for OpenAI structured output compatibility."""
+
+        extra = "forbid"
+
+    def to_graph_model(self) -> "GraphModel":
+        """Convert LLMGraphModel to GraphModel for schema export."""
+        from .graph_models import (
+            GraphModel,
+            GraphNode,
+            GraphRelationship,
+            GraphProperty,
+            GraphIndex,
+            GraphConstraint,
+        )
+        from .sources import (
+            NodeSource,
+            RelationshipSource,
+            PropertySource,
+            IndexSource,
+            ConstraintSource,
+        )
+
+        # Convert nodes
+        graph_nodes = []
+        node_indexes = []
+        node_constraints = []
+
+        for llm_node in self.nodes:
+            # Create properties with proper GraphProperty objects
+            properties = []
+            for prop_name in llm_node.properties:
+                graph_prop = GraphProperty(
+                    key=prop_name,
+                    count=1,
+                    filling_factor=100.0,
+                    types=[{"type": "String", "count": 1, "examples": [""]}],
+                    source=PropertySource(field=f"{llm_node.source_table}.{prop_name}"),
+                )
+                properties.append(graph_prop)
+
+            # Create node source
+            node_source = NodeSource(
+                type="table",
+                name=llm_node.source_table,
+                location=f"database.schema.{llm_node.source_table}",
+                mapping={
+                    "labels": llm_node.labels,
+                    "id_field": (f"{llm_node.source_table}.{llm_node.primary_key}"),
+                },
+            )
+
+            graph_node = GraphNode(
+                labels=llm_node.labels,
+                count=1,
+                properties=properties,
+                examples=[{"gid": 0}],
+                source=node_source,
+            )
+            graph_nodes.append(graph_node)
+
+            # Create indexes for this node
+            for index_prop in llm_node.indexes:
+                index_source = IndexSource(
+                    origin="llm_recommendation",
+                    reason=f"Index recommended by LLM for {llm_node.name}.{index_prop}",
+                    created_by="ai_analysis",
+                    index_name=None,
+                    migrated_from=None,
+                )
+                graph_index = GraphIndex(
+                    labels=llm_node.labels,
+                    properties=[index_prop],
+                    type="label+property",
+                    source=index_source,
+                )
+                node_indexes.append(graph_index)
+
+            # Create constraints for this node
+            for constraint_prop in llm_node.constraints:
+                constraint_source = ConstraintSource(
+                    origin="llm_recommendation",
+                    constraint_name=f"ai_unique_constraint_{llm_node.name}_{constraint_prop}",
+                    migrated_from="ai_analysis",
+                )
+                graph_constraint = GraphConstraint(
+                    type="unique",
+                    labels=llm_node.labels,
+                    properties=[constraint_prop],
+                    source=constraint_source,
+                )
+                node_constraints.append(graph_constraint)
+
+        # Convert relationships
+        graph_relationships = []
+        for llm_rel in self.relationships:
+            # Find source/target node labels
+            from_labels = []
+            to_labels = []
+            for node in self.nodes:
+                if node.name == llm_rel.from_node:
+                    from_labels = node.labels
+                if node.name == llm_rel.to_node:
+                    to_labels = node.labels
+
+            # Create relationship properties
+            rel_properties = []
+            for prop_name in llm_rel.properties:
+                rel_prop = GraphProperty(
+                    key=prop_name,
+                    count=1,
+                    filling_factor=100.0,
+                    types=[{"type": "String", "count": 1, "examples": [""]}],
+                )
+                rel_properties.append(rel_prop)
+
+            # Create relationship source
+            rel_source = RelationshipSource(
+                type="derived",
+                name=f"{llm_rel.from_node}_{llm_rel.name}_{llm_rel.to_node}",
+                location=f"derived.{llm_rel.name}",
+                mapping={
+                    "start_node": llm_rel.from_node,
+                    "end_node": llm_rel.to_node,
+                    "edge_type": llm_rel.name,
+                },
+            )
+
+            graph_rel = GraphRelationship(
+                edge_type=llm_rel.name,
+                start_node_labels=from_labels,
+                end_node_labels=to_labels,
+                count=1,
+                properties=rel_properties,
+                examples=[{}],
+                source=rel_source,
+                directionality=llm_rel.directionality,
+            )
+            graph_relationships.append(graph_rel)
+
+        return GraphModel(
+            nodes=graph_nodes,
+            edges=graph_relationships,
+            node_indexes=node_indexes,
+            node_constraints=node_constraints,
+        )

core/hygm/models/operations.py

@@ -0,0 +1,176 @@
+"""
+Operation models for interactive graph model modifications.
+
+These models define the structure for operations that can be applied to
+graph models during interactive sessions.
+"""
+
+from typing import List, Union, Literal
+from pydantic import BaseModel, Field
+
+
+class ModelOperation(BaseModel):
+    """Base class for model operations."""
+
+    operation_type: str = Field(description="Type of operation to perform")
+    description: str = Field(description="Human-readable description of the operation")
+
+    class Config:
+        """Pydantic config for OpenAI structured output compatibility."""
+
+        extra = "forbid"
+
+
+class ChangeNodeLabelOperation(ModelOperation):
+    """Operation to change a node's label."""
+
+    operation_type: Literal["change_node_label"] = "change_node_label"
+    old_label: str = Field(description="Current node label")
+    new_label: str = Field(description="New node label")
+
+
+class RenamePropertyOperation(ModelOperation):
+    """Operation to rename a property."""
+
+    operation_type: Literal["rename_property"] = "rename_property"
+    node_label: str = Field(description="Node label containing the property")
+    old_property: str = Field(description="Current property name")
+    new_property: str = Field(description="New property name")
+
+
+class DropPropertyOperation(ModelOperation):
+    """Operation to drop a property."""
+
+    operation_type: Literal["drop_property"] = "drop_property"
+    node_label: str = Field(description="Node label containing the property")
+    property_name: str = Field(description="Property name to drop")
+
+
+class AddPropertyOperation(ModelOperation):
+    """Operation to add a property."""
+
+    operation_type: Literal["add_property"] = "add_property"
+    node_label: str = Field(description="Node label to add property to")
+    property_name: str = Field(description="Property name to add")
+
+
+class ChangeRelationshipNameOperation(ModelOperation):
+    """Operation to change a relationship name."""
+
+    operation_type: Literal["change_relationship_name"] = "change_relationship_name"
+    old_name: str = Field(description="Current relationship name")
+    new_name: str = Field(description="New relationship name")
+
+
+class DropRelationshipOperation(ModelOperation):
+    """Operation to drop a relationship."""
+
+    operation_type: Literal["drop_relationship"] = "drop_relationship"
+    relationship_name: str = Field(description="Relationship name to drop")
+
+
+class AddIndexOperation(ModelOperation):
+    """Operation to add an index."""
+
+    operation_type: Literal["add_index"] = "add_index"
+    node_label: str = Field(description="Node label for the index")
+    property_name: str = Field(description="Property name for the index")
+
+
+class DropIndexOperation(ModelOperation):
+    """Operation to drop an index."""
+
+    operation_type: Literal["drop_index"] = "drop_index"
+    node_label: str = Field(description="Node label for the index")
+    property_name: str = Field(description="Property name for the index")
+
+
+class AddConstraintOperation(ModelOperation):
+    """Operation to add a constraint."""
+
+    operation_type: Literal["add_constraint"] = "add_constraint"
+    node_label: str = Field(description="Node label for the constraint")
+    property_name: str = Field(description="Property name for the constraint")
+    constraint_type: Literal["unique", "existence", "data_type"] = Field(
+        description="Type of constraint (unique, existence, or data_type)"
+    )
+    data_type: str = Field(
+        default="", description="Data type for data_type constraints"
+    )
+
+
+class DropConstraintOperation(ModelOperation):
+    """Operation to drop a constraint."""
+
+    operation_type: Literal["drop_constraint"] = "drop_constraint"
+    node_label: str = Field(description="Node label for the constraint")
+    property_name: str = Field(description="Property name for the constraint")
+    constraint_type: Literal["unique", "existence", "data_type"] = Field(
+        description="Type of constraint to drop"
+    )
+
+
+class AddNodeOperation(ModelOperation):
+    """Operation to add a new node type."""
+
+    operation_type: Literal["add_node"] = "add_node"
+    node_label: str = Field(description="Label for the new node")
+    properties: List[str] = Field(
+        default_factory=list, description="List of property names for the new node"
+    )
+    source_table: str = Field(
+        default="", description="Source table name if mapping from database"
+    )
+
+
+class DropNodeOperation(ModelOperation):
+    """Operation to drop a node type."""
+
+    operation_type: Literal["drop_node"] = "drop_node"
+    node_label: str = Field(description="Label of the node to drop")
+
+
+class AddRelationshipOperation(ModelOperation):
+    """Operation to add a new relationship."""
+
+    operation_type: Literal["add_relationship"] = "add_relationship"
+    relationship_name: str = Field(description="Name of the new relationship")
+    start_node_label: str = Field(description="Label of the start node")
+    end_node_label: str = Field(description="Label of the end node")
+    properties: List[str] = Field(
+        default_factory=list, description="List of property names for the relationship"
+    )
+
+
+# Union type for all operations with discriminator
+OperationType = Union[
+    ChangeNodeLabelOperation,
+    RenamePropertyOperation,
+    DropPropertyOperation,
+    AddPropertyOperation,
+    ChangeRelationshipNameOperation,
+    DropRelationshipOperation,
+    AddIndexOperation,
+    DropIndexOperation,
+    AddConstraintOperation,
+    DropConstraintOperation,
+    AddNodeOperation,
+    DropNodeOperation,
+    AddRelationshipOperation,
+]
+
+
+class ModelModifications(BaseModel):
+    """Container for multiple model operations."""
+
+    operations: List[OperationType] = Field(
+        description="List of operations to apply to the graph model"
+    )
+    reasoning: str = Field(
+        description="Explanation of why these changes improve the model"
+    )
+
+    class Config:
+        """Pydantic config for OpenAI structured output compatibility."""
+
+        extra = "forbid"

core/hygm/models/sources.py

@@ -0,0 +1,68 @@
+"""
+Source tracking models for Hypothetical Graph Modeling (HyGM).
+
+These models track the origin and mapping of graph elements to their source data.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+
+
+@dataclass
+class PropertySource:
+    """Source information for a property."""
+
+    field: str  # Source field name (e.g., "users.name")
+    transformation: Optional[str] = None  # Any transformation applied
+
+
+@dataclass
+class NodeSource:
+    """Source information for a node."""
+
+    type: str  # "table", "view", "file", "api", "manual"
+    name: str  # Source name (e.g., table name)
+    location: str  # Full location path
+    mapping: Dict[str, Any]  # Mapping details for labels, id_field, etc.
+
+
+@dataclass
+class RelationshipSource:
+    """Source information for a relationship."""
+
+    type: str  # "table", "view", "many_to_many", "derived"
+    name: str  # Source name
+    location: str  # Full location path
+    mapping: Dict[str, Any]  # Mapping for start_node, end_node, edge_type
+
+
+@dataclass
+class IndexSource:
+    """Source information for an index."""
+
+    origin: str  # "source_database_index", "migration_requirement", etc.
+    reason: str  # Why this index was created
+    created_by: str  # Who/what created this index
+    index_name: Optional[str] = None  # Original index name if applicable
+    migrated_from: Optional[str] = None  # Source location
+
+
+@dataclass
+class ConstraintSource:
+    """Source information for a constraint."""
+
+    origin: str  # "source_database_constraint", "migration_requirement", etc.
+    constraint_name: Optional[str] = None  # Original constraint name
+    migrated_from: Optional[str] = None  # Source location
+    reason: Optional[str] = None  # Why this constraint exists
+    created_by: Optional[str] = None  # Who/what created this constraint
+
+
+@dataclass
+class EnumSource:
+    """Source information for an enum."""
+
+    origin: str  # "source_database_enum", "detected_from_data", etc.
+    enum_name: Optional[str] = None  # Original enum name if applicable
+    migrated_from: Optional[str] = None  # Source location
+    created_by: Optional[str] = None  # Who/what created this enum

core/hygm/models/user_operations.py

@@ -0,0 +1,139 @@
+"""
+User operation tracking for preserving user intentions in graph modeling.
+
+This module tracks user operations to ensure they are preserved when
+LLM strategies regenerate models for validation fixes.
+"""
+
+from typing import List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .operations import OperationType
+else:
+    try:
+        from .operations import OperationType
+    except ImportError:
+        # Fallback for circular imports
+        pass
+
+
+class UserOperationRecord:
+    """Record of a user operation."""
+
+    def __init__(self, operation: "OperationType"):
+        self.operation = operation
+
+
+class UserOperationHistory:
+    """Container for tracking all user operations in a session."""
+
+    def __init__(self, session_id: str):
+        self.operations: List[UserOperationRecord] = []
+        self.session_id = session_id
+
+    def add_operation(self, operation: "OperationType") -> None:
+        """Add a new user operation to the history."""
+        record = UserOperationRecord(operation)
+        self.operations.append(record)
+
+    def get_operations_by_type(self, operation_type: str) -> List[UserOperationRecord]:
+        """Get all operations of a specific type."""
+        return [
+            op
+            for op in self.operations
+            if op.operation.operation_type == operation_type
+        ]
+
+    def has_label_changes(self) -> bool:
+        """Check if user has made any label changes."""
+        return len(self.get_operations_by_type("change_node_label")) > 0
+
+    def to_llm_context(self) -> str:
+        """Generate context string for LLM about user operations."""
+        if not self.operations:
+            return ""
+
+        context_parts = ["USER CHANGES TO PRESERVE:", ""]
+
+        for i, record in enumerate(self.operations, 1):
+            op = record.operation
+
+            if op.operation_type == "change_node_label":
+                old_label = getattr(op, "old_label", "unknown")
+                new_label = getattr(op, "new_label", "unknown")
+                context_parts.append(f"{i}. Node label: '{old_label}' → '{new_label}'")
+            elif op.operation_type == "rename_property":
+                node_label = getattr(op, "node_label", "unknown")
+                old_prop = getattr(op, "old_property", "unknown")
+                new_prop = getattr(op, "new_property", "unknown")
+                context_parts.append(
+                    f"{i}. Property: {node_label}.{old_prop} → {new_prop}"
+                )
+            elif op.operation_type == "drop_property":
+                node_label = getattr(op, "node_label", "unknown")
+                prop_name = getattr(op, "property_name", "unknown")
+                context_parts.append(f"{i}. Remove: {node_label}.{prop_name}")
+            elif op.operation_type == "add_property":
+                node_label = getattr(op, "node_label", "unknown")
+                prop_name = getattr(op, "property_name", "unknown")
+                context_parts.append(f"{i}. Add: {node_label}.{prop_name}")
+            elif op.operation_type == "drop_constraint":
+                node_label = getattr(op, "node_label", "unknown")
+                prop_name = getattr(op, "property_name", "unknown")
+                constraint_type = getattr(op, "constraint_type", "unknown")
+                context_parts.append(
+                    f"{i}. Drop constraint: {constraint_type.upper()} on "
+                    f"{node_label}.{prop_name}"
+                )
+            elif op.operation_type == "add_constraint":
+                node_label = getattr(op, "node_label", "unknown")
+                prop_name = getattr(op, "property_name", "unknown")
+                constraint_type = getattr(op, "constraint_type", "unknown")
+                context_parts.append(
+                    f"{i}. Add constraint: {constraint_type.upper()} on "
+                    f"{node_label}.{prop_name}"
+                )
+            elif op.operation_type == "drop_index":
+                node_label = getattr(op, "node_label", "unknown")
+                prop_name = getattr(op, "property_name", "unknown")
+                context_parts.append(f"{i}. Drop index: {node_label}.{prop_name}")
+            elif op.operation_type == "add_index":
+                node_label = getattr(op, "node_label", "unknown")
+                prop_name = getattr(op, "property_name", "unknown")
+                context_parts.append(f"{i}. Add index: {node_label}.{prop_name}")
+            elif op.operation_type == "change_relationship_name":
+                old_name = getattr(op, "old_name", "unknown")
+                new_name = getattr(op, "new_name", "unknown")
+                context_parts.append(f"{i}. Relationship: {old_name} → {new_name}")
+            elif op.operation_type == "drop_relationship":
+                rel_name = getattr(op, "relationship_name", "unknown")
+                context_parts.append(f"{i}. Drop relationship: {rel_name}")
+            elif op.operation_type == "add_node":
+                node_label = getattr(op, "node_label", "unknown")
+                properties = getattr(op, "properties", [])
+                prop_list = ", ".join(properties) if properties else "no properties"
+                context_parts.append(f"{i}. Add node: {node_label} ({prop_list})")
+            elif op.operation_type == "drop_node":
+                node_label = getattr(op, "node_label", "unknown")
+                context_parts.append(f"{i}. Drop node: {node_label}")
+            elif op.operation_type == "add_relationship":
+                rel_name = getattr(op, "relationship_name", "unknown")
+                start_node = getattr(op, "start_node_label", "unknown")
+                end_node = getattr(op, "end_node_label", "unknown")
+                context_parts.append(
+                    f"{i}. Add relationship: ({start_node})-[:{rel_name}]->({end_node})"
+                )
+
+        context_parts.extend(
+            ["", "PRESERVE these user changes exactly when improving the model."]
+        )
+
+        return "\n".join(context_parts)
+
+    def copy(self) -> "UserOperationHistory":
+        """Create a deep copy of the user operation history."""
+        new_history = UserOperationHistory(self.session_id)
+        new_history.operations = [
+            UserOperationRecord(op.operation) for op in self.operations
+        ]
+        return new_history

core/hygm/strategies/__init__.py

@@ -0,0 +1,17 @@
+"""
+Modeling strategies for Hypothetical Graph Modeling (HyGM).
+
+This package contains different strategies for creating graph models:
+- DeterministicStrategy: Rule-based deterministic modeling
+- LLMStrategy: AI-powered modeling using language models
+"""
+
+from .base import BaseModelingStrategy
+from .deterministic import DeterministicStrategy
+from .llm import LLMStrategy
+
+__all__ = [
+    "BaseModelingStrategy",
+    "DeterministicStrategy",
+    "LLMStrategy",
+]

core/hygm/strategies/base.py

@@ -0,0 +1,36 @@
+"""
+Base strategy interface for Hypothetical Graph Modeling (HyGM).
+
+This module defines the base interface that all modeling strategies must implement.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..models.graph_models import GraphModel
+
+
+class BaseModelingStrategy(ABC):
+    """Base class for all graph modeling strategies."""
+
+    @abstractmethod
+    def create_model(
+        self, database_structure: Dict[str, Any], domain_context: Optional[str] = None
+    ) -> "GraphModel":
+        """
+        Create a graph model from database structure.
+
+        Args:
+            database_structure: Analyzed database structure
+            domain_context: Optional domain-specific context
+
+        Returns:
+            GraphModel: Generated graph model
+        """
+        pass
+
+    @abstractmethod
+    def get_strategy_name(self) -> str:
+        """Return the name of this strategy."""
+        pass