aikosh 0.1.0__py3-none-any.whl

aikosh/__init__.py

@@ -0,0 +1,196 @@
+"""AIKosh platform SDK."""
+
+import importlib
+import inspect
+from typing import Any
+
+import aikosh
+from aikosh._version import __version__
+from aikosh.config import get_access_key, set_access_key, set_api_key
+from aikosh.datasets.journey import (
+    download,
+    get_dataset_metadata_journey as get_dataset_metadata,
+    get_metadata,
+    list_directory,
+    ping,
+    to_json,
+    get_datasets_filter_info,
+)
+from aikosh.exceptions import enrich_api_exception
+from aikosh.datasets.journey import list_files as _list_files_dataset
+from aikosh.models.journey import list_files as _list_files_model
+from aikosh.models.journey import get_models_filter_info
+
+
+def get_model_metadata(model_id: str, **kwargs: Any) -> dict[str, Any]:
+    """Model metadata; prefer :func:`get_metadata` with ``type='model'``."""
+    return get_metadata("model", model_id, **kwargs)
+
+
+def list_files(
+    type: str,
+    identifier: str,
+    filters: dict[str, Any] | None = None,
+    *,
+    api_base_url: str | None = None,
+    timeout: float = 60.0,
+    transport: Any = None,
+    trust_env: bool | None = None,
+) -> dict[str, Any]:
+    """
+    List files inside a dataset or model (same entry point as ``list_directory`` / ``get_metadata`` / ``download``).
+
+    Parameters
+    ----------
+    type:
+        ``"dataset"`` (aliases: ``"datasets"``, ``"data"``) or ``"model"`` (alias: ``"models"``).
+    identifier:
+        Dataset or model UUID.
+    filters:
+        Same filters supported by the domain-specific helpers
+        (``directory_path``, ``version_id``, ``page``, ``limit``).
+
+    Returns
+    -------
+    dict
+        ``{"status": "success", "type": ..., "identifier": ..., "<asset>_id": ..., "data": ...}``.
+        The legacy ``dataset_id`` / ``model_id`` keys are preserved for backward compatibility.
+    """
+    t = (type or "").strip().lower()
+    iid = str(identifier).strip()
+    try:
+        if t in {"dataset", "datasets", "data"}:
+            out = _list_files_dataset(
+                iid,
+                filters,
+                api_base_url=api_base_url,
+                timeout=timeout,
+                transport=transport,
+                trust_env=trust_env,
+            )
+            out["type"] = "dataset"
+            out["identifier"] = iid
+            if "externalUrl" in out["data"]:
+                out["data"]["msg"] = f'{out["type"]} is onboarded from the external source : {out["data"]["source"]}. Kindly redirect to the mentioned URL'
+            return out
+
+        if t in {"model", "models"}:
+            out = _list_files_model(
+                iid,
+                filters,
+                api_base_url=api_base_url,
+                timeout=timeout,
+                transport=transport,
+                trust_env=trust_env,
+            )
+            out["type"] = "model"
+            out["identifier"] = iid
+            if "externalUrl" in out["data"]:
+                out["data"]["msg"] = f'{out["type"]} is onboarded from the external source : {out["data"]["source"]}. Kindly redirect to the mentioned URL'
+            return out
+        
+        if t == "metadata":
+            raise NotImplementedError("Metadata functionality is not implemented yet.")
+
+        raise ValueError(f"list_files() received unsupported type={t!r}. Expected 'dataset' or 'model' or 'metadata'.")
+    
+    except Exception as exc:
+        # Don't re-wrap errors already enriched by the inner handlers — pass them through as-is
+        from aikosh.exceptions import APIError
+        if isinstance(exc, APIError):
+            raise
+        raise enrich_api_exception(
+            exc,
+            operation="list_files.validate_type(type must be 'dataset' or 'model' or 'metadata'.)",
+            filters_used={"type": t},
+        ) from exc 
+
+
+_FEATURE_MODULES: tuple[tuple[str, str], ...] = (
+    ("aikosh", "Top-level helpers"),
+    ("aikosh.datasets", "Datasets module"),
+    ("aikosh.models", "Models module"),
+)
+
+
+def _describe_callable(obj: Any) -> str:
+    """Return the first non-empty docstring line, else '(no description)'."""
+    doc = inspect.getdoc(obj) or ""
+    for line in doc.splitlines():
+        text = line.strip()
+        if text:
+            return text
+    return "(no description)"
+
+
+def list_functions(
+    *,
+    include_submodules: bool = True,
+    print_output: bool = True,
+) -> dict[str, dict[str, str]]:
+    """
+    List all user-facing functions exposed by the AIKosh SDK, with one-line descriptions.
+
+    Output is generated dynamically by inspecting each module's ``__all__`` and the first
+    line of every callable's docstring, so this stays in sync as new features are added.
+
+    Parameters
+    ----------
+    include_submodules:
+        If True (default), also include ``aikosh.datasets`` and ``aikosh.models``.
+    print_output:
+        If True (default), pretty-print the listing to stdout.
+
+    Returns
+    -------
+    dict
+        Mapping of ``module_path -> {function_name: one_liner}``.
+    """
+    modules = list(_FEATURE_MODULES) if include_submodules else [_FEATURE_MODULES[0]]
+    result: dict[str, dict[str, str]] = {}
+
+    for mod_path, _label in modules:
+        try:
+            mod = importlib.import_module(mod_path)
+        except Exception:
+            continue
+        names = list(getattr(mod, "__all__", []) or [])
+        functions: dict[str, str] = {}
+        for name in names:
+            obj = getattr(mod, name, None)
+            if obj is None or not callable(obj):
+                continue
+            functions[name] = _describe_callable(obj)
+        if functions:
+            result[mod_path] = functions
+
+    if print_output:
+        for mod_path, fns in result.items():
+            header = f"{mod_path}  (v{__version__})" if mod_path == "aikosh" else mod_path
+            print()
+            print(header)
+            print("-" * len(header))
+            width = max((len(name) for name in fns), default=0)
+            for name, desc in fns.items():
+                print(f"  {name:<{width}}  {desc}")
+
+    return result
+
+
+__all__ = [
+    "__version__",
+    "get_access_key",
+    "set_access_key",
+    "set_api_key",
+    "get_metadata",
+    "get_dataset_metadata",
+    "get_model_metadata",
+    "list_directory",
+    "list_files",
+    "download",
+    "to_json",
+    "ping",
+    "list_functions",
+    "get_datasets_filter_info",
+    "get_models_filter_info",
+]

