julee 0.1.0__py3-none-any.whl

julee/domain/repositories/base.py

@@ -0,0 +1,146 @@
+"""
+Generic base repository protocol for common CRUD operations.
+
+This module defines a generic BaseRepository protocol that captures the common
+patterns shared across all domain repositories in the Capture, Extract,
+Assemble, Publish workflow. This reduces code duplication while maintaining
+type safety and clean interfaces.
+
+All repository operations follow the same principles:
+
+- **Idempotency**: All methods are designed to be idempotent and safe for
+  retry. Multiple calls with the same parameters will produce the same
+  result without unintended side effects.
+
+- **Workflow Safety**: All operations are safe to call from deterministic
+  workflow contexts. Non-deterministic operations (like ID generation) are
+  explicitly delegated to activities.
+
+- **Domain Objects**: Methods accept and return domain objects or primitives,
+  never framework-specific types.
+
+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 pydantic import BaseModel
+
+# Type variable bound to Pydantic BaseModel for domain entities
+T = TypeVar("T", bound=BaseModel)
+
+
+@runtime_checkable
+class BaseRepository(Protocol[T]):
+    """Generic base repository protocol for common CRUD operations.
+
+    This protocol defines the common interface shared by all domain
+    repositories in the system. It uses generics to provide type safety
+    while eliminating code duplication.
+
+    Type Parameter:
+        T: The domain entity type (must extend Pydantic BaseModel)
+    """
+
+    async def get(self, entity_id: str) -> Optional[T]:
+        """Retrieve an entity by ID.
+
+        Args:
+            entity_id: Unique entity identifier
+
+        Returns:
+            Entity if found, None otherwise
+
+        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]]:
+        """Retrieve multiple entities by ID.
+
+        Args:
+            entity_ids: List of unique entity identifiers
+
+        Returns:
+            Dict mapping entity_id to entity (or None if not found)
+
+        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
+          to individual get() calls
+        - Keys in returned dict correspond exactly to input entity_ids
+        - Missing entities have None values in the returned dict
+
+        Workflow Context:
+        In Temporal workflows, this method is implemented as an activity
+        to ensure batch operations are durably stored and consistent
+        across workflow replays.
+        """
+        ...
+
+    async def save(self, entity: T) -> None:
+        """Save an entity.
+
+        Args:
+            entity: Complete entity to save
+
+        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]:
+        """List all entities.
+
+        Returns:
+            List of all entities in the repository
+
+        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:
+        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:
+        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.
+        """
+        return []
+
+    async def generate_id(self) -> str:
+        """Generate a unique entity identifier.
+
+        This operation is non-deterministic and must be called from
+        workflow activities, not directly from workflow code.
+
+        Returns:
+            Unique entity ID string
+
+        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:
+        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

@@ -0,0 +1,49 @@
+"""
+Document repository interface defined as Protocol for the Capture, Extract,
+Assemble, Publish workflow.
+
+This module defines the core document storage and retrieval repository
+protocol. The repository works with Document domain objects that use BinaryIO
+streams for efficient content handling.
+
+All repository operations follow the same principles as the sample
+repositories:
+
+- **Idempotency**: All methods are designed to be idempotent and safe for
+  retry. Multiple calls with the same parameters will produce the same
+  result without unintended side effects.
+
+- **Workflow Safety**: All operations are safe to call from deterministic
+  workflow contexts. Non-deterministic operations (like ID generation) are
+  explicitly delegated to activities.
+
+- **Domain Objects**: Methods accept and return domain objects or primitives,
+  never framework-specific types. Content streams are handled through the
+  BinaryIO interface.
+
+- **Content Streaming**: Repository implementations should support both
+  small content (via BytesIO) and large content (via file streams) through
+  the unified ContentStream interface wrapping io.IOBase.
+
+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 julee.domain.models import Document
+from .base import BaseRepository
+
+
+@runtime_checkable
+class DocumentRepository(BaseRepository[Document], Protocol):
+    """Handles document storage and retrieval operations.
+
+    This repository manages the core document storage and metadata
+    operations within the Capture, Extract, Assemble, Publish workflow.
+
+    Inherits common CRUD operations (get, save, generate_id) from
+    BaseRepository. The save method handles both content and metadata
+    storage atomically.
+    """
+
+    pass

julee/domain/repositories/document_policy_validation.py

@@ -0,0 +1,52 @@
+"""
+DocumentPolicyValidation repository interface defined as Protocol for the
+Capture, Extract, Assemble, Publish workflow.
+
+This module defines the core document policy validation storage and retrieval
+repository protocol. The repository works with DocumentPolicyValidation
+domain objects that track the validation of documents against policies.
+
+All repository operations follow the same principles as the sample
+repositories:
+
+- **Idempotency**: All methods are designed to be idempotent and safe for
+  retry. Multiple calls with the same parameters will produce the same
+  result without unintended side effects.
+
+- **Workflow Safety**: All operations are safe to call from deterministic
+  workflow contexts. Non-deterministic operations (like ID generation) are
+  explicitly delegated to activities.
+
+- **Domain Objects**: Methods accept and return domain objects or primitives,
+  never framework-specific types. DocumentPolicyValidation contains
+  validation results, scores, and transformation tracking.
+
+- **Validation Management**: Repository handles DocumentPolicyValidation
+  entities with their status tracking, score recording, and transformation
+  results for the quality assurance workflow.
+
+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 julee.domain.models.policy import DocumentPolicyValidation
+from .base import BaseRepository
+
+
+@runtime_checkable
+class DocumentPolicyValidationRepository(
+    BaseRepository[DocumentPolicyValidation], Protocol
+):
+    """Handles document policy validation storage and retrieval operations.
+
+    This repository manages DocumentPolicyValidation entities within the
+    Capture, Extract, Assemble, Publish workflow. These entities track the
+    complete lifecycle of validating documents against policies, including
+    initial validation scores, transformation results, and final outcomes.
+
+    Inherits common CRUD operations (get, save, generate_id) from
+    BaseRepository.
+    """
+
+    pass

