julee 0.1.0__py3-none-any.whl

julee/domain/models/assembly_specification/tests/test_knowledge_service_query.py

@@ -0,0 +1,310 @@
+"""
+Comprehensive tests for KnowledgeServiceQuery domain model.
+
+This test module documents the design decisions made for the
+KnowledgeServiceQuery domain model using table-based tests. It covers:
+
+- KnowledgeServiceQuery instantiation with various field combinations
+- JSON Pointer validation for schema_pointer field
+- JSON serialization behavior
+- Field validation for required fields
+
+Design decisions documented:
+- KnowledgeServiceQuery must have all required fields (query_id, name,
+  knowledge_service_id, prompt, schema_pointer)
+- Schema pointer must be a valid JSON Pointer (RFC 6901)
+- All text fields must be non-empty and non-whitespace
+- Version field has a default but can be customized
+- Status defaults to ACTIVE
+"""
+
+import pytest
+
+from julee.domain.models.assembly_specification import (
+    KnowledgeServiceQuery,
+)
+from .factories import KnowledgeServiceQueryFactory
+
+
+class TestKnowledgeServiceQueryInstantiation:
+    """Test KnowledgeServiceQuery creation with various field combinations."""
+
+    @pytest.mark.parametrize(
+        "query_id,name,knowledge_service_id,prompt,expected_success",
+        [
+            # Valid cases
+            (
+                "query-1",
+                "Extract Attendees",
+                "ragflow-service-1",
+                "Extract list of meeting attendees with their roles",
+                True,
+            ),
+            (
+                "query-2",
+                "Extract Action Items",
+                "knowledge-service-2",
+                "Extract action items with assignees and due dates",
+                True,
+            ),
+            (
+                "query-3",
+                "Extract Meeting Metadata",
+                "service-alpha",
+                "Extract basic meeting information like title, date, time",
+                True,
+            ),
+            # Invalid cases - empty required fields
+            (
+                "",
+                "Test Query",
+                "service-1",
+                "Test prompt",
+                False,
+            ),  # Empty query_id
+            (
+                "query-4",
+                "",
+                "service-1",
+                "Test prompt",
+                False,
+            ),  # Empty name
+            (
+                "query-5",
+                "Test Query",
+                "",
+                "Test prompt",
+                False,
+            ),  # Empty knowledge_service_id
+            (
+                "query-6",
+                "Test Query",
+                "service-1",
+                "",
+                False,
+            ),  # Empty prompt
+            # Invalid cases - whitespace only
+            (
+                "   ",
+                "Test Query",
+                "service-1",
+                "Test prompt",
+                False,
+            ),  # Whitespace query_id
+            (
+                "query-8",
+                "   ",
+                "service-1",
+                "Test prompt",
+                False,
+            ),  # Whitespace name
+            (
+                "query-9",
+                "Test Query",
+                "   ",
+                "Test prompt",
+                False,
+            ),  # Whitespace knowledge_service_id
+            (
+                "query-10",
+                "Test Query",
+                "service-1",
+                "   ",
+                False,
+            ),  # Whitespace prompt
+        ],
+    )
+    def test_knowledge_service_query_creation_validation(
+        self,
+        query_id: str,
+        name: str,
+        knowledge_service_id: str,
+        prompt: str,
+        expected_success: bool,
+    ) -> None:
+        """Test query creation with various field validation scenarios."""
+        if expected_success:
+            # Should create successfully
+            query = KnowledgeServiceQuery(
+                query_id=query_id,
+                name=name,
+                knowledge_service_id=knowledge_service_id,
+                prompt=prompt,
+            )
+            assert query.query_id == query_id.strip()
+            assert query.name == name.strip()
+            assert query.knowledge_service_id == knowledge_service_id.strip()
+            assert query.prompt == prompt.strip()
+        else:
+            # Should raise validation error
+            with pytest.raises(Exception):  # Could be ValueError or ValidationError
+                KnowledgeServiceQuery(
+                    query_id=query_id,
+                    name=name,
+                    knowledge_service_id=knowledge_service_id,
+                    prompt=prompt,
+                )
+
+
+class TestKnowledgeServiceQuerySerialization:
+    """Test KnowledgeServiceQuery JSON serialization behavior."""
+
+    def test_knowledge_service_query_json_serialization(self) -> None:
+        """Test that KnowledgeServiceQuery serializes to JSON correctly."""
+        query = KnowledgeServiceQueryFactory.build(
+            query_id="attendee-extractor",
+            name="Meeting Attendee Extractor",
+            knowledge_service_id="ragflow-primary",
+            prompt="Extract meeting attendees with names, roles",
+        )
+
+        json_str = query.model_dump_json()
+        import json
+
+        json_data = json.loads(json_str)
+
+        # All fields should be present in JSON
+        assert json_data["query_id"] == query.query_id
+        assert json_data["name"] == query.name
+        assert json_data["knowledge_service_id"] == query.knowledge_service_id
+        assert json_data["prompt"] == query.prompt
+
+    def test_knowledge_service_query_json_roundtrip(self) -> None:
+        """Test that KnowledgeServiceQuery can be serialized to JSON and
+        deserialized back."""
+        original_query = KnowledgeServiceQueryFactory.build()
+
+        # Serialize to JSON
+        json_str = original_query.model_dump_json()
+        import json
+
+        json_data = json.loads(json_str)
+
+        # Deserialize back to KnowledgeServiceQuery
+        reconstructed_query = KnowledgeServiceQuery(**json_data)
+
+        # Should be equivalent
+        assert reconstructed_query.query_id == original_query.query_id
+        assert reconstructed_query.name == original_query.name
+        assert (
+            reconstructed_query.knowledge_service_id
+            == original_query.knowledge_service_id
+        )
+        assert reconstructed_query.prompt == original_query.prompt
+
+
+class TestKnowledgeServiceQueryDefaults:
+    """Test KnowledgeServiceQuery default values and behavior."""
+
+    def test_knowledge_service_query_default_values(self) -> None:
+        """Test that KnowledgeServiceQuery has correct default values."""
+        minimal_query = KnowledgeServiceQuery(
+            query_id="test-id",
+            name="Test Query",
+            knowledge_service_id="test-service",
+            prompt="Test prompt",
+        )
+
+        assert minimal_query.created_at is not None
+        assert minimal_query.updated_at is not None
+
+    def test_knowledge_service_query_custom_values(self) -> None:
+        """Test KnowledgeServiceQuery with custom non-default values."""
+        custom_query = KnowledgeServiceQuery(
+            query_id="custom-id",
+            name="Custom Query",
+            knowledge_service_id="custom-service",
+            prompt="Custom prompt",
+        )
+
+        assert custom_query.query_id == "custom-id"
+        assert custom_query.name == "Custom Query"
+
+
+class TestKnowledgeServiceQueryMetadata:
+    """Test KnowledgeServiceQuery query_metadata field functionality."""
+
+    def test_query_metadata_defaults_to_empty_dict(self) -> None:
+        """Test that query_metadata defaults to an empty dict."""
+        query = KnowledgeServiceQuery(
+            query_id="test-id",
+            name="Test Query",
+            knowledge_service_id="test-service",
+            prompt="Test prompt",
+        )
+
+        assert query.query_metadata == {}
+
+    def test_query_metadata_accepts_custom_values(self) -> None:
+        """Test that query_metadata can accept custom service values."""
+        metadata = {
+            "model": "claude-sonnet-4-20250514",
+            "max_tokens": 4000,
+            "temperature": 0.1,
+        }
+
+        query = KnowledgeServiceQuery(
+            query_id="test-id",
+            name="Test Query",
+            knowledge_service_id="anthropic-service",
+            prompt="Test prompt",
+            query_metadata=metadata,
+        )
+
+        assert query.query_metadata == metadata
+        assert query.query_metadata["model"] == "claude-sonnet-4-20250514"
+        assert query.query_metadata["max_tokens"] == 4000
+        assert query.query_metadata["temperature"] == 0.1
+
+    def test_query_metadata_serialization(self) -> None:
+        """Test that query_metadata serializes correctly in JSON."""
+        metadata = {
+            "model": "gpt-4",
+            "temperature": 0.2,
+            "top_p": 0.9,
+            "custom_config": {"endpoint": "v2", "retries": 3},
+        }
+
+        query = KnowledgeServiceQuery(
+            query_id="openai-query",
+            name="OpenAI Query",
+            knowledge_service_id="openai-service",
+            prompt="Test prompt for OpenAI",
+            query_metadata=metadata,
+        )
+
+        json_str = query.model_dump_json()
+        import json
+
+        json_data = json.loads(json_str)
+
+        assert json_data["query_metadata"] == metadata
+        assert json_data["query_metadata"]["model"] == "gpt-4"
+        assert json_data["query_metadata"]["custom_config"]["endpoint"] == "v2"
+
+    def test_query_metadata_roundtrip_serialization(self) -> None:
+        """Test query_metadata survives JSON roundtrip serialization."""
+        metadata = {
+            "model": "claude-sonnet-4-20250514",
+            "max_tokens": 2000,
+            "temperature": 0.0,
+            "citations": True,
+        }
+
+        original = KnowledgeServiceQuery(
+            query_id="roundtrip-test",
+            name="Roundtrip Test",
+            knowledge_service_id="test-service",
+            prompt="Test roundtrip serialization",
+            query_metadata=metadata,
+        )
+
+        # Serialize and deserialize
+        json_str = original.model_dump_json()
+        import json
+
+        json_data = json.loads(json_str)
+        reconstructed = KnowledgeServiceQuery(**json_data)
+
+        assert reconstructed.query_metadata == original.query_metadata
+        assert reconstructed.query_metadata == metadata

