ai-pipeline-core 0.1.8__py3-none-any.whl → 0.1.11__py3-none-any.whl

ai_pipeline_core/documents/task_document.py

@@ -1,28 +1,133 @@
-"""Task-specific document base class."""
+"""Task-specific document base class for temporary pipeline data.
 
-from typing import Any, Literal, final
+@public
+
+This module provides the TaskDocument abstract base class for documents
+that exist only during Prefect task execution and are not persisted.
+"""
+
+from typing import Literal, final
 
 from .document import Document
 
 
 class TaskDocument(Document):
-    """
-    Abstract base class for task-specific documents.
+    """Abstract base class for temporary documents within task execution.
+
+    @public
+
+    TaskDocument is used for intermediate data that exists only during
+    the execution of a Prefect task and is not persisted to disk. These
+    documents are ideal for temporary processing results, transformations,
+    and data that doesn't need to survive beyond the current task.
+
+    Key characteristics:
+    - Not persisted to file system
+    - Exists only during task execution
+    - Garbage collected after task completes
+    - Used for intermediate processing results
+    - Reduces persistent I/O for temporary data
+
+    Creating TaskDocuments:
+        **Use the `create` classmethod** for most use cases. It handles automatic
+        conversion of various content types. Only use __init__ when you have bytes.
+
+        >>> from enum import StrEnum
+        >>>
+        >>> # Simple task document:
+        >>> class TempDoc(TaskDocument):
+        ...     pass
+        >>>
+        >>> # With restricted files:
+        >>> class CacheDoc(TaskDocument):
+        ...     class FILES(StrEnum):
+        ...         CACHE = "cache.json"
+        ...         INDEX = "index.dat"
+        >>>
+        >>> # RECOMMENDED - automatic conversion:
+        >>> doc = TempDoc.create(name="temp.json", content={"status": "processing"})
+        >>> doc = CacheDoc.create(name="cache.json", content={"data": [1, 2, 3]})
+
+    Use Cases:
+        - Intermediate transformation results
+        - Temporary buffers during processing
+        - Task-local cache data
+        - Processing status documents
 
-    Task documents represent inputs, outputs, and intermediate results
-    within a Prefect task execution context.
+    Note:
+        - Cannot instantiate TaskDocument directly - must subclass
+        - Not saved by simple_runner utilities
+        - Reduces I/O overhead for temporary data
+        - No additional abstract methods to implement
 
