defmodule HuggingfaceClient.Hub.Hub do
  @moduledoc """
  HuggingFace Hub — complete API client for the HF platform.

  The Hub is the central platform for sharing ML models, datasets, and Spaces.
  This module provides a unified facade over all Hub services organized by category:

  ## Service categories

  | Category | Module(s) | Functions |
  |----------|-----------|-----------|
  | **Authentication** | `Auth` | `who_am_i/1` |
  | **Repositories** | `Repos`, `Commits`, `Files`, `Snapshots`, `Tags` | create, delete, upload, download |
  | **Models** | `Models` | list_models, model_info |
  | **Datasets** | `Datasets`, `DatasetViewer` | list, info, rows, search |
  | **Spaces** | `Spaces` | runtime, secrets, hardware |
  | **Discovery** | `Search`, `Collections`, `Papers` | search, trending |
  | **Collaboration** | `Discussions`, `Webhooks` | PRs, comments, events |
  | **Storage** | `Buckets`, `Cache`, `FileSystem` | S3-like, hf:// URIs |
  | **Compute** | `Jobs`, `AutoTrain` | GPU workloads, training |
  | **Deployment** | `Endpoints` | managed inference |
  | **Enterprise** | `Organizations`, `GatedRepos`, `OAuth` | access control |
  | **Evaluation** | `Evaluate`, `Leaderboards` | metrics, benchmarks |
  | **Community** | `Users` | profiles, followers |
  | **Metadata** | `Metadata` | model cards |

  ## Example

      # Search models
      HuggingfaceClient.Hub.list_models(
        task: "text-generation",
        sort: "downloads",
        limit: 10,
        access_token: "hf_..."
      )
      |> Enum.each(fn m -> IO.puts(m["id"]) end)

      # Upload a file
      {:ok, _} = HuggingfaceClient.Hub.upload_file("my-org/my-model",
        path: "README.md",
        content: "# My Model",
        access_token: "hf_..."
      )

      # Run a GPU job
      {:ok, job} = HuggingfaceClient.Hub.run_job(
        image: "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
        command: ["python", "train.py"],
        flavor: "a10g-small",
        access_token: "hf_..."
      )
  """

  # ── Module aliases ────────────────────────────────────────────────────────────

  alias HuggingfaceClient.Hub.Auth
  alias HuggingfaceClient.Hub.AutoTrain
  alias HuggingfaceClient.Hub.Buckets
  alias HuggingfaceClient.Hub.Cache
  alias HuggingfaceClient.Hub.Collections
  alias HuggingfaceClient.Hub.Commits
  alias HuggingfaceClient.Hub.DatasetViewer
  alias HuggingfaceClient.Hub.Discussions
  alias HuggingfaceClient.Hub.Endpoints
  alias HuggingfaceClient.Hub.Evaluate
  alias HuggingfaceClient.Hub.Files
  alias HuggingfaceClient.Hub.FileSystem
  alias HuggingfaceClient.Hub.GatedRepos
  alias HuggingfaceClient.Hub.Jobs
  alias HuggingfaceClient.Hub.Leaderboards
  alias HuggingfaceClient.Hub.Metadata
  alias HuggingfaceClient.Hub.Models
  alias HuggingfaceClient.Hub.OAuth
  alias HuggingfaceClient.Hub.Organizations
  alias HuggingfaceClient.Hub.Papers
  alias HuggingfaceClient.Hub.Repos
  alias HuggingfaceClient.Hub.Search
  alias HuggingfaceClient.Hub.Snapshots
  alias HuggingfaceClient.Hub.Spaces
  alias HuggingfaceClient.Hub.Tags
  alias HuggingfaceClient.Hub.Users
  alias HuggingfaceClient.Hub.Webhooks

  # ── Authentication ────────────────────────────────────────────────────────────

  @doc "Returns info about the authenticated user."
  @spec who_am_i(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate who_am_i(opts \\ []), to: Auth

  # ── Repositories ──────────────────────────────────────────────────────────────

  @doc "Creates a new repository."
  @spec create_repo(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_repo(name, opts \\ []), do: Repos.create(name, opts)

  @doc "Deletes a repository."
  @spec delete_repo(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_repo(name, opts \\ []), do: Repos.delete(name, opts)

  @doc "Checks if a repository exists."
  @spec repo_exists?(String.t(), keyword()) :: {:ok, boolean()} | {:error, Exception.t()}
  def repo_exists?(name, opts \\ []), do: Repos.exists?(name, opts)

  @doc "Moves or renames a repository."
  @spec move_repo(any()) :: {:ok, term()} | {:error, Exception.t()}
  def move_repo(opts), do: Repos.move(opts)

  @doc "Updates repository settings (private, gated, etc.)."
  @spec update_repo_settings(any()) :: {:ok, term()} | {:error, Exception.t()}
  def update_repo_settings(repo, opts \\ []), do: Repos.update_settings(repo, opts)

  @doc "Checks if a token has access to a repository."
  @spec auth_check(any()) :: {:ok, term()} | {:error, Exception.t()}
  def auth_check(repo, opts \\ []), do: Repos.auth_check(repo, opts)

  @doc "Lists commits for a repository."
  @spec list_commits(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_commits(repo, opts \\ []), do: Repos.list_commits(repo, opts)

  @doc "Creates a branch."
  @spec create_branch(any(), any(), keyword()) :: {:ok, term()} | {:error, Exception.t()}
  def create_branch(repo, branch, opts \\ []), do: Repos.create_branch(repo, branch, opts)

  @doc "Deletes a branch."
  @spec delete_branch(any(), any(), keyword()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_branch(repo, branch, opts \\ []), do: Repos.delete_branch(repo, branch, opts)

  @doc "Lists all branches and tags for a repository."
  @spec list_repo_refs(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate list_repo_refs(repo, opts \\ []), to: Tags

  @doc "Creates a tag."
  @spec create_tag(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_tag(repo, opts \\ []), do: Tags.create_tag(repo, opts)

  @doc "Deletes a tag."
  @spec delete_tag(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_tag(repo, opts \\ []), do: Tags.delete_tag(repo, opts)

  # ── Files ─────────────────────────────────────────────────────────────────────

  @doc "Lists files in a repository."
  @spec list_files(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_files(repo, opts \\ []), do: Files.list(repo, opts)

  @doc "Checks if a file exists."
  @spec file_exists?(String.t(), String.t(), keyword()) :: {:ok, boolean()} | {:error, Exception.t()}
  def file_exists?(repo, path, opts \\ []), do: Files.exists?(repo, path, opts)

  @doc "Downloads a file's content."
  @spec download_file(String.t(), String.t(), keyword()) :: {:ok, binary()} | {:error, Exception.t()}
  def download_file(repo, path, opts \\ []), do: Files.download(repo, path, opts)

  @doc "Downloads a file to the local HF cache and returns the path."
  @spec hf_hub_download(any()) :: {:ok, term()} | {:error, Exception.t()}
  def hf_hub_download(repo_id, opts \\ []), do: Files.hf_hub_download(repo_id, opts)

  @doc "Returns the download URL for a file."
  @spec hf_hub_url(any()) :: String.t()
  def hf_hub_url(repo_id, opts \\ []), do: Files.hf_hub_url(repo_id, opts)

  @doc "Uploads a single file."
  @spec upload_file(any()) :: {:ok, term()} | {:error, Exception.t()}
  def upload_file(repo, opts \\ []), do: Commits.upload_file(repo, opts)

  @doc "Uploads multiple files in a single commit."
  @spec upload_files(any()) :: {:ok, term()} | {:error, Exception.t()}
  def upload_files(repo, opts \\ []), do: Commits.upload_files(repo, opts)

  @doc "Uploads an entire local folder."
  @spec upload_folder(any()) :: {:ok, term()} | {:error, Exception.t()}
  def upload_folder(repo, opts \\ []), do: Repos.upload_folder(repo, opts)

  @doc "Deletes a file."
  @spec delete_file(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_file(repo, opts \\ []), do: Commits.delete_file(repo, opts)

  @doc "Deletes multiple files."
  @spec delete_files(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_files(repo, opts \\ []), do: Commits.delete_files(repo, opts)

  @doc "Downloads an entire repository to the local cache."
  @spec snapshot_download(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate snapshot_download(repo, opts \\ []), to: Snapshots

  # ── Models ────────────────────────────────────────────────────────────────────

  @doc "Lists models with full filter support (lazy stream)."
  @spec list_models(any()) :: Enumerable.t()
  def list_models(opts \\ []), do: Search.models(opts)

  @doc "Gets detailed info about a model."
  @spec model_info(any()) :: {:ok, term()} | {:error, Exception.t()}
  def model_info(repo, opts \\ []), do: Models.info(repo, opts)

  # ── Datasets ──────────────────────────────────────────────────────────────────

  @doc "Lists datasets with full filter support (lazy stream)."
  @spec list_datasets(any()) :: Enumerable.t()
  def list_datasets(opts \\ []), do: Search.datasets(opts)

  @doc "Gets detailed info about a dataset."
  @spec dataset_info(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_info(repo, opts \\ []), do: Models.dataset_info(repo, opts)

  @doc "Lists spaces (lazy stream)."
  @spec list_spaces(any()) :: Enumerable.t()
  def list_spaces(opts \\ []), do: Search.spaces(opts)

  @doc "Gets info about a Space."
  @spec space_info(any()) :: {:ok, term()} | {:error, Exception.t()}
  def space_info(repo, opts \\ []), do: Models.space_info(repo, opts)

  # ── Dataset Viewer ────────────────────────────────────────────────────────────

  @doc "Checks if a dataset is in the Dataset Viewer."
  @spec dataset_viewer_is_valid?(any(), keyword()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_is_valid?(ds, opts \\ []), do: DatasetViewer.valid?(ds, opts)
  @doc "Lists dataset configs."
  @spec dataset_viewer_configs(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_configs(ds, opts \\ []), do: DatasetViewer.list_configs(ds, opts)
  @doc "Lists dataset splits."
  @spec dataset_viewer_splits(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_splits(ds, opts \\ []), do: DatasetViewer.list_splits(ds, opts)
  @doc "Returns first rows of a split."
  @spec dataset_viewer_first_rows(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_first_rows(ds, opts \\ []), do: DatasetViewer.first_rows(ds, opts)
  @doc "Returns paginated rows."
  @spec dataset_viewer_rows(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_rows(ds, opts \\ []), do: DatasetViewer.rows(ds, opts)
  @doc "Searches dataset rows."
  @spec dataset_viewer_search(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_search(ds, opts \\ []), do: DatasetViewer.search(ds, opts)
  @doc "Returns column statistics."
  @spec dataset_viewer_statistics(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_statistics(ds, opts \\ []), do: DatasetViewer.statistics(ds, opts)
  @doc "Returns Parquet file URLs."
  @spec dataset_viewer_parquet(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_parquet(ds, opts \\ []), do: DatasetViewer.parquet(ds, opts)
  @doc "Returns dataset info."
  @spec dataset_viewer_info(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_info(ds, opts \\ []), do: DatasetViewer.info(ds, opts)
  @doc "Returns feature schema."
  @spec dataset_viewer_features(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_features(ds, opts \\ []), do: DatasetViewer.features(ds, opts)
  @doc "Returns dataset size."
  @spec dataset_viewer_size(any()) :: {:ok, term()} | {:error, Exception.t()}
  def dataset_viewer_size(ds, opts \\ []), do: DatasetViewer.size(ds, opts)

  # ── Spaces ────────────────────────────────────────────────────────────────────

  @doc "Gets Space runtime info."
  @spec get_space_runtime(any()) :: {:ok, term()} | {:error, Exception.t()}
  def get_space_runtime(space, opts \\ []), do: Spaces.get_runtime(space, opts)
  @doc "Requests hardware upgrade."
  @spec request_space_hardware(any()) :: {:ok, term()} | {:error, Exception.t()}
  def request_space_hardware(space, opts \\ []), do: Spaces.request_hardware(space, opts)
  @doc "Pauses a Space."
  @spec pause_space(any()) :: {:ok, term()} | {:error, Exception.t()}
  def pause_space(space, opts \\ []), do: Spaces.pause(space, opts)
  @doc "Restarts a Space."
  @spec restart_space(any()) :: {:ok, term()} | {:error, Exception.t()}
  def restart_space(space, opts \\ []), do: Spaces.restart(space, opts)
  @doc "Sets sleep time."
  @spec set_space_sleep_time(any()) :: {:ok, term()} | {:error, Exception.t()}
  def set_space_sleep_time(space, opts \\ []), do: Spaces.set_sleep_time(space, opts)
  @doc "Duplicates a Space."
  @spec duplicate_space(any()) :: {:ok, term()} | {:error, Exception.t()}
  def duplicate_space(from_id, opts \\ []), do: Spaces.duplicate(from_id, opts)
  @doc "Adds a Space secret."
  @spec add_space_secret(any()) :: {:ok, term()} | {:error, Exception.t()}
  def add_space_secret(space, opts \\ []), do: Spaces.add_secret(space, opts)
  @doc "Deletes a Space secret."
  @spec delete_space_secret(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_space_secret(space, opts \\ []), do: Spaces.delete_secret(space, opts)
  @doc "Lists Space secrets (keys only)."
  @spec list_space_secrets(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_space_secrets(space, opts \\ []), do: Spaces.list_secrets(space, opts)
  @doc "Adds a Space environment variable."
  @spec add_space_variable(any()) :: {:ok, term()} | {:error, Exception.t()}
  def add_space_variable(space, opts \\ []), do: Spaces.add_variable(space, opts)
  @doc "Deletes a Space environment variable."
  @spec delete_space_variable(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_space_variable(space, opts \\ []), do: Spaces.delete_variable(space, opts)
  @doc "Gets Space environment variables."
  @spec get_space_variables(any()) :: {:ok, term()} | {:error, Exception.t()}
  def get_space_variables(space, opts \\ []), do: Spaces.get_variables(space, opts)
  @doc "Enables/disables dev mode."
  @spec space_dev_mode(any()) :: {:ok, term()} | {:error, Exception.t()}
  def space_dev_mode(space, opts \\ []), do: Spaces.dev_mode(space, opts)

  # ── Discovery ─────────────────────────────────────────────────────────────────

  @doc "Full-text search across Hub content."
  @spec search_hub(any()) :: {:ok, term()} | {:error, Exception.t()}
  def search_hub(query, opts \\ []), do: Search.unified(query, opts)
  @doc "Searches models with full filter support."
  @spec search_models(any()) :: Enumerable.t()
  def search_models(opts \\ []), do: Search.models(opts)
  @doc "Searches datasets."
  @spec search_datasets(any()) :: Enumerable.t()
  def search_datasets(opts \\ []), do: Search.datasets(opts)
  @doc "Searches Spaces."
  @spec search_spaces(any()) :: Enumerable.t()
  def search_spaces(opts \\ []), do: Search.spaces(opts)
  @doc "Returns trending models."
  @spec trending_models(any()) :: {:ok, term()} | {:error, Exception.t()}
  def trending_models(opts \\ []), do: Search.trending_models(opts)
  @doc "Returns trending Spaces."
  @spec trending_spaces(any()) :: {:ok, term()} | {:error, Exception.t()}
  def trending_spaces(opts \\ []), do: Search.trending_spaces(opts)
  @doc "Returns all model tags."
  @spec model_tags(any()) :: {:ok, term()} | {:error, Exception.t()}
  def model_tags(opts \\ []), do: Search.model_tags(opts)
  @doc "Returns all dataset tags."
  def dataset_tags(opts \\ []), do: Search.dataset_tags(opts)

  @doc "Lists collections."
  @spec list_collections(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_collections(opts \\ []), do: Collections.list(opts)
  @doc "Gets a collection."
  @spec get_collection(any()) :: {:ok, term()} | {:error, Exception.t()}
  def get_collection(slug, opts \\ []), do: Collections.info(slug, opts)
  @doc "Creates a collection."
  @spec create_collection(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_collection(opts \\ []), do: Collections.create(opts, opts)
  @doc "Adds item to a collection."
  @spec add_collection_item(any()) :: {:ok, term()} | {:error, Exception.t()}
  def add_collection_item(slug, opts \\ []),
    do: Collections.add_item(slug, opts[:item_id], opts[:item_type], opts)

  @doc "Deletes item from a collection."
  @spec delete_collection_item(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_collection_item(slug, opts \\ []), do: Collections.delete_item(slug, opts[:item_object_id], opts)
  @doc "Updates a collection."
  @spec update_collection(any()) :: {:ok, term()} | {:error, Exception.t()}
  def update_collection(slug, opts \\ []), do: Collections.update(slug, opts)
  @doc "Deletes a collection."
  @spec delete_collection(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_collection(slug, opts \\ []), do: Collections.delete(slug, opts)

  @doc "Lists papers."
  @spec list_papers(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_papers(opts \\ []), do: Papers.list(opts)
  @doc "Searches papers."
  @spec search_papers(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
  def search_papers(query, opts \\ []), do: Papers.search(query, opts)
  @doc "Gets paper info."
  @spec paper_info(any()) :: {:ok, term()} | {:error, Exception.t()}
  def paper_info(arxiv_id, opts \\ []), do: Papers.info(arxiv_id, opts)
  @doc "Gets papers associated with a repo."
  @spec repo_papers(any()) :: {:ok, term()} | {:error, Exception.t()}
  def repo_papers(repo_id, opts \\ []), do: Papers.repo_papers(repo_id, opts)

  # ── Collaboration ─────────────────────────────────────────────────────────────

  @doc "Lists discussions and PRs."
  @spec list_discussions(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_discussions(repo, opts \\ []), do: Discussions.list(repo, opts)
  @doc "Gets a discussion."
  @spec get_discussion(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
  def get_discussion(repo, num, opts \\ []), do: Discussions.get(repo, num, opts)
  @doc "Creates a discussion."
  @spec create_discussion(String.t(), keyword()) :: {:ok, term()} | {:error, Exception.t()}
  def create_discussion(repo, opts \\ []), do: Discussions.create(repo, opts)
  @doc "Creates a pull request."
  @spec create_pull_request(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_pull_request(repo, opts \\ []), do: Discussions.create_pull_request(repo, opts)
  @doc "Comments on a discussion."
  @spec comment_discussion(any()) :: {:ok, term()} | {:error, Exception.t()}
  def comment_discussion(repo, opts \\ []), do: Discussions.comment(repo, opts)
  @doc "Edits a comment."
  @spec edit_discussion_comment(any()) :: {:ok, term()} | {:error, Exception.t()}
  def edit_discussion_comment(repo, opts \\ []), do: Discussions.edit_comment(repo, opts)
  @doc "Hides a comment."
  @spec hide_discussion_comment(any()) :: {:ok, term()} | {:error, Exception.t()}
  def hide_discussion_comment(repo, opts \\ []), do: Discussions.hide_comment(repo, opts)
  @doc "Changes discussion status."
  @spec change_discussion_status(any()) :: {:ok, term()} | {:error, Exception.t()}
  def change_discussion_status(repo, opts \\ []), do: Discussions.change_status(repo, opts)
  @doc "Renames a discussion."
  @spec rename_discussion(any()) :: {:ok, term()} | {:error, Exception.t()}
  def rename_discussion(repo, opts \\ []), do: Discussions.rename(repo, opts)
  @doc "Merges a pull request."
  @spec merge_pull_request(any()) :: {:ok, term()} | {:error, Exception.t()}
  def merge_pull_request(repo, opts \\ []), do: Discussions.merge_pull_request(repo, opts)

  @doc "Creates a webhook."
  @spec create_webhook(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_webhook(opts \\ []), do: Webhooks.create(opts)
  @doc "Gets a webhook."
  @spec get_webhook(any()) :: {:ok, term()} | {:error, Exception.t()}
  def get_webhook(id, opts \\ []), do: Webhooks.get(id, opts)
  @doc "Lists webhooks."
  @spec list_webhooks(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_webhooks(opts \\ []), do: Webhooks.list(opts)
  @doc "Updates a webhook."
  @spec update_webhook(any()) :: {:ok, term()} | {:error, Exception.t()}
  def update_webhook(id, opts \\ []), do: Webhooks.update(id, opts)
  @doc "Deletes a webhook."
  @spec delete_webhook(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_webhook(id, opts \\ []), do: Webhooks.delete(id, opts)

  # ── Storage ───────────────────────────────────────────────────────────────────

  @doc "Creates a bucket."
  @spec create_bucket(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_bucket(bucket_id, opts \\ []), do: Buckets.create(bucket_id, opts)
  @doc "Gets bucket info."
  @spec bucket_info(any()) :: {:ok, term()} | {:error, Exception.t()}
  def bucket_info(bucket_id, opts \\ []), do: Buckets.info(bucket_id, opts)
  @doc "Lists buckets."
  @spec list_buckets(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_buckets(opts \\ []), do: Buckets.list(opts)
  @doc "Deletes a bucket."
  @spec delete_bucket(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_bucket(bucket_id, opts \\ []), do: Buckets.delete(bucket_id, opts)
  @doc "Renames a bucket."
  @spec move_bucket(any()) :: {:ok, term()} | {:error, Exception.t()}
  def move_bucket(opts), do: Buckets.move(opts)
  @doc "Lists bucket files."
  @spec list_bucket_tree(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_bucket_tree(bucket_id, opts \\ []), do: Buckets.list_tree(bucket_id, opts)
  @doc "Downloads a bucket file."
  @spec get_bucket_file(any()) :: {:ok, term()} | {:error, Exception.t()}
  def get_bucket_file(bucket_id, opts \\ []), do: Buckets.get_file(bucket_id, opts)
  @doc "Uploads a file to a bucket."
  @spec upload_bucket_file(any()) :: {:ok, term()} | {:error, Exception.t()}
  def upload_bucket_file(bucket_id, opts \\ []), do: Buckets.upload_file(bucket_id, opts)
  @doc "Batch upload/delete bucket files."
  @spec batch_bucket_files(any()) :: {:ok, term()} | {:error, Exception.t()}
  def batch_bucket_files(bucket_id, opts \\ []), do: Buckets.batch_files(bucket_id, opts)
  @doc "Copies files between hf:// locations."
  @spec copy_files(any()) :: {:ok, term()} | {:error, Exception.t()}
  def copy_files(opts), do: Buckets.copy_files(opts)

  @doc "Scans the local HF cache."
  @spec scan_cache(any()) :: {:ok, term()} | {:error, Exception.t()}
  def scan_cache(opts \\ []), do: Cache.scan(opts)
  @doc "Default cache directory."
  @spec default_cache_dir() :: String.t()
  def default_cache_dir, do: Cache.default_cache_dir()
  @doc "Deletes a cached revision."
  @spec delete_cached_revision(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_cached_revision(repo_id, opts \\ []), do: Cache.delete_revision(repo_id, opts)
  @doc "Deletes all cached files for a repo."
  @spec delete_cached_repo(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_cached_repo(repo_id, opts \\ []), do: Cache.delete_repo_cache(repo_id, opts)

  # ── Compute ───────────────────────────────────────────────────────────────────

  @doc "Runs a Docker job on HF infrastructure."
  @spec run_job(any()) :: {:ok, term()} | {:error, Exception.t()}
  def run_job(opts), do: Jobs.run(opts)
  @doc "Runs a UV Python script."
  def run_uv_job(opts), do: Jobs.run_uv(opts)
  @doc "Gets job status."
  @spec inspect_job(any()) :: {:ok, term()} | {:error, Exception.t()}
  def inspect_job(job_id, opts \\ []), do: Jobs.inspect_job(job_id, opts)
  @doc "Lists jobs."
  def list_jobs(opts \\ []), do: Jobs.list(opts)
  @doc "Cancels a job."
  @spec cancel_job(any()) :: {:ok, term()} | {:error, Exception.t()}
  def cancel_job(job_id, opts \\ []), do: Jobs.cancel(job_id, opts)
  @doc "Streams job logs."
  def fetch_job_logs(job_id, opts \\ []), do: Jobs.fetch_logs(job_id, opts)
  @doc "Streams job metrics."
  @spec fetch_job_metrics(any()) :: Enumerable.t()
  def fetch_job_metrics(job_id, opts \\ []), do: Jobs.fetch_metrics(job_id, opts)
  @doc "Waits for a job to finish."
  def wait_for_job(job_id, opts \\ []), do: Jobs.wait(job_id, opts)
  @doc "Creates a scheduled job."
  @spec create_scheduled_job(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_scheduled_job(opts), do: Jobs.create_scheduled(opts)
  @doc "Lists scheduled jobs."
  def list_scheduled_jobs(opts \\ []), do: Jobs.list_scheduled(opts)
  @doc "Deletes a scheduled job."
  @spec delete_scheduled_job(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_scheduled_job(job_id, opts \\ []), do: Jobs.delete_scheduled(job_id, opts)
  @doc "Lists available hardware flavors."
  def list_job_hardware(opts \\ []), do: Jobs.list_hardware(opts)

  @doc "Creates an AutoTrain project."
  @spec autotrain_create(any()) :: {:ok, term()} | {:error, Exception.t()}
  def autotrain_create(opts), do: AutoTrain.create(opts)
  @doc "Lists AutoTrain projects."
  def autotrain_list(opts \\ []), do: AutoTrain.list(opts)
  @doc "Gets AutoTrain project status."
  @spec autotrain_status(any()) :: {:ok, term()} | {:error, Exception.t()}
  def autotrain_status(id, opts \\ []), do: AutoTrain.status(id, opts)
  @doc "Cancels an AutoTrain project."
  def autotrain_cancel(id, opts \\ []), do: AutoTrain.cancel(id, opts)

  # ── Deployment ────────────────────────────────────────────────────────────────

  @doc "Lists inference endpoints."
  @spec list_inference_endpoints(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_inference_endpoints(opts \\ []), do: Endpoints.list(opts)
  @doc "Gets an inference endpoint."
  def get_inference_endpoint(name, opts \\ []), do: Endpoints.get(name, opts)
  @doc "Creates an inference endpoint."
  @spec create_inference_endpoint(any()) :: {:ok, term()} | {:error, Exception.t()}
  def create_inference_endpoint(opts \\ []), do: Endpoints.create(opts)
  @doc "Updates an inference endpoint."
  def update_inference_endpoint(name, opts \\ []), do: Endpoints.update(name, opts)
  @doc "Deletes an inference endpoint."
  @spec delete_inference_endpoint(any()) :: {:ok, term()} | {:error, Exception.t()}
  def delete_inference_endpoint(name, opts \\ []), do: Endpoints.delete(name, opts)
  @doc "Pauses an inference endpoint."
  def pause_inference_endpoint(name, opts \\ []), do: Endpoints.pause(name, opts)
  @doc "Resumes an inference endpoint."
  @spec resume_inference_endpoint(any()) :: {:ok, term()} | {:error, Exception.t()}
  def resume_inference_endpoint(name, opts \\ []), do: Endpoints.resume(name, opts)
  @doc "Scales endpoint to zero."
  def scale_inference_endpoint_to_zero(name, opts \\ []), do: Endpoints.scale_to_zero(name, opts)

  # ── Enterprise ────────────────────────────────────────────────────────────────

  @doc "Lists pending gated repo requests."
  @spec list_pending_access_requests(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_pending_access_requests(repo, opts \\ []), do: GatedRepos.list_pending(repo, opts)
  @doc "Lists accepted gated repo requests."
  def list_accepted_access_requests(repo, opts \\ []), do: GatedRepos.list_accepted(repo, opts)
  @doc "Lists rejected gated repo requests."
  @spec list_rejected_access_requests(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_rejected_access_requests(repo, opts \\ []), do: GatedRepos.list_rejected(repo, opts)
  @doc "Accepts a gated repo request."
  def accept_access_request(repo, opts \\ []), do: GatedRepos.accept(repo, opts)
  @doc "Rejects a gated repo request."
  @spec reject_access_request(any()) :: {:ok, term()} | {:error, Exception.t()}
  def reject_access_request(repo, opts \\ []), do: GatedRepos.reject(repo, opts)
  @doc "Cancels a gated repo request."
  def cancel_access_request(repo, opts \\ []), do: GatedRepos.cancel(repo, opts)
  @doc "Grants repo access."
  @spec grant_access(any()) :: {:ok, term()} | {:error, Exception.t()}
  def grant_access(repo, opts \\ []), do: GatedRepos.grant_access(repo, opts)
  @doc "Revokes repo access."
  def revoke_access(repo, opts \\ []), do: GatedRepos.revoke_access(repo, opts)

  @doc "Lists org members."
  @spec list_org_members(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_org_members(org, opts \\ []), do: Organizations.list_members(org, opts)
  @doc "Invites an org member."
  def invite_org_member(org, opts), do: Organizations.invite_member(org, opts)
  @doc "Removes an org member."
  @spec remove_org_member(any()) :: {:ok, term()} | {:error, Exception.t()}
  def remove_org_member(org, opts \\ []), do: Organizations.remove_member(org, opts)
  @doc "Gets org info."
  def org_info(org, opts \\ []), do: Organizations.info(org, opts)
  @doc "Lists orgs for the authenticated user."
  @spec list_my_orgs(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_my_orgs(opts \\ []), do: Organizations.list_mine(opts)

  @doc "OAuth login URL."
  @spec oauth_login_url(any()) :: String.t()
  def oauth_login_url(opts \\ []), do: OAuth.login_url(opts)
  @doc "OAuth callback handler."
  def oauth_handle_redirect(opts \\ []), do: OAuth.handle_redirect(opts)

  # ── Community ─────────────────────────────────────────────────────────────────

  @doc "Gets authenticated user info."
  @spec get_authenticated_user(any()) :: {:ok, term()} | {:error, Exception.t()}
  def get_authenticated_user(opts \\ []), do: Users.get_authenticated_user(opts)
  @doc "Gets a user's profile."
  def user_info(username, opts \\ []), do: Users.get_user(username, opts)
  @doc "Lists a user's followers."
  @spec list_user_followers(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_user_followers(username, opts \\ []), do: Users.list_followers(username, opts)
  @doc "Lists users that a user follows."
  def list_user_following(username, opts \\ []), do: Users.list_following(username, opts)

  # ── Metadata ─────────────────────────────────────────────────────────────────

  @doc "Reads a model card."
  @spec read_model_card(any()) :: {:ok, term()} | {:error, Exception.t()}
  def read_model_card(repo_id, opts \\ []), do: Metadata.read_model_card(repo_id, opts)
  @doc "Gets model card metadata."
  def get_model_card_metadata(repo_id, opts \\ []), do: Metadata.get_metadata(repo_id, opts)
  @doc "Updates repo metadata."
  @spec update_repo_metadata(any()) :: {:ok, term()} | {:error, Exception.t()}
  def update_repo_metadata(repo_id, opts \\ []), do: Metadata.update_metadata(repo_id, opts)
  @doc "Pushes eval results."
  def push_eval_results(repo_id, opts \\ []), do: Metadata.push_eval_results(repo_id, opts)

  # ── Evaluation ────────────────────────────────────────────────────────────────

  @doc "Lists available metrics."
  @spec list_metrics(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_metrics(opts \\ []), do: Evaluate.list_metrics(opts)
  @doc "Computes a metric."
  def compute_metric(metric, opts), do: Evaluate.compute(metric, opts)
  @doc "Computes multiple metrics."
  @spec compute_metrics(any()) :: {:ok, term()} | {:error, Exception.t()}
  def compute_metrics(opts), do: Evaluate.compute_multiple(opts)
  @doc "Evaluates a model on a dataset."
  def evaluate_model(opts), do: Evaluate.evaluate_model(opts)
  @doc "Gets model benchmarks."
  @spec model_benchmarks(any()) :: {:ok, term()} | {:error, Exception.t()}
  def model_benchmarks(model_id, opts \\ []), do: Evaluate.model_benchmarks(model_id, opts)

  @doc "Lists leaderboards."
  @spec list_leaderboards(any()) :: {:ok, term()} | {:error, Exception.t()}
  def list_leaderboards(opts \\ []), do: Leaderboards.list(opts)
  @doc "Gets a leaderboard."
  def get_leaderboard(id, opts \\ []), do: Leaderboards.get(id, opts)
  @doc "Submits to a leaderboard."
  @spec submit_to_leaderboard(any()) :: {:ok, term()} | {:error, Exception.t()}
  def submit_to_leaderboard(opts), do: Leaderboards.submit(opts)
  @doc "Returns Open LLM Leaderboard results."
  def open_llm_leaderboard(opts \\ []), do: Leaderboards.open_llm_leaderboard(opts)

  # ── Aliases for new modules ───────────────────────────────────────────────────

  # ── 7.2 Security ─────────────────────────────────────────────────────────────

  @doc "Returns audit logs for an organization."
  @spec audit_logs(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate audit_logs(org, opts \\ []), to: Security
  @doc "Streams audit log entries for an organization."
  defdelegate stream_audit_logs(org, opts \\ []), to: Security
  @doc "Returns user's role in an organization."
  @spec my_org_role(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate my_org_role(org, opts \\ []), to: Security
  @doc "Checks if user has at least a given role."
  defdelegate has_org_role?(org, role, opts \\ []), to: Security

  # ── Safetensors ───────────────────────────────────────────────────────────────

  @doc "Parses safetensors metadata from a model repo."
  @spec parse_safetensors(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate parse_safetensors(repo, opts \\ []), to: HuggingfaceClient.Hub.Files

  # ── Training ──────────────────────────────────────────────────────────────────

  @doc "Builds a LoRA fine-tuning configuration."
  @spec lora_config(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate lora_config(opts \\ []), to: Training
  @doc "Builds a full fine-tuning configuration."
  defdelegate full_finetune_config(opts \\ []), to: Training
  @doc "Builds a DPO alignment configuration."
  @spec dpo_config(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate dpo_config(opts \\ []), to: Training
  @doc "Returns a pre-built fine-tuning recipe."
  defdelegate training_recipe(name, opts \\ []), to: Training, as: :recipe

  # ── Likes ─────────────────────────────────────────────────────────────────────

  @doc "Likes a repository on the Hub."
  @spec like(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate like(repo_id, opts \\ []), to: HuggingfaceClient.Hub.Repos, as: :like

  @doc "Unlikes a repository on the Hub."
  @spec unlike(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate unlike(repo_id, opts \\ []), to: HuggingfaceClient.Hub.Repos, as: :unlike

  @doc "Lists repositories liked by a user."
  @spec list_liked_repos(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate list_liked_repos(opts \\ []), to: HuggingfaceClient.Hub.Repos, as: :list_liked_repos

  @doc "Squashes all commits in a branch into one."
  @spec super_squash_history(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate super_squash_history(repo_id, opts \\ []),
    to: HuggingfaceClient.Hub.Repos,
    as: :super_squash_history

  @doc "Gets repository settings."
  @spec get_repo_settings(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate get_repo_settings(repo_id, opts \\ []), to: HuggingfaceClient.Hub.Repos, as: :settings

  @doc "Tags a specific commit."
  @spec tag_commit(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate tag_commit(repo_id, opts), to: HuggingfaceClient.Hub.Repos, as: :tag_commit

  @doc "Gets logs from a Space."
  @spec list_space_logs(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate list_space_logs(space_id, opts \\ []), to: HuggingfaceClient.Hub.Repos, as: :list_space_logs

  @doc "Updates a collection item (position, note)."
  @spec update_collection_item(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate update_collection_item(slug, opts \\ []),
    to: HuggingfaceClient.Hub.Collections,
    as: :update_item

  # ── DDUF Serialization ────────────────────────────────────────────────────────

  @doc "Exports a model folder as a DDUF file."
  @spec export_folder_as_dduf(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate export_folder_as_dduf(dduf_path, opts \\ []),
    to: HuggingfaceClient.Serialization,
    as: :export_folder_as_dduf

  @doc "Exports specific entries as a DDUF file."
  @spec export_entries_as_dduf(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate export_entries_as_dduf(dduf_path, opts \\ []),
    to: HuggingfaceClient.Serialization,
    as: :export_entries_as_dduf

  @doc "Reads a DDUF file."
  @spec read_dduf_file(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate read_dduf_file(dduf_path), to: HuggingfaceClient.Serialization, as: :read_dduf_file

  @doc "Downloads and opens a DDUF file from the Hub."
  @spec load_dduf_from_hub(any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate load_dduf_from_hub(repo_id, opts \\ []),
    to: HuggingfaceClient.Serialization,
    as: :load_dduf_from_hub

  # ── Integration Mixins ────────────────────────────────────────────────────────

  @doc "Pushes a model (weights + config) to a Hub repo."
  @spec push_to_hub(any(), any(), any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate push_to_hub(weights, repo_id, opts \\ []), to: HuggingfaceClient.Hub.Mixins, as: :push_to_hub

  @doc "Downloads a model from the Hub (equivalent to from_pretrained)."
  @spec load_from_hub(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate load_from_hub(repo_id, opts \\ []), to: HuggingfaceClient.Hub.Mixins, as: :load_from_hub

  @doc "Pushes a model card to the Hub."
  @spec push_model_card(any(), any()) :: {:ok, term()} | {:error, Exception.t()}
  defdelegate push_model_card(repo_id, opts), to: HuggingfaceClient.Hub.Mixins, as: :push_model_card
end