feat: add Vocabulary system and message validation

- Implemented complete Vocabulary class with 120+ semantic concepts
  - 10 categories: ENT, ACT, PROP, REL, LOG, MATH, TIME, SPACE, DATA, META
  - Concept validation, search, and category management
  - Detailed descriptions and examples for each concept

- Implemented MessageValidator with three-stage validation:
  - Envelope validation (structure, required fields, formats)
  - Content validation (semantic concepts from vocabulary)
  - Timestamp validation (freshness, replay protection)

- Integrated validation into PulseMessage:
  - Automatic validation on creation (can be disabled)
  - Manual validation method
  - Vocabulary-based concept checking

- Added comprehensive test suites:
  - test_vocabulary.py: 40+ tests for vocabulary functionality
  - test_validator.py: 35+ tests for validation logic
  - Full coverage of validation edge cases and error handling

- Created vocabulary_validation example:
  - Demonstrates vocabulary search and categories
  - Shows validation in action with valid/invalid messages
  - Provides helpful error messages with suggestions

This completes core Week 1 functionality:
✓ PulseMessage class with JSON serialization
✓ Vocabulary system with semantic concepts
✓ Message validation framework
✓ 70+ unit tests
✓ 2 working examples

Author: Sergey Klein

examples/02_vocabulary_validation.py

@@ -0,0 +1,190 @@
+"""
+PULSE Protocol - Vocabulary and Validation Example.
+
+This example demonstrates:
+1. Using different vocabulary concepts
+2. Message validation
+3. Handling validation errors
+4. Vocabulary search functionality
+"""
+
+from pulse import PulseMessage, Vocabulary, MessageValidator, ValidationError
+
+
+def print_section(title):
+    """Print a section header."""
+    print("\n" + "=" * 60)
+    print(title)
+    print("=" * 60)
+
+
+def example_vocabulary_categories():
+    """Demonstrate vocabulary categories."""
+    print_section("1. Vocabulary Categories")
+
+    categories = Vocabulary.get_all_categories()
+    print(f"Available categories: {sorted(categories)}")
+    print()
+
+    counts = Vocabulary.count_by_category()
+    print("Concepts per category:")
+    for cat in sorted(counts.keys()):
+        count = counts[cat]
+        print(f"  {cat}: {count} concepts")
+
+    print(f"\nTotal concepts: {Vocabulary.get_total_count()}")
+
+
+def example_vocabulary_search():
+    """Demonstrate vocabulary search."""
+    print_section("2. Vocabulary Search")
+
+    # Search for sentiment-related concepts
+    print("Searching for 'sentiment':")
+    results = Vocabulary.search("sentiment")
+    for concept in results:
+        desc = Vocabulary.get_description(concept)
+        print(f"  {concept}: {desc}")
+
+    print("\nSearching for 'query':")
+    results = Vocabulary.search("query")
+    for concept in results[:5]:  # Show first 5
+        desc = Vocabulary.get_description(concept)
+        print(f"  {concept}: {desc}")
+
+    print("\nSearching for 'data':")
+    results = Vocabulary.search("data")
+    print(f"  Found {len(results)} concepts containing 'data'")
+
+
+def example_valid_messages():
+    """Create valid messages with different concepts."""
+    print_section("3. Creating Valid Messages")
+
+    examples = [
+        {
+            "name": "Sentiment Analysis",
+            "action": "ACT.ANALYZE.SENTIMENT",
+            "target": "ENT.DATA.TEXT",
+            "params": {"text": "I love PULSE Protocol!"},
+        },
+        {
+            "name": "Data Query",
+            "action": "ACT.QUERY.DATA",
+            "target": "ENT.RESOURCE.DATABASE",
+            "params": {"table": "users", "limit": 10},
+        },
+        {
+            "name": "Text Generation",
+            "action": "ACT.CREATE.TEXT",
+            "target": "ENT.DATA.TEXT",
+            "params": {"prompt": "Write a poem", "max_length": 100},
+        },
+        {
+            "name": "Image Classification",
+            "action": "ACT.ANALYZE.CLASSIFY",
+            "target": "ENT.DATA.IMAGE",
+            "params": {"model": "resnet50"},
+        },
+    ]
+
+    for ex in examples:
+        message = PulseMessage(
+            action=ex["action"], target=ex["target"], parameters=ex["params"]
+        )
+        print(f"\n✓ {ex['name']}:")
+        print(f"  Action: {ex['action']}")
+        print(f"  Target: {ex['target']}")
+        print(f"  Valid: {MessageValidator.validate_message(message, check_freshness=False)}")
+
+
+def example_invalid_messages():
+    """Demonstrate validation errors."""
+    print_section("4. Validation Errors")
+
+    print("\nTrying to create message with invalid action:")
+    try:
+        message = PulseMessage(action="INVALID.ACTION")
+    except ValidationError as e:
+        print(f"✗ ValidationError: {e}")
+
+    print("\nTrying to create message with invalid target:")
+    try:
+        message = PulseMessage(action="ACT.QUERY.DATA", target="INVALID.TARGET")
+    except ValidationError as e:
+        print(f"✗ ValidationError: {e}")
+
+    print("\nSkipping validation on creation, then validating manually:")
+    message = PulseMessage(action="ACT.QUERY.DATA", target="INVALID.TARGET", validate=False)
+    print("✓ Message created (validation skipped)")
+
+    try:
+        message.validate()
+    except ValidationError as e:
+        print(f"✗ Manual validation failed: {e}")
+
+
+def example_concept_details():
+    """Show detailed concept information."""
+    print_section("5. Concept Details")
+
+    concept = "ACT.ANALYZE.SENTIMENT"
+    print(f"Concept: {concept}")
+    print(f"  Category: {Vocabulary.get_category(concept)}")
+    print(f"  Description: {Vocabulary.get_description(concept)}")
+    print(f"  Examples: {', '.join(Vocabulary.get_examples(concept))}")
+
+    print(f"\nConcept: ENT.DATA.TEXT")
+    print(f"  Category: {Vocabulary.get_category('ENT.DATA.TEXT')}")
+    print(f"  Description: {Vocabulary.get_description('ENT.DATA.TEXT')}")
+    print(f"  Examples: {', '.join(Vocabulary.get_examples('ENT.DATA.TEXT'))}")
+
+
+def example_list_by_category():
+    """List concepts by category."""
+    print_section("6. List Concepts by Category")
+
+    # List action concepts
+    actions = Vocabulary.list_by_category("ACT")
+    print(f"ACT (Actions) - {len(actions)} concepts:")
+    for concept in sorted(actions)[:10]:  # Show first 10
+        print(f"  {concept}")
+    if len(actions) > 10:
+        print(f"  ... and {len(actions) - 10} more")
+
+    # List entity concepts
+    print(f"\nENT (Entities) - {len(Vocabulary.list_by_category('ENT'))} concepts:")
+    entities = Vocabulary.list_by_category("ENT")
+    for concept in sorted(entities)[:10]:  # Show first 10
+        print(f"  {concept}")
+    if len(entities) > 10:
+        print(f"  ... and {len(entities) - 10} more")
+
+
+def main():
+    """Run all examples."""
+    print("=" * 60)
+    print("PULSE Protocol - Vocabulary & Validation Demo")
+    print("=" * 60)
+
+    example_vocabulary_categories()
+    example_vocabulary_search()
+    example_valid_messages()
+    example_invalid_messages()
+    example_concept_details()
+    example_list_by_category()
+
+    print("\n" + "=" * 60)
+    print("✓ Demo completed successfully!")
+    print("=" * 60)
+    print("\nKey Takeaways:")
+    print("  • PULSE has 120+ semantic concepts across 10 categories")
+    print("  • All concepts are validated automatically")
+    print("  • Invalid concepts provide helpful suggestions")
+    print("  • You can search vocabulary by keyword")
+    print("  • Validation can be skipped if needed")
+    print()
+
+
+if __name__ == "__main__":
+    main()

