pipelines-sdk 0.1.7__py3-none-any.whl

pipelines/__init__.py

@@ -0,0 +1,69 @@
+from ._logging import enable_debug_logging, get_logger
+from ._version import __version__
+from .artifacts import (
+    ARTIFACT_BUNDLE_TEMPLATE_KINDS,
+    ARTIFACT_BUNDLE_TYPE,
+    ArtifactValidationError,
+    artifact_bundle_template,
+    load_artifact_bundle,
+    validate_artifact_bundle,
+)
+from .async_client import AsyncPipelinesClient
+from .client import DEFAULT_BASE_URL, PipelinesClient
+from .config import (
+    NAMED_ENVIRONMENTS,
+    clear_config,
+    config_path,
+    load_config,
+    resolve_base_url,
+    resolve_credentials,
+    save_config,
+    unset_config_key,
+)
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    ForbiddenError,
+    NotFoundError,
+    PipelinesAPIError,
+    PipelinesConnectionError,
+    PipelinesError,
+    PipelinesTimeoutError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = [
+    "ARTIFACT_BUNDLE_TYPE",
+    "ARTIFACT_BUNDLE_TEMPLATE_KINDS",
+    "ArtifactValidationError",
+    "AsyncPipelinesClient",
+    "AuthenticationError",
+    "ConflictError",
+    "DEFAULT_BASE_URL",
+    "ForbiddenError",
+    "NAMED_ENVIRONMENTS",
+    "NotFoundError",
+    "PipelinesAPIError",
+    "PipelinesConnectionError",
+    "PipelinesClient",
+    "PipelinesError",
+    "PipelinesTimeoutError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "__version__",
+    "artifact_bundle_template",
+    "clear_config",
+    "config_path",
+    "enable_debug_logging",
+    "get_logger",
+    "load_artifact_bundle",
+    "load_config",
+    "resolve_base_url",
+    "resolve_credentials",
+    "save_config",
+    "unset_config_key",
+    "validate_artifact_bundle",
+]

pipelines/_logging.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import logging
+import os
+
+_LOGGER_NAME = "pipelines"
+_DEBUG_ENV_VAR = "PIPELINES_DEBUG"
+
+
+def get_logger() -> logging.Logger:
+    """Return the SDK's root logger.
+
+    Library callers can configure handlers/level via standard ``logging``
+    APIs. By default the logger has a NullHandler so importing the SDK
+    does not produce log output unless the caller opts in.
+    """
+    logger = logging.getLogger(_LOGGER_NAME)
+    if not logger.handlers:
+        logger.addHandler(logging.NullHandler())
+    if os.getenv(_DEBUG_ENV_VAR) and logger.level == logging.NOTSET:
+        logger.setLevel(logging.DEBUG)
+    return logger
+
+
+def enable_debug_logging() -> None:
+    """Convenience helper for CLI/--verbose: stream DEBUG records to stderr."""
+    logger = logging.getLogger(_LOGGER_NAME)
+    logger.setLevel(logging.DEBUG)
+    if not any(isinstance(h, logging.StreamHandler) for h in logger.handlers):
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(asctime)s %(name)s %(levelname)s %(message)s"))
+        logger.addHandler(handler)

pipelines/_transport.py