julee/domain/repositories/knowledge_service_config.py

@@ -0,0 +1,54 @@
+"""
+KnowledgeServiceConfig repository interface defined as Protocol for the
+Capture, Extract, Assemble, Publish workflow.
+
+This module defines the knowledge service configuration repository protocol.
+The repository works with KnowledgeService domain objects for metadata
+persistence only. External service operations are handled by the service
+layer.
+
+All repository operations follow the same principles as the sample
+repositories:
+
+- **Idempotency**: All methods are designed to be idempotent and safe for
+  retry. Multiple calls with the same parameters will produce the same
+  result without unintended side effects.
+
+- **Workflow Safety**: All operations are safe to call from deterministic
+  workflow contexts. Non-deterministic operations (like ID generation) are
+  explicitly delegated to activities.
+
+- **Domain Objects**: Methods accept and return domain objects or primitives,
+  never framework-specific types. Results are returned as structured domain
+  objects.
+
+- **External Service Integration**: Repository implementations handle the
+  complexities of integrating with external knowledge services while
+  maintaining a clean, consistent interface.
+
+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, runtime_checkable
+from julee.domain.models.knowledge_service_config import (
+    KnowledgeServiceConfig,
+)
+from .base import BaseRepository
+
+
+@runtime_checkable
+class KnowledgeServiceConfigRepository(
+    BaseRepository[KnowledgeServiceConfig], Protocol
+):
+    """Handles knowledge service configuration persistence.
+
+    This repository manages knowledge service metadata and configuration
+    storage within the Capture, Extract, Assemble, Publish workflow.
+    External service operations are handled separately by the service layer.
+
+    Inherits common CRUD operations (get, save, generate_id) from
+    BaseRepository.
+    """
+
+    pass

julee/domain/repositories/knowledge_service_query.py

@@ -0,0 +1,44 @@
+"""
+KnowledgeServiceQuery repository interface defined as Protocol for the
+Capture, Extract, Assemble, Publish workflow.
+
+This module defines the knowledge service query repository protocol.
+The repository works with KnowledgeServiceQuery domain objects for
+storing and retrieving query configurations that define how to extract
+data using external knowledge services.
+
+All repository operations follow the same principles as the sample
+repositories:
+- Protocol-based design for Clean Architecture
+- Type safety with runtime validation
+- Idempotent operations
+- Proper error handling
+- Framework independence
+
+The repository handles the persistence of query definitions including
+prompts, assistant prompts, metadata, and service configurations
+that are used during the assembly process.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from julee.domain.models.assembly_specification import (
+    KnowledgeServiceQuery,
+)
+from .base import BaseRepository
+
+
+@runtime_checkable
+class KnowledgeServiceQueryRepository(BaseRepository[KnowledgeServiceQuery], Protocol):
+    """Handles knowledge service query persistence and retrieval.
+
+    This repository manages the storage and retrieval of
+    KnowledgeServiceQuery domain objects within the Capture, Extract,
+    Assemble, Publish workflow. These queries define how to extract
+    specific data using external knowledge services during assembly.
+
+    Inherits common CRUD operations (get, save, generate_id) from
+    BaseRepository.
+    """
+
+    pass

julee/domain/repositories/policy.py

