@elizaos/python 2.0.0-alpha.10

package/tests/test_streaming.py

@@ -0,0 +1,295 @@
+"""Tests for streaming utilities.
+
+This test module validates the streaming extractors:
+1. MarkableExtractor - passthrough with external completion control
+2. ValidationStreamExtractor - validation-aware streaming
+3. Cross-language parity with TypeScript and Rust
+"""
+
+import pytest
+
+from elizaos.types.state import SchemaRow, StreamEvent, StreamEventType
+from elizaos.utils.streaming import (
+    MAX_CHUNK_SIZE,
+    ChunkSizeError,
+    ExtractorState,
+    FieldState,
+    MarkableExtractor,
+    ValidationDiagnosis,
+    ValidationStreamExtractor,
+    ValidationStreamExtractorConfig,
+    validate_chunk_size,
+)
+
+
+class TestMarkableExtractor:
+    """Tests for MarkableExtractor."""
+
+    def test_new(self) -> None:
+        """Test creating a new extractor."""
+        extractor = MarkableExtractor()
+        assert extractor.done is False
+
+    def test_passthrough(self) -> None:
+        """Test that chunks pass through unchanged."""
+        extractor = MarkableExtractor()
+        output = extractor.push("test chunk")
+        assert output == "test chunk"
+
+    def test_mark_complete(self) -> None:
+        """Test marking extractor as complete."""
+        extractor = MarkableExtractor()
+        assert extractor.done is False
+        extractor.mark_complete()
+        assert extractor.done is True
+
+    def test_reset(self) -> None:
+        """Test resetting extractor state."""
+        extractor = MarkableExtractor()
+        extractor.mark_complete()
+        assert extractor.done is True
+        extractor.reset()
+        assert extractor.done is False
+
+    def test_flush(self) -> None:
+        """Test flush returns empty string."""
+        extractor = MarkableExtractor()
+        assert extractor.flush() == ""
+
+
+class TestChunkValidation:
+    """Tests for chunk size validation."""
+
+    def test_validate_chunk_size_ok(self) -> None:
+        """Test that small chunks pass validation."""
+        # Should not raise
+        validate_chunk_size("small chunk")
+
+    def test_validate_chunk_size_error(self) -> None:
+        """Test that large chunks fail validation."""
+        large_chunk = "x" * (MAX_CHUNK_SIZE + 1)
+        with pytest.raises(ChunkSizeError) as exc_info:
+            validate_chunk_size(large_chunk)
+
+        error = exc_info.value
+        assert "exceeds maximum" in str(error)
+
+
+class TestValidationStreamExtractor:
+    """Tests for ValidationStreamExtractor."""
+
+    def test_level0_immediate_streaming(self) -> None:
+        """Test level 0 streams content immediately."""
+        chunks_received: list[tuple[str, str | None]] = []
+
+        config = ValidationStreamExtractorConfig(
+            level=0,
+            schema=[SchemaRow("text", "Response text")],
+            stream_fields=["text"],
+            expected_codes={},
+            on_chunk=lambda chunk, field: chunks_received.append((chunk, field)),
+        )
+
+        extractor = ValidationStreamExtractor(config)
+        assert extractor.done is False
+        assert extractor.get_state() == ExtractorState.STREAMING
+
+        # Push XML content
+        extractor.push("<text>Hello ")
+        extractor.push("World</text>")
+
+        # At level 0, content should be emitted immediately
+        assert len(chunks_received) > 0
+
+        # Flush to complete
+        extractor.flush()
+        assert extractor.done is True
+        assert extractor.get_state() == ExtractorState.COMPLETE
+
+    def test_diagnosis(self) -> None:
+        """Test diagnosis of extraction state."""
+        config = ValidationStreamExtractorConfig(
+            level=1,
+            schema=[
+                SchemaRow("field1", "First field"),
+                SchemaRow("field2", "Second field"),
+            ],
+            stream_fields=["field1", "field2"],
+            expected_codes={},
+            on_chunk=lambda _c, _f: None,
+        )
+
+        extractor = ValidationStreamExtractor(config)
+        extractor.push("<field1>content</field1>")  # Only field1 is complete
+
+        diagnosis = extractor.diagnose()
+        # field2 should be either missing or incomplete
+        assert "field2" in diagnosis.missing_fields or "field2" in diagnosis.incomplete_fields
+
+    def test_signal_retry(self) -> None:
+        """Test signaling a retry attempt."""
+        retry_separator_received = [False]
+
+        def on_chunk(chunk: str, field: str | None) -> None:
+            if "let me start again" in chunk:
+                retry_separator_received[0] = True
+
+        config = ValidationStreamExtractorConfig(
+            level=0,
+            schema=[SchemaRow("text", "Response")],
+            stream_fields=["text"],
+            expected_codes={},
+            on_chunk=on_chunk,
+        )
+
+        extractor = ValidationStreamExtractor(config)
+        result = extractor.signal_retry(1)
+
+        assert result["validated_fields"] == []  # No validated fields yet
+        assert extractor.get_state() == ExtractorState.RETRYING
+        assert retry_separator_received[0] is True  # Separator was emitted
+
+    def test_signal_error(self) -> None:
+        """Test signaling an error."""
+        config = ValidationStreamExtractorConfig(
+            level=0,
+            schema=[SchemaRow("text", "Response")],
+            stream_fields=["text"],
+            expected_codes={},
+            on_chunk=lambda _c, _f: None,
+        )
+
+        extractor = ValidationStreamExtractor(config)
+        extractor.signal_error("Test error")
+
+        assert extractor.done is True
+        assert extractor.get_state() == ExtractorState.FAILED
+
+    def test_abort_signal(self) -> None:
+        """Test abort signal handling."""
+        aborted = [False]
+
+        config = ValidationStreamExtractorConfig(
+            level=0,
+            schema=[SchemaRow("text", "Response")],
+            stream_fields=["text"],
+            expected_codes={},
+            on_chunk=lambda _c, _f: None,
+            abort_signal=lambda: aborted[0],
+        )
+
+        extractor = ValidationStreamExtractor(config)
+
+        # Push before abort
+        extractor.push("<text>Hello")
+        assert extractor.done is False
+
+        # Set abort signal
+        aborted[0] = True
+
+        # Push after abort - should transition to failed
+        extractor.push(" World</text>")
+        assert extractor.done is True
+        assert extractor.get_state() == ExtractorState.FAILED
+
+    def test_rich_consumer_events(self) -> None:
+        """Test rich event emission to consumers."""
+        events_received: list[StreamEvent] = []
+
+        config = ValidationStreamExtractorConfig(
+            level=0,
+            schema=[SchemaRow("text", "Response")],
+            stream_fields=["text"],
+            expected_codes={},
+            on_chunk=lambda _c, _f: None,
+            on_event=lambda event: events_received.append(event),
+            has_rich_consumer=True,
+        )
+
+        extractor = ValidationStreamExtractor(config)
+        extractor.push("<text>Hello</text>")
+        extractor.flush()
+
+        # Should have received chunk and complete events
+        event_types = [e.event_type for e in events_received]
+        assert StreamEventType.CHUNK in event_types
+        assert StreamEventType.COMPLETE in event_types
+
+    def test_get_validated_fields(self) -> None:
+        """Test getting validated fields."""
+        config = ValidationStreamExtractorConfig(
+            level=0,
+            schema=[SchemaRow("text", "Response")],
+            stream_fields=["text"],
+            expected_codes={},
+            on_chunk=lambda _c, _f: None,
+        )
+
+        extractor = ValidationStreamExtractor(config)
+        extractor.push("<text>Content</text>")
+
+        # At level 0 without validation codes, fields aren't in validated_fields
+        # They're just emitted directly
+        validated = extractor.get_validated_fields()
+        # The implementation may or may not add to validated_fields at level 0
+        # Just verify the method works
+        assert isinstance(validated, dict)
+
+
+class TestEnumValues:
+    """Tests for enum value consistency."""
+
+    def test_extractor_state_values(self) -> None:
+        """Test ExtractorState values match TypeScript/Rust."""
+        assert ExtractorState.STREAMING == "streaming"
+        assert ExtractorState.VALIDATING == "validating"
+        assert ExtractorState.RETRYING == "retrying"
+        assert ExtractorState.COMPLETE == "complete"
+        assert ExtractorState.FAILED == "failed"
+
+    def test_field_state_values(self) -> None:
+        """Test FieldState values match TypeScript/Rust."""
+        assert FieldState.PENDING == "pending"
+        assert FieldState.PARTIAL == "partial"
+        assert FieldState.COMPLETE == "complete"
+        assert FieldState.INVALID == "invalid"
+
+
+class TestCrossLanguageParity:
+    """Tests for cross-language parity."""
+
+    def test_validation_stream_extractor_config_fields(self) -> None:
+        """Test ValidationStreamExtractorConfig has same fields as TypeScript."""
+        # These fields must match TypeScript ValidationStreamExtractorConfig
+
+        # Check that config accepts all fields
+        config = ValidationStreamExtractorConfig(
+            level=0,
+            schema=[],
+            stream_fields=[],
+            expected_codes={},
+            on_chunk=lambda _c, _f: None,
+            on_event=lambda _e: None,
+            abort_signal=lambda: False,
+            has_rich_consumer=True,
+        )
+
+        # If we get here, all fields are accepted
+        assert config.level == 0
+        assert config.has_rich_consumer is True
+
+    def test_validation_diagnosis_fields(self) -> None:
+        """Test ValidationDiagnosis has same fields as TypeScript."""
+        diagnosis = ValidationDiagnosis(
+            missing_fields=["a"],
+            invalid_fields=["b"],
+            incomplete_fields=["c"],
+        )
+
+        assert diagnosis.missing_fields == ["a"]
+        assert diagnosis.invalid_fields == ["b"]
+        assert diagnosis.incomplete_fields == ["c"]
+
+    def test_max_chunk_size_matches(self) -> None:
+        """Test MAX_CHUNK_SIZE matches TypeScript (1MB)."""
+        assert MAX_CHUNK_SIZE == 1024 * 1024

