julee 0.1.0__py3-none-any.whl

julee/services/knowledge_service/anthropic/knowledge_service.py

@@ -0,0 +1,331 @@
+"""
+Anthropic implementation of KnowledgeService for the Capture, Extract,
+Assemble, Publish workflow.
+
+This module provides the Anthropic-specific implementation of the
+KnowledgeService protocol. It handles interactions with Anthropic's API
+for document registration and query execution.
+
+Requirements:
+    - ANTHROPIC_API_KEY environment variable must be set
+"""
+
+import os
+import logging
+import time
+import uuid
+from typing import Optional, List, Dict, Any
+from datetime import datetime, timezone
+
+from anthropic import AsyncAnthropic
+
+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__)
+
+# Default configuration constants
+DEFAULT_MODEL = "claude-sonnet-4-20250514"
+DEFAULT_MAX_TOKENS = 4000
+
+
+class AnthropicKnowledgeService(KnowledgeService):
+    """
+    Anthropic implementation of the KnowledgeService protocol.
+
+    This class handles interactions with Anthropic's API for document
+    registration and query execution. It implements the KnowledgeService
+    protocol with Anthropic-specific logic.
+    """
+
+    def __init__(self) -> None:
+        """Initialize Anthropic knowledge service without configuration.
+
+        Configuration will be provided per method call to maintain
+        stateless operation compatible with Temporal workflows.
+        """
+        # No initialization needed - everything happens per method call
+        pass
+
+    def _get_client(self, config: KnowledgeServiceConfig) -> AsyncAnthropic:
+        """Get an initialized Anthropic client.
+
+        Args:
+            config: KnowledgeServiceConfig (for future extensibility)
+
+        Returns:
+            Configured AsyncAnthropic client instance
+
+        Raises:
+            ValueError: If ANTHROPIC_API_KEY environment variable is not set
+        """
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "ANTHROPIC_API_KEY environment variable is required for "
+                "AnthropicKnowledgeService"
+            )
+
+        return AsyncAnthropic(
+            api_key=api_key,
+            default_headers={"anthropic-beta": "files-api-2025-04-14"},
+        )
+
+    async def register_file(
+        self, config: KnowledgeServiceConfig, document: Document
+    ) -> FileRegistrationResult:
+        """Register a document file with Anthropic.
+
+        Args:
+            config: KnowledgeServiceConfig for this operation
+            document: Document domain object to register
+
+        Returns:
+            FileRegistrationResult with Anthropic-specific details
+        """
+        logger.debug(
+            "Registering file with Anthropic",
+            extra={
+                "knowledge_service_id": config.knowledge_service_id,
+                "document_id": document.document_id,
+            },
+        )
+
+        try:
+            # Get Anthropic client for this operation
+            client = self._get_client(config)
+
+            # Ensure content stream is positioned at beginning for upload
+            if document.content:
+                document.content.seek(0)
+
+            # Upload file using Anthropic beta Files API
+            # Use tuple format: (filename, file_stream, media_type)
+            if not document.content:
+                raise ValueError("Document content stream is required for upload")
+
+            # Anthropic only supports PDF and plaintext files
+            # Convert JSON content type to text/plain for compatibility
+            content_type = document.content_type
+            if content_type == "application/json":
+                content_type = "text/plain"
+
+            file_response = await client.beta.files.upload(
+                file=(
+                    document.original_filename,
+                    document.content.stream,  # type: ignore[arg-type]
+                    content_type,
+                )
+            )
+
+            anthropic_file_id = file_response.id
+
+            result = FileRegistrationResult(
+                document_id=document.document_id,
+                knowledge_service_file_id=anthropic_file_id,
+                registration_metadata={
+                    "service": "anthropic",
+                    "registered_via": "beta_files_api",
+                    "filename": document.original_filename,
+                    "content_type": document.content_type,
+                    "size_bytes": document.size_bytes,
+                    "content_multihash": document.content_multihash,
+                    "anthropic_file_id": anthropic_file_id,
+                },
+                created_at=datetime.now(timezone.utc),
+            )
+
+            logger.info(
+                "File registered with Anthropic beta Files API",
+                extra={
+                    "knowledge_service_id": config.knowledge_service_id,
+                    "document_id": document.document_id,
+                    "anthropic_file_id": anthropic_file_id,
+                    "original_filename": document.original_filename,
+                    "size_bytes": document.size_bytes,
+                },
+            )
+
+            return result
+
+        except Exception as e:
+            logger.error(
+                "Failed to register file with Anthropic",
+                extra={
+                    "knowledge_service_id": config.knowledge_service_id,
+                    "document_id": document.document_id,
+                    "error": str(e),
+                },
+                exc_info=True,
+            )
+            raise
+
+    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 Anthropic.
+
+        Args:
+            config: KnowledgeServiceConfig for this operation
+            query_text: The query to execute
+            service_file_ids: Optional list of Anthropic file IDs to provide
+                             as context for the query
+            query_metadata: Optional Anthropic-specific configuration such as
+                           model, temperature, max_tokens, etc.
+            assistant_prompt: Optional assistant message content to constrain
+                             or prime the model's response
+
+        Returns:
+            QueryResult with Anthropic query results
+        """
+        logger.debug(
+            "Executing query with Anthropic",
+            extra={
+                "knowledge_service_id": config.knowledge_service_id,
+                "query_text": query_text,
+                "document_count": (len(service_file_ids) if service_file_ids else 0),
+                "file_count": (len(service_file_ids) if service_file_ids else 0),
+            },
+        )
+
+        start_time = time.time()
+        query_id = f"anthropic_{uuid.uuid4().hex[:12]}"
+
+        # Extract configuration from query_metadata
+        metadata = query_metadata or {}
+        model = metadata.get("model", DEFAULT_MODEL)
+        max_tokens = metadata.get("max_tokens", DEFAULT_MAX_TOKENS)
+        temperature = metadata.get("temperature")
+
+        try:
+            # Get Anthropic client for this operation
+            client = self._get_client(config)
+
+            # Prepare the message content with file attachments if provided
+            content_parts = []
+
+            # Add file attachments if service_file_ids are provided
+            if service_file_ids:
+                for file_id in service_file_ids:
+                    content_parts.append(
+                        {
+                            "type": "document",
+                            "source": {"type": "file", "file_id": file_id},
+                        }
+                    )
+
+            # Add the text query
+            content_parts.append({"type": "text", "text": query_text})
+
+            # Prepare messages for the API
+            messages = [{"role": "user", "content": content_parts}]
+
+            # Add assistant message if provided to constrain response
+            if assistant_prompt:
+                messages.append({"role": "assistant", "content": assistant_prompt})
+
+            create_params = {
+                "model": model,
+                "max_tokens": max_tokens,
+                "messages": messages,
+            }
+
+            # Add temperature if specified
+            if temperature is not None:
+                create_params["temperature"] = temperature
+
+            response = await client.messages.create(**create_params)
+
+            # Calculate execution time
+            execution_time_ms = int((time.time() - start_time) * 1000)
+
+            # Validate response has exactly one content block of type 'text'
+            if len(response.content) != 1:
+                raise ValueError(
+                    f"Expected exactly 1 content block, got " f"{len(response.content)}"
+                )
+
+            content_block = response.content[0]
+
+            if not hasattr(content_block, "type") or content_block.type != "text":
+                block_type = getattr(content_block, "type", "unknown")
+                raise ValueError(
+                    f"Expected content block type 'text', got '{block_type}'"
+                )
+
+            if not hasattr(content_block, "text"):
+                raise ValueError("Text content block missing 'text' attribute")
+
+            response_text = str(content_block.text)
+
+            logger.debug(
+                "Single text content block validated and extracted",
+                extra={
+                    "knowledge_service_id": config.knowledge_service_id,
+                    "query_id": query_id,
+                    "response_length": len(response_text),
+                },
+            )
+
+            # Structure the result with single text content
+            result_data = {
+                "response": response_text,
+                "model": model,
+                "service": "anthropic",
+                "sources": service_file_ids or [],
+                "usage": {
+                    "input_tokens": response.usage.input_tokens,
+                    "output_tokens": response.usage.output_tokens,
+                },
+                "stop_reason": response.stop_reason,
+            }
+
+            result = QueryResult(
+                query_id=query_id,
+                query_text=query_text,
+                result_data=result_data,
+                execution_time_ms=execution_time_ms,
+                created_at=datetime.now(timezone.utc),
+            )
+
+            logger.info(
+                "Query executed with Anthropic successfully",
+                extra={
+                    "knowledge_service_id": config.knowledge_service_id,
+                    "query_id": query_id,
+                    "execution_time_ms": execution_time_ms,
+                    "input_tokens": response.usage.input_tokens,
+                    "output_tokens": response.usage.output_tokens,
+                    "file_count": (len(service_file_ids) if service_file_ids else 0),
+                },
+            )
+
+            return result
+
+        except Exception as e:
+            execution_time_ms = int((time.time() - start_time) * 1000)
+            logger.error(
+                "Failed to execute query with Anthropic",
+                extra={
+                    "knowledge_service_id": config.knowledge_service_id,
+                    "query_id": query_id,
+                    "query_text": query_text,
+                    "execution_time_ms": execution_time_ms,
+                    "file_count": (len(service_file_ids) if service_file_ids else 0),
+                    "error": str(e),
+                },
+                exc_info=True,
+            )
+            raise

julee/services/knowledge_service/anthropic/tests/test_knowledge_service.py

@@ -0,0 +1,318 @@
+"""
+Tests for AnthropicKnowledgeService implementation.
+
+This module contains tests for the Anthropic implementation of the
+KnowledgeService protocol, verifying file registration and query
+execution functionality.
+"""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+from datetime import datetime, timezone
+import io
+
+from julee.domain.models.knowledge_service_config import (
+    KnowledgeServiceConfig,
+)
+from julee.domain.models.document import Document, DocumentStatus
+from julee.domain.models.knowledge_service_config import ServiceApi
+from julee.domain.models.custom_fields.content_stream import (
+    ContentStream,
+)
+from julee.services.knowledge_service.anthropic import (
+    knowledge_service as anthropic_ks,
+)
+from julee.services.knowledge_service.anthropic import (
+    knowledge_service as anthropic_ks_module,
+)
+
+
+@pytest.fixture
+def test_document() -> Document:
+    """Create a test Document for testing."""
+    content_text = "This is test document content for knowledge service testing."
+    content_bytes = content_text.encode("utf-8")
+    content_stream = ContentStream(io.BytesIO(content_bytes))
+
+    return Document(
+        document_id="test-doc-123",
+        original_filename="test_document.txt",
+        content_type="text/plain",
+        size_bytes=len(content_bytes),
+        content_multihash="test-hash-123",
+        status=DocumentStatus.CAPTURED,
+        content=content_stream,
+        created_at=datetime.now(timezone.utc),
+        updated_at=datetime.now(timezone.utc),
+    )
+
+
+@pytest.fixture
+def knowledge_service_config() -> KnowledgeServiceConfig:
+    """Create a test KnowledgeServiceConfig for Anthropic."""
+    return KnowledgeServiceConfig(
+        knowledge_service_id="ks-anthropic-test",
+        name="Test Anthropic Service",
+        description="Anthropic service for testing",
+        service_api=ServiceApi.ANTHROPIC,
+    )
+
+
+@pytest.fixture
+def mock_anthropic_client() -> MagicMock:
+    """Create a mock Anthropic client."""
+    mock_client = MagicMock()
+
+    # Mock the messages.create response
+    mock_response = MagicMock()
+    mock_content_block = MagicMock()
+    mock_content_block.type = "text"
+    mock_content_block.text = "This is a test response from Anthropic."
+    mock_response.content = [mock_content_block]
+    mock_response.usage.input_tokens = 150
+    mock_response.usage.output_tokens = 25
+    mock_response.stop_reason = "end_turn"
+
+    mock_client.messages.create = AsyncMock(return_value=mock_response)
+
+    return mock_client
+
+
+class TestAnthropicKnowledgeService:
+    """Test cases for AnthropicKnowledgeService."""
+
+    @patch.dict("os.environ", {"ANTHROPIC_API_KEY": "test-key"})
+    async def test_execute_query_without_files(
+        self,
+        knowledge_service_config: KnowledgeServiceConfig,
+        mock_anthropic_client: MagicMock,
+    ) -> None:
+        """Test execute_query without service file IDs."""
+        with patch(
+            "julee.services.knowledge_service.anthropic.knowledge_service.AsyncAnthropic"
+        ) as mock_anthropic:
+            mock_anthropic.return_value = mock_anthropic_client
+
+            service = anthropic_ks.AnthropicKnowledgeService()
+
+            query_text = "What is machine learning?"
+            result = await service.execute_query(knowledge_service_config, query_text)
+
+            # Verify the result structure
+            assert result.query_text == query_text
+            assert (
+                result.result_data["response"]
+                == "This is a test response from Anthropic."
+            )
+            assert result.result_data["model"] == anthropic_ks_module.DEFAULT_MODEL
+            assert result.result_data["service"] == "anthropic"
+            assert result.result_data["sources"] == []
+            assert result.result_data["usage"]["input_tokens"] == 150
+            assert result.result_data["usage"]["output_tokens"] == 25
+            assert result.result_data["stop_reason"] == "end_turn"
+            assert result.execution_time_ms is not None
+            assert result.execution_time_ms >= 0
+            assert isinstance(result.created_at, datetime)
+
+            # Verify the API call was made correctly
+            mock_anthropic_client.messages.create.assert_called_once()
+            call_args = mock_anthropic_client.messages.create.call_args
+            assert call_args[1]["model"] == anthropic_ks_module.DEFAULT_MODEL
+            assert call_args[1]["max_tokens"] == anthropic_ks_module.DEFAULT_MAX_TOKENS
+            assert len(call_args[1]["messages"]) == 1
+            assert call_args[1]["messages"][0]["role"] == "user"
+
+            # Should have only one content part (the text query)
+            content_parts = call_args[1]["messages"][0]["content"]
+            assert len(content_parts) == 1
+            assert content_parts[0]["type"] == "text"
+            assert content_parts[0]["text"] == query_text
+
+    @patch.dict("os.environ", {"ANTHROPIC_API_KEY": "test-key"})
+    async def test_execute_query_with_files(
+        self,
+        knowledge_service_config: KnowledgeServiceConfig,
+        mock_anthropic_client: MagicMock,
+    ) -> None:
+        """Test execute_query with service file IDs."""
+        with patch(
+            "julee.services.knowledge_service.anthropic.knowledge_service.AsyncAnthropic"
+        ) as mock_anthropic:
+            mock_anthropic.return_value = mock_anthropic_client
+
+            service = anthropic_ks.AnthropicKnowledgeService()
+
+            query_text = "What is in the document?"
+            service_file_ids = ["file_123", "file_456"]
+            result = await service.execute_query(
+                knowledge_service_config,
+                query_text,
+                service_file_ids=service_file_ids,
+            )
+
+            # Verify the result structure
+            assert result.query_text == query_text
+            assert result.result_data["sources"] == service_file_ids
+            assert result.execution_time_ms is not None
+            assert result.execution_time_ms >= 0
+
+            # Verify the API call was made with file attachments
+            mock_anthropic_client.messages.create.assert_called_once()
+            call_args = mock_anthropic_client.messages.create.call_args
+
+            # Should have file attachments plus text query
+            content_parts = call_args[1]["messages"][0]["content"]
+            assert len(content_parts) == 3  # 2 files + 1 text query
+
+            # Check file attachments
+            assert content_parts[0]["type"] == "document"
+            assert content_parts[0]["source"]["type"] == "file"
+            assert content_parts[0]["source"]["file_id"] == "file_123"
+
+            assert content_parts[1]["type"] == "document"
+            assert content_parts[1]["source"]["type"] == "file"
+            assert content_parts[1]["source"]["file_id"] == "file_456"
+
+            # Check text query
+            assert content_parts[2]["type"] == "text"
+            assert content_parts[2]["text"] == query_text
+
+    @patch.dict("os.environ", {"ANTHROPIC_API_KEY": "test-key"})
+    async def test_execute_query_handles_api_error(
+        self,
+        knowledge_service_config: KnowledgeServiceConfig,
+    ) -> None:
+        """Test execute_query handles API errors gracefully."""
+        mock_client = MagicMock()
+        mock_client.messages.create = AsyncMock(side_effect=Exception("API Error"))
+
+        with patch(
+            "julee.services.knowledge_service.anthropic.knowledge_service.AsyncAnthropic"
+        ) as mock_anthropic:
+            mock_anthropic.return_value = mock_client
+
+            service = anthropic_ks.AnthropicKnowledgeService()
+
+            with pytest.raises(Exception):
+                await service.execute_query(knowledge_service_config, "Test query")
+
+    @patch.dict("os.environ", {"ANTHROPIC_API_KEY": "test-key"})
+    async def test_query_id_generation(
+        self,
+        knowledge_service_config: KnowledgeServiceConfig,
+        mock_anthropic_client: MagicMock,
+    ) -> None:
+        """Test that query IDs are unique and properly formatted."""
+        with patch(
+            "julee.services.knowledge_service.anthropic.knowledge_service.AsyncAnthropic"
+        ) as mock_anthropic:
+            mock_anthropic.return_value = mock_anthropic_client
+
+            service = anthropic_ks.AnthropicKnowledgeService()
+
+            # Execute two queries
+            result1 = await service.execute_query(
+                knowledge_service_config, "First query"
+            )
+            result2 = await service.execute_query(
+                knowledge_service_config, "Second query"
+            )
+
+            # Query IDs should be unique and follow expected format
+            assert result1.query_id != result2.query_id
+            assert result1.query_id.startswith("anthropic_")
+            assert result2.query_id.startswith("anthropic_")
+            assert len(result1.query_id) == len("anthropic_") + 12  # UUID hex[:12]
+            assert len(result2.query_id) == len("anthropic_") + 12
+
+    @patch.dict("os.environ", {"ANTHROPIC_API_KEY": "test-key"})
+    async def test_empty_service_file_ids(
+        self,
+        knowledge_service_config: KnowledgeServiceConfig,
+        mock_anthropic_client: MagicMock,
+    ) -> None:
+        """Test execute_query with empty service_file_ids list."""
+        with patch(
+            "julee.services.knowledge_service.anthropic.knowledge_service.AsyncAnthropic"
+        ) as mock_anthropic:
+            mock_anthropic.return_value = mock_anthropic_client
+
+            service = anthropic_ks.AnthropicKnowledgeService()
+
+            query_text = "What is in the document?"
+            result = await service.execute_query(
+                knowledge_service_config, query_text, service_file_ids=[]
+            )
+
+            # Should behave the same as None
+            assert result.result_data["sources"] == []
+
+            # Verify API call structure
+            call_args = mock_anthropic_client.messages.create.call_args
+            content_parts = call_args[1]["messages"][0]["content"]
+            assert len(content_parts) == 1  # Only text query, no files
+            assert content_parts[0]["type"] == "text"
+
+    @patch.dict("os.environ", {"ANTHROPIC_API_KEY": "test-key"})
+    async def test_execute_query_with_metadata(
+        self,
+        knowledge_service_config: KnowledgeServiceConfig,
+        mock_anthropic_client: MagicMock,
+    ) -> None:
+        """Test execute_query with query_metadata configuration."""
+        with patch(
+            "julee.services.knowledge_service.anthropic.knowledge_service.AsyncAnthropic"
+        ) as mock_anthropic:
+            mock_anthropic.return_value = mock_anthropic_client
+
+            service = anthropic_ks.AnthropicKnowledgeService()
+
+            metadata = {
+                "model": "claude-opus-4-1-20250805",
+                "max_tokens": 2000,
+                "temperature": 0.7,
+            }
+
+            query_text = "Custom query with metadata"
+            result = await service.execute_query(
+                knowledge_service_config, query_text, query_metadata=metadata
+            )
+
+            # Verify the result uses metadata values
+            assert result.result_data["model"] == "claude-opus-4-1-20250805"
+            assert result.execution_time_ms is not None
+            assert result.execution_time_ms >= 0
+
+            # Verify API call used metadata values
+            mock_anthropic_client.messages.create.assert_called_once()
+            call_args = mock_anthropic_client.messages.create.call_args
+            assert call_args[1]["model"] == "claude-opus-4-1-20250805"
+            assert call_args[1]["max_tokens"] == 2000
+            assert call_args[1]["temperature"] == 0.7
+
+    @patch.dict("os.environ", {"ANTHROPIC_API_KEY": "test-key"})
+    async def test_execute_query_metadata_defaults(
+        self,
+        knowledge_service_config: KnowledgeServiceConfig,
+        mock_anthropic_client: MagicMock,
+    ) -> None:
+        """Test execute_query uses default values when metadata is None."""
+        with patch(
+            "julee.services.knowledge_service.anthropic.knowledge_service.AsyncAnthropic"
+        ) as mock_anthropic:
+            mock_anthropic.return_value = mock_anthropic_client
+
+            service = anthropic_ks.AnthropicKnowledgeService()
+
+            result = await service.execute_query(
+                knowledge_service_config, "Test query", query_metadata=None
+            )
+
+            # Verify defaults are used
+            assert result.result_data["model"] == anthropic_ks_module.DEFAULT_MODEL
+
+            # Verify API call used defaults
+            call_args = mock_anthropic_client.messages.create.call_args
+            assert call_args[1]["model"] == anthropic_ks_module.DEFAULT_MODEL
+            assert call_args[1]["max_tokens"] == anthropic_ks_module.DEFAULT_MAX_TOKENS
+            assert "temperature" not in call_args[1]  # Not set by default