julee 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,297 @@
+"""
+Comprehensive tests for Document domain model.
+
+This test module documents the design decisions made for the Document domain
+model
+using table-based tests. It covers:
+
+- Document instantiation with various field combinations
+- Content stream operations (read, seek, tell)
+- Validation rules and error conditions
+- JSON serialization behavior
+- Stream-like interface compatibility
+
+Design decisions documented:
+- Documents must have all required fields
+- Content streams are excluded from JSON serialization
+- Size must be positive, filenames and content types non-empty
+- Multihash is required and non-empty
+- Documents act as readable streams with standard methods
+"""
+
+import pytest
+import json
+
+from julee.domain.models.document import Document
+from .factories import DocumentFactory, ContentStreamFactory
+
+
+class TestDocumentInstantiation:
+    """Test Document creation with various field combinations."""
+
+    @pytest.mark.parametrize(
+        "document_id,original_filename,content_type,size_bytes,multihash,expected_success",
+        [
+            # Valid cases
+            ("doc-1", "test.txt", "text/plain", 100, "sha256:hash", True),
+            (
+                "doc-2",
+                "document.pdf",
+                "application/pdf",
+                1024,
+                "sha256:pdf-hash",
+                True,
+            ),
+            (
+                "doc-3",
+                "data.json",
+                "application/json",
+                50,
+                "sha256:json-hash",
+                True,
+            ),
+            # Invalid cases - empty required fields
+            (
+                "",
+                "test.txt",
+                "text/plain",
+                100,
+                "sha256:hash",
+                False,
+            ),  # Empty document_id
+            (
+                "doc-4",
+                "",
+                "text/plain",
+                100,
+                "sha256:hash",
+                False,
+            ),  # Empty filename
+            (
+                "doc-5",
+                "test.txt",
+                "",
+                100,
+                "sha256:hash",
+                False,
+            ),  # Empty content_type
+            (
+                "doc-6",
+                "test.txt",
+                "text/plain",
+                100,
+                "",
+                False,
+            ),  # Empty multihash
+            # Invalid cases - whitespace only
+            (
+                "   ",
+                "test.txt",
+                "text/plain",
+                100,
+                "sha256:hash",
+                False,
+            ),  # Whitespace document_id
+            (
+                "doc-7",
+                "   ",
+                "text/plain",
+                100,
+                "sha256:hash",
+                False,
+            ),  # Whitespace filename
+            (
+                "doc-8",
+                "test.txt",
+                "   ",
+                100,
+                "sha256:hash",
+                False,
+            ),  # Whitespace content_type
+            (
+                "doc-9",
+                "test.txt",
+                "text/plain",
+                100,
+                "   ",
+                False,
+            ),  # Whitespace multihash
+            # Invalid cases - size validation
+            (
+                "doc-10",
+                "test.txt",
+                "text/plain",
+                0,
+                "sha256:hash",
+                False,
+            ),  # Zero size
+            (
+                "doc-11",
+                "test.txt",
+                "text/plain",
+                -1,
+                "sha256:hash",
+                False,
+            ),  # Negative size
+        ],
+    )
+    def test_document_creation_validation(
+        self,
+        document_id: str,
+        original_filename: str,
+        content_type: str,
+        size_bytes: int,
+        multihash: str,
+        expected_success: bool,
+    ) -> None:
+        """Test document creation with various field validation scenarios."""
+        content_stream = ContentStreamFactory.build()
+
+        if expected_success:
+            # Should create successfully
+            doc = Document(
+                document_id=document_id,
+                original_filename=original_filename,
+                content_type=content_type,
+                size_bytes=size_bytes,
+                content_multihash=multihash,
+                content=content_stream,
+            )
+            assert doc.document_id == document_id
+            assert doc.original_filename.strip() == original_filename.strip()
+            assert doc.content_type.strip() == content_type.strip()
+            assert doc.size_bytes == size_bytes
+            assert doc.content_multihash.strip() == multihash.strip()
+        else:
+            # Should raise validation error
+            with pytest.raises(Exception):  # Could be ValueError or ValidationError
+                Document(
+                    document_id=document_id,
+                    original_filename=original_filename,
+                    content_type=content_type,
+                    size_bytes=size_bytes,
+                    content_multihash=multihash,
+                    content=ContentStreamFactory.build(),
+                )
+
+
+class TestDocumentSerialization:
+    """Test Document JSON serialization behavior."""
+
+    def test_document_json_excludes_content(self) -> None:
+        """Test that content stream is excluded from JSON serialization."""
+        content = b"Secret content not for JSON"
+        content_stream = ContentStreamFactory.build(content=content)
+        doc = DocumentFactory.build(content=content_stream, size_bytes=len(content))
+
+        json_str = doc.model_dump_json()
+        json_data = json.loads(json_str)
+
+        # Content should not be in JSON
+        assert "content" not in json_data
+
+        # But all other fields should be present
+        assert json_data["document_id"] == doc.document_id
+        assert json_data["original_filename"] == doc.original_filename
+        assert json_data["content_type"] == doc.content_type
+        assert json_data["size_bytes"] == doc.size_bytes
+        assert json_data["content_multihash"] == doc.content_multihash
+        assert json_data["status"] == doc.status.value
+
+
+class TestDocumentContentValidation:
+    """Test Document content and content_string validation rules."""
+
+    def test_document_with_both_content_and_content_string_fails(
+        self,
+    ) -> None:
+        """Test that both content and content_string raises error."""
+        content_stream = ContentStreamFactory.build()
+        content_string = '{"type": "string"}'
+
+        with pytest.raises(
+            ValueError, match="cannot have both content and content_string"
+        ):
+            Document(
+                document_id="test-doc-both",
+                original_filename="both.json",
+                content_type="application/json",
+                size_bytes=100,
+                content_multihash="test_hash",
+                content=content_stream,
+                content_string=content_string,
+            )
+
+    def test_document_without_content_or_content_string_fails(self) -> None:
+        """Test that no content or content_string raises error."""
+        with pytest.raises(
+            ValueError, match="must have either content or content_string"
+        ):
+            Document(
+                document_id="test-doc-no-content",
+                original_filename="empty.json",
+                content_type="application/json",
+                size_bytes=100,
+                content_multihash="test_hash",
+                content=None,
+                content_string=None,
+            )
+
+    def test_document_with_content_only_succeeds(self) -> None:
+        """Test that document with only content field succeeds."""
+        content_stream = ContentStreamFactory.build()
+
+        doc = Document(
+            document_id="test-doc-content",
+            original_filename="content.json",
+            content_type="application/json",
+            size_bytes=100,
+            content_multihash="test_hash",
+            content=content_stream,
+            content_string=None,
+        )
+
+        assert doc.content is not None
+        assert doc.content_string is None
+
+    def test_document_with_content_string_only_succeeds(self) -> None:
+        """Test that document with only content_string field succeeds."""
+        content_string = '{"type": "string"}'
+
+        doc = Document(
+            document_id="test-doc-string",
+            original_filename="string.json",
+            content_type="application/json",
+            size_bytes=100,
+            content_multihash="test_hash",
+            content=None,
+            content_string=content_string,
+        )
+
+        assert doc.content is None
+        assert doc.content_string == content_string
+
+    def test_document_deserialization_with_empty_content_succeeds(
+        self,
+    ) -> None:
+        """Test Temporal deserialization allows empty content."""
+        # This simulates what happens when a Document comes back from Temporal
+        # activities - the ContentStream is excluded from serialization
+        document_data = {
+            "document_id": "test-temporal",
+            "original_filename": "temporal.json",
+            "content_type": "application/json",
+            "size_bytes": 100,
+            "content_multihash": "test_hash",
+            "content": None,
+            "content_string": None,
+        }
+
+        # Should succeed with temporal_validation context
+        doc = Document.model_validate(
+            document_data, context={"temporal_validation": True}
+        )
+
+        assert doc.document_id == "test-temporal"
+        assert doc.content is None
+        assert doc.content_string is None