package/tests/test_types.py

@@ -0,0 +1,221 @@
+import pytest
+from google.protobuf import struct_pb2
+
+from elizaos.types import (
+    DEFAULT_UUID,
+    Character,
+    Content,
+    Entity,
+    Memory,
+    Plugin,
+    Room,
+    State,
+    Task,
+    TaskStatus,
+    World,
+    as_uuid,
+)
+
+
+class TestUUID:
+    def test_valid_uuid(self) -> None:
+        valid_uuid = "12345678-1234-1234-1234-123456789012"
+        result = as_uuid(valid_uuid)
+        assert result == valid_uuid
+
+    def test_invalid_uuid_format(self) -> None:
+        with pytest.raises(ValueError, match="Invalid UUID format"):
+            as_uuid("not-a-uuid")
+
+    def test_empty_uuid(self) -> None:
+        with pytest.raises(ValueError, match="Invalid UUID format"):
+            as_uuid("")
+
+    def test_uuid_case_insensitive(self) -> None:
+        lower = "12345678-1234-1234-1234-123456789012"
+        upper = "12345678-1234-1234-1234-123456789012".upper()
+        assert as_uuid(lower) == lower
+        assert as_uuid(upper) == upper
+
+    def test_default_uuid(self) -> None:
+        assert DEFAULT_UUID == "00000000-0000-0000-0000-000000000000"
+        assert as_uuid(DEFAULT_UUID) == DEFAULT_UUID
+
+    def test_default_uuid_can_be_used_in_memory(self) -> None:
+        memory = Memory(
+            entity_id=as_uuid("12345678-1234-1234-1234-123456789012"),
+            room_id=DEFAULT_UUID,
+            content=Content(text="Hello"),
+        )
+        assert memory.room_id == DEFAULT_UUID
+
+
+class TestContent:
+    def test_minimal_content(self) -> None:
+        content = Content(text="Hello world")
+        assert content.text == "Hello world"
+        assert content.thought == ""  # Protobuf defaults optional string to ""
+        assert list(content.actions) == []
+
+    def test_full_content(self) -> None:
+        content = Content(
+            text="Hello world",
+            thought="Thinking about response",
+            actions=["RESPOND", "SEARCH"],
+            providers=["KNOWLEDGE"],
+            source="cli",
+            target="user",
+        )
+        assert content.text == "Hello world"
+        assert content.thought == "Thinking about response"
+        assert content.actions == ["RESPOND", "SEARCH"]
+        assert content.providers == ["KNOWLEDGE"]
+
+
+class TestMemory:
+    def test_minimal_memory(self) -> None:
+        memory = Memory(
+            entity_id=as_uuid("12345678-1234-1234-1234-123456789012"),
+            room_id=as_uuid("12345678-1234-1234-1234-123456789013"),
+            content=Content(text="Hello"),
+        )
+        assert memory.entity_id == "12345678-1234-1234-1234-123456789012"
+        assert memory.content.text == "Hello"
+
+    def test_memory_with_embedding(self) -> None:
+        embedding = [0.1, 0.2, 0.3, 0.4, 0.5]
+        memory = Memory(
+            entity_id=as_uuid("12345678-1234-1234-1234-123456789012"),
+            room_id=as_uuid("12345678-1234-1234-1234-123456789013"),
+            content=Content(text="Hello"),
+            embedding=embedding,
+        )
+        # Use approximate comparison due to float32 precision in protobuf
+        assert list(memory.embedding) == pytest.approx(embedding, rel=1e-6)
+
+
+class TestCharacter:
+    def test_minimal_character(self) -> None:
+        character = Character(
+            name="TestAgent",
+            bio=["A test agent for testing."],
+        )
+        assert character.name == "TestAgent"
+        assert character.bio == ["A test agent for testing."]
+
+    def test_full_character(self) -> None:
+        character = Character(
+            name="TestAgent",
+            username="testagent",
+            bio=["Line 1", "Line 2"],
+            system="You are a test agent.",
+            topics=["testing", "automation"],
+            adjectives=["helpful", "precise"],
+            plugins=["@elizaos/plugin-sql"],
+            settings=None,
+            secrets={"API_KEY": "secret"},
+        )
+        assert character.name == "TestAgent"
+        assert character.username == "testagent"
+        assert character.bio == ["Line 1", "Line 2"]
+        assert character.topics == ["testing", "automation"]
+
+
+class TestEntity:
+    def test_minimal_entity(self) -> None:
+        entity = Entity(
+            names=["TestUser"],
+            agent_id=as_uuid("12345678-1234-1234-1234-123456789012"),
+        )
+        assert entity.names == ["TestUser"]
+        assert entity.metadata is not None
+
+    def test_entity_with_metadata(self) -> None:
+        metadata = struct_pb2.Struct()
+        metadata.update({"email": "test@example.com"})
+        entity = Entity(
+            names=["TestUser"],
+            agent_id=as_uuid("12345678-1234-1234-1234-123456789012"),
+            metadata=metadata,
+        )
+        assert entity.metadata is not None
+
+
+class TestRoom:
+    def test_room_creation(self) -> None:
+        room = Room(
+            id=as_uuid("12345678-1234-1234-1234-123456789012"),
+            source="cli",
+            type="DM",
+        )
+        assert room.type == "DM"
+        assert room.source == "cli"
+
+    def test_room_with_world(self) -> None:
+        room = Room(
+            id=as_uuid("12345678-1234-1234-1234-123456789012"),
+            source="discord",
+            type="GROUP",
+            world_id=as_uuid("12345678-1234-1234-1234-123456789013"),
+            name="general",
+        )
+        assert room.name == "general"
+        assert room.world_id == "12345678-1234-1234-1234-123456789013"
+
+
+class TestWorld:
+    def test_world_creation(self) -> None:
+        world = World(
+            id=as_uuid("12345678-1234-1234-1234-123456789012"),
+            agent_id=as_uuid("12345678-1234-1234-1234-123456789013"),
+            name="Test World",
+        )
+        assert world.name == "Test World"
+
+
+class TestPlugin:
+    def test_minimal_plugin(self) -> None:
+        plugin = Plugin(
+            name="test-plugin",
+            description="A test plugin",
+        )
+        assert plugin.name == "test-plugin"
+        assert plugin.description == "A test plugin"
+
+    def test_plugin_with_dependencies(self) -> None:
+        plugin = Plugin(
+            name="test-plugin",
+            description="A test plugin",
+            dependencies=["core-plugin", "util-plugin"],
+        )
+        assert plugin.dependencies == ["core-plugin", "util-plugin"]
+
+
+class TestState:
+    def test_empty_state(self) -> None:
+        state = State()
+        assert state.values is not None
+        assert state.text == ""
+
+    def test_state_with_data(self) -> None:
+        state = State(text="State context")
+        assert state.text == "State context"
+
+
+class TestTask:
+    def test_task_creation(self) -> None:
+        task = Task(
+            name="test-task",
+            description="A test task",
+        )
+        assert task.name == "test-task"
+        assert task.status == TaskStatus.TASK_STATUS_UNSPECIFIED
+
+    def test_task_with_metadata(self) -> None:
+        task = Task(
+            name="scheduled-task",
+            status=TaskStatus.TASK_STATUS_IN_PROGRESS,
+            tags=["important", "daily"],
+        )
+        assert task.status == TaskStatus.TASK_STATUS_IN_PROGRESS
+        assert "important" in (task.tags or [])

