julee 0.1.0__py3-none-any.whl

julee/services/knowledge_service/factory.py

@@ -0,0 +1,138 @@
+"""
+Factory function for creating KnowledgeService implementations.
+
+This module provides the factory function for creating configured
+KnowledgeService instances based on the service API configuration.
+"""
+
+import logging
+
+from julee.domain.models.knowledge_service_config import (
+    KnowledgeServiceConfig,
+    ServiceApi,
+)
+from .knowledge_service import KnowledgeService
+from .anthropic import AnthropicKnowledgeService
+from julee.domain.models.document import Document
+from julee.services.knowledge_service import (
+    QueryResult,
+    FileRegistrationResult,
+)
+from typing import Dict, Any, List, Optional
+
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigurableKnowledgeService(KnowledgeService):
+    """
+    KnowledgeService implementation that uses the factory pattern.
+
+    This class implements the KnowledgeService protocol by delegating to
+    a factory-created service instance. It can be wrapped by temporal
+    decorators while maintaining proper protocol compliance.
+
+    No constructor configuration is required - the factory is called
+    within each method using the provided config parameter.
+    """
+
+    async def register_file(
+        self, config: KnowledgeServiceConfig, document: Document
+    ) -> FileRegistrationResult:
+        """Register a document with the knowledge service."""
+        service = knowledge_service_factory(config)
+        return await service.register_file(config, document)
+
+    async def execute_query(
+        self,
+        config: KnowledgeServiceConfig,
+        query_text: str,
+        service_file_ids: Optional[List[str]] = None,
+        query_metadata: Optional[Dict[str, Any]] = None,
+        assistant_prompt: Optional[str] = None,
+    ) -> QueryResult:
+        """Execute a query against the knowledge service."""
+        service = knowledge_service_factory(config)
+        return await service.execute_query(
+            config=config,
+            query_text=query_text,
+            service_file_ids=service_file_ids,
+            query_metadata=query_metadata,
+            assistant_prompt=assistant_prompt,
+        )
+
+
+def knowledge_service_factory(
+    knowledge_service_config: "KnowledgeServiceConfig",
+) -> KnowledgeService:
+    """Create a configured KnowledgeService instance.
+
+    This factory function takes a KnowledgeServiceConfig domain object
+    (containing metadata and service_api information) and returns a properly
+    configured KnowledgeService implementation that can handle external
+    operations.
+
+    Args:
+        knowledge_service_config: KnowledgeServiceConfig domain object with
+                                 configuration and API information
+
+    Returns:
+        Configured KnowledgeService implementation ready for external
+        operations
+
+    Raises:
+        ValueError: If the service_api is not supported
+
+    Example:
+        >>> from julee.domain import KnowledgeServiceConfig
+        >>> from julee.domain.models.knowledge_service_config import (
+        ...     ServiceApi
+        ... )
+        >>> config = KnowledgeServiceConfig(
+        ...     knowledge_service_id="ks-123",
+        ...     name="My Anthropic Service",
+        ...     description="Anthropic-powered document analysis",
+        ...     service_api=ServiceApi.ANTHROPIC
+        ... )
+        >>> service = knowledge_service_factory(config)
+        >>> result = await service.register_file(document)
+    """
+    logger.debug(
+        "Creating KnowledgeService via factory",
+        extra={
+            "knowledge_service_id": (knowledge_service_config.knowledge_service_id),
+            "service_api": knowledge_service_config.service_api.value,
+        },
+    )
+
+    # Route to appropriate implementation based on service_api
+    service: KnowledgeService
+    if knowledge_service_config.service_api == ServiceApi.ANTHROPIC:
+        service = AnthropicKnowledgeService()
+    else:
+        raise ValueError(
+            f"Unsupported service API: {knowledge_service_config.service_api}"
+        )
+
+    # Validate that the service satisfies the protocol
+    from . import ensure_knowledge_service
+
+    validated_service = ensure_knowledge_service(service)
+
+    logger.info(
+        "KnowledgeService created successfully",
+        extra={
+            "knowledge_service_id": (knowledge_service_config.knowledge_service_id),
+            "service_api": knowledge_service_config.service_api.value,
+            "implementation": type(validated_service).__name__,
+        },
+    )
+
+    return validated_service
+
+
+# Export both the factory function and the configurable class
+__all__ = [
+    "knowledge_service_factory",
+    "ConfigurableKnowledgeService",
+]

julee/services/knowledge_service/knowledge_service.py

