ai-pipeline-core 0.1.11__tar.gz → 0.1.12__tar.gz

{ai_pipeline_core-0.1.11 → ai_pipeline_core-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ai-pipeline-core
-Version: 0.1.11
+Version: 0.1.12
 Summary: Core utilities for AI-powered processing pipelines using prefect
 Project-URL: Homepage, https://github.com/bbarwik/ai-pipeline-core
 Project-URL: Repository, https://github.com/bbarwik/ai-pipeline-core

{ai_pipeline_core-0.1.11 → ai_pipeline_core-0.1.12}/ai_pipeline_core/__init__.py

@@ -113,7 +113,7 @@ from .prompt_manager import PromptManager
 from .settings import Settings
 from .tracing import TraceInfo, TraceLevel, trace
 
-__version__ = "0.1.11"
+__version__ = "0.1.12"
 
 __all__ = [
     # Config/Settings

{ai_pipeline_core-0.1.11 → ai_pipeline_core-0.1.12}/ai_pipeline_core/documents/document.py

@@ -156,7 +156,7 @@ class Document(BaseModel, ABC):
     DESCRIPTION_EXTENSION: ClassVar[str] = ".description.md"
     """File extension for description files."""
 
-    MARKDOWN_LIST_SEPARATOR: ClassVar[str] = "\n\n---\n\n"
+    MARKDOWN_LIST_SEPARATOR: ClassVar[str] = "\n\n-----------------\n\n"
     """Separator for markdown list items."""
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
@@ -254,7 +254,8 @@ class Document(BaseModel, ABC):
                 - bytes: Used directly without conversion
                 - str: Encoded to UTF-8 bytes
                 - dict[str, Any]: Serialized to JSON (.json) or YAML (.yaml/.yml)
-                - list[str]: Joined with separator for .md, else JSON/YAML
+                - list[str]: Joined with separator for .md (validates no items
+                            contain separator), else JSON/YAML
                 - list[BaseModel]: Serialized to JSON or YAML based on extension
                 - BaseModel: Serialized to JSON or YAML based on extension
             description: Optional description - USUALLY OMIT THIS (defaults to None).
@@ -264,7 +265,8 @@ class Document(BaseModel, ABC):
             New Document instance with content converted to bytes
 
         Raises:
-            ValueError: If content type is not supported for the file extension
+            ValueError: If content type is not supported for the file extension,
+                       or if markdown list items contain the separator
             DocumentNameError: If filename violates validation rules
             DocumentSizeError: If content exceeds MAX_CONTENT_SIZE
 
@@ -573,7 +575,7 @@ class Document(BaseModel, ABC):
             2. str → UTF-8 encoding
             3. dict/BaseModel + .json → JSON serialization (indented)
             4. dict/BaseModel + .yaml/.yml → YAML serialization
-            5. list[str] + .md → Join with markdown separator
+            5. list[str] + .md → Join with markdown separator (validates no items contain separator)
             6. list[Any] + .json/.yaml → JSON/YAML array
             7. int/float/bool + .json → JSON primitive
 
@@ -622,6 +624,13 @@ class Document(BaseModel, ABC):
             if name_lower.endswith(".md"):
                 # For markdown files, join with separator
                 if all(isinstance(item, str) for item in v):
+                    # Check that no string contains the separator
+                    for item in v:
+                        if cls.MARKDOWN_LIST_SEPARATOR in item:
+                            raise ValueError(
+                                f"Markdown list item cannot contain the separator "
+                                f"'{cls.MARKDOWN_LIST_SEPARATOR}' as it will mess up formatting"
+                            )
                     v = cls.MARKDOWN_LIST_SEPARATOR.join(v).encode("utf-8")
                 else:
                     raise ValueError(
@@ -1060,7 +1069,7 @@ class Document(BaseModel, ABC):
 
         @public
 
-        Splits text content using markdown separator ("\n\n---\n\n").
+        Splits text content using markdown separator ("\n\n-----------------\n\n").
         Designed for markdown documents with multiple sections.
 
         Returns:
@@ -1076,7 +1085,7 @@ class Document(BaseModel, ABC):
             >>> doc.as_markdown_list()  # Returns original sections
 
             >>> # Manual creation with separator
-            >>> content = "Part 1\n\n---\n\nPart 2\n\n---\n\nPart 3"
+            >>> content = "Part 1\n\n-----------------\n\nPart 2\n\n-----------------\n\nPart 3"
             >>> doc2 = MyDocument(name="parts.md", content=content.encode())
             >>> doc2.as_markdown_list()  # ['Part 1', 'Part 2', 'Part 3']
         """

{ai_pipeline_core-0.1.11 → ai_pipeline_core-0.1.12}/ai_pipeline_core/flow/config.py

@@ -11,7 +11,7 @@ Best Practice:
 """
 
 from abc import ABC
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Iterable
 
 from ai_pipeline_core.documents import DocumentList, FlowDocument
 from ai_pipeline_core.exceptions import DocumentValidationError
@@ -267,7 +267,7 @@ class FlowConfig(ABC):
 
     @classmethod
     def create_and_validate_output(
-        cls, output: FlowDocument | list[FlowDocument] | DocumentList
+        cls, output: FlowDocument | Iterable[FlowDocument] | DocumentList
     ) -> DocumentList:
         """Create and validate flow output documents.
 
@@ -280,7 +280,7 @@ class FlowConfig(ABC):
         and validates it matches the expected OUTPUT_DOCUMENT_TYPE.
 
         Args:
-            output: Single document, list of documents, or DocumentList.
+            output: Single document, iterable of documents, or DocumentList.
 
         Returns:
             Validated DocumentList containing the output documents.
@@ -308,7 +308,7 @@ class FlowConfig(ABC):
         elif isinstance(output, DocumentList):
             documents = output
         else:
-            assert isinstance(output, list)
-            documents = DocumentList(output)  # type: ignore[arg-type]
+            # Handle any iterable of FlowDocuments
+            documents = DocumentList(list(output))  # type: ignore[arg-type]
         cls.validate_output_documents(documents)
         return documents

{ai_pipeline_core-0.1.11 → ai_pipeline_core-0.1.12}/ai_pipeline_core/pipeline.py

@@ -177,6 +177,38 @@ def _callable_name(obj: Any, fallback: str) -> str:
         return fallback
 
 
+def _is_already_traced(func: Callable[..., Any]) -> bool:
+    """Check if a function has already been wrapped by the trace decorator.
+
+    This checks both for the explicit __is_traced__ marker and walks
+    the __wrapped__ chain to detect nested trace decorations.
+
+    Args:
+        func: Function to check for existing trace decoration.
+
+    Returns:
+        True if the function is already traced, False otherwise.
+    """
+    # Check for explicit marker
+    if hasattr(func, "__is_traced__") and func.__is_traced__:  # type: ignore[attr-defined]
+        return True
+
+    # Walk the __wrapped__ chain to detect nested traces
+    current = func
+    depth = 0
+    max_depth = 10  # Prevent infinite loops
+
+    while hasattr(current, "__wrapped__") and depth < max_depth:
+        wrapped = current.__wrapped__  # type: ignore[attr-defined]
+        # Check if the wrapped function has the trace marker
+        if hasattr(wrapped, "__is_traced__") and wrapped.__is_traced__:  # type: ignore[attr-defined]
+            return True
+        current = wrapped
+        depth += 1
+
+    return False
+
+
 # --------------------------------------------------------------------------- #
 # @pipeline_task — async-only, traced, returns Prefect's Task object
 # --------------------------------------------------------------------------- #
@@ -264,6 +296,9 @@ def pipeline_task(
     Wraps an async function with both Prefect task functionality and
     LMNR tracing. The function MUST be async (declared with 'async def').
 
+    IMPORTANT: Never combine with @trace decorator - this includes tracing automatically.
+    The framework will raise TypeError if you try to use both decorators together.
+
     Best Practice - Use Defaults:
         For 90% of use cases, use this decorator WITHOUT any parameters.
         Only specify parameters when you have EXPLICIT requirements.
@@ -354,13 +389,21 @@ def pipeline_task(
             Wrapped task with tracing and Prefect functionality.
 
         Raises:
-            TypeError: If function is not async.
+            TypeError: If function is not async or already traced.
         """
         if not inspect.iscoroutinefunction(fn):
             raise TypeError(
                 f"@pipeline_task target '{_callable_name(fn, 'task')}' must be 'async def'"
             )
 
+        # Check if function is already traced
+        if _is_already_traced(fn):
+            raise TypeError(
+                f"@pipeline_task target '{_callable_name(fn, 'task')}' is already decorated "
+                f"with @trace. Remove the @trace decorator - @pipeline_task includes "
+                f"tracing automatically."
+            )
+
         fname = _callable_name(fn, "task")
         traced_fn = trace(
             level=trace_level,
@@ -482,6 +525,9 @@ def pipeline_flow(
     Wraps an async function as a Prefect flow with tracing and type safety.
     The decorated function MUST be async and follow the required signature.
 
+    IMPORTANT: Never combine with @trace decorator - this includes tracing automatically.
+    The framework will raise TypeError if you try to use both decorators together.
+
     Best Practice - Use Defaults:
         For 90% of use cases, use this decorator WITHOUT any parameters.
         Only specify parameters when you have EXPLICIT requirements.
@@ -590,13 +636,22 @@ def pipeline_flow(
             Wrapped flow with tracing and Prefect functionality.
 
         Raises:
-            TypeError: If function is not async, doesn't have required
-                      parameters, or doesn't return DocumentList.
+            TypeError: If function is not async, already traced, doesn't have
+                      required parameters, or doesn't return DocumentList.
         """
         fname = _callable_name(fn, "flow")
 
         if not inspect.iscoroutinefunction(fn):
             raise TypeError(f"@pipeline_flow '{fname}' must be declared with 'async def'")
+
+        # Check if function is already traced
+        if _is_already_traced(fn):
+            raise TypeError(
+                f"@pipeline_flow target '{fname}' is already decorated "
+                f"with @trace. Remove the @trace decorator - @pipeline_flow includes "
+                f"tracing automatically."
+            )
+
         if len(inspect.signature(fn).parameters) < 3:
             raise TypeError(
                 f"@pipeline_flow '{fname}' must accept "

{ai_pipeline_core-0.1.11 → ai_pipeline_core-0.1.12}/ai_pipeline_core/tracing.py

@@ -336,7 +336,25 @@ def trace(
 
         Returns:
             Wrapped function with LMNR observability.
+
+        Raises:
+            TypeError: If function is already decorated with @pipeline_task or @pipeline_flow.
         """
+        # Check if this is already a traced pipeline_task or pipeline_flow
+        # This happens when @trace is applied after @pipeline_task/@pipeline_flow
+        if hasattr(f, "__is_traced__") and f.__is_traced__:  # type: ignore[attr-defined]
+            # Check if it's a Prefect Task or Flow object (they have specific attributes)
+            # Prefect objects have certain attributes that regular functions don't
+            is_prefect_task = hasattr(f, "fn") and hasattr(f, "submit") and hasattr(f, "map")
+            is_prefect_flow = hasattr(f, "fn") and hasattr(f, "serve")
+            if is_prefect_task or is_prefect_flow:
+                fname = getattr(f, "__name__", "function")
+                raise TypeError(
+                    f"Function '{fname}' is already decorated with @pipeline_task or "
+                    f"@pipeline_flow. Remove the @trace decorator - pipeline decorators "
+                    f"include tracing automatically."
+                )
+
         # Handle 'debug' level logic - only trace when LMNR_DEBUG is "true"
         if level == "debug" and os.getenv("LMNR_DEBUG", "").lower() != "true":
             return f
@@ -437,6 +455,9 @@ def trace(
 
         wrapper = async_wrapper if is_coroutine else sync_wrapper
 
+        # Mark function as traced for detection by pipeline decorators
+        wrapper.__is_traced__ = True  # type: ignore[attr-defined]
+
         # Preserve the original function signature
         try:
             wrapper.__signature__ = sig  # type: ignore[attr-defined]

{ai_pipeline_core-0.1.11 → ai_pipeline_core-0.1.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ai-pipeline-core"
-version = "0.1.11"
+version = "0.1.12"
 description = "Core utilities for AI-powered processing pipelines using prefect"
 readme = "README.md"
 license = {text = "MIT"}
@@ -175,7 +175,7 @@ reportIncompatibleVariableOverride = "error"
 reportMissingParameterType = "warning"
 
 [tool.bumpversion]
-current_version = "0.1.11"
+current_version = "0.1.12"
 commit = true
 tag = true
 tag_name = "v{new_version}"