@@ -0,0 +1,49 @@
+"""
+Policy repository interface defined as Protocol for the Capture, Extract,
+Assemble, Publish workflow.
+
+This module defines the core policy storage and retrieval repository
+protocol. The repository works with Policy domain objects that define
+validation criteria and optional transformations for documents.
+
+All repository operations follow the same principles as the sample
+repositories:
+
+- **Idempotency**: All methods are designed to be idempotent and safe for
+  retry. Multiple calls with the same parameters will produce the same
+  result without unintended side effects.
+
+- **Workflow Safety**: All operations are safe to call from deterministic
+  workflow contexts. Non-deterministic operations (like ID generation) are
+  explicitly delegated to activities.
+
+- **Domain Objects**: Methods accept and return domain objects or primitives,
+  never framework-specific types. Policy contains validation scores and
+  optional transformation queries.
+
+- **Policy Management**: Repository handles Policy entities with their
+  validation criteria, transformation queries, and status management for
+  the quality assurance workflow.
+
+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 julee.domain.models import Policy
+from .base import BaseRepository
+
+
+@runtime_checkable
+class PolicyRepository(BaseRepository[Policy], Protocol):
+    """Handles policy storage and retrieval operations.
+
+    This repository manages Policy entities within the Capture, Extract,
+    Assemble, Publish workflow. Policies define validation criteria and
+    optional transformations for documents in the quality assurance process.
+
+    Inherits common CRUD operations (get, save, generate_id) from
+    BaseRepository.
+    """
+
+    pass

julee/domain/use_cases/__init__.py

@@ -0,0 +1,17 @@
+"""
+Use cases for julee domain.
+
+This package contains use case classes that orchestrate business logic
+for the Capture, Extract, Assemble, Publish workflow while remaining
+framework-agnostic following Clean Architecture principles.
+"""
+
+from .extract_assemble_data import ExtractAssembleDataUseCase
+from .initialize_system_data import InitializeSystemDataUseCase
+from .validate_document import ValidateDocumentUseCase
+
+__all__ = [
+    "ExtractAssembleDataUseCase",
+    "InitializeSystemDataUseCase",
+    "ValidateDocumentUseCase",
+]

julee/domain/use_cases/decorators.py

@@ -0,0 +1,107 @@
+"""
+Decorators for use case step error handling and logging.
+
+This module provides decorators that implement consistent error handling
+and logging patterns across all use cases in the julee domain,
+following the patterns established in the sample use cases.
+"""
+
+import logging
+from functools import wraps
+from typing import Any, Callable, Dict, Optional, TypeVar, Awaitable
+
+logger = logging.getLogger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
+
+
+def try_use_case_step(
+    step_name: str,
+    extra_context: Optional[Dict[str, Any]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator that wraps use case steps with consistent error handling and
+    logging.
+
+    This decorator provides the same error handling and logging pattern used
+    in the sample use cases, eliminating boilerplate and ensuring consistency
+    across all use case implementations.
+
+    Args:
+        step_name: Name of the step (e.g., "assembly_id_generation")
+        extra_context: Optional additional context to include in all log
+            messages
+
+    Returns:
+        Decorated function with consistent error handling and logging
+
+    Example:
+        >>> @try_use_case_step(
+        ...     "assembly_id_generation", {"document_id": "doc-123"}
+        ... )
+        >>> async def generate_assembly_id(self) -> str:
+        ...     return await self.assembly_repo.generate_id()
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            # Build base logging context
+            log_context = {
+                "debug_step": f"before_{step_name}",
+            }
+            if extra_context:
+                log_context.update(extra_context)
+
+            # Pre-step logging
+            logger.debug(
+                f"About to {step_name}",
+                extra=log_context,
+            )
+
+            try:
+                # Execute the wrapped function
+                result = await func(*args, **kwargs)
+
+                # Success logging with result information
+                success_context = {
+                    "debug_step": f"{step_name}_success",
+                }
+                if extra_context:
+                    success_context.update(extra_context)
+
+                # Add result to logging context if it's a simple type
+                if isinstance(result, str):
+                    success_context["result"] = result
+                elif hasattr(result, "id"):
+                    success_context["result_id"] = result.id
+                elif hasattr(result, "__dict__"):
+                    # For complex objects, just log the type
+                    success_context["result_type"] = type(result).__name__
+
+                logger.debug(
+                    f"{step_name} completed successfully",
+                    extra=success_context,
+                )
+
+                return result
+
+            except Exception as e:
+                # Error logging
+                error_context = {
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                    "debug_step": f"{step_name}_failed",
+                }
+                if extra_context:
+                    error_context.update(extra_context)
+
+                logger.error(
+                    f"Failed to {step_name}",
+                    extra=error_context,
+                )
+                raise
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator