diff --git a/docs/semantic-layer.md b/docs/semantic-layer.md index 01ea35e..fe7249d 100644 --- a/docs/semantic-layer.md +++ b/docs/semantic-layer.md @@ -1,50 +1,250 @@ --- title: Semantic Layer layout: default -nav_order: 6 +nav_order: 2 --- -# Semantic Layer +# Semantic Layer Architecture -## Overview +## Core Concepts -The semantic layer in Memory Graph SQL provides enhanced meaning and structure to the relationships between entities. It enables validation of relationships, type hierarchies, and semantic constraints. +The semantic layer is the distinguishing feature of this Memory Graph SQL implementation. It provides a sophisticated system for understanding and enforcing relationships between entities, going beyond simple graph connections to enable rich semantic validation and inference. -## Features +### Key Components -### Type Hierarchy -- Defines valid entity types and their relationships -- Enforces type constraints on relations -- Validates entity type assignments - -### Relation Types -- Implements - For plugin implementation relationships -- Contains - For hierarchical relationships -- References - For loose coupling between entities -- Depends - For dependency relationships - -### Semantic Validation -- Validates relation types between entity types -- Ensures data integrity through semantic rules -- Prevents invalid relationships - -## Examples - -### Type Hierarchy Definition +#### 1. Type System ```sql CREATE TABLE type_hierarchy ( + id INTEGER PRIMARY KEY AUTOINCREMENT, parent_type TEXT NOT NULL, child_type TEXT NOT NULL, - PRIMARY KEY (parent_type, child_type) + inheritance_type TEXT CHECK(inheritance_type IN ('IS_A', 'CAN_BE', 'IMPLEMENTS')) NOT NULL, + metadata JSONB, + UNIQUE(parent_type, child_type) +); + +CREATE TABLE type_attributes ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + type_name TEXT NOT NULL, + attribute_name TEXT NOT NULL, + attribute_type TEXT NOT NULL, + is_required BOOLEAN DEFAULT false, + validation_rules JSONB, + UNIQUE(type_name, attribute_name) ); ``` -### Valid Relations +#### 2. Semantic Relations ```sql -CREATE TABLE valid_relations ( +CREATE TABLE semantic_relations ( + id INTEGER PRIMARY KEY AUTOINCREMENT, from_type TEXT NOT NULL, relation_type TEXT NOT NULL, to_type TEXT NOT NULL, - PRIMARY KEY (from_type, relation_type, to_type) + cardinality TEXT CHECK(cardinality IN ('ONE_TO_ONE', 'ONE_TO_MANY', 'MANY_TO_ONE', 'MANY_TO_MANY')), + constraints JSONB, + inference_rules JSONB, + UNIQUE(from_type, relation_type, to_type) +); +``` + +#### 3. Inference Engine +```sql +CREATE TABLE inference_rules ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + rule_name TEXT NOT NULL, + pattern JSONB NOT NULL, -- Describes the pattern to match + inference TEXT NOT NULL, -- The relation or attribute to infer + confidence FLOAT CHECK(confidence BETWEEN 0 AND 1), + metadata JSONB ); +``` + +## Semantic Validation System + +### Type Validation +```python +def validate_type_assignment(entity_type, attributes): + # Check if type exists and validate all required attributes + required_attrs = db.query(type_attributes)\ + .filter_by(type_name=entity_type, is_required=True)\ + .all() + + for attr in required_attrs: + if attr.attribute_name not in attributes: + raise ValidationError(f"Missing required attribute: {attr.attribute_name}") + + # Validate attribute value against rules + validate_attribute( + attributes[attr.attribute_name], + attr.attribute_type, + attr.validation_rules + ) +``` + +### Relation Validation +```python +def validate_relation(from_entity, relation_type, to_entity): + # Get semantic relation rules + rules = db.query(semantic_relations)\ + .filter_by( + from_type=from_entity.type, + relation_type=relation_type, + to_type=to_entity.type + ).first() + + if not rules: + # Check type hierarchy for valid inheritance-based relations + if not is_valid_through_hierarchy(from_entity.type, relation_type, to_entity.type): + raise ValidationError("Invalid relation between types") + + # Check cardinality constraints + validate_cardinality(from_entity, relation_type, to_entity, rules.cardinality) + + # Apply custom constraints + apply_relation_constraints(from_entity, to_entity, rules.constraints) +``` + +## Inference Capabilities + +### Pattern-Based Inference +```python +def infer_relations(entity): + # Find applicable inference rules + rules = db.query(inference_rules)\ + .filter(match_pattern(inference_rules.pattern, entity))\ + .all() + + inferred_relations = [] + for rule in rules: + # Apply inference rule and calculate confidence + inference = apply_inference_rule(rule, entity) + if inference.confidence >= CONFIDENCE_THRESHOLD: + inferred_relations.append(inference) + + return inferred_relations +``` + +### Semantic Propagation +```python +def propagate_semantics(entity, relation): + # Identify semantic implications + implications = db.query(semantic_implications)\ + .filter_by(source_relation=relation.type)\ + .all() + + for implication in implications: + # Calculate transitive relations + transitive_relations = calculate_transitive_relations( + entity, + implication.pattern, + implication.depth_limit + ) + + # Apply semantic rules to transitive relations + apply_semantic_rules(transitive_relations, implication.rules) +``` + +## Advanced Features + +### Context-Aware Validation +```python +def validate_in_context(entity, context): + # Get context-specific validation rules + context_rules = db.query(context_validation_rules)\ + .filter_by(context_type=context.type)\ + .all() + + for rule in context_rules: + # Apply contextual validation + validate_contextual_rule(entity, rule, context) +``` + +### Semantic Query Enhancement +```python +def enhance_query(base_query, semantic_context): + # Analyze query semantics + semantic_patterns = analyze_query_semantics(base_query) + + # Enhance query with semantic understanding + enhanced_query = apply_semantic_patterns( + base_query, + semantic_patterns, + semantic_context + ) + + return enhanced_query +``` + +## Best Practices + +### 1. Type Hierarchy Design +- Use specific, well-defined types +- Implement clear inheritance patterns +- Document type relationships + +### 2. Relation Definition +- Define clear cardinality rules +- Implement comprehensive validation +- Use semantic constraints effectively + +### 3. Inference Rule Creation +- Set appropriate confidence thresholds +- Define clear inference patterns +- Document rule implications + +### 4. Performance Optimization +- Index frequently queried semantic patterns +- Cache common inference results +- Optimize validation checks + +## Usage Examples + +### Define Complex Type Hierarchies +```python +# Define a plugin type hierarchy +db.add_type_hierarchy( + parent_type='Plugin', + child_type='VideoPlugin', + inheritance_type='IS_A', + metadata={ + 'capabilities': ['streaming', 'recording'], + 'validation_level': 'strict' + } +) +``` + +### Create Semantic Relations +```python +# Define a semantic relation with constraints +db.add_semantic_relation( + from_type='VideoPlugin', + relation_type='IMPLEMENTS', + to_type='StreamInterface', + cardinality='ONE_TO_MANY', + constraints={ + 'requires_attributes': ['stream_protocol', 'max_resolution'], + 'validate_method': 'strict' + } +) +``` + +### Apply Inference Rules +```python +# Create an inference rule +db.add_inference_rule( + rule_name='stream_capability_inference', + pattern={ + 'type': 'VideoPlugin', + 'attributes': { + 'has_streaming': True + } + }, + inference='CAN_STREAM', + confidence=0.95, + metadata={ + 'description': 'Infers streaming capability from plugin attributes', + 'author': 'system' + } +) ``` \ No newline at end of file