julee 0.1.0__py3-none-any.whl

julee/__init__.py

@@ -0,0 +1,3 @@
+"""Julee - Clean architecture for accountable and transparent digital supply chains."""
+
+__version__ = "0.1.0"

julee/api/__init__.py

@@ -0,0 +1,20 @@
+"""
+FastAPI interface adapters for the julee CEAP workflow system.
+
+This package contains the HTTP API layer that provides external access to the
+CEAP (Capture, Extract, Assemble, Publish) workflow functionality.
+
+The API follows clean architecture patterns:
+- Request models for external client contracts (API-specific validation)
+- Domain models returned directly as responses (no wrapper models needed)
+- Dependency injection for use cases and repositories
+- HTTPException for error responses with appropriate status codes
+
+Modules:
+- requests: Pydantic models for API request validation
+- responses: Minimal API-specific response models (health checks, etc.)
+- app: FastAPI application setup and endpoint definitions
+- dependencies: Dependency injection configuration
+"""
+
+__all__: list[str] = []

julee/api/app.py

@@ -0,0 +1,180 @@
+"""
+FastAPI application for julee CEAP workflow system.
+
+This module provides the HTTP API layer for the Capture, Extract, Assemble,
+Publish workflow system. It follows clean architecture principles with
+proper dependency injection and error handling.
+
+The API provides endpoints for:
+- Knowledge service queries (CRUD operations)
+- Assembly specifications (CRUD operations)
+- Health checks and system status
+
+All endpoints use domain models for responses and follow RESTful conventions
+with proper HTTP status codes and error handling.
+"""
+
+import logging
+import uvicorn
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator, Any, Callable
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi_pagination import add_pagination
+from fastapi_pagination.utils import disable_installed_extensions_check
+
+from julee.api.routers import (
+    assembly_specifications_router,
+    knowledge_service_queries_router,
+    knowledge_service_configs_router,
+    system_router,
+    documents_router,
+    workflows_router,
+)
+from julee.api.dependencies import (
+    get_startup_dependencies,
+    get_knowledge_service_config_repository,
+)
+
+# Disable pagination extensions check for cleaner startup
+disable_installed_extensions_check()
+
+logger = logging.getLogger(__name__)
+
+
+def setup_logging() -> None:
+    """Configure logging for the application."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[
+            logging.StreamHandler(),
+        ],
+    )
+
+    # Set specific log levels
+    logging.getLogger("julee").setLevel(logging.DEBUG)
+    logging.getLogger("fastapi").setLevel(logging.INFO)
+    logging.getLogger("uvicorn").setLevel(logging.INFO)
+
+
+# Setup logging
+setup_logging()
+
+
+def resolve_dependency(app: FastAPI, dependency_func: Callable[[], Any]) -> Any:
+    """Resolve a dependency, respecting test overrides."""
+    override = app.dependency_overrides.get(dependency_func)
+    return override() if override else dependency_func()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Lifespan context manager for application startup and shutdown."""
+    # Startup
+    logger.info("Starting application initialization")
+
+    try:
+        # Check if we're in test mode by looking for repository overrides
+        if get_knowledge_service_config_repository in app.dependency_overrides:
+            logger.info("Test mode detected, skipping system initialization")
+        else:
+            # Normal production initialization
+            startup_deps = await resolve_dependency(app, get_startup_dependencies)
+            service = await startup_deps.get_system_initialization_service()
+
+            # Execute initialization
+            results = await service.initialize()
+
+            logger.info(
+                "Application initialization completed successfully",
+                extra={
+                    "initialization_results": results,
+                    "tasks_completed": results.get("tasks_completed", []),
+                },
+            )
+
+    except Exception as e:
+        logger.error(
+            "Application initialization failed",
+            exc_info=True,
+            extra={
+                "error_type": type(e).__name__,
+                "error_message": str(e),
+            },
+        )
+        # Re-raise to prevent application startup if critical init fails
+        raise
+
+    yield
+
+    # Shutdown (if needed)
+    logger.info("Application shutdown")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="Julee Example CEAP API",
+    description="API for the Capture, Extract, Assemble, Publish workflow",
+    version="0.1.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan,
+)
+
+# Add CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # Configure appropriately for production
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Add pagination support
+_ = add_pagination(app)
+
+
+# Include routers
+app.include_router(system_router, tags=["System"])
+
+app.include_router(
+    knowledge_service_queries_router,
+    prefix="/knowledge_service_queries",
+    tags=["Knowledge Service Queries"],
+)
+
+app.include_router(
+    knowledge_service_configs_router,
+    prefix="/knowledge_service_configs",
+    tags=["Knowledge Service Configs"],
+)
+
+app.include_router(
+    assembly_specifications_router,
+    prefix="/assembly_specifications",
+    tags=["Assembly Specifications"],
+)
+
+app.include_router(
+    documents_router,
+    prefix="/documents",
+    tags=["Documents"],
+)
+
+app.include_router(
+    workflows_router,
+    prefix="/workflows",
+    tags=["Workflows"],
+)
+
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "julee.api.app:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+        log_level="info",
+    )

