dystopic 0.6.0__py3-none-any.whl

dystopic/__init__.py

@@ -0,0 +1,65 @@
+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 AsyncDystopicClient
+from .client import DEFAULT_BASE_URL, DystopicClient
+from .config import (
+    clear_config,
+    config_path,
+    load_config,
+    resolve_credentials,
+    save_config,
+    unset_config_key,
+)
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    DystopicAPIError,
+    DystopicConnectionError,
+    DystopicError,
+    DystopicTimeoutError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+__all__ = [
+    "ARTIFACT_BUNDLE_TYPE",
+    "ARTIFACT_BUNDLE_TEMPLATE_KINDS",
+    "ArtifactValidationError",
+    "AsyncDystopicClient",
+    "AuthenticationError",
+    "ConflictError",
+    "DEFAULT_BASE_URL",
+    "ForbiddenError",
+    "NotFoundError",
+    "DystopicAPIError",
+    "DystopicConnectionError",
+    "DystopicClient",
+    "DystopicError",
+    "DystopicTimeoutError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "__version__",
+    "artifact_bundle_template",
+    "clear_config",
+    "config_path",
+    "enable_debug_logging",
+    "get_logger",
+    "load_artifact_bundle",
+    "load_config",
+    "resolve_credentials",
+    "save_config",
+    "unset_config_key",
+    "validate_artifact_bundle",
+]

dystopic/_logging.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import logging
+import os
+
+_LOGGER_NAME = "dystopic"
+_DEBUG_ENV_VAR = "DYSTOPIC_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)

dystopic/_secret_store.py

@@ -0,0 +1,102 @@
+"""OS-keyring-backed storage for the Dystopic API key.
+
+The only secret we persist is the API key. This module owns every interaction
+with the ``keyring`` library plus the decision to fall back to the plaintext
+``0600`` config file when no usable keychain exists. ``keyring`` is imported
+lazily and every call is guarded so an SDK-only consumer (or a headless box)
+degrades to the file rather than crashing.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from urllib.parse import urlsplit, urlunsplit
+
+__all__ = ["SERVICE", "account_for", "get_secret", "set_secret", "delete_secret"]
+
+SERVICE = "dystopic"
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+def account_for(base_url: str) -> str:
+    """Canonical keyring account for a base URL.
+
+    Must be byte-identical on the read and write paths, so we lowercase the
+    scheme+host, drop a default port, and strip a trailing slash. A scheme-less
+    input (e.g. ``localhost:8000`` or ``api.pipelines.tech``) is treated as
+    ``https://…`` so ``urlsplit`` populates the host instead of mis-parsing it.
+    """
+    raw = base_url.strip()
+    if "://" not in raw:
+        raw = "https://" + raw
+    parts = urlsplit(raw)
+    scheme = (parts.scheme or "https").lower()
+    host = (parts.hostname or "").lower()
+    port = parts.port
+    netloc = host if port in (None, _DEFAULT_PORTS.get(scheme)) else f"{host}:{port}"
+    path = parts.path.rstrip("/")
+    return urlunsplit((scheme, netloc, path, "", ""))
+
+
+def _force_disabled() -> bool:
+    """True when we must not touch the keychain (opt-out / CI / headless Linux)."""
+    if os.getenv("DYSTOPIC_DISABLE_KEYRING"):
+        return True
+    if os.getenv("CI"):
+        return True
+    if sys.platform.startswith("linux") and not os.getenv("DBUS_SESSION_BUS_ADDRESS"):
+        return True
+    return False
+
+
+def get_secret(account: str) -> str | None:
+    """Return the stored secret, or None on miss / no usable backend."""
+    if _force_disabled():
+        return None
+    try:
+        import keyring
+
+        return keyring.get_password(SERVICE, account)
+    except Exception:
+        return None
+
+
+def set_secret(account: str, secret: str) -> bool:
+    """Store ``secret`` and verify it by reading back.
+
+    Returns True ONLY when the value is confirmed present in the keychain — the
+    caller relies on this before deleting any plaintext copy. Best-effort cleanup
+    on a partial/failed write.
+    """
+    if _force_disabled():
+        return False
+    try:
+        import keyring
+    except Exception:
+        return False
+    try:
+        keyring.set_password(SERVICE, account, secret)
+        stored = keyring.get_password(SERVICE, account)
+    except Exception:
+        return False
+    if stored != secret:
+        try:
+            keyring.delete_password(SERVICE, account)
+        except Exception:
+            pass
+        return False
+    return True
+
+
+def delete_secret(account: str) -> None:
+    """Best-effort removal of the stored secret. Never raises."""
+    if _force_disabled():
+        return
+    try:
+        import keyring
+
+        keyring.delete_password(SERVICE, account)
+    except Exception:
+        pass

dystopic/_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 (
+    DystopicAPIError,
+    DystopicError,
+    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"dystopic/{__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 DystopicAPIError 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(
+        "dystopic 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",
+    "DystopicAPIError",
+    "DystopicError",
+    "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",
+]

dystopic/_version.py

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

dystopic/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 DystopicError
+
+ARTIFACT_BUNDLE_TYPE = "dystopic.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(DystopicError):
+    """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 Dystopic 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 Dystopic 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 Dystopic 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 Dystopic 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}'")