aikosh/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

aikosh/config.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import os
+from threading import Lock
+
+from aikosh.exceptions import ConfigurationError
+
+_ENV_ACCESS_KEY = "AIKOSH_ACCESS_KEY"
+_ENV_API_KEY = "AIKOSH_API_KEY"
+
+_lock = Lock()
+_access_key: str | None = None
+
+
+def set_access_key(key: str) -> None:
+    """Store the API access key for subsequent requests."""
+    if not key or not str(key).strip():
+        raise ConfigurationError("Access key must be a non-empty string.")
+    global _access_key
+    with _lock:
+        _access_key = str(key).strip()
+
+
+def set_api_key(key: str) -> None:
+    """Alias for :func:`set_access_key` (matches user-journey naming)."""
+    set_access_key(key)
+
+
+def get_access_key() -> str:
+    """Return the configured access key (explicit, ``AIKOSH_API_KEY``, or ``AIKOSH_ACCESS_KEY``)."""
+    with _lock:
+        if _access_key:
+            return _access_key
+    for env_name in (_ENV_API_KEY, _ENV_ACCESS_KEY):
+        env = os.environ.get(env_name, "").strip()
+        if env:
+            return env
+    raise ConfigurationError(
+        f"No API key configured. Call set_api_key(...) / set_access_key(...), "
+        f"or set {_ENV_API_KEY} / {_ENV_ACCESS_KEY}."
+    )
+
+# ---------------------------------------------------------------------------
+# Allowed keys for filters, list directory, metadata, listfiles
+# ---------------------------------------------------------------------------
+
+# For filters-related configs / responses
+ALLOWED_FILTER_KEYS = [
+    'data',
+    'datasetTypesList',
+    'id',
+    'licensesList',
+    'message',
+    'modelTypesList',
+    'name',
+    'organisationList',
+    'sector',
+    'sectorsList',
+    # 'slug',
+    'status',
+    'type'
+ ]
+
+# For "list directory" operations
+ALLOWED_LIST_DIRECTORY_KEYS = [
+    # 'createdAt',
+    'currentOwner',
+    'data',
+    'datasetMetadata',
+    'dataset_external_url',
+    'dataset_source',
+    'designation',
+    'downloads',
+    'externally_hosted',
+    'id',
+    'items',
+    # 'imageUrl',
+    'license',
+    # 'logo',
+    'metadata',
+    'modelType',
+    'model_external_url',
+    'model_source',
+    'name',
+    'organization',
+    'page',
+    # 'profilepic',
+    # 'recent_upvotes',
+    'remark',
+    'reviewStatus',
+    'role',
+    'sector',
+    'shortDescription',
+    'size',
+    # 'slug',
+    'sourceOrg',
+    'stats',
+    'status',
+    'tag',
+    'tags',
+    'total',
+    # 'trendingWeightage',
+    'type',
+    # 'updatedAt',
+    'upvotes',
+    # 'username',
+    'version_score',
+    'views',
+    'vote'
+]
+
+# For metadata operations
+ALLOWED_METADATA_KEYS = [
+    # 'aiReady',
+    # 'approvalRequired',
+    # 'approvedDate',
+    'author',
+    'baseDirectory',
+    'bdpDatasetID',
+    'createdAt',
+    'createdBy',
+    'createdDate',
+    'currentOwner',
+    'data',
+    # 'dataCollectionMethod',
+    'dataType',
+    'datasetId',
+    'datasetMetadata',
+    # 'datasetOrigin',
+    'datasetType',
+    'dataset_external_url',
+    'dataset_id',
+    'dataset_source',
+    # 'deleteRequest',
+    # 'deleteRequestRemark',
+    'designation',
+    # 'downloadApprovalRequired',
+    'downloads',
+    # 'dynamicUrl',
+    'endDate',
+    # 'expiredAt',
+    # 'expiredDays',
+    'externally_hosted',
+    'fileDownloadableUrl',
+    'filePath',
+    'fileSource',
+    'frequency',
+    'fullDescription',
+    # 'geographicalCoverage',
+    'id',
+    'identifier',
+    # 'imageUrl',
+    # 'isFlaggedBySystemAdmin',
+    'isFree',
+    'isTryoutAvailable',
+    'license',
+    'likes',
+    # 'logo',
+    'metadata',
+    'modelFormat',
+    'modelId',
+    'modelType',
+    'model_external_url',
+    'model_id',
+    'model_source',
+    # 'nId',
+    'name',
+    'organization',
+    'organizationId',
+    'permission',
+    'permissionType',
+    'platform',
+    # 'platformSource',
+    # 'primaryKey',
+    # 'profilepic',
+    'purpose',
+    # 'rawPermissions',
+    # 'recent_upvotes',
+    'redirectionSource',
+    'relatedDataset',
+    'relatedModel',
+    'remark',
+    'reviewStatus',
+    'role',
+    'sector',
+    'shortDescription',
+    'size',
+    # 'slug',
+    'sourceOrg',
+    'startDate',
+    'stats',
+    'status',
+    'tag',
+    'tags',
+    # 'timeGranularity',
+    'title',
+    'token',
+    # 'trainingDataset',
+    # 'trainingModel',
+    # 'trendingWeightage',
+    'type',
+    # 'updatedAt',
+    # 'updatedDate',
+    'uploadedBy',
+    'upvotes',
+    # 'username',
+    'version_score',
+    'views',
+    'visibility',
+    'vote'
+]
+
+# For listfiles operations
+ALLOWED_LISTFILES_KEYS = [
+    'currentPage',
+    'data',
+    'directories',
+    'directoryInfo',
+    'fileTypeCount',
+    'files',
+    'identifier',
+    # 'key',
+    'limit',
+    'model_id',
+    'name',
+    # 'path',
+    'relativeUrl',
+    'status',
+    'totalChildren',
+    'totalDirectories',
+    'totalFiles',
+    'totalPages',
+    # 'type',
+    'msg',
+    'externalUrl',
+    'source'
+]
+