julee/domain/models/custom_fields/content_stream.py

@@ -0,0 +1,68 @@
+"""
+Custom Pydantic field types for the CEAP workflow domain.
+
+This module contains custom field types that provide proper Pydantic
+validation
+for specialized data types used in the document processing workflow.
+"""
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+from typing import Any
+import io
+
+
+class ContentStream:
+    """Wrapper for IO streams that provides proper Pydantic validation.
+
+    This class wraps io.IOBase instances to provide proper Pydantic validation
+    without requiring arbitrary_types_allowed. It ensures that only valid
+    stream objects are accepted while providing a clean interface for
+    stream operations.
+    """
+
+    def __init__(self, stream: io.IOBase):
+        if not isinstance(stream, io.IOBase):
+            raise ValueError(
+                "ContentStream requires an io.IOBase instance, " + f"got {type(stream)}"
+            )
+        self._stream = stream
+
+    def read(self, size: int = -1) -> bytes:
+        """Read from the underlying stream."""
+        result = self.stream.read(size)
+        if not isinstance(result, bytes):
+            # Handle case where stream returns str (like StringIO)
+            if isinstance(result, str):
+                return result.encode("utf-8")
+            return b""  # Fallback for other types
+        return result
+
+    def seek(self, offset: int, whence: int = 0) -> int:
+        """Seek in the underlying stream."""
+        return self._stream.seek(offset, whence)
+
+    def tell(self) -> int:
+        """Get current position in stream."""
+        return self._stream.tell()
+
+    @property
+    def stream(self) -> io.IOBase:
+        """Access the underlying stream."""
+        return self._stream
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: type, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        """Define how Pydantic should validate this type."""
+        return core_schema.no_info_plain_validator_function(cls._validate)
+
+    @classmethod
+    def _validate(cls, value: Any) -> "ContentStream":
+        """Validate input and convert to ContentStream."""
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, io.IOBase):
+            return cls(value)
+        raise ValueError(f"ContentStream expects io.IOBase, got {type(value)}")

