julee 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

julee/domain/models/document/document.py

@@ -8,11 +8,13 @@ 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 collections.abc import Callable
 from datetime import datetime, timezone
 from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, ValidationInfo, field_validator, model_validator
+
 from julee.domain.models.custom_fields.content_stream import (
     ContentStream,
 )
@@ -75,21 +77,21 @@ class Document(BaseModel):
 
     # Document processing state
     status: DocumentStatus = DocumentStatus.CAPTURED
-    knowledge_service_id: Optional[str] = None
-    assembly_types: List[str] = Field(default_factory=list)
+    knowledge_service_id: str | None = None
+    assembly_types: list[str] = Field(default_factory=list)
 
     # Timestamps
-    created_at: Optional[datetime] = Field(
+    created_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
-    updated_at: Optional[datetime] = Field(
+    updated_at: datetime | None = 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(
+    additional_metadata: dict[str, Any] = Field(default_factory=dict)
+    content: ContentStream | None = Field(default=None, exclude=True)
+    content_string: str | None = Field(
         default=None,
         description="Small content as string (few KB max). Use for "
         "workflow-generated content to avoid ContentStream serialization "

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

@@ -8,14 +8,15 @@ 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 factory.faker import Faker
 
-from julee.domain.models.document import Document, DocumentStatus
 from julee.domain.models.custom_fields.content_stream import (
     ContentStream,
 )
+from julee.domain.models.document import Document, DocumentStatus
 
 
 # Helper functions to generate content bytes consistently

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

@@ -19,11 +19,14 @@ Design decisions documented:
 - Documents act as readable streams with standard methods
 """
 
-import pytest
 import json
 
+import pytest
+from pydantic import ValidationError
+
 from julee.domain.models.document import Document
-from .factories import DocumentFactory, ContentStreamFactory
+
+from .factories import ContentStreamFactory, DocumentFactory
 
 
 class TestDocumentInstantiation:
@@ -164,7 +167,7 @@ class TestDocumentInstantiation:
             assert doc.content_multihash.strip() == multihash.strip()
         else:
             # Should raise validation error
-            with pytest.raises(Exception):  # Could be ValueError or ValidationError
+            with pytest.raises((ValueError, ValidationError)):
                 Document(
                     document_id=document_id,
                     original_filename=original_filename,

julee/domain/models/knowledge_service_config/knowledge_service_config.py

@@ -13,11 +13,11 @@ 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
 
+from pydantic import BaseModel, Field, field_validator
+
 
 class ServiceApi(str, Enum):
     """Supported knowledge service APIs."""
@@ -48,10 +48,10 @@ class KnowledgeServiceConfig(BaseModel):
     )
 
     # Timestamps
-    created_at: Optional[datetime] = Field(
+    created_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
-    updated_at: Optional[datetime] = Field(
+    updated_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
 

julee/domain/models/policy/__init__.py

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

julee/domain/models/policy/document_policy_validation.py

@@ -17,11 +17,11 @@ 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
 
+from pydantic import BaseModel, Field, field_validator
+
 
 class DocumentPolicyValidationStatus(str, Enum):
     """Status of a document policy validation process."""
@@ -70,7 +70,7 @@ class DocumentPolicyValidation(BaseModel):
     status: DocumentPolicyValidationStatus = DocumentPolicyValidationStatus.PENDING
 
     # Initial validation results
-    validation_scores: List[Tuple[str, int]] = Field(
+    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. "
@@ -78,13 +78,13 @@ class DocumentPolicyValidation(BaseModel):
     )
 
     # Transformation results (if applicable)
-    transformed_document_id: Optional[str] = Field(
+    transformed_document_id: str | None = 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(
+    post_transform_validation_scores: list[tuple[str, int]] | None = Field(
         default=None,
         description="List of (knowledge_service_query_id, actual_score) "
         "tuples representing scores achieved after transformation. "
@@ -93,19 +93,19 @@ class DocumentPolicyValidation(BaseModel):
     )
 
     # Validation metadata
-    started_at: Optional[datetime] = Field(
+    started_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc),
         description="When the validation process was initiated",
     )
-    completed_at: Optional[datetime] = Field(
+    completed_at: datetime | None = Field(
         default=None, description="When the validation process completed"
     )
-    error_message: Optional[str] = Field(
+    error_message: str | None = Field(
         default=None, description="Error message if validation process failed"
     )
 
     # Results summary
-    passed: Optional[bool] = Field(
+    passed: bool | None = Field(
         default=None,
         description="Whether the document passed policy validation. "
         "None while validation is in progress, True/False when complete",
@@ -128,8 +128,8 @@ class DocumentPolicyValidation(BaseModel):
     @field_validator("validation_scores")
     @classmethod
     def validation_scores_must_be_valid(
-        cls, v: List[Tuple[str, int]]
-    ) -> List[Tuple[str, int]]:
+        cls, v: list[tuple[str, int]]
+    ) -> list[tuple[str, int]]:
         if not isinstance(v, list):
             raise ValueError("Validation scores must be a list")
 
@@ -142,8 +142,8 @@ class DocumentPolicyValidation(BaseModel):
     @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]]]:
+        cls, v: list[tuple[str, int]] | None
+    ) -> list[tuple[str, int]] | None:
         if v is None:
             return v
 
@@ -158,7 +158,7 @@ class DocumentPolicyValidation(BaseModel):
 
     @field_validator("error_message")
     @classmethod
-    def error_message_must_be_valid(cls, v: Optional[str]) -> Optional[str]:
+    def error_message_must_be_valid(cls, v: str | None) -> str | None:
         if v is None:
             return v
         if not isinstance(v, str):
@@ -167,7 +167,7 @@ class DocumentPolicyValidation(BaseModel):
 
     @field_validator("transformed_document_id")
     @classmethod
-    def transformed_document_id_must_be_valid(cls, v: Optional[str]) -> Optional[str]:
+    def transformed_document_id_must_be_valid(cls, v: str | None) -> str | None:
         if v is None:
             return v
         if not isinstance(v, str) or not v.strip():
@@ -178,8 +178,8 @@ class DocumentPolicyValidation(BaseModel):
 
     @classmethod
     def _validate_score_tuples(
-        cls, scores: List[Tuple[str, int]], field_name: str
-    ) -> List[Tuple[str, int]]:
+        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()

julee/domain/models/policy/policy.py

@@ -13,11 +13,11 @@ 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
 
+from pydantic import BaseModel, Field, field_validator
+
 
 class PolicyStatus(str, Enum):
     """Status of a policy configuration."""
@@ -38,9 +38,11 @@ class Policy(BaseModel):
     be applied to improve document quality before re-validation.
 
     The policy operates in two modes:
+
     1. Validation-only: Calculates scores and passes/fails based on criteria
     2. Validation with transformation: Calculates scores, applies
        transformations, then re-calculates scores for final pass/fail
+
     """
 
     # Core policy identification
@@ -53,12 +55,12 @@ class Policy(BaseModel):
 
     # Policy configuration
     status: PolicyStatus = PolicyStatus.ACTIVE
-    validation_scores: List[Tuple[str, int]] = Field(
+    validation_scores: list[tuple[str, int]] = Field(
         description="List of (knowledge_service_query_id, required_score) "
         "tuples where required_score is between 0 and 100. All scores "
         "must be met or exceeded for the policy to pass"
     )
-    transformation_queries: Optional[List[str]] = Field(
+    transformation_queries: list[str] | None = Field(
         default=None,
         description="Optional list of knowledge service query IDs for "
         "transformations to apply before re-validation. If not provided "
@@ -67,10 +69,10 @@ class Policy(BaseModel):
 
     # Policy metadata
     version: str = Field(default="0.1.0", description="Policy version")
-    created_at: Optional[datetime] = Field(
+    created_at: datetime | None = Field(
         default_factory=lambda: datetime.now(timezone.utc)
     )
-    updated_at: Optional[datetime] = Field(default=None)
+    updated_at: datetime | None = Field(default=None)
 
     @field_validator("policy_id")
     @classmethod
@@ -96,8 +98,8 @@ class Policy(BaseModel):
     @field_validator("validation_scores")
     @classmethod
     def validation_scores_must_be_valid(
-        cls, v: List[Tuple[str, int]]
-    ) -> List[Tuple[str, int]]:
+        cls, v: list[tuple[str, int]]
+    ) -> list[tuple[str, int]]:
         if not isinstance(v, list):
             raise ValueError("Validation scores must be a list")
 
@@ -145,8 +147,8 @@ class Policy(BaseModel):
     @field_validator("transformation_queries")
     @classmethod
     def transformation_queries_must_be_valid(
-        cls, v: Optional[List[str]]
-    ) -> Optional[List[str]]:
+        cls, v: list[str] | None
+    ) -> list[str] | None:
         if v is None:
             return v
 

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

@@ -6,9 +6,10 @@ Policy domain objects with sensible defaults.
 """
 
 from datetime import datetime, timezone
+
 from factory.base import Factory
-from factory.faker import Faker
 from factory.declarations import LazyFunction
+from factory.faker import Faker
 
 from julee.domain.models.policy import (
     DocumentPolicyValidation,

julee/domain/models/policy/tests/test_document_policy_validation.py

@@ -13,14 +13,16 @@ Tests focus on:
 - Edge cases and error conditions
 """
 
-import pytest
 from datetime import datetime, timezone
+
+import pytest
 from pydantic import ValidationError
 
 from julee.domain.models.policy import (
     DocumentPolicyValidation,
     DocumentPolicyValidationStatus,
 )
+
 from .factories import DocumentPolicyValidationFactory
 
 

julee/domain/models/policy/tests/test_policy.py

@@ -5,8 +5,9 @@ These tests verify the behavior of Policy domain objects,
 including validation, serialization, and business logic.
 """
 
-import pytest
 from datetime import datetime, timezone
+
+import pytest
 from pydantic import ValidationError
 
 from julee.domain.models.policy import (

julee/domain/repositories/__init__.py

@@ -6,14 +6,14 @@ Extract, Assemble, Publish workflow, following the Clean Architecture
 patterns established in the Fun-Police framework.
 """
 
-from .base import BaseRepository
-from .document import DocumentRepository
 from .assembly import AssemblyRepository
 from .assembly_specification import AssemblySpecificationRepository
+from .base import BaseRepository
+from .document import DocumentRepository
+from .document_policy_validation import DocumentPolicyValidationRepository
 from .knowledge_service_config import KnowledgeServiceConfigRepository
 from .knowledge_service_query import KnowledgeServiceQueryRepository
 from .policy import PolicyRepository
-from .document_policy_validation import DocumentPolicyValidationRepository
 
 __all__ = [
     "BaseRepository",

julee/domain/repositories/assembly.py

@@ -27,8 +27,10 @@ In Temporal workflow contexts, these protocols are implemented by workflow
 stubs that delegate to activities for durability and proper error handling.
 """
 
-from typing import runtime_checkable, Protocol
+from typing import Protocol, runtime_checkable
+
 from julee.domain.models import Assembly
+
 from .base import BaseRepository
 
 

julee/domain/repositories/assembly_specification.py

@@ -30,9 +30,11 @@ stubs that delegate to activities for durability and proper error handling.
 """
 
 from typing import Protocol, runtime_checkable
+
 from julee.domain.models.assembly_specification import (
     AssemblySpecification,
 )
+
 from .base import BaseRepository
 
 

julee/domain/repositories/base.py

@@ -23,7 +23,8 @@ In Temporal workflow contexts, these protocols are implemented by workflow
 stubs that delegate to activities for durability and proper error handling.
 """
 
-from typing import Protocol, Optional, runtime_checkable, TypeVar, List, Dict
+from typing import Protocol, TypeVar, runtime_checkable
+
 from pydantic import BaseModel
 
 # Type variable bound to Pydantic BaseModel for domain entities
@@ -42,7 +43,7 @@ class BaseRepository(Protocol[T]):
         T: The domain entity type (must extend Pydantic BaseModel)
     """
 
-    async def get(self, entity_id: str) -> Optional[T]:
+    async def get(self, entity_id: str) -> T | None:
         """Retrieve an entity by ID.
 
         Args:
@@ -51,14 +52,16 @@ class BaseRepository(Protocol[T]):
         Returns:
             Entity if found, None otherwise
 
-        Implementation Notes:
+        .. rubric:: Implementation Notes
+
         - Must be idempotent: multiple calls return same result
         - Should handle missing entities gracefully (return None)
         - Loads complete entity with all relationships
+
         """
         ...
 
-    async def get_many(self, entity_ids: List[str]) -> Dict[str, Optional[T]]:
+    async def get_many(self, entity_ids: list[str]) -> dict[str, T | None]:
         """Retrieve multiple entities by ID.
 
         Args:
@@ -67,7 +70,8 @@ class BaseRepository(Protocol[T]):
         Returns:
             Dict mapping entity_id to entity (or None if not found)
 
-        Implementation Notes:
+        .. rubric:: Implementation Notes
+
         - Must be idempotent: multiple calls return same result
         - Should handle missing entities gracefully (return None for missing)
         - Implementations may optimize with batch operations or fall back
@@ -75,10 +79,12 @@ class BaseRepository(Protocol[T]):
         - Keys in returned dict correspond exactly to input entity_ids
         - Missing entities have None values in the returned dict
 
-        Workflow Context:
+        .. rubric:: Workflow Context
+
         In Temporal workflows, this method is implemented as an activity
         to ensure batch operations are durably stored and consistent
         across workflow replays.
+
         """
         ...
 
@@ -88,38 +94,46 @@ class BaseRepository(Protocol[T]):
         Args:
             entity: Complete entity to save
 
-        Implementation Notes:
+        .. rubric:: Implementation Notes
+
         - Must be idempotent: saving same entity state is safe
         - Should update the updated_at timestamp
         - Must save complete entity with all relationships
         - Handles both new entities and updates to existing ones
+
         """
         ...
 
-    async def list_all(self) -> List[T]:
+    async def list_all(self) -> list[T]:
         """List all entities.
 
         Returns:
             List of all entities in the repository
 
-        Implementation Notes:
+        .. rubric:: Implementation Notes
+
         - Must be idempotent: multiple calls return same result
         - Returns empty list if no entities exist
         - Should return entities in a consistent order (e.g., by ID)
         - For large datasets, consider pagination at the use case level
 
-        Workflow Context:
+        .. rubric:: Workflow Context
+
         In Temporal workflows, this method is implemented as an activity
         to ensure the list operation is durably stored and consistent
         across workflow replays.
 
-        Default Implementation:
+        .. rubric:: Default Implementation
+
         Base protocol provides a default that returns empty list.
         Repository implementations should override this method as needed.
 
-        TODO: This default implementation returns empty list to avoid
-        breaking existing repositories. Specific repositories should
-        implement proper list_all() functionality as needed.
+        .. note::
+
+            This default implementation returns empty list to avoid
+            breaking existing repositories. Specific repositories should
+            implement proper list_all() functionality as needed.
+
         """
         return []
 
@@ -132,15 +146,18 @@ class BaseRepository(Protocol[T]):
         Returns:
             Unique entity ID string
 
-        Implementation Notes:
+        .. rubric:: Implementation Notes
+
         - Must generate globally unique identifiers
         - May use UUIDs, database sequences, or distributed ID generators
         - Should be fast and reliable
         - Failure here should be rare but handled gracefully
 
-        Workflow Context:
+        .. rubric:: Workflow Context
+
         In Temporal workflows, this method is implemented as an activity
         to ensure the generated ID is durably stored and consistent
         across workflow replays.
+
         """
         ...

julee/domain/repositories/document.py

@@ -29,8 +29,10 @@ In Temporal workflow contexts, these protocols are implemented by workflow
 stubs that delegate to activities for durability and proper error handling.
 """
 
-from typing import runtime_checkable, Protocol
+from typing import Protocol, runtime_checkable
+
 from julee.domain.models import Document
+
 from .base import BaseRepository
 
 

julee/domain/repositories/document_policy_validation.py

@@ -29,8 +29,10 @@ In Temporal workflow contexts, these protocols are implemented by workflow
 stubs that delegate to activities for durability and proper error handling.
 """
 
-from typing import runtime_checkable, Protocol
+from typing import Protocol, runtime_checkable
+
 from julee.domain.models.policy import DocumentPolicyValidation
+
 from .base import BaseRepository
 
 

julee/domain/repositories/knowledge_service_config.py

@@ -31,9 +31,11 @@ stubs that delegate to activities for durability and proper error handling.
 """
 
 from typing import Protocol, runtime_checkable
+
 from julee.domain.models.knowledge_service_config import (
     KnowledgeServiceConfig,
 )
+
 from .base import BaseRepository
 
 

julee/domain/repositories/knowledge_service_query.py

@@ -25,6 +25,7 @@ from typing import Protocol, runtime_checkable
 from julee.domain.models.assembly_specification import (
     KnowledgeServiceQuery,
 )
+
 from .base import BaseRepository
 
 

julee/domain/repositories/policy.py

@@ -29,8 +29,10 @@ In Temporal workflow contexts, these protocols are implemented by workflow
 stubs that delegate to activities for durability and proper error handling.
 """
 
-from typing import runtime_checkable, Protocol
+from typing import Protocol, runtime_checkable
+
 from julee.domain.models import Policy
+
 from .base import BaseRepository
 
 

julee/domain/use_cases/decorators.py

@@ -7,8 +7,9 @@ following the patterns established in the sample use cases.
 """
 
 import logging
+from collections.abc import Awaitable, Callable
 from functools import wraps
-from typing import Any, Callable, Dict, Optional, TypeVar, Awaitable
+from typing import Any, TypeVar
 
 logger = logging.getLogger(__name__)
 
@@ -17,7 +18,7 @@ F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
 
 def try_use_case_step(
     step_name: str,
-    extra_context: Optional[Dict[str, Any]] = None,
+    extra_context: dict[str, Any] | None = None,
 ) -> Callable[[F], F]:
     """
     Decorator that wraps use case steps with consistent error handling and