pulse/__init__.py

@@ -7,6 +7,8 @@
 
 from pulse.version import __version__, __version_info__
 from pulse.message import PulseMessage
+from pulse.vocabulary import Vocabulary
+from pulse.validator import MessageValidator
 from pulse.exceptions import (
     PulseException,
     ValidationError,
@@ -22,6 +24,8 @@
     "__version__",
     "__version_info__",
     "PulseMessage",
+    "Vocabulary",
+    "MessageValidator",
     "PulseException",
     "ValidationError",
     "EncodingError",

pulse/message.py

@@ -3,6 +3,8 @@
 from typing import Optional, Dict, Any
 import uuid
 import json
+from pulse.validator import MessageValidator
+from pulse.exceptions import ValidationError
 
 
 class PulseMessage:
@@ -31,6 +33,7 @@ def __init__(
         target: Optional[str] = None,
         parameters: Optional[Dict[str, Any]] = None,
         sender: str = "default-agent",
+        validate: bool = True,
     ) -> None:
         """
         Initialize a PULSE message.
@@ -40,6 +43,10 @@ def __init__(
             target: Target object concept (e.g., "ENT.DATA.TEXT")
             parameters: Additional parameters for the action
             sender: Agent ID of the sender
+            validate: Whether to validate the message (default True)
+
+        Raises:
+            ValidationError: If validation is enabled and message is invalid
 
         Example:
             >>> message = PulseMessage(
@@ -56,6 +63,10 @@ def __init__(
             "parameters": parameters or {},
         }
 
+        # Validate message if requested
+        if validate:
+            self.validate()
+
     def _create_envelope(self, sender: str) -> Dict[str, Any]:
         """
         Create message envelope with metadata.
@@ -144,3 +155,23 @@ def __repr__(self) -> str:
     def __str__(self) -> str:
         """Return human-readable string representation."""
         return self.to_json()
+
+    def validate(self, check_freshness: bool = False) -> bool:
+        """
+        Validate this message.
+
+        Args:
+            check_freshness: Whether to check timestamp freshness (default False)
+
+        Returns:
+            True if message is valid
+
+        Raises:
+            ValidationError: If message is invalid
+
+        Example:
+            >>> message = PulseMessage(action="ACT.QUERY.DATA", validate=False)
+            >>> message.validate()
+            True
+        """
+        return MessageValidator.validate_message(self, check_freshness=check_freshness)