julee 0.1.0__py3-none-any.whl

julee/api/routers/knowledge_service_queries.py

@@ -0,0 +1,293 @@
+"""
+Knowledge Service Queries API router for the julee CEAP system.
+
+This module provides the API endpoints for knowledge service queries,
+which define how to extract specific data using external knowledge services
+during the assembly process.
+
+Routes defined at root level:
+- GET / - List knowledge service queries (paginated)
+- GET /{query_id} - Get individual query details
+- POST / - Create new knowledge service query
+
+These routes are mounted at /knowledge_service_queries in the main app.
+"""
+
+import logging
+from typing import Optional, cast
+from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi_pagination import Page, paginate
+
+from julee.domain.models import KnowledgeServiceQuery
+from julee.domain.repositories.knowledge_service_query import (
+    KnowledgeServiceQueryRepository,
+)
+from julee.api.dependencies import (
+    get_knowledge_service_query_repository,
+)
+from julee.api.requests import CreateKnowledgeServiceQueryRequest
+
+logger = logging.getLogger(__name__)
+
+# Create the router for knowledge service queries
+router = APIRouter()
+
+
+@router.get("/", response_model=Page[KnowledgeServiceQuery])
+async def get_knowledge_service_queries(
+    ids: Optional[str] = Query(
+        None,
+        description="Comma-separated list of query IDs for bulk retrieval",
+        openapi_examples={
+            "bulk_query": {
+                "summary": "Bulk retrieval example",
+                "value": "query-123,query-456,query-789",
+            }
+        },
+    ),
+    repository: KnowledgeServiceQueryRepository = Depends(  # type: ignore[misc]
+        get_knowledge_service_query_repository
+    ),
+) -> Page[KnowledgeServiceQuery]:
+    """
+    Get knowledge service queries by IDs or list all with pagination.
+
+    This endpoint supports two modes:
+    1. Bulk retrieval: Pass comma-separated IDs to get specific queries
+    2. List all: Without IDs parameter, returns paginated list of all queries
+
+    Each query contains the configuration needed to extract specific data
+    using external knowledge services.
+
+    Args:
+        ids: Optional comma-separated list of query IDs for bulk retrieval
+
+    Returns:
+        Page[KnowledgeServiceQuery]: List of queries (bulk) or paginated
+            list (all)
+    """
+    if ids is not None:
+        # Check for empty or whitespace-only parameter
+        if not ids.strip():
+            raise HTTPException(
+                status_code=400,
+                detail="Invalid ids parameter: must contain at least one " "valid ID",
+            )
+
+        # Bulk retrieval mode
+        logger.info(
+            "Bulk knowledge service queries requested",
+            extra={"ids_param": ids},
+        )
+
+        try:
+            # Parse and validate IDs
+            id_list = [id.strip() for id in ids.split(",") if id.strip()]
+            if not id_list:
+                raise HTTPException(
+                    status_code=400,
+                    detail="Invalid ids parameter: must contain at least "
+                    "one valid ID",
+                )
+
+            if len(id_list) > 100:  # Reasonable limit
+                raise HTTPException(
+                    status_code=400,
+                    detail="Too many IDs requested: maximum 100 IDs per " "request",
+                )
+
+            # Use repository's get_many method
+            results = await repository.get_many(id_list)
+
+            # Filter out None results and preserve found queries
+            found_queries = [query for query in results.values() if query is not None]
+
+            logger.info(
+                "Bulk knowledge service queries retrieved successfully",
+                extra={
+                    "requested_count": len(id_list),
+                    "found_count": len(found_queries),
+                    "missing_count": len(id_list) - len(found_queries),
+                },
+            )
+
+            # Return as paginated result for consistent API response format
+            return cast(Page[KnowledgeServiceQuery], paginate(found_queries))
+
+        except HTTPException:
+            # Re-raise HTTP exceptions (like 400 Bad Request)
+            raise
+        except Exception as e:
+            logger.error(
+                "Failed to retrieve bulk knowledge service queries",
+                exc_info=True,
+                extra={
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                    "ids_param": ids,
+                },
+            )
+            raise HTTPException(
+                status_code=500,
+                detail="Failed to retrieve queries due to an internal error.",
+            )
+    else:
+        # List all mode (existing functionality)
+        logger.info("All knowledge service queries requested")
+
+        try:
+            # Get all knowledge service queries from the repository
+            queries = await repository.list_all()
+
+            logger.info(
+                "Knowledge service queries retrieved successfully",
+                extra={"count": len(queries)},
+            )
+
+            # Use fastapi-pagination to paginate the results
+            return cast(Page[KnowledgeServiceQuery], paginate(queries))
+
+        except Exception as e:
+            logger.error(
+                "Failed to retrieve knowledge service queries",
+                exc_info=True,
+                extra={
+                    "error_type": type(e).__name__,
+                    "error_message": str(e),
+                },
+            )
+            raise HTTPException(
+                status_code=500,
+                detail="Failed to retrieve queries due to an internal error.",
+            )
+
+
+@router.post("/", response_model=KnowledgeServiceQuery)
+async def create_knowledge_service_query(
+    request: CreateKnowledgeServiceQueryRequest,
+    repository: KnowledgeServiceQueryRepository = Depends(  # type: ignore[misc]
+        get_knowledge_service_query_repository
+    ),
+) -> KnowledgeServiceQuery:
+    """
+    Create a new knowledge service query.
+
+    This endpoint creates a new knowledge service query configuration that
+    defines how to extract specific data using external knowledge services
+    during the assembly process.
+
+    Args:
+        request: The knowledge service query creation request
+        repository: Injected repository for persistence
+
+    Returns:
+        KnowledgeServiceQuery: The created query with generated ID and
+            timestamps
+    """
+    logger.info(
+        "Knowledge service query creation requested",
+        extra={"query_name": request.name},
+    )
+
+    try:
+        # Generate unique ID for the new query
+        query_id = await repository.generate_id()
+
+        # Convert request to domain model with generated ID
+        query = request.to_domain_model(query_id)
+
+        # Save the query via repository
+        await repository.save(query)
+
+        logger.info(
+            "Knowledge service query created successfully",
+            extra={
+                "query_id": query.query_id,
+                "query_name": query.name,
+                "knowledge_service_id": query.knowledge_service_id,
+            },
+        )
+
+        return query
+
+    except Exception as e:
+        logger.error(
+            "Failed to create knowledge service query",
+            exc_info=True,
+            extra={
+                "error_type": type(e).__name__,
+                "error_message": str(e),
+                "query_name": request.name,
+            },
+        )
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to create query due to an internal error.",
+        )
+
+
+@router.get("/{query_id}", response_model=KnowledgeServiceQuery)
+async def get_knowledge_service_query(
+    query_id: str,
+    repository: KnowledgeServiceQueryRepository = Depends(  # type: ignore[misc]
+        get_knowledge_service_query_repository
+    ),
+) -> KnowledgeServiceQuery:
+    """
+    Get a specific knowledge service query by ID.
+
+    Args:
+        query_id: The ID of the query to retrieve
+        repository: Injected repository for data access
+
+    Returns:
+        KnowledgeServiceQuery: The requested query
+
+    Raises:
+        HTTPException: 404 if query not found, 500 for internal errors
+    """
+    logger.info(
+        "Knowledge service query detail requested",
+        extra={"query_id": query_id},
+    )
+
+    try:
+        query = await repository.get(query_id)
+
+        if query is None:
+            logger.warning(
+                "Knowledge service query not found",
+                extra={"query_id": query_id},
+            )
+            raise HTTPException(
+                status_code=404,
+                detail=f"Knowledge service query with ID '{query_id}' " "not found",
+            )
+
+        logger.info(
+            "Knowledge service query retrieved successfully",
+            extra={
+                "query_id": query.query_id,
+                "query_name": query.name,
+            },
+        )
+
+        return query
+
+    except HTTPException:
+        # Re-raise HTTP exceptions (like 404 Not Found)
+        raise
+    except Exception as e:
+        logger.error(
+            "Failed to retrieve knowledge service query",
+            exc_info=True,
+            extra={
+                "error_type": type(e).__name__,
+                "error_message": str(e),
+                "query_id": query_id,
+            },
+        )
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to retrieve query due to an internal error.",
+        )