julee/domain/models/knowledge_service_config/__init__.py

@@ -0,0 +1,17 @@
+"""
+Knowledge Service domain models for julee domain.
+
+This module exports domain models for knowledge services in the Capture,
+Extract, Assemble, Publish workflow. Knowledge services represent external
+AI/ML services that can store documents and execute queries against them.
+"""
+
+from .knowledge_service_config import (
+    KnowledgeServiceConfig,
+    ServiceApi,
+)
+
+__all__ = [
+    "KnowledgeServiceConfig",
+    "ServiceApi",
+]

julee/domain/models/knowledge_service_config/knowledge_service_config.py

@@ -0,0 +1,86 @@
+"""
+KnowledgeService domain models for the Capture, Extract, Assemble,
+Publish workflow.
+
+This module contains the KnowledgeService domain object that represents
+knowledge services in the CEAP workflow system.
+
+A KnowledgeService defines a service that can store documents and execute
+queries against them. It acts as an interface to external AI/ML services
+that can analyze and extract information from documents.
+
+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
+from typing import Optional
+from datetime import datetime, timezone
+from enum import Enum
+
+
+class ServiceApi(str, Enum):
+    """Supported knowledge service APIs."""
+
+    ANTHROPIC = "anthropic"
+
+
+class KnowledgeServiceConfig(BaseModel):
+    """Knowledge service configuration that defines how to interact with
+    an external knowledge/AI service.
+
+    A KnowledgeServiceConfig represents a service endpoint that can store
+    documents and execute queries against them. This could be an AI service,
+    vector database, search engine, or any other service that can analyze
+    documents and answer questions about them.
+    """
+
+    # Core service identification
+    knowledge_service_id: str = Field(
+        description="Unique identifier for this knowledge service"
+    )
+    name: str = Field(description="Human-readable name for the knowledge service")
+    description: str = Field(
+        description="Description of what this knowledge service does"
+    )
+    service_api: ServiceApi = Field(
+        description="The external API/service this knowledge service uses"
+    )
+
+    # 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)
+    )
+
+    @field_validator("knowledge_service_id")
+    @classmethod
+    def knowledge_service_id_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Knowledge service ID cannot be empty")
+        return v.strip()
+
+    @field_validator("name")
+    @classmethod
+    def name_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Knowledge service name cannot be empty")
+        return v.strip()
+
+    @field_validator("description")
+    @classmethod
+    def description_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Knowledge service description cannot be empty")
+        return v.strip()
+
+    @field_validator("service_api")
+    @classmethod
+    def service_api_must_be_valid(cls, v: ServiceApi) -> ServiceApi:
+        if v not in ServiceApi:
+            raise ValueError(
+                f"Invalid service API: {v}. Must be one of {list(ServiceApi)}"
+            )
+        return v

julee/domain/models/policy/__init__.py

@@ -0,0 +1,15 @@
+from .policy import (
+    Policy,
+    PolicyStatus,
+)
+from .document_policy_validation import (
+    DocumentPolicyValidation,
+    DocumentPolicyValidationStatus,
+)
+
+__all__ = [
+    "Policy",
+    "PolicyStatus",
+    "DocumentPolicyValidation",
+    "DocumentPolicyValidationStatus",
+]

julee/domain/models/policy/document_policy_validation.py

@@ -0,0 +1,220 @@
+"""
+DocumentPolicyValidation domain models for the Capture, Extract, Assemble,
+Publish workflow.
+
+This module contains the DocumentPolicyValidation domain object that
+represents
+the result of validating a document against a policy configuration in the CEAP
+workflow system.
+
+A DocumentPolicyValidation captures the complete validation process including:
+- The document being validated and the policy used
+- Actual validation scores achieved against policy criteria
+- Optional transformation results and post-transformation scores
+- Status tracking throughout the validation lifecycle
+
+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
+from typing import Optional, List, Tuple
+from datetime import datetime, timezone
+from enum import Enum
+
+
+class DocumentPolicyValidationStatus(str, Enum):
+    """Status of a document policy validation process."""
+
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    VALIDATION_COMPLETE = "validation_complete"
+    TRANSFORMATION_REQUIRED = "transformation_required"
+    TRANSFORMATION_IN_PROGRESS = "transformation_in_progress"
+    TRANSFORMATION_COMPLETE = "transformation_complete"
+    PASSED = "passed"
+    FAILED = "failed"
+    ERROR = "error"
+
+
+class DocumentPolicyValidation(BaseModel):
+    """Represents the validation of a document against a policy configuration.
+
+    A DocumentPolicyValidation tracks the complete lifecycle of validating
+    a document against policy criteria. It includes:
+
+    1. Initial validation: Document is scored against policy validation
+       queries
+    2. Optional transformation: If policy includes transformation queries and
+       initial validation fails, transformations are applied
+    3. Re-validation: Transformed document is re-scored against policy
+       criteria
+    4. Final determination: Pass/fail based on final validation scores
+
+    The validation process supports both validation-only policies and policies
+    that include transformations for document quality improvement.
+    """
+
+    # Core validation identification
+    validation_id: str = Field(
+        description="Unique identifier for this validation instance"
+    )
+    input_document_id: str = Field(
+        description="ID of the document being validated against the policy"
+    )
+    policy_id: str = Field(
+        description="ID of the policy configuration used for validation"
+    )
+
+    # Validation process status
+    status: DocumentPolicyValidationStatus = DocumentPolicyValidationStatus.PENDING
+
+    # Initial validation results
+    validation_scores: List[Tuple[str, int]] = Field(
+        default_factory=list,
+        description="List of (knowledge_service_query_id, actual_score) "
+        "tuples representing the scores achieved during initial validation. "
+        "Scores are between 0 and 100",
+    )
+
+    # Transformation results (if applicable)
+    transformed_document_id: Optional[str] = Field(
+        default=None,
+        description="ID of the document after transformations have been "
+        "applied. Only present if the policy includes transformation queries "
+        "and they were executed",
+    )
+    post_transform_validation_scores: Optional[List[Tuple[str, int]]] = Field(
+        default=None,
+        description="List of (knowledge_service_query_id, actual_score) "
+        "tuples representing scores achieved after transformation. "
+        "Only present if transformations were applied and re-validation "
+        "occurred",
+    )
+
+    # Validation metadata
+    started_at: Optional[datetime] = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        description="When the validation process was initiated",
+    )
+    completed_at: Optional[datetime] = Field(
+        default=None, description="When the validation process completed"
+    )
+    error_message: Optional[str] = Field(
+        default=None, description="Error message if validation process failed"
+    )
+
+    # Results summary
+    passed: Optional[bool] = Field(
+        default=None,
+        description="Whether the document passed policy validation. "
+        "None while validation is in progress, True/False when complete",
+    )
+
+    @field_validator("input_document_id")
+    @classmethod
+    def input_document_id_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Input document ID cannot be empty")
+        return v.strip()
+
+    @field_validator("policy_id")
+    @classmethod
+    def policy_id_must_not_be_empty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("Policy ID cannot be empty")
+        return v.strip()
+
+    @field_validator("validation_scores")
+    @classmethod
+    def validation_scores_must_be_valid(
+        cls, v: List[Tuple[str, int]]
+    ) -> List[Tuple[str, int]]:
+        if not isinstance(v, list):
+            raise ValueError("Validation scores must be a list")
+
+        # Empty list is valid for pending validations
+        if not v:
+            return v
+
+        return cls._validate_score_tuples(v, "validation_scores")
+
+    @field_validator("post_transform_validation_scores")
+    @classmethod
+    def post_transform_scores_must_be_valid(
+        cls, v: Optional[List[Tuple[str, int]]]
+    ) -> Optional[List[Tuple[str, int]]]:
+        if v is None:
+            return v
+
+        if not isinstance(v, list):
+            raise ValueError("Post-transform validation scores must be a list or None")
+
+        # Empty list is valid
+        if not v:
+            return v
+
+        return cls._validate_score_tuples(v, "post_transform_validation_scores")
+
+    @field_validator("error_message")
+    @classmethod
+    def error_message_must_be_valid(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        if not isinstance(v, str):
+            raise ValueError("Error message must be a string or None")
+        return v.strip() if v.strip() else None
+
+    @field_validator("transformed_document_id")
+    @classmethod
+    def transformed_document_id_must_be_valid(cls, v: Optional[str]) -> Optional[str]:
+        if v is None:
+            return v
+        if not isinstance(v, str) or not v.strip():
+            raise ValueError(
+                "Transformed document ID must be a non-empty string or None"
+            )
+        return v.strip()
+
+    @classmethod
+    def _validate_score_tuples(
+        cls, scores: List[Tuple[str, int]], field_name: str
+    ) -> List[Tuple[str, int]]:
+        """Helper method to validate score tuple lists."""
+        validated_scores = []
+        query_ids_seen = set()
+
+        for item in scores:
+            if not isinstance(item, tuple) or len(item) != 2:
+                raise ValueError(
+                    f"Each item in {field_name} must be a 2-tuple of "
+                    f"(query_id, actual_score)"
+                )
+
+            query_id, actual_score = item
+
+            # Validate query ID
+            if not isinstance(query_id, str) or not query_id.strip():
+                raise ValueError(f"Query ID in {field_name} must be a non-empty string")
+            query_id = query_id.strip()
+
+            # Check for duplicate query IDs within this field
+            if query_id in query_ids_seen:
+                raise ValueError(f"Duplicate query ID '{query_id}' in {field_name}")
+            query_ids_seen.add(query_id)
+
+            # Validate actual score
+            if not isinstance(actual_score, int):
+                raise ValueError(
+                    f"Actual score in {field_name} must be an integer "
+                    f"between 0 and 100"
+                )
+            if actual_score < 0 or actual_score > 100:
+                raise ValueError(
+                    f"Actual score {actual_score} in {field_name} must be "
+                    f"between 0 and 100"
+                )
+
+            validated_scores.append((query_id, actual_score))
+
+        return validated_scores