appkit-assistant 0.17.3__py3-none-any.whl → 1.0.0__py3-none-any.whl

appkit_assistant/backend/services/auth_error_detector.py

@@ -0,0 +1,99 @@
+"""Auth Error Detector for detecting authentication failures.
+
+Provides unified error detection utilities shared across all AI processors.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class AuthErrorDetector:
+    """Utility class for detecting authentication errors."""
+
+    # Common authentication error indicators
+    AUTH_INDICATORS: tuple[str, ...] = (
+        "401",
+        "403",
+        "unauthorized",
+        "forbidden",
+        "authentication required",
+        "access denied",
+        "invalid token",
+        "token expired",
+        "not authenticated",
+        "auth_required",
+    )
+
+    def is_auth_error(self, error: Any) -> bool:
+        """Check if an error indicates authentication failure (401/403).
+
+        Args:
+            error: The error object or message
+
+        Returns:
+            True if the error appears to be authentication-related
+        """
+        error_str = str(error).lower()
+        return any(indicator in error_str for indicator in self.AUTH_INDICATORS)
+
+    def extract_error_text(self, error: Any) -> str:
+        """Extract readable error text from an error object.
+
+        Handles various error formats:
+        - dict with 'message' key
+        - objects with 'message' attribute
+        - plain strings or other objects
+
+        Args:
+            error: The error object
+
+        Returns:
+            Human-readable error string
+        """
+        if error is None:
+            return ""
+
+        if isinstance(error, dict):
+            return error.get("message", str(error))
+
+        if hasattr(error, "message"):
+            return getattr(error, "message", str(error))
+
+        return str(error)
+
+    def find_matching_server_in_error(
+        self,
+        error_str: str,
+        servers: list[Any],
+    ) -> Any | None:
+        """Find a server whose name appears in the error message.
+
+        Args:
+            error_str: The error message string (should be lowercase)
+            servers: List of server objects with 'name' attribute
+
+        Returns:
+            The matching server or None
+        """
+        for server in servers:
+            if hasattr(server, "name") and server.name.lower() in error_str.lower():
+                return server
+        return None
+
+
+# Singleton instance for convenience
+_auth_error_detector: AuthErrorDetector | None = None
+
+
+def get_auth_error_detector() -> AuthErrorDetector:
+    """Get or create the auth error detector singleton.
+
+    Returns:
+        The AuthErrorDetector instance
+    """
+    global _auth_error_detector
+    if _auth_error_detector is None:
+        _auth_error_detector = AuthErrorDetector()
+    return _auth_error_detector

appkit_assistant/backend/services/chunk_factory.py

@@ -0,0 +1,273 @@
+"""Chunk Factory for creating standardized Chunk objects.
+
+Provides unified chunk creation with consistent metadata handling
+across all AI processors.
+"""
+
+from typing import Any
+
+from appkit_assistant.backend.schemas import Chunk, ChunkType
+
+
+class ChunkFactory:
+    """Factory for creating Chunk objects with processor-specific metadata."""
+
+    def __init__(self, processor_name: str) -> None:
+        """Initialize the chunk factory.
+
+        Args:
+            processor_name: Name to include in chunk metadata (e.g., "claude_responses")
+        """
+        self._processor_name = processor_name
+
+    @property
+    def processor_name(self) -> str:
+        """Get the processor name."""
+        return self._processor_name
+
+    def create(
+        self,
+        chunk_type: ChunkType,
+        content: str,
+        extra_metadata: dict[str, Any] | None = None,
+    ) -> Chunk:
+        """Create a Chunk with standardized metadata.
+
+        Args:
+            chunk_type: The type of chunk (TEXT, THINKING, TOOL_CALL, etc.)
+            content: The text content of the chunk
+            extra_metadata: Additional metadata to include (values will be stringified)
+
+        Returns:
+            A Chunk instance with processor metadata
+        """
+        metadata: dict[str, str] = {
+            "processor": self._processor_name,
+        }
+
+        if extra_metadata:
+            for key, value in extra_metadata.items():
+                if value is not None:
+                    metadata[key] = str(value)
+
+        return Chunk(
+            type=chunk_type,
+            text=content,
+            chunk_metadata=metadata,
+        )
+
+    def text(self, content: str, delta: str | None = None) -> Chunk:
+        """Create a TEXT chunk.
+
+        Args:
+            content: The text content
+            delta: Optional delta text for streaming
+
+        Returns:
+            A TEXT Chunk
+        """
+        metadata = {"delta": delta} if delta else None
+        return self.create(ChunkType.TEXT, content, metadata)
+
+    def thinking(
+        self,
+        content: str,
+        reasoning_id: str | None = None,
+        status: str = "in_progress",
+        delta: str | None = None,
+    ) -> Chunk:
+        """Create a THINKING chunk.
+
+        Args:
+            content: The thinking content
+            reasoning_id: Optional reasoning session ID
+            status: Status of the thinking (starting, in_progress, completed)
+            delta: Optional delta text for streaming
+
+        Returns:
+            A THINKING Chunk
+        """
+        metadata: dict[str, Any] = {"status": status}
+        if reasoning_id:
+            metadata["reasoning_id"] = reasoning_id
+        if delta is not None:
+            metadata["delta"] = delta
+        return self.create(ChunkType.THINKING, content, metadata)
+
+    def thinking_result(
+        self,
+        content: str,
+        reasoning_id: str | None = None,
+    ) -> Chunk:
+        """Create a THINKING_RESULT chunk.
+
+        Args:
+            content: The result content
+            reasoning_id: Optional reasoning session ID
+
+        Returns:
+            A THINKING_RESULT Chunk
+        """
+        metadata: dict[str, Any] = {"status": "completed"}
+        if reasoning_id:
+            metadata["reasoning_id"] = reasoning_id
+        return self.create(ChunkType.THINKING_RESULT, content, metadata)
+
+    def tool_call(
+        self,
+        content: str,
+        tool_name: str,
+        tool_id: str,
+        server_label: str | None = None,
+        status: str = "starting",
+        reasoning_session: str | None = None,
+    ) -> Chunk:
+        """Create a TOOL_CALL chunk.
+
+        Args:
+            content: Description of the tool call
+            tool_name: Name of the tool being called
+            tool_id: Unique identifier for this tool call
+            server_label: Optional MCP server label
+            status: Status of the tool call
+            reasoning_session: Optional reasoning session ID
+
+        Returns:
+            A TOOL_CALL Chunk
+        """
+        metadata: dict[str, Any] = {
+            "tool_name": tool_name,
+            "tool_id": tool_id,
+            "status": status,
+        }
+        if server_label:
+            metadata["server_label"] = server_label
+        if reasoning_session:
+            metadata["reasoning_session"] = reasoning_session
+        return self.create(ChunkType.TOOL_CALL, content, metadata)
+
+    def tool_result(
+        self,
+        content: str,
+        tool_id: str,
+        status: str = "completed",
+        is_error: bool = False,
+        reasoning_session: str | None = None,
+        tool_name: str | None = None,
+        server_label: str | None = None,
+    ) -> Chunk:
+        """Create a TOOL_RESULT chunk.
+
+        Args:
+            content: The tool result content
+            tool_id: The tool call ID this result corresponds to
+            status: Status of the result
+            is_error: Whether the result is an error
+            reasoning_session: Optional reasoning session ID
+            tool_name: Optional tool name for display
+            server_label: Optional server label for MCP tools
+
+        Returns:
+            A TOOL_RESULT Chunk
+        """
+        metadata: dict[str, Any] = {
+            "tool_id": tool_id,
+            "status": status,
+            "error": is_error,
+        }
+        if reasoning_session:
+            metadata["reasoning_session"] = reasoning_session
+        if tool_name:
+            metadata["tool_name"] = tool_name
+        if server_label:
+            metadata["server_label"] = server_label
+        return self.create(ChunkType.TOOL_RESULT, content, metadata)
+
+    def lifecycle(self, stage: str, extra: dict[str, Any] | None = None) -> Chunk:
+        """Create a LIFECYCLE chunk.
+
+        Args:
+            stage: The lifecycle stage (created, in_progress, done)
+            extra: Additional metadata
+
+        Returns:
+            A LIFECYCLE Chunk
+        """
+        metadata: dict[str, Any] = {"stage": stage}
+        if extra:
+            metadata.update(extra)
+        return self.create(ChunkType.LIFECYCLE, stage, metadata)
+
+    def completion(self, status: str = "response_complete") -> Chunk:
+        """Create a COMPLETION chunk.
+
+        Args:
+            status: The completion status
+
+        Returns:
+            A COMPLETION Chunk
+        """
+        return self.create(
+            ChunkType.COMPLETION,
+            "Response generation completed",
+            {"status": status},
+        )
+
+    def error(self, message: str, error_type: str = "unknown") -> Chunk:
+        """Create an ERROR chunk.
+
+        Args:
+            message: The error message
+            error_type: The type of error
+
+        Returns:
+            An ERROR Chunk
+        """
+        return self.create(
+            ChunkType.ERROR,
+            message,
+            {"error_type": error_type},
+        )
+
+    def auth_required(
+        self,
+        server_name: str,
+        server_id: str | None = None,
+        auth_url: str = "",
+        state: str = "",
+    ) -> Chunk:
+        """Create an AUTH_REQUIRED chunk.
+
+        Args:
+            server_name: Name of the server requiring auth
+            server_id: Optional server ID
+            auth_url: The authorization URL
+            state: The OAuth state parameter
+
+        Returns:
+            An AUTH_REQUIRED Chunk
+        """
+        metadata: dict[str, Any] = {
+            "server_name": server_name,
+            "auth_url": auth_url,
+            "state": state,
+        }
+        if server_id:
+            metadata["server_id"] = server_id
+        return self.create(
+            ChunkType.AUTH_REQUIRED,
+            f"{server_name} benötigt Ihre Autorisierung",
+            metadata,
+        )
+
+    def annotation(self, text: str, annotation_data: dict[str, Any]) -> Chunk:
+        """Create an ANNOTATION chunk.
+
+        Args:
+            text: The annotation text
+            annotation_data: Annotation metadata
+
+        Returns:
+            An ANNOTATION Chunk
+        """
+        return self.create(ChunkType.ANNOTATION, text, annotation_data)

appkit_assistant/backend/services/citation_handler.py

@@ -0,0 +1,292 @@
+"""Citation Handler Protocol and implementations.
+
+Provides a unified interface for extracting and yielding citations
+from different AI API responses.
+"""
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from appkit_assistant.backend.schemas import Chunk, ChunkType
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Citation:
+    """Standardized citation data structure."""
+
+    cited_text: str = ""
+    document_title: str | None = None
+    document_index: int = 0
+    url: str | None = None
+    # Location info (varies by type)
+    start_char_index: int | None = None
+    end_char_index: int | None = None
+    start_page_number: int | None = None
+    end_page_number: int | None = None
+    start_block_index: int | None = None
+    end_block_index: int | None = None
+    # Raw data for passthrough
+    raw_data: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "cited_text": self.cited_text,
+            "document_index": self.document_index,
+        }
+        if self.document_title:
+            result["document_title"] = self.document_title
+        if self.url:
+            result["url"] = self.url
+        if self.start_char_index is not None:
+            result["start_char_index"] = self.start_char_index
+            result["end_char_index"] = self.end_char_index
+        if self.start_page_number is not None:
+            result["start_page_number"] = self.start_page_number
+            result["end_page_number"] = self.end_page_number
+        if self.start_block_index is not None:
+            result["start_block_index"] = self.start_block_index
+            result["end_block_index"] = self.end_block_index
+        return result
+
+
+class CitationHandlerProtocol(Protocol):
+    """Protocol for citation handlers."""
+
+    def extract_citations(self, delta: Any) -> list[Citation]:
+        """Extract citations from a response delta/chunk.
+
+        Args:
+            delta: The response delta object (vendor-specific)
+
+        Returns:
+            List of extracted Citation objects
+        """
+        ...
+
+    async def yield_citation_chunks(
+        self,
+        citations: list[Citation] | list[str],
+        processor_name: str,
+    ) -> AsyncGenerator[Chunk, None]:
+        """Yield citation chunks for display.
+
+        Args:
+            citations: List of Citation objects or URL strings
+            processor_name: Name of the processor for metadata
+
+        Yields:
+            Chunk objects for citation display
+        """
+        ...
+
+
+class BaseCitationHandler(ABC):
+    """Base class for citation handlers."""
+
+    @abstractmethod
+    def extract_citations(self, delta: Any) -> list[Citation]:
+        """Extract citations from a response delta."""
+
+    async def yield_citation_chunks(
+        self,
+        citations: list[Citation] | list[str],
+        processor_name: str,
+    ) -> AsyncGenerator[Chunk, None]:
+        """Default implementation yields ANNOTATION chunks."""
+        if not citations:
+            return
+
+        logger.debug("Processing %d citations", len(citations))
+
+        for citation in citations:
+            if isinstance(citation, str):
+                # URL string
+                yield Chunk(
+                    type=ChunkType.ANNOTATION,
+                    text=citation,
+                    chunk_metadata={
+                        "url": citation,
+                        "processor": processor_name,
+                    },
+                )
+            else:
+                # Citation object
+                text = citation.url or citation.document_title or citation.cited_text
+                yield Chunk(
+                    type=ChunkType.ANNOTATION,
+                    text=text or "",
+                    chunk_metadata={
+                        "citation": json.dumps(citation.to_dict()),
+                        "processor": processor_name,
+                    },
+                )
+
+
+class ClaudeCitationHandler(BaseCitationHandler):
+    """Citation handler for Claude API responses.
+
+    Claude provides citations in text delta's citations field with
+    various location types (char, page, content_block).
+    """
+
+    def extract_citations(self, delta: Any) -> list[Citation]:
+        """Extract citations from Claude text delta.
+
+        Args:
+            delta: Claude API text delta object
+
+        Returns:
+            List of Citation objects
+        """
+        citations = []
+
+        text_block_citations = getattr(delta, "citations", None)
+        if not text_block_citations:
+            return citations
+
+        for citation_obj in text_block_citations:
+            citation = Citation(
+                cited_text=getattr(citation_obj, "cited_text", ""),
+                document_index=getattr(citation_obj, "document_index", 0),
+                document_title=getattr(citation_obj, "document_title", None),
+            )
+
+            # Handle different citation location types
+            citation_type = getattr(citation_obj, "type", None)
+            if citation_type == "char_location":
+                citation.start_char_index = getattr(citation_obj, "start_char_index", 0)
+                citation.end_char_index = getattr(citation_obj, "end_char_index", 0)
+            elif citation_type == "page_location":
+                citation.start_page_number = getattr(
+                    citation_obj, "start_page_number", 0
+                )
+                citation.end_page_number = getattr(citation_obj, "end_page_number", 0)
+            elif citation_type == "content_block_location":
+                citation.start_block_index = getattr(
+                    citation_obj, "start_block_index", 0
+                )
+                citation.end_block_index = getattr(citation_obj, "end_block_index", 0)
+
+            citations.append(citation)
+
+        return citations
+
+
+class PerplexityCitationHandler(BaseCitationHandler):
+    """Citation handler for Perplexity API responses.
+
+    Perplexity provides URL-based citations that should be displayed
+    as annotation chunks after streaming completes.
+    """
+
+    def extract_citations(self, delta: Any) -> list[Citation]:
+        """Extract citations from Perplexity response.
+
+        Args:
+            delta: Perplexity response with citations attribute
+
+        Returns:
+            List of Citation objects with URLs
+        """
+        citations = []
+
+        raw_citations = getattr(delta, "citations", None)
+        if not raw_citations:
+            return citations
+
+        citations.extend(
+            Citation(url=url, document_title=url)
+            for url in raw_citations
+            if isinstance(url, str)
+        )
+
+        return citations
+
+    async def yield_citation_chunks(
+        self,
+        citations: list[Citation] | list[str],
+        processor_name: str,
+    ) -> AsyncGenerator[Chunk, None]:
+        """Yield citation chunks for Perplexity.
+
+        Perplexity yields:
+        1. A TEXT chunk with all citations in metadata (for accumulator)
+        2. Individual ANNOTATION chunks for immediate display
+        """
+        if not citations:
+            return
+
+        logger.debug("Processing %d Perplexity citations", len(citations))
+
+        # Convert to list of dicts for JSON
+        citations_data = []
+        for citation in citations:
+            if isinstance(citation, str):
+                citations_data.append({"url": citation, "document_title": citation})
+            else:
+                citations_data.append(
+                    {
+                        "url": citation.url,
+                        "document_title": citation.document_title,
+                    }
+                )
+
+        # Yield TEXT chunk with citations metadata for accumulator
+        yield Chunk(
+            type=ChunkType.TEXT,
+            text="",  # Empty text, just carries citations metadata
+            chunk_metadata={
+                "citations": json.dumps(citations_data),
+                "source": "perplexity",
+                "processor": processor_name,
+            },
+        )
+
+        # Yield individual ANNOTATION chunks for display
+        for citation in citations:
+            url = citation if isinstance(citation, str) else citation.url
+            if url:
+                yield Chunk(
+                    type=ChunkType.ANNOTATION,
+                    text=url,
+                    chunk_metadata={
+                        "url": url,
+                        "source": "perplexity",
+                        "processor": processor_name,
+                    },
+                )
+
+
+class NullCitationHandler(BaseCitationHandler):
+    """No-op citation handler for APIs without citation support.
+
+    Use this for OpenAI and Gemini processors that don't have
+    built-in citation extraction.
+    """
+
+    def extract_citations(self, delta: Any) -> list[Citation]:  # noqa: ARG002
+        """Return empty list - no citation support.
+
+        Args:
+            delta: Ignored
+
+        Returns:
+            Empty list
+        """
+        return []
+
+    async def yield_citation_chunks(
+        self,
+        citations: list[Citation] | list[str],  # noqa: ARG002
+        processor_name: str,  # noqa: ARG002
+    ) -> AsyncGenerator[Chunk, None]:
+        """Yield nothing - no citation support."""
+        return
+        yield  # Make this a generator  # noqa: B901