tangle-cli 0.1.9__tar.gz → 0.1.10__tar.gz

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tangle-cli
-Version: 0.1.9
+Version: 0.1.10
 Summary: CLI for Tangle, the open-source ML pipeline orchestration platform
 Author: Alexey Volkov, Tangle authors, Volv Grebennikov
 Author-email: Alexey Volkov <alexey.volkov@ark-kun.com>, Volv Grebennikov <volv.grebennikov@shopify.com>
@@ -439,6 +439,56 @@ def collision(runtime_condition: In[str]) -> Out[str]:
 
 The bound value remains under `arguments.is_enabled`; the call-site value emits as `isEnabled`. Tangle does not evaluate conditions on graph-component tasks, so `subpipeline(...)(is_enabled=...)` is rejected with guidance to condition tasks inside the child pipeline. A child graph input with that name remains available through `subpipeline(...).bind(is_enabled=...)(...)`. There is no `condition` alias.
 
+##### Task execution options and caching
+
+Tangle caches task results, so a task that reads state which changes between runs (a run's `createdBy`, wall-clock time, an external table that the graph does not depend on) must opt out of caching explicitly. Use the reserved task-call metadata keyword `max_cache_staleness=`:
+
+```python
+@pipeline("Scheduled-run gate")
+def scheduled_gate() -> Out[str]:
+    is_scheduled = read_runtime_state(
+        name="CLOUD_PIPELINES_PIPELINE_RUN_CREATED_BY",
+        max_cache_staleness="P0D",
+    )
+    return is_scheduled.Output
+```
+
+This emits the canonical task field rather than a component argument:
+
+```yaml
+executionOptions:
+  cachingStrategy:
+    maxCacheStaleness: P0D
+```
+
+`P0D` means "never reuse a cached result"; any other ISO-8601 duration (`P7D`) caps how stale a reusable result may be. For the rest of `ExecutionOptionsSpec`, use the general `execution_options=` passthrough:
+
+```python
+uploaded = flaky_upload(
+    payload=data.Output,
+    execution_options={"retryStrategy": {"maxRetries": 3}},
+)
+```
+
+Both keywords may be combined; `max_cache_staleness=` wins over a `cachingStrategy.maxCacheStaleness` supplied through `execution_options=`, and every other passthrough field is preserved. A mapping passed as `execution_options=` is never mutated, so one shared constant can be reused across tasks.
+
+Tangle models exactly two execution-option groups today — `cachingStrategy.maxCacheStaleness` and `retryStrategy.maxRetries` (required whenever `retryStrategy` is present). Any other key is rejected at compile time: the backend ignores unmodeled keys silently, so accepting one would advertise a setting that never takes effect.
+
+Execution options are STATIC compile-time settings, so `max_cache_staleness` takes an RFC3339 duration string and `retryStrategy.maxRetries` a non-negative integer. Graph inputs, task outputs, `dynamic_secret(...)`, and `raw(...)` values are rejected because the backend does not resolve them for `executionOptions`. Passing an empty `execution_options={}` is an error — omit the keyword instead.
+
+If a component itself declares an input named `max_cache_staleness` or `execution_options`, bind that component argument separately while using the call-site keyword for task metadata:
+
+```python
+result = work.bind(max_cache_staleness="component-input-value")(
+    message="hello",
+    max_cache_staleness="P0D",
+)
+```
+
+The bound value remains under `arguments.max_cache_staleness`; the call-site value emits as `executionOptions`. Tangle applies caching and retries to container-component tasks, so `subpipeline(...)(max_cache_staleness=...)` and `subpipeline(...)(execution_options=...)` are rejected with guidance to set them on tasks inside the child pipeline. A child graph input with either name remains available through `subpipeline(...).bind(...)`.
+
+See `examples/python_pipeline/execution_options_pipeline.py` for a runnable example.
+
 ##### Task images, dependencies, and image IDs
 
 Use `@task(image="...")` to write the component image directly. Use `dependencies_from="pyproject.toml"` when generated components need to install Python dependencies. Several tasks can share one authoring-only `TaskEnv`:

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/README.md

@@ -413,6 +413,56 @@ def collision(runtime_condition: In[str]) -> Out[str]:
 
 The bound value remains under `arguments.is_enabled`; the call-site value emits as `isEnabled`. Tangle does not evaluate conditions on graph-component tasks, so `subpipeline(...)(is_enabled=...)` is rejected with guidance to condition tasks inside the child pipeline. A child graph input with that name remains available through `subpipeline(...).bind(is_enabled=...)(...)`. There is no `condition` alias.
 
+##### Task execution options and caching
+
+Tangle caches task results, so a task that reads state which changes between runs (a run's `createdBy`, wall-clock time, an external table that the graph does not depend on) must opt out of caching explicitly. Use the reserved task-call metadata keyword `max_cache_staleness=`:
+
+```python
+@pipeline("Scheduled-run gate")
+def scheduled_gate() -> Out[str]:
+    is_scheduled = read_runtime_state(
+        name="CLOUD_PIPELINES_PIPELINE_RUN_CREATED_BY",
+        max_cache_staleness="P0D",
+    )
+    return is_scheduled.Output
+```
+
+This emits the canonical task field rather than a component argument:
+
+```yaml
+executionOptions:
+  cachingStrategy:
+    maxCacheStaleness: P0D
+```
+
+`P0D` means "never reuse a cached result"; any other ISO-8601 duration (`P7D`) caps how stale a reusable result may be. For the rest of `ExecutionOptionsSpec`, use the general `execution_options=` passthrough:
+
+```python
+uploaded = flaky_upload(
+    payload=data.Output,
+    execution_options={"retryStrategy": {"maxRetries": 3}},
+)
+```
+
+Both keywords may be combined; `max_cache_staleness=` wins over a `cachingStrategy.maxCacheStaleness` supplied through `execution_options=`, and every other passthrough field is preserved. A mapping passed as `execution_options=` is never mutated, so one shared constant can be reused across tasks.
+
+Tangle models exactly two execution-option groups today — `cachingStrategy.maxCacheStaleness` and `retryStrategy.maxRetries` (required whenever `retryStrategy` is present). Any other key is rejected at compile time: the backend ignores unmodeled keys silently, so accepting one would advertise a setting that never takes effect.
+
+Execution options are STATIC compile-time settings, so `max_cache_staleness` takes an RFC3339 duration string and `retryStrategy.maxRetries` a non-negative integer. Graph inputs, task outputs, `dynamic_secret(...)`, and `raw(...)` values are rejected because the backend does not resolve them for `executionOptions`. Passing an empty `execution_options={}` is an error — omit the keyword instead.
+
+If a component itself declares an input named `max_cache_staleness` or `execution_options`, bind that component argument separately while using the call-site keyword for task metadata:
+
+```python
+result = work.bind(max_cache_staleness="component-input-value")(
+    message="hello",
+    max_cache_staleness="P0D",
+)
+```
+
+The bound value remains under `arguments.max_cache_staleness`; the call-site value emits as `executionOptions`. Tangle applies caching and retries to container-component tasks, so `subpipeline(...)(max_cache_staleness=...)` and `subpipeline(...)(execution_options=...)` are rejected with guidance to set them on tasks inside the child pipeline. A child graph input with either name remains available through `subpipeline(...).bind(...)`.
+
+See `examples/python_pipeline/execution_options_pipeline.py` for a runnable example.
+
 ##### Task images, dependencies, and image IDs
 
 Use `@task(image="...")` to write the component image directly. Use `dependencies_from="pyproject.toml"` when generated components need to install Python dependencies. Several tasks can share one authoring-only `TaskEnv`:

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/packages/tangle-cli/src/tangle_cli/__init__.py

@@ -14,6 +14,6 @@ from tangle_cli.dynamic_discovery_client import TangleDynamicDiscoveryClient
 try:
     __version__ = metadata_version("tangle-cli")
 except PackageNotFoundError:
-    __version__ = "0.1.9"
+    __version__ = "0.1.10"
 
 __all__ = ["TangleDynamicDiscoveryClient", "__version__"]

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/packages/tangle-cli/src/tangle_cli/openapi/codegen.py

@@ -24,7 +24,7 @@ import urllib.parse
 import urllib.request
 from collections.abc import Sequence
 from pathlib import Path
-from typing import Any
+from typing import Any, NamedTuple
 
 from .parser import (
     DEFAULT_OPENAPI_PATH,
@@ -384,7 +384,7 @@ from pydantic import BaseModel
 try:
     from pydantic import ConfigDict
 except ImportError:  # pragma: no cover - pydantic v1 fallback
-    ConfigDict = None  # type: ignore[assignment]
+    ConfigDict = None  # type: ignore[misc, assignment]
 
 
 class TangleGeneratedModel(BaseModel):
@@ -464,6 +464,21 @@ def generate_models(
     lines.append("")
     return "\n".join(lines)
 
+
+class _ParamName(NamedTuple):
+    """Pair a generated Python parameter name with its OpenAPI wire name.
+
+    ``local_name`` is the collision-avoided Python identifier used in the
+    generated method signature; ``wire_name`` is the schema/OpenAPI name that
+    must be used as the JSON/query/path key sent to the backend. They differ
+    whenever the parser had to rename a field (for example a request-body field
+    literally named ``body`` becomes the local ``body_2``).
+    """
+
+    local_name: str
+    wire_name: str
+
+
 def _method_name(group_name: str, command_name: str) -> str:
     return f"{_safe_identifier(group_name)}_{_safe_identifier(command_name)}"
 
@@ -481,7 +496,7 @@ def _param_signature(
     has_request_body: bool,
     *,
     raw_body_override: bool = False,
-) -> tuple[str, list[str], list[str], list[str], set[str], bool]:
+) -> tuple[str, list[_ParamName], list[_ParamName], list[_ParamName], set[str], bool]:
     required: list[Any] = []
     optional: list[Any] = []
     for parameter in parameters:
@@ -489,25 +504,32 @@ def _param_signature(
     ordered = required + optional
     seen: set[str] = set()
     signature_parts: list[str] = []
-    path_names: list[str] = []
-    query_names: list[str] = []
-    body_names: list[str] = []
+    path_names: list[_ParamName] = []
+    query_names: list[_ParamName] = []
+    body_names: list[_ParamName] = []
     required_body_names: set[str] = set()
     for parameter in ordered:
         name = _safe_identifier(parameter.local_name)
         if name in seen:
             continue
         seen.add(name)
+        # Collision-avoiding Python locals (e.g. ``body_2``) must never leak into
+        # the emitted wire payload; the schema field name is the wire key. Only
+        # a missing name falls back to the local identifier, so schema-valid
+        # empty property names keep their exact wire spelling.
+        original_name = getattr(parameter, "original_name", None)
+        wire_name = name if original_name is None else str(original_name)
+        entry = _ParamName(local_name=name, wire_name=wire_name)
         if parameter.required:
             signature_parts.append(f"{name}: Any")
         else:
             signature_parts.append(f"{name}: Any = None")
         if parameter.location == "path":
-            path_names.append(name)
+            path_names.append(entry)
         elif parameter.location == "query":
-            query_names.append(name)
+            query_names.append(entry)
         elif parameter.location == "body":
-            body_names.append(name)
+            body_names.append(entry)
             if parameter.required:
                 required_body_names.add(name)
     include_body = has_request_body
@@ -517,27 +539,27 @@ def _param_signature(
     return ", ".join(signature_parts), path_names, query_names, body_names, required_body_names, include_body
 
 
-def _dict_literal(names: list[str]) -> str:
+def _dict_literal(names: list[_ParamName]) -> str:
     if not names:
         return "None"
-    return "{" + ", ".join(f"{name!r}: {name}" for name in names) + "}"
+    return "{" + ", ".join(f"{name.wire_name!r}: {name.local_name}" for name in names) + "}"
 
 
-def _body_dict_literal(names: list[str], required_names: set[str]) -> str:
+def _body_dict_literal(names: list[_ParamName], required_names: set[str]) -> str:
     if not names:
         return "None"
-    optional_names = [name for name in names if name not in required_names]
+    optional_names = [name for name in names if name.local_name not in required_names]
     if not optional_names:
         return _dict_literal(names)
     optional_literal = _dict_literal(optional_names)
     optional_expr = f"key: value for key, value in {optional_literal}.items() if value is not None"
     if not required_names:
         return "{" + optional_expr + "}"
-    required_literal = _dict_literal([name for name in names if name in required_names])
+    required_literal = _dict_literal([name for name in names if name.local_name in required_names])
     return "{" + f"**{required_literal}, **{{{optional_expr}}}" + "}"
 
 
-def _merged_body_dict_literal(names: list[str], required_names: set[str]) -> str:
+def _merged_body_dict_literal(names: list[_ParamName], required_names: set[str]) -> str:
     """Return request JSON with generic body fields overridden by named fields."""
 
     return f"{{**(body or {{}}), **{_body_dict_literal(names, required_names)}}}"

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/packages/tangle-cli/src/tangle_cli/python_pipeline/emit.py

@@ -4,7 +4,7 @@ Canonical top-level key order:
     name, description, metadata, inputs, outputs, implementation
 
 Per-task key order:
-    annotations?, componentRef, arguments?, isEnabled?
+    annotations?, componentRef, arguments?, isEnabled?, executionOptions?
 
 Argument values are emitted in the runnable ``ArgumentValue`` shape,
 dispatched purely on the VALUE's runtime type — never on the argument
@@ -34,11 +34,18 @@ The literal key the user wrote (``wait_for``, ``depends_on``,
 """
 from __future__ import annotations
 
+from collections.abc import Mapping
 from typing import Any
 
 from .dynamic_data import DynamicData
 from .errors import CompileError, InvalidArgumentTypeError
-from .graph import IS_ENABLED_UNSET, EdgeRef, GraphBuilder, TaskNode
+from .graph import (
+    EXECUTION_OPTIONS_UNSET,
+    IS_ENABLED_UNSET,
+    EdgeRef,
+    GraphBuilder,
+    TaskNode,
+)
 from .placeholders import GraphInputPlaceholder, TaskOutputProxy
 from .raw import Raw
 
@@ -141,7 +148,7 @@ def _emit_task(
     node: TaskNode, task_path: str, exempt_paths: set[str]
 ) -> dict[str, Any]:
     """Build the per-task body dict in canonical key order:
-    ``annotations?, componentRef, arguments?, isEnabled?``.
+    ``annotations?, componentRef, arguments?, isEnabled?, executionOptions?``.
 
     ``task_path`` is this task's dot-delimited JSON path
     (``implementation.graph.tasks.<task_id>``); each argument's path is
@@ -167,6 +174,10 @@ def _emit_task(
     if node.is_enabled is not IS_ENABLED_UNSET:
         body["isEnabled"] = _emit_is_enabled(node.is_enabled)
 
+    execution_options = _emit_execution_options(node)
+    if execution_options is not None:
+        body["executionOptions"] = execution_options
+
     return body
 
 
@@ -316,6 +327,171 @@ def _emit_is_enabled(value: Any) -> Any:
     )
 
 
+# The fields the BACKEND actually models on ``ExecutionOptionsSpec`` —
+# mirrored from ``cloud_pipelines_backend.component_structures`` and vendored
+# into ``schemas/pipeline_schema.json`` (kept honest by
+# ``test_execution_option_fields_match_generated_schema``).
+#
+# This allowlist exists because the backend's pydantic models leave ``extra``
+# unset, i.e. ``extra="ignore"``: an unmodeled key such as ``timeout`` or
+# ``retryStrategy.backoff`` is SILENTLY DROPPED server-side rather than
+# rejected. Accepting one here would let an author believe a timeout/backoff
+# is in effect when nothing applies it, so the passthrough fails closed.
+_EXECUTION_OPTION_FIELDS: dict[str, frozenset[str]] = {
+    "cachingStrategy": frozenset({"maxCacheStaleness"}),
+    "retryStrategy": frozenset({"maxRetries"}),
+}
+
+# ``RetryStrategySpec.max_retries`` is a required (non-Optional) backend field,
+# so a retryStrategy without it is a submit-time validation failure.
+_REQUIRED_EXECUTION_OPTION_FIELDS: dict[str, frozenset[str]] = {
+    "retryStrategy": frozenset({"maxRetries"}),
+}
+
+
+def _emit_execution_options(node: TaskNode) -> dict[str, Any] | None:
+    """Merge the reserved execution-option keywords into ``executionOptions``.
+
+    ``execution_options=`` is the general passthrough for the modeled
+    ``ExecutionOptionsSpec`` (``cachingStrategy`` and ``retryStrategy``).
+    ``max_cache_staleness=`` is the narrow ergonomic knob for the common
+    "do not cache this task" case and WINS over any
+    ``cachingStrategy.maxCacheStaleness`` supplied through the passthrough.
+
+    Returns ``None`` when neither keyword was authored, so the key is omitted
+    entirely. Unlike arguments and ``isEnabled``, execution options are STATIC
+    compile-time settings: graph inputs, task outputs, dynamic data, and raw
+    values are rejected because the backend does not resolve them here. Keys
+    the backend does not model are rejected too — see
+    :data:`_EXECUTION_OPTION_FIELDS`.
+    """
+    options_value = node.execution_options
+    staleness = node.max_cache_staleness
+
+    if (
+        options_value is EXECUTION_OPTIONS_UNSET
+        and staleness is EXECUTION_OPTIONS_UNSET
+    ):
+        return None
+
+    options: dict[str, Any] = {}
+    if options_value is not EXECUTION_OPTIONS_UNSET:
+        if not isinstance(options_value, Mapping):
+            raise InvalidArgumentTypeError(
+                "unsupported execution_options value type "
+                f"{type(options_value).__name__!r}. Task execution options must "
+                "be a mapping such as "
+                '{"cachingStrategy": {"maxCacheStaleness": "P0D"}}.'
+            )
+        options = _normalize_execution_option_value(
+            options_value, "execution_options"
+        )
+        _validate_execution_option_fields(options)
+
+    if staleness is not EXECUTION_OPTIONS_UNSET:
+        if not isinstance(staleness, str):
+            raise InvalidArgumentTypeError(
+                "unsupported max_cache_staleness value type "
+                f"{type(staleness).__name__!r}. Task cache staleness must be a "
+                "duration string such as 'P0D' (never reuse cached results) or "
+                "'P7D'."
+            )
+        caching = options.get("cachingStrategy")
+        if not isinstance(caching, dict):
+            caching = {}
+        # The narrow keyword is the authoritative source for this one field.
+        caching["maxCacheStaleness"] = staleness
+        options["cachingStrategy"] = caching
+
+    if not options:
+        raise CompileError(
+            "execution_options={} is empty; omit the keyword instead of "
+            "passing an empty mapping so the task emits no executionOptions."
+        )
+    return options
+
+
+def _validate_execution_option_fields(options: dict[str, Any]) -> None:
+    """Reject execution-option keys the Tangle backend does not model.
+
+    The backend ignores (silently discards) unknown keys, so a typo or an
+    aspirational field would compile, submit, and quietly do nothing. Failing
+    at compile time keeps the passthrough as fail-closed as every other value
+    the Python authoring surface emits.
+    """
+    for group, value in options.items():
+        known_fields = _EXECUTION_OPTION_FIELDS.get(group)
+        if known_fields is None:
+            supported = ", ".join(sorted(_EXECUTION_OPTION_FIELDS))
+            raise InvalidArgumentTypeError(
+                f"unknown execution_options key {group!r}. Tangle models only "
+                f"{supported}; unmodeled keys are silently ignored by the "
+                "backend, so they are rejected here instead of looking like "
+                "a setting that never takes effect."
+            )
+        if not isinstance(value, dict):
+            raise InvalidArgumentTypeError(
+                f"execution_options.{group} must be a mapping; got "
+                f"{type(value).__name__!r}."
+            )
+        unknown = sorted(set(value) - known_fields)
+        if unknown:
+            supported = ", ".join(sorted(known_fields))
+            raise InvalidArgumentTypeError(
+                f"unknown execution_options.{group} field {unknown[0]!r}. "
+                f"Tangle models only {supported} here; unmodeled keys are "
+                "silently ignored by the backend, so they are rejected at "
+                "compile time."
+            )
+        required = _REQUIRED_EXECUTION_OPTION_FIELDS.get(group, frozenset())
+        missing = sorted(required - set(value))
+        if missing:
+            raise InvalidArgumentTypeError(
+                f"execution_options.{group} requires {missing[0]!r}. The "
+                "backend rejects a partial "
+                f"{group} spec."
+            )
+
+
+def _normalize_execution_option_value(value: Any, path: str) -> Any:
+    """Recursively validate/normalize one static execution-option value.
+
+    Mappings and sequences are copied (so a caller's dict is never mutated by
+    the ``max_cache_staleness`` merge) and tuples become lists so the result is
+    plain YAML-serializable data. Anything else — a task output, graph input,
+    ``dynamic_secret(...)``, ``raw(...)`` value, or an arbitrary object — is
+    rejected: ``executionOptions`` is applied at submit time, not resolved from
+    the running graph.
+    """
+    if isinstance(value, Mapping):
+        normalized: dict[str, Any] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise InvalidArgumentTypeError(
+                    f"unsupported execution_options key type "
+                    f"{type(key).__name__!r} at {path}. Execution option keys "
+                    "must be strings."
+                )
+            normalized[key] = _normalize_execution_option_value(
+                item, f"{path}.{key}"
+            )
+        return normalized
+    if isinstance(value, (list, tuple)):
+        return [
+            _normalize_execution_option_value(item, f"{path}[{index}]")
+            for index, item in enumerate(value)
+        ]
+    if value is None or isinstance(value, (str, bool, int, float)):
+        return value
+    raise InvalidArgumentTypeError(
+        f"unsupported execution_options value type {type(value).__name__!r} at "
+        f"{path}. Task execution options are static compile-time settings, so "
+        "only strings, numbers, booleans, null, lists, and nested mappings are "
+        "supported; graph inputs, task outputs, dynamic data, and raw values "
+        "are not evaluated for executionOptions."
+    )
+
+
 def _emit_edge_value(edge: EdgeRef) -> dict[str, Any]:
     """Render an :class:`EdgeRef` as a dehydrated ``ArgumentValue``
     sub-dict (``{taskOutput|graphInput: {...}}``) used in

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/packages/tangle-cli/src/tangle_cli/python_pipeline/graph.py

@@ -15,6 +15,11 @@ from typing import Any, Literal
 # instead of being silently omitted.
 IS_ENABLED_UNSET = object()
 
+# Distinguishes omitted task execution options from an explicitly supplied
+# value, so ``execution_options=None`` / ``max_cache_staleness=None`` fail
+# closed in the emitter instead of being silently dropped.
+EXECUTION_OPTIONS_UNSET = object()
+
 
 @dataclass
 class EdgeRef:
@@ -37,6 +42,11 @@ class TaskNode:
     ``arguments`` values may be plain strings, TaskOutputProxy objects, or
     GraphInputPlaceholder objects. ``is_enabled`` is separate task metadata;
     the emitter normalizes and serializes it as ``isEnabled`` when supplied.
+
+    ``execution_options`` (general passthrough) and ``max_cache_staleness``
+    (narrow ergonomic knob) are likewise task metadata, not component inputs.
+    The emitter merges them — the narrow keyword wins — and serializes the
+    result as the canonical ``executionOptions`` task field.
     """
 
     task_id: str
@@ -46,6 +56,8 @@ class TaskNode:
     arguments: dict[str, Any] = field(default_factory=dict)
     annotations: dict[str, str] | None = None
     is_enabled: Any = IS_ENABLED_UNSET
+    execution_options: Any = EXECUTION_OPTIONS_UNSET
+    max_cache_staleness: Any = EXECUTION_OPTIONS_UNSET
 
 
 @dataclass

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/packages/tangle-cli/src/tangle_cli/python_pipeline/ref.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from typing import Any
 
 from .errors import CompileError
-from .graph import IS_ENABLED_UNSET
+from .graph import EXECUTION_OPTIONS_UNSET, IS_ENABLED_UNSET
 
 _UNWRAPPED_KEY_RE = re.compile(r"^[A-Za-z0-9_-]+$")
 
@@ -296,6 +296,8 @@ class CallableRef:
         self,
         *,
         is_enabled: Any = IS_ENABLED_UNSET,
+        execution_options: Any = EXECUTION_OPTIONS_UNSET,
+        max_cache_staleness: Any = EXECUTION_OPTIONS_UNSET,
         **kwargs: Any,
     ) -> Any:
         """Trace-mode invocation.
@@ -313,7 +315,21 @@ class CallableRef:
         input named ``is_enabled``, bind that input with
         ``ref(...).bind(is_enabled=...)``; bound kwargs remain component
         arguments while the reserved call-site keyword remains task metadata,
-        so both may be used on the same task. Edge kwargs (``wait_for`` /
+        so both may be used on the same task.
+
+        ``execution_options`` and ``max_cache_staleness`` follow the same
+        reserved-keyword convention and are emitted as the canonical
+        ``executionOptions`` task field. ``execution_options`` takes the whole
+        ``ExecutionOptionsSpec`` mapping (``cachingStrategy`` and
+        ``retryStrategy`` — the only groups Tangle models);
+        ``max_cache_staleness`` is the narrow knob for
+        ``cachingStrategy.maxCacheStaleness`` (e.g. ``"P0D"`` to never reuse
+        cached results) and wins when both supply that field.
+        A component input named ``execution_options`` or
+        ``max_cache_staleness`` is bound the same way, with
+        ``ref(...).bind(max_cache_staleness=...)``.
+
+        Edge kwargs (``wait_for`` /
         ``depends_on``) and regular kwargs share one ``arguments`` dict in the
         IR; the value-vs-key dispatch happens at emit time. ``.bind(...)``
         kwargs are merged in last so call-site kwargs win on conflict (same
@@ -377,6 +393,8 @@ class CallableRef:
             arguments=merged,
             annotations=dict(self.annotations) if self.annotations else None,
             is_enabled=is_enabled,
+            execution_options=execution_options,
+            max_cache_staleness=max_cache_staleness,
         )
         builder.add_task(node)
 

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/packages/tangle-cli/src/tangle_cli/python_pipeline/subpipeline.py

@@ -16,8 +16,9 @@ ergonomics (``.bind`` / ``.named`` / ``.with_annotations`` and call-site
 kwargs). Calling the handle inside an active ``@pipeline`` trace records
 ONE parent task (never the child's internals) and returns a
 :class:`tangle_cli.python_pipeline.placeholders.TaskOutputProxy`. Tangle only
-supports conditional execution for container-component tasks, so the reserved
-call-site ``is_enabled=`` metadata keyword is rejected on subpipeline boundary
+supports conditional execution and execution options for container-component
+tasks, so the reserved call-site ``is_enabled=``, ``execution_options=`` and
+``max_cache_staleness=`` metadata keywords are rejected on subpipeline boundary
 (graph-component) tasks.
 
 The child body is NOT executed into the parent's :class:`GraphBuilder`.
@@ -128,6 +129,10 @@ class SubpipelineRef:
         evaluate conditions on graph-component tasks. A child graph input with
         that name remains available through ``.bind(is_enabled=...)``, matching
         the reserved-metadata collision convention used by ``CallableRef``.
+        ``execution_options`` / ``max_cache_staleness`` are rejected for the
+        same reason: caching and retries apply to the container executions
+        inside the child graph, so silently emitting them on the boundary task
+        would look like a setting that is not actually applied.
         """
         import sys
 
@@ -154,6 +159,17 @@ class SubpipelineRef:
                 "input with .bind(is_enabled=...)."
             )
 
+        for reserved in ("execution_options", "max_cache_staleness"):
+            if reserved in kwargs:
+                raise CompileError(
+                    f"subpipeline tasks do not support call-site {reserved}= "
+                    "because Tangle execution options (caching, retries) "
+                    "apply to container-component tasks. Set "
+                    f"{reserved}= on the tasks inside the child pipeline. If "
+                    f"the child declares a graph input named {reserved!r}, pass "
+                    f"that input with .bind({reserved}=...)."
+                )
+
         # Resolve the parent task ID. ``.named(...)`` always wins over the
         # AST-derived auto ID.
         if self.task_id_hint is not None:

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/packages/tangle-cli/src/tangle_cli/schemas/dehydrated_pipeline_schema.json

@@ -263,8 +263,7 @@
       "additionalProperties": true,
       "properties": {
         "cachingStrategy": { "$ref": "#/$defs/CachingStrategySpec" },
-        "retryStrategy":   { "$ref": "#/$defs/RetryStrategySpec" },
-        "timeout":         { "type": "string", "description": "Go-style duration, e.g. `30m`, `2h`." }
+        "retryStrategy":   { "$ref": "#/$defs/RetryStrategySpec" }
       }
     },
 
@@ -274,7 +273,7 @@
       "properties": {
         "maxCacheStaleness": {
           "type": ["string", "null"],
-          "description": "Maximum allowed cache age, e.g. `P7D` (ISO-8601) or `7d`."
+          "description": "Maximum allowed cache age as an RFC3339 duration, e.g. `P7D`; `P0D` never reuses a cached result."
         }
       }
     },
@@ -282,9 +281,9 @@
     "RetryStrategySpec": {
       "type": "object",
       "additionalProperties": true,
+      "required": ["maxRetries"],
       "properties": {
-        "maxRetries": { "type": "integer", "minimum": 0 },
-        "backoff":    { "type": "string", "description": "Go-style duration, e.g. `30s`." }
+        "maxRetries": { "type": "integer", "minimum": 0 }
       }
     }
   }

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tangle-cli"
-version = "0.1.9"
+version = "0.1.10"
 description = "CLI for Tangle, the open-source ML pipeline orchestration platform"
 readme = "README.md"
 requires-python = ">=3.10"

{tangle_cli-0.1.9 → tangle_cli-0.1.10}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "tangle-cli"
-version = "0.1.9"
+version = "0.1.10"
 description = "CLI for Tangle, the open-source ML pipeline orchestration platform"
 readme = "README.md"
 authors = [