julee/api/dependencies.py

@@ -0,0 +1,257 @@
+"""
+Dependency injection for julee FastAPI endpoints.
+
+This module provides dependency injection for the julee API endpoints,
+following the same patterns established in the sample project. It manages
+singleton lifecycle for expensive resources and provides clean separation
+between infrastructure concerns and business logic.
+
+The dependencies focus on real Minio implementations for production use,
+with test overrides available through FastAPI's dependency override system.
+"""
+
+import os
+import logging
+from typing import Any, Dict, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from julee.api.services.system_initialization import (
+        SystemInitializationService,
+    )
+
+from fastapi import Depends
+from temporalio.client import Client
+from temporalio.contrib.pydantic import pydantic_data_converter
+
+from julee.domain.repositories.knowledge_service_query import (
+    KnowledgeServiceQueryRepository,
+)
+from julee.domain.repositories.knowledge_service_config import (
+    KnowledgeServiceConfigRepository,
+)
+from julee.domain.repositories.assembly_specification import (
+    AssemblySpecificationRepository,
+)
+from julee.domain.repositories.document import (
+    DocumentRepository,
+)
+from julee.repositories.minio.knowledge_service_query import (
+    MinioKnowledgeServiceQueryRepository,
+)
+from julee.repositories.minio.knowledge_service_config import (
+    MinioKnowledgeServiceConfigRepository,
+)
+from julee.repositories.minio.assembly_specification import (
+    MinioAssemblySpecificationRepository,
+)
+from julee.repositories.minio.document import (
+    MinioDocumentRepository,
+)
+from julee.repositories.minio.client import MinioClient
+from minio import Minio
+
+logger = logging.getLogger(__name__)
+
+
+class DependencyContainer:
+    """
+    Dependency injection container with singleton lifecycle management.
+    Always creates real clients; mocks are provided by test overrides.
+    """
+
+    def __init__(self) -> None:
+        self._instances: Dict[str, Any] = {}
+
+    async def get_or_create(self, key: str, factory: Any) -> Any:
+        """Get or create a singleton instance."""
+        if key not in self._instances:
+            self._instances[key] = await factory()
+        return self._instances[key]
+
+    async def get_temporal_client(self) -> Client:
+        """Get or create Temporal client."""
+        client = await self.get_or_create(
+            "temporal_client", self._create_temporal_client
+        )
+        return client  # type: ignore[no-any-return]
+
+    async def _create_temporal_client(self) -> Client:
+        """Create Temporal client with proper configuration."""
+        temporal_endpoint = os.environ.get("TEMPORAL_ENDPOINT", "temporal:7233")
+        logger.debug(
+            "Creating Temporal client",
+            extra={"endpoint": temporal_endpoint, "namespace": "default"},
+        )
+
+        client = await Client.connect(
+            temporal_endpoint,
+            namespace="default",
+            data_converter=pydantic_data_converter,
+        )
+
+        logger.debug(
+            "Temporal client created",
+            extra={
+                "endpoint": temporal_endpoint,
+                "data_converter_type": type(client.data_converter).__name__,
+            },
+        )
+        return client
+
+    async def get_minio_client(self) -> MinioClient:
+        """Get or create Minio client."""
+        client = await self.get_or_create("minio_client", self._create_minio_client)
+        return client  # type: ignore[no-any-return]
+
+    async def _create_minio_client(self) -> MinioClient:
+        """Create Minio client with proper configuration."""
+        endpoint = os.environ.get("MINIO_ENDPOINT", "localhost:9000")
+        access_key = os.environ.get("MINIO_ACCESS_KEY", "minioadmin")
+        secret_key = os.environ.get("MINIO_SECRET_KEY", "minioadmin")
+        secure = os.environ.get("MINIO_SECURE", "false").lower() == "true"
+
+        logger.debug(
+            "Creating Minio client",
+            extra={
+                "endpoint": endpoint,
+                "secure": secure,
+                "access_key": access_key[:4] + "***",  # Log partial key only
+            },
+        )
+
+        # Create the actual minio client which implements MinioClient protocol
+        client = Minio(
+            endpoint=endpoint,
+            access_key=access_key,
+            secret_key=secret_key,
+            secure=secure,
+        )
+
+        logger.debug("Minio client created", extra={"endpoint": endpoint})
+        return client  # type: ignore[return-value]
+
+
+# Global container instance
+_container = DependencyContainer()
+
+
+async def get_temporal_client() -> Client:
+    """FastAPI dependency for Temporal client."""
+    return await _container.get_temporal_client()
+
+
+async def get_minio_client() -> MinioClient:
+    """FastAPI dependency for Minio client."""
+    return await _container.get_minio_client()
+
+
+async def get_knowledge_service_query_repository(
+    minio_client: MinioClient = Depends(get_minio_client),
+) -> KnowledgeServiceQueryRepository:
+    """FastAPI dependency for KnowledgeServiceQueryRepository."""
+    return MinioKnowledgeServiceQueryRepository(client=minio_client)
+
+
+async def get_knowledge_service_config_repository(
+    minio_client: MinioClient = Depends(get_minio_client),
+) -> KnowledgeServiceConfigRepository:
+    """FastAPI dependency for KnowledgeServiceConfigRepository."""
+    return MinioKnowledgeServiceConfigRepository(client=minio_client)
+
+
+async def get_assembly_specification_repository(
+    minio_client: MinioClient = Depends(get_minio_client),
+) -> AssemblySpecificationRepository:
+    """FastAPI dependency for AssemblySpecificationRepository."""
+    return MinioAssemblySpecificationRepository(client=minio_client)
+
+
+async def get_document_repository(
+    minio_client: MinioClient = Depends(get_minio_client),
+) -> DocumentRepository:
+    """FastAPI dependency for DocumentRepository."""
+    return MinioDocumentRepository(client=minio_client)
+
+
+class StartupDependenciesProvider:
+    """
+    Provider for dependencies needed during application startup.
+
+    This class provides clean access to repositories and services needed
+    during the lifespan startup phase, without exposing internal container
+    details or requiring FastAPI's dependency injection system.
+    """
+
+    def __init__(self, container: DependencyContainer):
+        """Initialize with dependency container."""
+        self.container = container
+        self.logger = logging.getLogger("StartupDependenciesProvider")
+
+    async def get_document_repository(self) -> DocumentRepository:
+        """Get document repository for startup dependencies."""
+        minio_client = await self.container.get_minio_client()
+        from julee.repositories.minio.document import (
+            MinioDocumentRepository,
+        )
+
+        return MinioDocumentRepository(client=minio_client)
+
+    async def get_knowledge_service_config_repository(
+        self,
+    ) -> KnowledgeServiceConfigRepository:
+        """Get knowledge service config repository for startup."""
+        minio_client = await self.container.get_minio_client()
+        return MinioKnowledgeServiceConfigRepository(client=minio_client)
+
+    async def get_knowledge_service_query_repository(
+        self,
+    ) -> KnowledgeServiceQueryRepository:
+        """Get knowledge service query repository for startup dependencies."""
+        minio_client = await self.container.get_minio_client()
+        return MinioKnowledgeServiceQueryRepository(client=minio_client)
+
+    async def get_assembly_specification_repository(
+        self,
+    ) -> AssemblySpecificationRepository:
+        """Get assembly specification repository for startup dependencies."""
+        minio_client = await self.container.get_minio_client()
+        return MinioAssemblySpecificationRepository(client=minio_client)
+
+    async def get_system_initialization_service(
+        self,
+    ) -> "SystemInitializationService":
+        """Get fully configured system initialization service."""
+        from julee.api.services.system_initialization import (
+            SystemInitializationService,
+        )
+        from julee.domain.use_cases.initialize_system_data import (
+            InitializeSystemDataUseCase,
+        )
+
+        self.logger.debug("Creating system initialization service")
+
+        # Create repositories and use case
+        config_repo = await self.get_knowledge_service_config_repository()
+        document_repo = await self.get_document_repository()
+        query_repo = await self.get_knowledge_service_query_repository()
+        assembly_spec_repo = await self.get_assembly_specification_repository()
+        use_case = InitializeSystemDataUseCase(
+            config_repo, document_repo, query_repo, assembly_spec_repo
+        )
+
+        # Create and return service
+        return SystemInitializationService(use_case)
+
+
+# Global startup dependencies provider
+_startup_provider = StartupDependenciesProvider(_container)
+
+
+async def get_startup_dependencies() -> StartupDependenciesProvider:
+    """Get startup dependencies provider for lifespan contexts."""
+    return _startup_provider
+
+
+# Note: Use cases and more complex dependencies can be added here as needed
+# following the same pattern. For simple CRUD operations like listing
+# queries, we can use the repository directly in the endpoint.

