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

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/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/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/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/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.dist-info → ai_pipeline_core-0.1.12.dist-info}/METADATA

@@ -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.dist-info → ai_pipeline_core-0.1.12.dist-info}/RECORD

@@ -1,13 +1,13 @@
-ai_pipeline_core/__init__.py,sha256=kq6f5Xzd7UeZQUgo4uzJoFCl3MC0A2mgQJrGuLTsufk,5396
+ai_pipeline_core/__init__.py,sha256=woPhgoXf2GlKkWqvzBmf57ODLMsmsoInB0nimFrsuzE,5396
 ai_pipeline_core/exceptions.py,sha256=vx-XLTw2fJSPs-vwtXVYtqoQUcOc0JeI7UmHqRqQYWU,1569
-ai_pipeline_core/pipeline.py,sha256=0yQLuFaaBipujfZPDI-P-c7irMcszW1p8ss6yYvjVj0,25986
+ai_pipeline_core/pipeline.py,sha256=EETCEoKkFcVvsQqtVIV5S5DrVII4XPSuCnqF7zA2_jc,28137
 ai_pipeline_core/prefect.py,sha256=CC8qeIpVqzNq8m6YWNIcRYeDEqkcAFiNjFwcuwwKO0k,2064
 ai_pipeline_core/prompt_manager.py,sha256=XZwah5fp3GyZ0e0na_yOs6m4ngCcotysh-K_cU2U978,11572
 ai_pipeline_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ai_pipeline_core/settings.py,sha256=XfIw-UOuelSiPAYCd3VmOhsGmAxsCy9IsxWPWAf0wGY,4427
-ai_pipeline_core/tracing.py,sha256=seGnOEQydUBzCBZI4C-hgzF_1t5Yzw6DurjlODQ5POU,17119
+ai_pipeline_core/tracing.py,sha256=75wKL__0arY54dnDcG3F-4KC6mDXg6lMA219-fpxhjI,18348
 ai_pipeline_core/documents/__init__.py,sha256=FOYBUKipW_uuzFieW3MigvNLEpbCI1jeY9_0VxJsoS0,692
-ai_pipeline_core/documents/document.py,sha256=bpfBDvYsgX5MBKzLogonRXT7MIT43SX0jju-TarQoio,50865
+ai_pipeline_core/documents/document.py,sha256=tDUBootN_hK75k3XASyBxt-ZqtZuynTwgcL_L5ZWN1Q,51521
 ai_pipeline_core/documents/document_list.py,sha256=m8ei2jLTHt47uCKHmn8BuMMbfwPIKH5g9oPO1jvIPmg,8282
 ai_pipeline_core/documents/flow_document.py,sha256=bJxLjvUE6xfR5-JCy1oi7XtZOwLBOSuUBBJjRaQk6TI,4748
 ai_pipeline_core/documents/mime_type.py,sha256=DkW88K95el5nAmhC00XLS0G3WpDXgs5IRsBWbKiqG3Y,7995
@@ -15,7 +15,7 @@ ai_pipeline_core/documents/task_document.py,sha256=HonlS7hO6zisu67JFXu6LjGLyc7Bu
 ai_pipeline_core/documents/temporary_document.py,sha256=cMuNLnRlWrMryzfZXOIrTrZ2blsxjmflnL8O3zicWIk,3240
 ai_pipeline_core/documents/utils.py,sha256=VHq1gAWTMmJNS55HSZ2--sDErE4DVtFsxrv6y2KXmdk,3472
 ai_pipeline_core/flow/__init__.py,sha256=2BfWYMOPYW5teGzwo-qzpn_bom1lxxry0bPsjVgcsCk,188
-ai_pipeline_core/flow/config.py,sha256=ZaTEyaGxPe2JUSlaX7tY0BsMyK4FMtSAmFu5CkzQTOM,12083
+ai_pipeline_core/flow/config.py,sha256=4JVc30tztSW9sYufWLN3hx6qSeR1VX31H1aI9I2jIrA,12114
 ai_pipeline_core/flow/options.py,sha256=UiddkxWrXAhsFtOOt06JhttTp-0gejc8kG0K8Falg1c,2297
 ai_pipeline_core/llm/__init__.py,sha256=QWhMVs4OLTgIvOHfxb7AQhpfCXlgGpoGiJ8PSbVyzZs,661
 ai_pipeline_core/llm/ai_messages.py,sha256=YS3tfqivj9kS6sYsDAgw9LHEjg9cKS1SAHviCzkvAos,8492
@@ -30,7 +30,7 @@ ai_pipeline_core/logging/logging_mixin.py,sha256=UFd_CfyJ6YP_XVA-CrpAszOr8g1FH8R
 ai_pipeline_core/simple_runner/__init__.py,sha256=OXKFOu3rRcqXCWwBBxnZ7Vz8KRFF5g-G3eJq-vm3CUY,521
 ai_pipeline_core/simple_runner/cli.py,sha256=sbIvv_d401o8h-b5JlcIJQhwzte1sttdmUi2a3As-wY,9357
 ai_pipeline_core/simple_runner/simple_runner.py,sha256=Q7PRAgf_VUPS72WV9pER9WT0AQo9r4WbRclsRXXJiW4,14329
-ai_pipeline_core-0.1.11.dist-info/METADATA,sha256=zPo-FixIjsW5ghdGNHcrM7LZtkSX4Rp4S5EeAfIIi5Q,13192
-ai_pipeline_core-0.1.11.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-ai_pipeline_core-0.1.11.dist-info/licenses/LICENSE,sha256=kKj8mfbdWwkyG3U6n7ztB3bAZlEwShTkAsvaY657i3I,1074
-ai_pipeline_core-0.1.11.dist-info/RECORD,,
+ai_pipeline_core-0.1.12.dist-info/METADATA,sha256=ytaOH7I8CR_jRrRvvZW8HDldFdFw8mT8gYC5G-X-NRA,13192
+ai_pipeline_core-0.1.12.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ai_pipeline_core-0.1.12.dist-info/licenses/LICENSE,sha256=kKj8mfbdWwkyG3U6n7ztB3bAZlEwShTkAsvaY657i3I,1074
+ai_pipeline_core-0.1.12.dist-info/RECORD,,