julee/domain/models/custom_fields/tests/test_custom_fields.py

@@ -0,0 +1,53 @@
+"""
+Tests for custom Pydantic field types.
+
+This test module validates the behavior of custom field types used in
+the domain models, particularly focusing on ContentStream which wraps
+io.IOBase instances for proper Pydantic validation.
+
+Design decisions documented:
+- ContentStream accepts any io.IOBase instance
+- ContentStream provides read, seek, tell interface
+- ContentStream validates input types at creation
+- ContentStream works with Pydantic validation without arbitrary_types_allowed
+"""
+
+import pytest
+import io
+from typing import Any
+
+from julee.domain.models.custom_fields.content_stream import (
+    ContentStream,
+)
+
+
+@pytest.mark.parametrize(
+    "stream_input,error_message",
+    [
+        # Valid inputs - io.IOBase instances
+        (io.BytesIO(b"test content"), None),
+        (io.StringIO("text content"), None),
+        (io.BufferedReader(io.BytesIO(b"buffered")), None),
+        (ContentStream(io.BytesIO(b"nested content")).stream, None),
+        # Invalid inputs - not io.IOBase
+        (b"raw bytes", "ContentStream requires an io.IOBase instance"),
+        ("string", "ContentStream requires an io.IOBase instance"),
+        (123, "ContentStream requires an io.IOBase instance"),
+        (None, "ContentStream requires an io.IOBase instance"),
+        ([], "ContentStream requires an io.IOBase instance"),
+        ({}, "ContentStream requires an io.IOBase instance"),
+    ],
+)
+def test_content_stream_validation(
+    stream_input: Any, error_message: str | None
+) -> None:
+    """Test ContentStream validation with various input types including nested
+    streams."""
+    if error_message is None:
+        # Should create successfully
+        content_stream = ContentStream(stream_input)
+        assert content_stream.stream is stream_input
+    else:
+        # Should raise ValueError with specific message
+        with pytest.raises(ValueError, match=error_message):
+            ContentStream(stream_input)