julee/api/routers/system.py

@@ -0,0 +1,137 @@
+"""
+System API router for the julee CEAP system.
+
+This module provides system-level API endpoints including health checks,
+status information, and other operational endpoints.
+
+Routes defined at root level:
+- GET /health - Health check endpoint
+
+These routes are mounted at the root level in the main app.
+"""
+
+import logging
+import asyncio
+from datetime import datetime, timezone
+from fastapi import APIRouter
+from temporalio.client import Client
+from minio import Minio
+import os
+
+from julee.api.responses import (
+    HealthCheckResponse,
+    ServiceHealthStatus,
+    ServiceStatus,
+    SystemStatus,
+)
+
+logger = logging.getLogger(__name__)
+
+# Create the router for system endpoints
+router = APIRouter()
+
+
+async def check_temporal_health() -> ServiceStatus:
+    """Check if Temporal service is available."""
+    try:
+        # Get Temporal server address from environment or use default
+        temporal_address = os.getenv(
+            "TEMPORAL_ENDPOINT", os.getenv("TEMPORAL_HOST", "localhost:7233")
+        )
+
+        # Create a client and try to connect
+        _ = await Client.connect(temporal_address, namespace="default")
+        # Simple check - if we can connect, assume it's working
+        return ServiceStatus.UP
+    except Exception as e:
+        logger.warning("Temporal health check failed: %s", e)
+        return ServiceStatus.DOWN
+
+
+async def check_storage_health() -> ServiceStatus:
+    """Check if storage service (Minio) is available."""
+    try:
+        # Get Minio configuration (prioritize Docker network address)
+        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"
+
+        # Create Minio client
+        client = Minio(
+            endpoint=endpoint,
+            access_key=access_key,
+            secret_key=secret_key,
+            secure=secure,
+        )
+
+        # Test connection by listing buckets
+        _ = list(client.list_buckets())
+        return ServiceStatus.UP
+    except Exception as e:
+        logger.warning("Storage health check failed: %s", e)
+        return ServiceStatus.DOWN
+
+
+async def check_api_health() -> ServiceStatus:
+    """Check if API service is available (self-check)."""
+    # Since we're responding, API is up
+    return ServiceStatus.UP
+
+
+def determine_overall_status(services: ServiceHealthStatus) -> SystemStatus:
+    """Determine overall system status based on service statuses."""
+    service_statuses = [services.api, services.temporal, services.storage]
+
+    if all(status == ServiceStatus.UP for status in service_statuses):
+        return SystemStatus.HEALTHY
+    elif any(status == ServiceStatus.UP for status in service_statuses):
+        return SystemStatus.DEGRADED
+    else:
+        return SystemStatus.UNHEALTHY
+
+
+@router.get("/health", response_model=HealthCheckResponse)
+async def health_check() -> HealthCheckResponse:
+    """Comprehensive health check endpoint that checks all services."""
+    logger.info("Performing health check")
+
+    # Check all services concurrently
+    results = await asyncio.gather(
+        check_api_health(),
+        check_temporal_health(),
+        check_storage_health(),
+        return_exceptions=True,
+    )
+
+    # Handle any exceptions from the health checks
+    api_status = results[0]
+    temporal_status = results[1]
+    storage_status = results[2]
+
+    if isinstance(api_status, Exception):
+        logger.error("API health check error: %s", api_status)
+        api_status = ServiceStatus.DOWN
+    if isinstance(temporal_status, Exception):
+        logger.error("Temporal health check error: %s", temporal_status)
+        temporal_status = ServiceStatus.DOWN
+    if isinstance(storage_status, Exception):
+        logger.error("Storage health check error: %s", storage_status)
+        storage_status = ServiceStatus.DOWN
+
+    # Create service health status with proper typing
+    services = ServiceHealthStatus(
+        api=ServiceStatus(api_status),
+        temporal=ServiceStatus(temporal_status),
+        storage=ServiceStatus(storage_status),
+    )
+
+    # Determine overall status
+    overall_status = determine_overall_status(services)
+
+    # Return response with string timestamp as expected by frontend
+    return HealthCheckResponse(
+        status=overall_status,
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        services=services,
+    )