@@ -0,0 +1,160 @@
+"""
+KnowledgeService protocol for external service operations in the Capture,
+Extract, Assemble, Publish workflow.
+
+This module defines the KnowledgeService protocol that handles interactions
+with external knowledge services, including document registration and query
+execution. This protocol is separate from the repository layer which only
+handles local metadata persistence.
+
+Concrete implementations of this protocol are provided for different external
+services (Anthropic, OpenAI, etc.) and are created via factory functions.
+"""
+
+from typing import (
+    Protocol,
+    Optional,
+    List,
+    runtime_checkable,
+    Dict,
+    Any,
+    TYPE_CHECKING,
+)
+from datetime import datetime, timezone
+from pydantic import BaseModel, Field
+
+if TYPE_CHECKING:
+    from julee.domain.models.knowledge_service_config import (
+        KnowledgeServiceConfig,
+    )
+
+from julee.domain.models.document import Document
+
+
+class QueryResult(BaseModel):
+    """Result of a knowledge service query execution."""
+
+    query_id: str = Field(description="Unique identifier for this query execution")
+    query_text: str = Field(description="The original query text that was executed")
+    result_data: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="The structured result data from the query",
+    )
+    execution_time_ms: Optional[int] = Field(
+        default=None,
+        description="Time taken to execute the query in milliseconds",
+    )
+    created_at: Optional[datetime] = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+
+
+class FileRegistrationResult(BaseModel):
+    """Result of registering a file with a knowledge service."""
+
+    document_id: str = Field(description="The original document ID from our system")
+    knowledge_service_file_id: str = Field(
+        description="The file identifier assigned by the knowledge service"
+    )
+    registration_metadata: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional metadata from the registration process",
+    )
+    created_at: Optional[datetime] = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+
+
+@runtime_checkable
+class KnowledgeService(Protocol):
+    """
+    Protocol for interacting with external knowledge services.
+
+    This protocol defines the interface for external operations that were
+    moved out of the repository layer. Implementations handle the specifics
+    of different knowledge service APIs (Anthropic, OpenAI, etc.).
+    """
+
+    async def register_file(
+        self, config: "KnowledgeServiceConfig", document: Document
+    ) -> FileRegistrationResult:
+        """Register a document file with the external knowledge service.
+
+        This method registers a document with the external knowledge service,
+        allowing that service to analyze and index the document content for
+        future queries.
+
+        Args:
+            config: KnowledgeServiceConfig for the service to use
+            document: Document domain object to register
+
+        Returns:
+            FileRegistrationResult containing registration details and the
+            service's internal file identifier
+
+        Implementation Notes:
+        - Must be idempotent: re-registering same document returns same result
+        - Should handle service unavailability gracefully
+        - Must return the service's internal file ID for future queries
+        - Document content is accessed directly from the Document object
+        - Should handle various document formats and sizes
+
+        Workflow Context:
+        In Temporal workflows, this method is implemented as an activity
+        to ensure registration results are durably stored and consistent
+        across workflow replays.
+        """
+        ...
+
+    async def execute_query(
+        self,
+        config: "KnowledgeServiceConfig",
+        query_text: str,
+        service_file_ids: Optional[List[str]] = None,
+        query_metadata: Optional[Dict[str, Any]] = None,
+        assistant_prompt: Optional[str] = None,
+    ) -> QueryResult:
+        """Execute a query against the external knowledge service.
+
+        This method executes a text query against the knowledge service,
+        optionally scoping the query to specific documents that have been
+        previously registered with the service.
+
+        Args:
+            config: KnowledgeServiceConfig for the service to use
+            query_text: The query to execute (natural language or structured)
+            service_file_ids: Optional list of service file IDs to provide as
+                             context for the query. These are the IDs returned
+                             by the knowledge service from register_file
+                             operations, and are included in the query to give
+                             the service access to specific documents.
+            query_metadata: Optional service-specific metadata and
+                           configuration options such as model selection,
+                           temperature, max_tokens, etc. The structure depends
+                           on the specific knowledge service being used.
+            assistant_prompt: Optional assistant message content to constrain
+                             or prime the model's response. This is added as
+                             the final assistant message before the model
+                             generates its response, allowing control over
+                             response format and structure.
+
+        Returns:
+            QueryResult containing query results and execution metadata
+
+        Implementation Notes:
+        - Must be idempotent: same query returns consistent results
+        - Service file IDs are provided as context to enhance query responses
+        - Should handle service unavailability gracefully
+        - Query results should be structured as domain objects
+        - Should track execution time and metadata
+        - Must handle various query formats (natural language, structured,
+          etc.)
+        - Should validate that service_file_ids exist in the service before
+          including them in the query context
+
+        Workflow Context:
+        In Temporal workflows, this method is implemented as an activity
+        to ensure query results are durably stored and can be replayed
+        consistently.
+        """
+        ...

julee/services/knowledge_service/memory/__init__.py

@@ -0,0 +1,13 @@
+"""
+Memory-based implementation of KnowledgeService for testing and development.
+
+This module provides an in-memory implementation of the KnowledgeService
+protocol that stores file registrations in memory and returns configurable
+canned responses for queries.
+"""
+
+from .knowledge_service import MemoryKnowledgeService
+
+__all__ = [
+    "MemoryKnowledgeService",
+]

julee/services/knowledge_service/memory/knowledge_service.py

@@ -0,0 +1,278 @@
+"""
+Memory implementation of KnowledgeService for testing and development.
+
+This module provides an in-memory implementation of the KnowledgeService
+protocol that stores file registrations in a dictionary and returns
+configurable canned query responses. Useful for testing and development
+scenarios where external service dependencies should be avoided.
+"""
+
+import logging
+from typing import Optional, List, Dict, Deque, Any
+from datetime import datetime, timezone
+from collections import deque
+
+from julee.domain.models.knowledge_service_config import (
+    KnowledgeServiceConfig,
+)
+from julee.domain.models.document import Document
+from ..knowledge_service import (
+    KnowledgeService,
+    QueryResult,
+    FileRegistrationResult,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryKnowledgeService(KnowledgeService):
+    """
+    In-memory implementation of the KnowledgeService protocol.
+
+    This class stores file registrations in memory using a dictionary
+    keyed by knowledge_service_file_id. Query results are returned from
+    a configurable queue of canned responses.
+
+    Useful for testing and development scenarios where you want to avoid
+    external service dependencies while still exercising the full
+    knowledge service workflow.
+    """
+
+    def __init__(
+        self,
+        config: KnowledgeServiceConfig,
+    ) -> None:
+        """Initialize memory knowledge service with configuration.
+
+        Args:
+            config: KnowledgeServiceConfig domain object containing metadata
+                   and service configuration
+        """
+        logger.debug(
+            "Initializing MemoryKnowledgeService",
+            extra={
+                "knowledge_service_id": config.knowledge_service_id,
+                "service_name": config.name,
+            },
+        )
+
+        self.config = config
+
+        # Storage for file registrations, keyed by knowledge_service_file_id
+        self._registered_files: Dict[str, FileRegistrationResult] = {}
+
+        # Queue of canned query results to return
+        self._canned_query_results: Deque[QueryResult] = deque()
+
+    def add_canned_query_result(self, query_result: QueryResult) -> None:
+        """Add a canned query result to be returned by execute_query.
+
+        Args:
+            query_result: QueryResult to return from future execute_query
+                         calls
+        """
+        logger.debug(
+            "Adding canned query result",
+            extra={
+                "knowledge_service_id": self.config.knowledge_service_id,
+                "query_id": query_result.query_id,
+            },
+        )
+        self._canned_query_results.append(query_result)
+
+    def add_canned_query_results(self, query_results: List[QueryResult]) -> None:
+        """Add multiple canned query results to be returned by execute_query.
+
+        Args:
+            query_results: List of QueryResult objects to return from future
+                          execute_query calls
+        """
+        logger.debug(
+            "Adding multiple canned query results",
+            extra={
+                "knowledge_service_id": self.config.knowledge_service_id,
+                "count": len(query_results),
+            },
+        )
+        self._canned_query_results.extend(query_results)
+
+    def clear_canned_query_results(self) -> None:
+        """Clear all canned query results."""
+        logger.debug(
+            "Clearing canned query results",
+            extra={
+                "knowledge_service_id": self.config.knowledge_service_id,
+                "count": len(self._canned_query_results),
+            },
+        )
+        self._canned_query_results.clear()
+
+    def get_registered_file(
+        self, knowledge_service_file_id: str
+    ) -> Optional[FileRegistrationResult]:
+        """Get a registered file by its knowledge service file ID.
+
+        Args:
+            knowledge_service_file_id: The file ID assigned by this service
+
+        Returns:
+            FileRegistrationResult if found, None otherwise
+        """
+        return self._registered_files.get(knowledge_service_file_id)
+
+    def get_all_registered_files(self) -> Dict[str, FileRegistrationResult]:
+        """Get all registered files.
+
+        Returns:
+            Dictionary mapping knowledge_service_file_id to
+            FileRegistrationResult
+        """
+        return self._registered_files.copy()
+
+    async def register_file(
+        self, config: KnowledgeServiceConfig, document: Document
+    ) -> FileRegistrationResult:
+        """Register a document file by storing metadata in memory.
+
+        Args:
+            config: KnowledgeServiceConfig for this operation
+            document: Document domain object to register
+
+        Returns:
+            FileRegistrationResult with memory-specific details
+        """
+        logger.debug(
+            "Registering file with memory service",
+            extra={
+                "knowledge_service_id": config.knowledge_service_id,
+                "document_id": document.document_id,
+            },
+        )
+
+        # Check if already registered
+        for existing_result in self._registered_files.values():
+            if existing_result.document_id == document.document_id:
+                logger.debug(
+                    "Document already registered, returning existing result",
+                    extra={
+                        "knowledge_service_id": (config.knowledge_service_id),
+                        "document_id": document.document_id,
+                        "knowledge_service_file_id": (
+                            existing_result.knowledge_service_file_id
+                        ),
+                    },
+                )
+                return existing_result
+
+        # Generate a unique file ID for this service
+        timestamp = int(datetime.now().timestamp())
+        memory_file_id = f"memory_{document.document_id}_{timestamp}"
+
+        # Create registration result
+        result = FileRegistrationResult(
+            document_id=document.document_id,
+            knowledge_service_file_id=memory_file_id,
+            registration_metadata={
+                "service": "memory",
+                "registered_via": "in_memory_storage",
+                "timestamp": timestamp,
+                "knowledge_service_id": config.knowledge_service_id,
+                "filename": document.original_filename,
+                "content_type": document.content_type,
+                "size_bytes": document.size_bytes,
+            },
+            created_at=datetime.now(timezone.utc),
+        )
+
+        # Store in memory dictionary keyed by knowledge_service_file_id
+        self._registered_files[memory_file_id] = result
+
+        logger.info(
+            "File registered with MemoryKnowledgeService",
+            extra={
+                "knowledge_service_id": config.knowledge_service_id,
+                "document_id": document.document_id,
+                "knowledge_service_file_id": memory_file_id,
+                "total_registered": len(self._registered_files),
+            },
+        )
+
+        return result
+
+    async def execute_query(
+        self,
+        config: KnowledgeServiceConfig,
+        query_text: str,
+        service_file_ids: Optional[List[str]] = None,
+        query_metadata: Optional[Dict[str, Any]] = None,
+        assistant_prompt: Optional[str] = None,
+    ) -> QueryResult:
+        """Execute a query by returning a canned response.
+
+        Args:
+            config: KnowledgeServiceConfig for this operation
+            query_text: The query to execute
+            service_file_ids: Optional list of service file IDs for query
+            query_metadata: Optional service-specific metadata (ignored in
+                           memory implementation)
+            assistant_prompt: Optional assistant message content (ignored in
+                             memory implementation)
+
+        Returns:
+            QueryResult from the queue of canned responses
+
+        Raises:
+            ValueError: If no canned query results are available
+        """
+        logger.debug(
+            "Executing query with MemoryKnowledgeService",
+            extra={
+                "knowledge_service_id": config.knowledge_service_id,
+                "query_text": query_text,
+                "document_count": (len(service_file_ids) if service_file_ids else 0),
+            },
+        )
+
+        # Check if we have canned results available
+        if not self._canned_query_results:
+            error_msg = (
+                "No canned query results available. Use "
+                "add_canned_query_result() to configure responses."
+            )
+            logger.error(
+                error_msg,
+                extra={
+                    "knowledge_service_id": config.knowledge_service_id,
+                    "query_text": query_text,
+                },
+            )
+            raise ValueError(error_msg)
+
+        # Pop and return the next canned result
+        result = self._canned_query_results.popleft()
+
+        # Update the result to reflect the actual query parameters
+        updated_result = QueryResult(
+            query_id=result.query_id,
+            query_text=query_text,  # Use actual query text
+            result_data={
+                **result.result_data,
+                "queried_documents": service_file_ids or [],
+                "service": "memory",
+                "knowledge_service_id": config.knowledge_service_id,
+            },
+            execution_time_ms=result.execution_time_ms,
+            created_at=datetime.now(timezone.utc),
+        )
+
+        logger.info(
+            "Query executed with MemoryKnowledgeService",
+            extra={
+                "knowledge_service_id": config.knowledge_service_id,
+                "query_id": updated_result.query_id,
+                "execution_time_ms": updated_result.execution_time_ms,
+                "remaining_canned_results": len(self._canned_query_results),
+            },
+        )
+
+        return updated_result