julee/domain/models/document/__init__.py

@@ -0,0 +1,17 @@
+"""
+Document domain package for the Capture, Extract, Assemble, Publish workflow.
+
+This package contains the Document domain object and its related functionality
+for the CEAP workflow system.
+
+Document represents complete document entities including content and metadata,
+providing a stream-like interface for efficient handling of both small and
+large documents.
+"""
+
+from .document import Document, DocumentStatus
+
+__all__ = [
+    "Document",
+    "DocumentStatus",
+]

julee/domain/models/document/document.py

@@ -0,0 +1,150 @@
+"""
+Document domain models for the Capture, Extract, Assemble, Publish workflow.
+
+This module contains the core document domain objects that represent
+documents and their metadata in the CEAP workflow system.
+
+All domain models use Pydantic BaseModel for validation, serialization,
+and type safety, following the patterns established in the sample project.
+"""
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic import ValidationInfo
+from typing import Callable, Optional, List, Dict, Any
+from datetime import datetime, timezone
+from enum import Enum
+from julee.domain.models.custom_fields.content_stream import (
+    ContentStream,
+)
+
+
+def delegate_to_content(*method_names: str) -> Callable[[type], type]:
+    """Decorator to delegate IO methods to the content stream property."""
+
+    def decorator(cls: type) -> type:
+        for method_name in method_names:
+
+            def make_delegated_method(name: str) -> Callable[..., Any]:
+                def delegated_method(self: Any, *args: Any, **kwargs: Any) -> Any:
+                    return getattr(self.content, name)(*args, **kwargs)
+
+                delegated_method.__name__ = name
+                delegated_method.__doc__ = f"Delegate {name} to content stream."
+                return delegated_method
+
+            setattr(cls, method_name, make_delegated_method(method_name))
+        return cls
+
+    return decorator
+
+
+class DocumentStatus(str, Enum):
+    """Status of a document through the Capture, Extract, Assemble, Publish
+    pipeline."""
+
+    CAPTURED = "captured"
+    REGISTERED = "registered"  # Registered with knowledge service
+    # Assembly specification types determined
+    ASSEMBLY_SPECIFICATION_IDENTIFIED = "assembly_specification_identified"
+    EXTRACTED = "extracted"  # Extractions completed
+    ASSEMBLED = "assembled"  # Template rendered and policies applied
+    PUBLISHED = "published"
+    FAILED = "failed"
+
+
+@delegate_to_content("read", "seek", "tell")
+class Document(BaseModel):
+    """Complete document entity including content and metadata.
+
+    This is the primary domain model that represents a complete document
+    in the CEAP workflow system. Content is provided as a ContentStream
+    for efficient handling of both small and large documents.
+
+    The content stream is excluded from JSON serialization - use separate
+    content endpoints for streaming binary data over HTTP.
+    """
+
+    # Core document identification
+    document_id: str
+    original_filename: str
+    content_type: str
+    size_bytes: int = Field(gt=0, description="Size must be positive")
+    content_multihash: str = Field(
+        description="Multihash of document content for integrity verification"
+    )
+
+    # Document processing state
+    status: DocumentStatus = DocumentStatus.CAPTURED
+    knowledge_service_id: Optional[str] = None
+    assembly_types: List[str] = Field(default_factory=list)
+
+    # Timestamps
+    created_at: Optional[datetime] = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Optional[datetime] = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+
+    # Additional data and content stream
+    additional_metadata: Dict[str, Any] = Field(default_factory=dict)
+    content: Optional[ContentStream] = Field(default=None, exclude=True)
+    content_string: Optional[str] = Field(
+        default=None,
+        description="Small content as string (few KB max). Use for "
+        "workflow-generated content to avoid ContentStream serialization "
+        "issues. For larger content, ensure calling from concrete "
+        "implementations (ie. outside workflows and use-cases) and use "
+        "content field instead.",
+    )
+
+    @field_validator("document_id")
+    @classmethod
+    def document_id_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Document ID cannot be empty")
+        return v.strip()
+
+    @field_validator("original_filename")
+    @classmethod
+    def filename_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Original filename cannot be empty")
+        return v.strip()
+
+    @field_validator("content_type")
+    @classmethod
+    def content_type_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Content type cannot be empty")
+        return v.strip()
+
+    @field_validator("content_multihash")
+    @classmethod
+    def content_multihash_must_not_be_empty(cls, v: str) -> str:
+        # TODO: actually validate the multihash against the content?
+        if not v or not v.strip():
+            raise ValueError("Content multihash cannot be empty")
+        return v.strip()
+
+    @model_validator(mode="after")
+    def validate_content_fields(self, info: ValidationInfo) -> "Document":
+        """Ensure document has either content or content_string, not both."""
+        # Check if we're in a Temporal deserialization context
+        if info.context and info.context.get("temporal_validation"):
+            return self
+
+        # Normal validation for direct instantiation
+        has_content = self.content is not None
+        has_content_string = self.content_string is not None
+
+        if has_content and has_content_string:
+            raise ValueError(
+                "Document cannot have both content and content_string. "
+                "Provide only one."
+            )
+        elif not has_content and not has_content_string:
+            raise ValueError(
+                "Document must have either content or content_string. " "Provide one."
+            )
+        return self