julee/api/routers/workflows.py

@@ -0,0 +1,234 @@
+"""
+Workflows API router for the julee CEAP system.
+
+This module provides workflow management API endpoints for starting,
+monitoring, and managing workflows in the system.
+
+Routes defined at root level:
+- POST /extract-assemble - Start extract-assemble workflow
+- GET /{workflow_id}/status - Get workflow status
+- GET / - List workflows
+
+These routes are mounted with '/workflows' prefix in the main app.
+"""
+
+import logging
+import uuid
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+from temporalio.client import Client
+
+from julee.api.dependencies import get_temporal_client
+from julee.workflows.extract_assemble import (
+    ExtractAssembleWorkflow,
+    EXTRACT_ASSEMBLE_RETRY_POLICY,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+class StartExtractAssembleRequest(BaseModel):
+    """Request model for starting extract-assemble workflow."""
+
+    document_id: str = Field(..., min_length=1, description="Document ID to process")
+    assembly_specification_id: str = Field(
+        ..., min_length=1, description="Assembly specification ID to use"
+    )
+    workflow_id: Optional[str] = Field(
+        None,
+        min_length=1,
+        description=("Optional custom workflow ID (auto-generated if not provided)"),
+    )
+
+
+class WorkflowStatusResponse(BaseModel):
+    """Response model for workflow status."""
+
+    workflow_id: str
+    run_id: str
+    status: str  # "RUNNING", "COMPLETED", "FAILED", "CANCELLED", etc.
+    current_step: Optional[str] = None
+    assembly_id: Optional[str] = None
+
+
+class StartWorkflowResponse(BaseModel):
+    """Response model for starting a workflow."""
+
+    workflow_id: str
+    run_id: str
+    status: str
+    message: str
+
+
+@router.post("/extract-assemble", response_model=StartWorkflowResponse)
+async def start_extract_assemble_workflow(
+    request: StartExtractAssembleRequest,
+    temporal_client: Client = Depends(get_temporal_client),
+) -> StartWorkflowResponse:
+    """
+    Start an extract-assemble workflow.
+
+    Args:
+        request: Workflow start request with document and spec IDs
+        temporal_client: Temporal client dependency
+
+    Returns:
+        Workflow ID and initial status
+
+    Raises:
+        HTTPException: If workflow start fails
+    """
+    try:
+        logger.info("Starting extract-assemble workflow request received")
+
+        # Generate workflow ID if not provided
+        workflow_id = request.workflow_id
+        if not workflow_id:
+            workflow_id = (
+                f"extract-assemble-{request.document_id}-"
+                f"{request.assembly_specification_id}-{uuid.uuid4().hex[:8]}"
+            )
+
+        logger.info(
+            "Starting ExtractAssemble workflow",
+            extra={
+                "workflow_id": workflow_id,
+                "document_id": request.document_id,
+                "assembly_specification_id": (request.assembly_specification_id),
+            },
+        )
+
+        # Start the workflow
+        handle = await temporal_client.start_workflow(
+            ExtractAssembleWorkflow.run,
+            args=[request.document_id, request.assembly_specification_id],
+            id=workflow_id,
+            task_queue="julee-extract-assemble-queue",
+            retry_policy=EXTRACT_ASSEMBLE_RETRY_POLICY,
+        )
+
+        logger.info(
+            "ExtractAssemble workflow started successfully",
+            extra={
+                "workflow_id": workflow_id,
+                "run_id": handle.run_id,
+            },
+        )
+
+        return StartWorkflowResponse(
+            workflow_id=workflow_id,
+            run_id=handle.run_id or "unknown",
+            status="RUNNING",
+            message="Workflow started successfully",
+        )
+
+    except Exception as e:
+        logger.error(
+            "Failed to start extract-assemble workflow: %s",
+            e,
+            extra={
+                "document_id": request.document_id,
+                "assembly_specification_id": (request.assembly_specification_id),
+            },
+        )
+        raise HTTPException(status_code=500, detail="Failed to start workflow") from e
+
+
+@router.get("/{workflow_id}/status", response_model=WorkflowStatusResponse)
+async def get_workflow_status(
+    workflow_id: str,
+    temporal_client: Client = Depends(get_temporal_client),
+) -> WorkflowStatusResponse:
+    """
+    Get the status of a workflow.
+
+    Args:
+        workflow_id: Workflow ID to query
+        temporal_client: Temporal client dependency
+
+    Returns:
+        Current workflow status and details
+
+    Raises:
+        HTTPException: If workflow not found or query fails
+    """
+    logger.info("Getting workflow status", extra={"workflow_id": workflow_id})
+
+    # Get workflow handle - if this fails, workflow doesn't exist
+    try:
+        handle = temporal_client.get_workflow_handle(workflow_id)
+    except Exception as e:
+        # Check if it's a workflow not found error (common patterns)
+        error_message = str(e).lower()
+        if any(
+            pattern in error_message
+            for pattern in [
+                "not found",
+                "notfound",
+                "does not exist",
+                "workflow_not_found",
+            ]
+        ):
+            raise HTTPException(
+                status_code=404,
+                detail=f"Workflow with ID '{workflow_id}' not found",
+            )
+
+        # Other errors from getting workflow handle
+        logger.error(
+            "Failed to get workflow handle: %s",
+            e,
+            extra={"workflow_id": workflow_id},
+        )
+        raise HTTPException(
+            status_code=500, detail="Failed to retrieve workflow handle"
+        ) from e
+
+    # Get workflow description - if this fails, it's a server error
+    try:
+        description = await handle.describe()
+    except Exception as e:
+        logger.error(
+            "Failed to describe workflow: %s",
+            e,
+            extra={"workflow_id": workflow_id},
+        )
+        raise HTTPException(
+            status_code=500, detail="Failed to retrieve workflow description"
+        ) from e
+
+    # Query current step and assembly ID if workflow supports it
+    current_step = None
+    assembly_id = None
+    try:
+        current_step = await handle.query("get_current_step")
+        assembly_id = await handle.query("get_assembly_id")
+    except Exception as query_error:
+        logger.debug(
+            "Could not query workflow details: %s",
+            query_error,
+            extra={"workflow_id": workflow_id},
+        )
+
+    status_response = WorkflowStatusResponse(
+        workflow_id=workflow_id,
+        run_id=description.run_id or "unknown",
+        status=description.status.name if description.status else "UNKNOWN",
+        current_step=current_step,
+        assembly_id=assembly_id,
+    )
+
+    logger.info(
+        "Retrieved workflow status",
+        extra={
+            "workflow_id": workflow_id,
+            "status": status_response.status,
+            "current_step": current_step,
+        },
+    )
+
+    return status_response

julee/api/services/__init__.py

@@ -0,0 +1,20 @@
+"""
+API services package for the julee CEAP system.
+
+This package contains service layer components that orchestrate use cases
+and provide higher-level application services. Services in this package
+act as facades between the API layer and the domain layer, coordinating
+multiple use cases and handling cross-cutting concerns.
+
+Services follow clean architecture principles:
+- Orchestrate domain use cases
+- Handle application-level concerns
+- Provide simplified interfaces for controllers
+- Maintain separation between API and domain layers
+"""
+
+from .system_initialization import SystemInitializationService
+
+__all__ = [
+    "SystemInitializationService",
+]