-    Compared to FlowDocument, TaskDocument are not persisted across Prefect task runs.
-    They are used for intermediate results that are not needed after the task completes.
+    See Also:
+        FlowDocument: For documents that persist across flow runs
+        TemporaryDocument: Alternative for non-persistent documents
     """
 
-    def __init__(self, **data: Any) -> None:
-        """Prevent direct instantiation of abstract TaskDocument class."""
+    def __init__(
+        self,
+        *,
+        name: str,
+        content: bytes,
+        description: str | None = None,
+    ) -> None:
+        """Initialize a TaskDocument with raw bytes content.
+
+        Important:
+            **Most users should use the `create` classmethod instead of __init__.**
+            The create method provides automatic content conversion for various types
+            (str, dict, list, Pydantic models) while __init__ only accepts bytes.
+
+        Prevents direct instantiation of the abstract TaskDocument class.
+        TaskDocument must be subclassed for specific temporary document types.
+
+        Args:
+            name: Document filename (required, keyword-only)
+            content: Document content as raw bytes (required, keyword-only)
+            description: Optional human-readable description (keyword-only)
+
+        Raises:
+            TypeError: If attempting to instantiate TaskDocument directly
+                      instead of using a concrete subclass.
+
+        Example:
+            >>> from enum import StrEnum
+            >>>
+            >>> # Simple subclass:
+            >>> class MyTaskDoc(TaskDocument):
+            ...     pass
+            >>>
+            >>> # With FILES restriction:
+            >>> class TempProcessDoc(TaskDocument):
+            ...     class FILES(StrEnum):
+            ...         BUFFER = "buffer.bin"
+            ...         STATUS = "status.json"
+            >>>
+            >>> # Direct constructor - only for bytes:
+            >>> doc = MyTaskDoc(name="temp.bin", content=b"raw data")
+            >>>
+            >>> # RECOMMENDED - use create for automatic conversion:
+            >>> doc = TempProcessDoc.create(name="status.json", content={"percent": 50})
+            >>> # This would raise DocumentNameError:
+            >>> # doc = TempProcessDoc.create(name="other.json", content={})
+        """
         if type(self) is TaskDocument:
             raise TypeError("Cannot instantiate abstract TaskDocument class directly")
-        super().__init__(**data)
+        super().__init__(name=name, content=content, description=description)
 
     @final
     def get_base_type(self) -> Literal["task"]:
-        """Get the document type."""
+        """Return the base type identifier for task documents.
+
+        This method is final and cannot be overridden by subclasses.
+        It identifies this document as a task-scoped temporary document.
+
+        Returns:
+            "task" - Indicates this document is temporary within task execution.
+
+        Note:
+            This determines that the document will not be persisted and
+            exists only during task execution.
+        """
         return "task"

ai_pipeline_core/documents/temporary_document.py

@@ -0,0 +1,95 @@
+"""Temporary document implementation for non-persistent data.
+
+@public
+
+This module provides the TemporaryDocument class for documents that
+are never persisted, regardless of context.
+"""
+
+from typing import Any, Literal, final
+
+from .document import Document
+
+
+@final
+class TemporaryDocument(Document):
+    r"""Concrete document class for data that is never persisted.
+
+    @public
+
+    TemporaryDocument is a final (non-subclassable) document type for
+    data that should never be saved to disk, regardless of whether it's
+    used in a flow or task context. Unlike FlowDocument and TaskDocument
+    which are abstract, TemporaryDocument can be instantiated directly.
+
+    Key characteristics:
+    - Never persisted to file system
+    - Can be instantiated directly (not abstract)
+    - Cannot be subclassed (annotated with Python's @final decorator in code)
+    - Useful for transient data like API responses or intermediate calculations
+    - Ignored by simple_runner save operations
+
+    Creating TemporaryDocuments:
+        **Use the `create` classmethod** for most use cases. It handles automatic
+        conversion of various content types. Only use __init__ when you have bytes.
+
+        >>> # RECOMMENDED - automatic conversion:
+        >>> doc = TemporaryDocument.create(
+        ...     name="api_response.json",
+        ...     content={"status": "ok", "data": [1, 2, 3]}
+        ... )
+        >>> doc = TemporaryDocument.create(
+        ...     name="credentials.txt",
+        ...     content="secret_token_xyz"
+        ... )
+        >>>
+        >>> # Direct constructor - only for bytes:
+        >>> doc = TemporaryDocument(
+        ...     name="binary.dat",
+        ...     content=b"\x00\x01\x02"
+        ... )
+        >>>
+        >>> doc.is_temporary  # Always True
+
+    Use Cases:
+        - API responses that shouldn't be cached
+        - Sensitive credentials or tokens
+        - Intermediate calculations
+        - Temporary transformations
+        - Data explicitly marked as non-persistent
+
+    Note:
+        - This is a final class and cannot be subclassed
+        - Use when you explicitly want to prevent persistence
+        - Useful for sensitive data that shouldn't be written to disk
+
+    See Also:
+        FlowDocument: For documents that persist across flow runs
+        TaskDocument: For documents temporary within task execution
+    """
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Disallow subclassing.
+
+        Args:
+            **kwargs: Additional keyword arguments (ignored).
+
+        Raises:
+            TypeError: Always raised to prevent subclassing of `TemporaryDocument`.
+        """
+        raise TypeError("TemporaryDocument is final and cannot be subclassed")
+
+    def get_base_type(self) -> Literal["temporary"]:
+        """Return the base type identifier for temporary documents.
+
+        Identifies this document as temporary, ensuring it will
+        never be persisted by the pipeline system.
+
+        Returns:
+            "temporary" - Indicates this document is never persisted.
+
+        Note:
+            Documents with this type are explicitly excluded from
+            all persistence operations in the pipeline system.
+        """
+        return "temporary"

ai_pipeline_core/documents/utils.py

@@ -1,12 +1,26 @@
+"""Utility functions for document handling.
+
+Provides helper functions for URL sanitization, naming conventions,
+and canonical key generation used throughout the document system.
+"""
+
 import re
 from typing import Any, Iterable, Type
 from urllib.parse import urlparse
 
 
 def sanitize_url(url: str) -> str:
-    """
-    Sanitize URL or query string for use in filenames.
+    """Sanitize URL or query string for use in filenames.
+
+    @public
+
     Removes or replaces characters that are invalid in filenames.
+
+    Args:
+        url: The URL or query string to sanitize.
+
+    Returns:
+        A sanitized string safe for use as a filename.
     """
     # Remove protocol if it's a URL
     if url.startswith(("http://", "https://")):
@@ -35,7 +49,14 @@ def sanitize_url(url: str) -> str:
 
 
 def camel_to_snake(name: str) -> str:
-    """Convert CamelCase (incl. acronyms) to snake_case."""
+    """Convert CamelCase (incl. acronyms) to snake_case.
+
+    Args:
+        name: The CamelCase string to convert.
+
+    Returns:
+        The converted snake_case string.
+    """
     s1 = re.sub(r"(.)([A-Z][a-z0-9]+)", r"\1_\2", name)
     s2 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)
     return s2.replace("__", "_").strip("_").lower()
@@ -47,17 +68,28 @@ def canonical_name_key(
     max_parent_suffixes: int = 3,
     extra_suffixes: Iterable[str] = (),
 ) -> str:
-    """
-    Produce a canonical snake_case key from a class or name by:
+    """Produce a canonical snake_case key from a class or name.
+
+    @public
+
+    Process:
       1) Starting with the class name (or given string),
       2) Stripping any trailing parent class names (up to `max_parent_suffixes` from the MRO),
       3) Stripping any `extra_suffixes`,
       4) Converting to snake_case.
 
-    Examples (given typical MROs):
-      FinalReportDocument(WorkflowDocument -> Document) -> 'final_report'
-      FooWorkflowDocument(WorkflowDocument -> Document) -> 'foo'
-      BarFlow(Config -> Base -> Flow) -> 'bar'
+    Args:
+        obj_or_name: A class or string to convert.
+        max_parent_suffixes: Maximum number of parent classes to consider for suffix removal.
+        extra_suffixes: Additional suffixes to strip.
+
+    Returns:
+        The canonical snake_case name.
+
+    Examples:
+        FinalReportDocument(WorkflowDocument -> Document) -> 'final_report'
+        FooWorkflowDocument(WorkflowDocument -> Document) -> 'foo'
+        BarFlow(Config -> Base -> Flow) -> 'bar'
     """
     name = obj_or_name.__name__ if isinstance(obj_or_name, type) else str(obj_or_name)
 

ai_pipeline_core/exceptions.py

@@ -1,61 +1,97 @@
-"""Exception hierarchy for AI Pipeline Core."""
+"""Exception hierarchy for AI Pipeline Core.
+
+@public
+
+This module defines the exception hierarchy used throughout the AI Pipeline Core library.
+All exceptions inherit from PipelineCoreError, providing a consistent error handling interface.
+"""
 
 
 class PipelineCoreError(Exception):
-    """Base exception for all pipeline errors."""
+    """Base exception for all AI Pipeline Core errors.
+
+    @public
+    """
 
     pass
 
 
 class DocumentError(PipelineCoreError):
-    """Document-related errors."""
+    """Base exception for document-related errors.
+
+    @public
+    """
 
     pass
 
 
 class DocumentValidationError(DocumentError):
-    """Document validation failed."""
+    """Raised when document validation fails.
+
+    @public
+    """
 
     pass
 
 
 class DocumentSizeError(DocumentValidationError):
-    """Document size exceeds limits."""
+    """Raised when document content exceeds MAX_CONTENT_SIZE limit.
+
+    @public
+    """
 
     pass
 
 
 class DocumentNameError(DocumentValidationError):
-    """Invalid document name."""
+    """Raised when document name contains invalid characters or patterns.
+
+    @public
+    """
 
     pass
 
 
 class LLMError(PipelineCoreError):
-    """LLM-related errors."""
+    """Raised when LLM generation fails after all retries.
+
+    @public
+    """
 
     pass
 
 
 class PromptError(PipelineCoreError):
-    """Prompt-related errors."""
+    """Base exception for prompt template errors.
+
+    @public
+    """
 
     pass
 
 
 class PromptRenderError(PromptError):
-    """Failed to render prompt template."""
+    """Raised when Jinja2 template rendering fails.
+
+    @public
+    """
 
     pass
 
 
 class PromptNotFoundError(PromptError):
-    """Prompt template not found."""
+    """Raised when prompt template file is not found in search paths.
+
+    @public
+    """
 
     pass
 
 
 class MimeTypeError(DocumentError):
-    """MIME type detection or validation error."""
+    """Raised when MIME type detection or validation fails.
+
+    @public
+    """
 
     pass

ai_pipeline_core/flow/__init__.py

@@ -1,3 +1,5 @@
+"""Flow configuration and options for Prefect-based pipeline flows."""
+
 from .config import FlowConfig
 from .options import FlowOptions