julee/domain/models/document/tests/factories.py

@@ -0,0 +1,76 @@
+"""
+Test factories for Document domain objects using factory_boy.
+
+This module provides factory_boy factories for creating test instances of
+Document domain objects with sensible defaults.
+"""
+
+import io
+from datetime import datetime, timezone
+from typing import Any
+from factory.base import Factory
+from factory.faker import Faker
+from factory.declarations import LazyAttribute, LazyFunction
+
+from julee.domain.models.document import Document, DocumentStatus
+from julee.domain.models.custom_fields.content_stream import (
+    ContentStream,
+)
+
+
+# Helper functions to generate content bytes consistently
+def _get_default_content_bytes() -> bytes:
+    """Generate the default content bytes for documents."""
+    return b"Test document content for testing purposes"
+
+
+class ContentStreamFactory(Factory):
+    class Meta:
+        model = ContentStream
+
+    # Create ContentStream with BytesIO containing test content
+    @classmethod
+    def _create(cls, model_class: type[ContentStream], **kwargs: Any) -> ContentStream:
+        content = kwargs.get("content", b"Test stream content")
+        return model_class(io.BytesIO(content))
+
+    @classmethod
+    def _build(cls, model_class: type[ContentStream], **kwargs: Any) -> ContentStream:
+        content = kwargs.get("content", b"Test stream content")
+        return model_class(io.BytesIO(content))
+
+
+class DocumentFactory(Factory):
+    """Factory for creating Document instances with sensible test defaults."""
+
+    class Meta:
+        model = Document
+
+    # Core document identification
+    document_id = Faker("uuid4")
+    original_filename = "test_document.txt"
+    content_type = "text/plain"
+    content_multihash = Faker("sha256")
+
+    # Document processing state
+    status = DocumentStatus.CAPTURED
+    knowledge_service_id = None
+    assembly_types: list[str] = []
+
+    # Timestamps
+    created_at = LazyFunction(lambda: datetime.now(timezone.utc))
+    updated_at = LazyFunction(lambda: datetime.now(timezone.utc))
+
+    # Additional data
+    additional_metadata: dict[str, Any] = {}
+
+    # Content - using LazyAttribute to create fresh BytesIO for each instance
+    @LazyAttribute
+    def size_bytes(self) -> int:
+        # Calculate size from the default content
+        return len(_get_default_content_bytes())
+
+    @LazyAttribute
+    def content(self) -> ContentStream:
+        # Create ContentStream with default content
+        return ContentStream(io.BytesIO(_get_default_content_bytes()))