aikosh/datasets/__init__.py

@@ -0,0 +1,42 @@
+"""Datasets domain module (staging SDK + journey helpers)."""
+
+from aikosh.datasets.api import (
+    get_dataset_metadata,
+    get_dataset_version_download_url,
+    get_file_download_url,
+    get_filters,
+    list_datasets,
+    list_file_details,
+    require_uuid_string,
+    stream_download_url_to_path,
+)
+from aikosh.datasets.journey import (
+    download,
+    get_dataset_metadata_journey,
+    get_metadata,
+    list_directory,
+    list_files,
+    ping,
+    to_json,
+)
+
+__all__ = [
+    # low-level API
+    "require_uuid_string",
+    "get_filters",
+    "list_datasets",
+    "get_dataset_metadata",
+    "list_file_details",
+    "get_dataset_version_download_url",
+    "get_file_download_url",
+    "stream_download_url_to_path",
+    # journey façade
+    "list_directory",
+    "list_files",
+    "get_metadata",
+    "get_dataset_metadata_journey",
+    "download",
+    "to_json",
+    "ping",
+]
+

aikosh/datasets/_download_helpers.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx
+
+_FILENAME_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def sanitize_filename(name: str, max_len: int = 120) -> str:
+    cleaned = _FILENAME_SAFE.sub("_", name).strip("._")
+    if not cleaned:
+        cleaned = "download"
+    return cleaned[:max_len]
+
+
+def infer_filename_from_url(download_url: str, fallback: str) -> str:
+    path = urlparse(download_url).path
+    name = Path(path).name
+    if name and name not in ("/", "."):
+        return name
+    return fallback
+
+
+def filename_from_content_disposition(value: str) -> str | None:
+    parts = [p.strip() for p in value.split(";") if p.strip()]
+    for part in parts[1:]:
+        if part.lower().startswith("filename*="):
+            _, v = part.split("=", 1)
+            v = v.strip().strip('"')
+            if "''" in v:
+                v = v.split("''", 1)[1]
+            v = v.strip()
+            if v:
+                return Path(v).name
+        if part.lower().startswith("filename="):
+            _, v = part.split("=", 1)
+            v = v.strip().strip('"').strip()
+            if v:
+                return Path(v).name
+    return None
+
+
+def extension_from_content_type(value: str) -> str | None:
+    ct = value.split(";", 1)[0].strip().lower()
+    if ct in {"application/zip", "application/x-zip-compressed"}:
+        return ".zip"
+    if ct in {"application/gzip", "application/x-gzip"}:
+        return ".gz"
+    if ct in {"application/x-tar"}:
+        return ".tar"
+    if ct in {"application/x-7z-compressed"}:
+        return ".7z"
+    return None
+
+
+def choose_output_filename(
+    *,
+    requested_filename: str | None,
+    url_filename: str,
+    fallback_name: str,
+    headers: httpx.Headers,
+) -> str:
+    if requested_filename:
+        return requested_filename
+
+    cd = headers.get("content-disposition", "")
+    cd_name = filename_from_content_disposition(cd) if cd else None
+    candidate = cd_name or url_filename or fallback_name
+
+    if Path(candidate).suffix:
+        return candidate
+    ext = extension_from_content_type(headers.get("content-type", ""))
+    if ext:
+        return f"{candidate}{ext}"
+    return candidate
+
+
+def destination_is_directory(dest: Path, *, has_explicit_filename: bool) -> bool:
+    s = str(dest)
+    if s.endswith(("/", "\\")):
+        return True
+    if dest.exists() and dest.is_dir():
+        return True
+    if has_explicit_filename:
+        return True
+    # No explicit filename; treat as directory by default.
+    # Users can force a file path by providing `filename=` in the download request.
+    return True
+