julee/api/requests.py

@@ -0,0 +1,175 @@
+"""
+Pydantic models for API requests.
+These define the contract between the API and external clients.
+
+Following clean architecture principles, request models delegate validation
+to domain model class methods and reuse field descriptions to avoid
+duplication while maintaining single source of truth in the domain layer.
+"""
+
+from typing import Dict, Any, Optional
+from pydantic import BaseModel, Field, field_validator, ValidationInfo
+from datetime import datetime, timezone
+
+from julee.domain.models import (
+    AssemblySpecification,
+    AssemblySpecificationStatus,
+    KnowledgeServiceQuery,
+)
+
+
+class CreateAssemblySpecificationRequest(BaseModel):
+    """Request model for creating an assembly specification.
+
+    This model defines what clients need to provide when creating a new
+    assembly specification. Validation logic is delegated to the domain
+    model to ensure consistency and avoid duplication.
+
+    Fields excluded from client control:
+    - assembly_specification_id: Always generated by the server
+    - status: Always set to DRAFT initially by the server
+    - created_at/updated_at: System-managed timestamps
+    """
+
+    # Field definitions with descriptions reused from domain model
+    name: str = Field(
+        description=AssemblySpecification.model_fields["name"].description
+    )
+    applicability: str = Field(
+        description=AssemblySpecification.model_fields["applicability"].description
+    )
+    jsonschema: Dict[str, Any] = Field(
+        description=AssemblySpecification.model_fields["jsonschema"].description
+    )
+    knowledge_service_queries: Dict[str, str] = Field(
+        default_factory=dict,
+        description=AssemblySpecification.model_fields[
+            "knowledge_service_queries"
+        ].description,
+    )
+    version: str = Field(
+        default=AssemblySpecification.model_fields["version"].default,
+        description=AssemblySpecification.model_fields["version"].description,
+    )
+
+    # Delegate validation to domain model class methods
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        return AssemblySpecification.name_must_not_be_empty(v)
+
+    @field_validator("applicability")
+    @classmethod
+    def validate_applicability(cls, v: str) -> str:
+        return AssemblySpecification.applicability_must_not_be_empty(v)
+
+    @field_validator("jsonschema")
+    @classmethod
+    def validate_jsonschema(cls, v: Dict[str, Any]) -> Dict[str, Any]:
+        return AssemblySpecification.jsonschema_must_be_valid(v)
+
+    @field_validator("knowledge_service_queries")
+    @classmethod
+    def validate_knowledge_service_queries(
+        cls, v: Dict[str, str], info: ValidationInfo
+    ) -> Dict[str, str]:
+        return AssemblySpecification.knowledge_service_queries_must_be_valid(v, info)
+
+    @field_validator("version")
+    @classmethod
+    def validate_version(cls, v: str) -> str:
+        return AssemblySpecification.version_must_not_be_empty(v)
+
+    def to_domain_model(self, assembly_specification_id: str) -> AssemblySpecification:
+        """Convert this request to a complete AssemblySpecification object.
+
+        Args:
+            assembly_specification_id: The ID to assign to the new spec
+
+        Returns:
+            AssemblySpecification: Complete domain object with system fields
+        """
+        now = datetime.now(timezone.utc)
+        return AssemblySpecification(
+            assembly_specification_id=assembly_specification_id,
+            name=self.name,
+            applicability=self.applicability,
+            jsonschema=self.jsonschema,
+            knowledge_service_queries=self.knowledge_service_queries,
+            version=self.version,
+            status=AssemblySpecificationStatus.DRAFT,
+            created_at=now,
+            updated_at=now,
+        )
+
+
+class CreateKnowledgeServiceQueryRequest(BaseModel):
+    """Request model for creating a knowledge service query.
+
+    This model defines what clients need to provide when creating a new
+    knowledge service query. Validation logic is delegated to the domain
+    model and descriptions are reused to avoid duplication while maintaining
+    single source of truth in the domain layer.
+
+    Fields excluded from client control:
+    - query_id: Always generated by the server
+    - created_at/updated_at: System-managed timestamps
+    """
+
+    # Field definitions with descriptions reused from domain model
+    name: str = Field(
+        description=KnowledgeServiceQuery.model_fields["name"].description
+    )
+    knowledge_service_id: str = Field(
+        description=KnowledgeServiceQuery.model_fields[
+            "knowledge_service_id"
+        ].description
+    )
+    prompt: str = Field(
+        description=KnowledgeServiceQuery.model_fields["prompt"].description
+    )
+    query_metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description=KnowledgeServiceQuery.model_fields["query_metadata"].description,
+    )
+    assistant_prompt: Optional[str] = Field(
+        default=KnowledgeServiceQuery.model_fields["assistant_prompt"].default,
+        description=KnowledgeServiceQuery.model_fields["assistant_prompt"].description,
+    )
+
+    # Delegate validation to domain model class methods
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        return KnowledgeServiceQuery.name_must_not_be_empty(v)
+
+    @field_validator("knowledge_service_id")
+    @classmethod
+    def validate_knowledge_service_id(cls, v: str) -> str:
+        return KnowledgeServiceQuery.knowledge_service_id_must_not_be_empty(v)
+
+    @field_validator("prompt")
+    @classmethod
+    def validate_prompt(cls, v: str) -> str:
+        return KnowledgeServiceQuery.prompt_must_not_be_empty(v)
+
+    def to_domain_model(self, query_id: str) -> KnowledgeServiceQuery:
+        """Convert this request to a complete KnowledgeServiceQuery object.
+
+        Args:
+            query_id: The ID to assign to the new query
+
+        Returns:
+            KnowledgeServiceQuery: Complete domain object with system fields
+        """
+        now = datetime.now(timezone.utc)
+        return KnowledgeServiceQuery(
+            query_id=query_id,
+            name=self.name,
+            knowledge_service_id=self.knowledge_service_id,
+            prompt=self.prompt,
+            query_metadata=self.query_metadata,
+            assistant_prompt=self.assistant_prompt,
+            created_at=now,
+            updated_at=now,
+        )

julee/api/responses.py

@@ -0,0 +1,43 @@
+"""
+Pydantic models for API responses.
+These define the contract between the API and external clients.
+
+Following clean architecture principles, most endpoints return domain models
+directly rather than creating wrapper response models. This file contains
+only response models that are specific to API concerns and not represented
+by existing domain models.
+"""
+
+from pydantic import BaseModel
+from enum import Enum
+
+
+class ServiceStatus(str, Enum):
+    """Service status enumeration."""
+
+    UP = "up"
+    DOWN = "down"
+
+
+class SystemStatus(str, Enum):
+    """Overall system status enumeration."""
+
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+
+
+class ServiceHealthStatus(BaseModel):
+    """Health status for individual services."""
+
+    api: ServiceStatus
+    temporal: ServiceStatus
+    storage: ServiceStatus
+
+
+class HealthCheckResponse(BaseModel):
+    """Response for health check endpoint."""
+
+    status: SystemStatus
+    timestamp: str
+    services: ServiceHealthStatus