@@ -0,0 +1,175 @@
+"""Shared HTTP transport helpers used by both the sync and async clients."""
+
+from __future__ import annotations
+
+import platform
+import sys
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._logging import get_logger
+from ._version import __version__
+from .config import DEFAULT_BASE_URL
+from .errors import (
+    PipelinesAPIError,
+    PipelinesError,
+    RateLimitError,
+    error_for_status,
+)
+
+_LOGGER = get_logger()
+
+RETRYABLE_STATUS_CODES = frozenset({429, 502, 503, 504})
+SAFE_RETRY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+TERMINAL_STATUSES = frozenset(
+    {
+        "completed",
+        "failed",
+        "cancelled",
+        "partially_cancelled",
+        "completed_with_partial_results",
+    }
+)
+
+
+def build_user_agent() -> str:
+    py_impl = platform.python_implementation()
+    py_version = "{}.{}.{}".format(*sys.version_info[:3])
+    return f"pipelines-sdk/{__version__} {py_impl}/{py_version} httpx/{httpx.__version__}"
+
+
+USER_AGENT = build_user_agent()
+
+
+def normalize_base_url(base_url: str) -> str:
+    return base_url.rstrip("/")
+
+
+def url_for(base_url: str, path: str) -> str:
+    normalized = path if path.startswith("/") else f"/{path}"
+    return f"{base_url}{normalized}"
+
+
+def build_headers(
+    api_key: str | None,
+    *,
+    accept: str = "application/json",
+    idempotency_key: str | None = None,
+    extra: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    headers: dict[str, str] = {
+        "Accept": accept,
+        "User-Agent": USER_AGENT,
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+    if extra:
+        headers.update(extra)
+    return headers
+
+
+def should_retry(
+    method: str,
+    response: httpx.Response,
+    attempt: int,
+    max_retries: int,
+    has_idempotency_key: bool,
+) -> bool:
+    if attempt >= max_retries:
+        return False
+    if response.status_code not in RETRYABLE_STATUS_CODES:
+        return False
+    return method.upper() in SAFE_RETRY_METHODS or has_idempotency_key
+
+
+def retry_delay(response: httpx.Response, attempt: int) -> float:
+    retry_after = response.headers.get("Retry-After")
+    if retry_after:
+        try:
+            return max(0.0, float(retry_after))
+        except ValueError:
+            pass
+    return float(min(2**attempt, 30))
+
+
+def parse_retry_after(response: httpx.Response) -> float | None:
+    retry_after = response.headers.get("Retry-After")
+    if retry_after is None:
+        return None
+    try:
+        return max(0.0, float(retry_after))
+    except ValueError:
+        return None
+
+
+def raise_api_error(response: httpx.Response) -> None:
+    """Pick the most specific PipelinesAPIError subclass for ``response``."""
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = response.text
+
+    error_cls = error_for_status(response.status_code)
+    message = error_message(body)
+
+    _LOGGER.debug(
+        "pipelines api error: %s %s -> %s %s",
+        response.request.method if response.request else "?",
+        response.request.url if response.request else "?",
+        response.status_code,
+        message,
+    )
+
+    if error_cls is RateLimitError:
+        raise RateLimitError(
+            response.status_code,
+            message,
+            body=body,
+            retry_after=parse_retry_after(response),
+        )
+    raise error_cls(response.status_code, message, body=body)
+
+
+def error_message(body: Any) -> str:
+    if not isinstance(body, dict):
+        return str(body)
+
+    detail = body.get("detail", body)
+    if isinstance(detail, str):
+        return detail
+    if isinstance(detail, list):
+        formatted_errors = []
+        for item in detail:
+            if not isinstance(item, dict):
+                formatted_errors.append(str(item))
+                continue
+            loc = item.get("loc")
+            location = ".".join(str(part) for part in loc) if isinstance(loc, list) else None
+            msg = item.get("msg", item)
+            formatted_errors.append(f"{location}: {msg}" if location else str(msg))
+        return "; ".join(formatted_errors)
+    return str(detail)
+
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "PipelinesAPIError",
+    "PipelinesError",
+    "RETRYABLE_STATUS_CODES",
+    "SAFE_RETRY_METHODS",
+    "TERMINAL_STATUSES",
+    "USER_AGENT",
+    "build_headers",
+    "build_user_agent",
+    "error_message",
+    "normalize_base_url",
+    "parse_retry_after",
+    "raise_api_error",
+    "retry_delay",
+    "should_retry",
+    "url_for",
+]

pipelines/_version.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.1.6"

pipelines/artifacts.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .errors import PipelinesError
+
+ARTIFACT_BUNDLE_TYPE = "pipelines.artifact.bundle.v1"
+ARTIFACT_BUNDLE_TEMPLATE_KINDS = {
+    "bundle",
+    "prompts",
+    "criteria",
+    "evaluations",
+    "tool-endpoints",
+    "tool-bindings",
+    "tool-ground-truths",
+}
+ARTIFACT_BUNDLE_SECTIONS = (
+    "prompts",
+    "criteria",
+    "evaluations",
+    "experiments",
+    "tool_endpoints",
+    "tool_bindings",
+    "tool_ground_truths",
+)
+TEMPLATE_ORG_ID = 2
+TEMPLATE_WORKFLOW_ID = 3086
+TEMPLATE_CRITERION_IDS = {
+    "exact_match": 7,
+    "contains_keywords": 8,
+    "safety": 9,
+}
+
+
+class ArtifactValidationError(PipelinesError):
+    """Raised when an artifact manifest cannot be imported safely."""
+
+
+def artifact_bundle_template(kind: str = "prompts") -> dict[str, Any]:
+    if kind not in ARTIFACT_BUNDLE_TEMPLATE_KINDS:
+        raise ArtifactValidationError(
+            "Artifact bundle template kind must be one of: "
+            f"{sorted(ARTIFACT_BUNDLE_TEMPLATE_KINDS)}"
+        )
+
+    # Keep templates focused: one bundle should normally import one artifact family.
+    normalized_kind = "prompts" if kind == "bundle" else kind
+    bundle = {
+        "artifact_type": ARTIFACT_BUNDLE_TYPE,
+        "name": f"demo-{normalized_kind}-bundle",
+        "description": f"Portable {normalized_kind} configs that can be versioned in git.",
+        "prompts": [],
+        "criteria": [],
+        "evaluations": [],
+        "experiments": [],
+        "tool_endpoints": [],
+        "tool_bindings": [],
+        "tool_ground_truths": [],
+    }
+    if normalized_kind == "prompts":
+        bundle["prompts"] = [
+            {
+                "name": "Concise demo prompt",
+                "description": "Created from a Pipelines artifact bundle",
+                "prompt_text": "Write a concise answer for {{input}}.",
+                "prompt_placeholders": [{"name": "input"}],
+                "role": "user",
+                "scope_type": "org",
+                "org_id": TEMPLATE_ORG_ID,
+            },
+            {
+                "name": "Detailed demo prompt",
+                "description": "Created from a Pipelines artifact bundle",
+                "prompt_text": "Write a detailed answer for {{input}} with examples.",
+                "prompt_placeholders": [{"name": "input"}],
+                "role": "user",
+                "scope_type": "org",
+                "org_id": TEMPLATE_ORG_ID,
+            },
+        ]
+    elif normalized_kind == "criteria":
+        bundle["criteria"] = [
+            {
+                "name": "Exact Match",
+                "display_label": "Exact Match",
+                "type": "programmatic",
+                "config": {"subtype": "exact_match"},
+                "output_schema": {"type": "boolean"},
+                "scope_type": "org",
+                "org_id": TEMPLATE_ORG_ID,
+            },
+            {
+                "name": "Contains Keywords",
+                "display_label": "Contains Keywords",
+                "type": "programmatic",
+                "config": {
+                    "subtype": "contains_keywords",
+                    "keywords": ["required phrase", "important keyword"],
+                    "mode": "any",
+                    "case_sensitive": False,
+                },
+                "output_schema": {"type": "boolean"},
+                "scope_type": "org",
+                "org_id": TEMPLATE_ORG_ID,
+            },
+        ]
+    elif normalized_kind == "evaluations":
+        bundle["evaluations"] = [
+            {
+                "name": "Quality evaluation",
+                "description": "Created from a Pipelines artifact bundle",
+                "criteria": [
+                    {"criterion_id": TEMPLATE_CRITERION_IDS["exact_match"]},
+                    {"criterion_id": TEMPLATE_CRITERION_IDS["contains_keywords"]},
+                ],
+                "scope_type": "org",
+                "org_id": TEMPLATE_ORG_ID,
+            },
+            {
+                "name": "Safety evaluation",
+                "description": "Created from a Pipelines artifact bundle",
+                "criteria": [{"criterion_id": TEMPLATE_CRITERION_IDS["safety"]}],
+                "scope_type": "org",
+                "org_id": TEMPLATE_ORG_ID,
+            },
+        ]
+    elif normalized_kind == "tool-endpoints":
+        bundle["tool_endpoints"] = [
+            {
+                "org_id": TEMPLATE_ORG_ID,
+                "name": "Docs MCP endpoint",
+                "description": "MCP server that exposes documentation search tools",
+                "endpoint_type": "mcp_server",
+                "url": "https://tools.example.com/mcp",
+                "auth_type": "none",
+                "auth_config": {},
+            },
+            {
+                "org_id": TEMPLATE_ORG_ID,
+                "name": "Support MCP endpoint",
+                "description": "MCP server that exposes support lookup tools",
+                "endpoint_type": "mcp_server",
+                "url": "https://support-tools.example.com/mcp",
+                "auth_type": "none",
+                "auth_config": {},
+            },
+        ]
+    elif normalized_kind == "tool-bindings":
+        bundle["tool_bindings"] = [
+            {
+                "workflow_id": TEMPLATE_WORKFLOW_ID,
+                "node_id": "replace-with-node-id",
+                "field_id": "replace-with-field-id",
+                "endpoint_id": "replace-with-tool-endpoint-id",
+                "selected_tools": ["search_docs"],
+                "max_tool_rounds": 3,
+            },
+            {
+                "workflow_id": TEMPLATE_WORKFLOW_ID,
+                "node_id": "replace-with-node-id",
+                "field_id": "replace-with-second-field-id",
+                "endpoint_id": "replace-with-tool-endpoint-id",
+                "selected_tools": ["fetch_url"],
+                "max_tool_rounds": 2,
+            },
+        ]
+    elif normalized_kind == "tool-ground-truths":
+        bundle["tool_ground_truths"] = [
+            {
+                "workflow_id": TEMPLATE_WORKFLOW_ID,
+                "node_id": "replace-with-node-id",
+                "field_id": "replace-with-field-id",
+                "expected_tools": [{"name": "search_docs"}],
+                "excluded_tools": [],
+                "ordering_matters": False,
+                "source": "manual",
+                "confidence": 1.0,
+            },
+            {
+                "workflow_id": TEMPLATE_WORKFLOW_ID,
+                "node_id": "replace-with-node-id",
+                "field_id": "replace-with-second-field-id",
+                "expected_tools": [{"name": "fetch_url"}],
+                "excluded_tools": [{"name": "delete_record"}],
+                "ordering_matters": True,
+                "source": "manual",
+                "confidence": 0.9,
+            },
+        ]
+    return bundle
+
+
+def load_artifact_bundle(path: str | Path) -> dict[str, Any]:
+    with Path(path).open(encoding="utf-8") as handle:
+        payload = json.load(handle)
+    if not isinstance(payload, dict):
+        raise ArtifactValidationError("Artifact bundle file must contain a JSON object")
+    return validate_artifact_bundle(payload)
+
+
+def validate_artifact_bundle(payload: Mapping[str, Any]) -> dict[str, Any]:
+    if payload.get("artifact_type") != ARTIFACT_BUNDLE_TYPE:
+        raise ArtifactValidationError(
+            f"Artifact bundle must include artifact_type='{ARTIFACT_BUNDLE_TYPE}'"
+        )
+
+    bundle = dict(payload)
+    for section in ARTIFACT_BUNDLE_SECTIONS:
+        value = bundle.get(section, [])
+        if not isinstance(value, list):
+            raise ArtifactValidationError(f"Artifact bundle field '{section}' must be a list")
+        for index, item in enumerate(value):
+            if not isinstance(item, dict):
+                raise ArtifactValidationError(
+                    f"Artifact bundle field '{section}[{index}]' must be a JSON object"
+                )
+        bundle[section] = value
+
+    for index, experiment in enumerate(bundle["experiments"]):
+        _require_experiment_field(experiment, index, "project_id")
+        _require_experiment_field(experiment, index, "workflow_id")
+        payload_value = experiment.get("payload")
+        if not isinstance(payload_value, dict):
+            raise ArtifactValidationError(
+                f"Artifact bundle experiment[{index}] must include a JSON object payload"
+            )
+
+    for index, endpoint in enumerate(bundle["tool_endpoints"]):
+        _require_artifact_field(endpoint, "tool_endpoints", index, "org_id")
+    for index, binding in enumerate(bundle["tool_bindings"]):
+        _require_artifact_field(binding, "tool_bindings", index, "workflow_id")
+    for index, ground_truth in enumerate(bundle["tool_ground_truths"]):
+        _require_artifact_field(ground_truth, "tool_ground_truths", index, "workflow_id")
+
+    return bundle
+
+
+def _require_experiment_field(experiment: Mapping[str, Any], index: int, field: str) -> None:
+    if experiment.get(field) is None:
+        raise ArtifactValidationError(f"Artifact bundle experiment[{index}] must include '{field}'")
+
+
+def _require_artifact_field(
+    artifact: Mapping[str, Any], section: str, index: int, field: str
+) -> None:
+    if artifact.get(field) is None:
+        raise ArtifactValidationError(f"{section}[{index}] must include '{field}'")