package/tests/test_uuid_parity.py

@@ -0,0 +1,46 @@
+import uuid as uuid_module
+
+import pytest
+
+from elizaos.types import string_to_uuid
+
+
+class TestStringToUuidParity:
+    def test_deterministic_vectors_match_typescript(self) -> None:
+        vectors = [
+            ("test", "a94a8fe5-ccb1-0ba6-9c4c-0873d391e987"),
+            ("hello world", "f0355dd5-2823-054c-ae66-a0b12842c215"),
+            ("", "da39a3ee-5e6b-0b0d-b255-bfef95601890"),
+            ("123", "40bd0015-6308-0fc3-9165-329ea1ff5c5e"),
+            ("user:agent", "a49810ce-da30-0d3b-97ee-d4d47774d8af"),
+        ]
+
+        for input_str, expected in vectors:
+            assert string_to_uuid(input_str) == expected
+
+    def test_returns_existing_uuid_unchanged(self) -> None:
+        existing = "550e8400-e29b-41d4-a716-446655440000"
+        assert string_to_uuid(existing) == existing
+
+    def test_number_inputs(self) -> None:
+        assert string_to_uuid(42) == string_to_uuid("42")
+        assert string_to_uuid(0) == string_to_uuid("0")
+        assert string_to_uuid(-1) == string_to_uuid("-1")
+
+    def test_invalid_inputs_raise_type_error(self) -> None:
+        with pytest.raises(TypeError):
+            string_to_uuid(None)  # type: ignore[arg-type]
+        with pytest.raises(TypeError):
+            string_to_uuid({"x": 1})  # type: ignore[arg-type]
+
+    def test_sets_variant_and_version_bits(self) -> None:
+        uuid_str = string_to_uuid("test")
+        parts = uuid_str.split("-")
+        assert len(parts) == 5
+
+        variant_byte = int(parts[3][0:2], 16)
+        assert (variant_byte & 0xC0) == 0x80
+
+        assert parts[2][0] == "0"
+
+        uuid_module.UUID(uuid_str)