# HuggingfaceClient

A complete, production-grade Elixir client for the entire HuggingFace platform.

Every service documented at https://huggingface.co/docs is implemented, organized into a clean folder hierarchy matching HuggingFace's own service groupings.

[![Hex.pm](https://img.shields.io/hexpm/v/huggingface_client.svg)](https://hex.pm/packages/huggingface_client)

## Package structure

```
lib/huggingface_client/
├── inference/           # ⚡ Inference Services
│   ├── providers/       # 25+ providers (Groq, Together, fal.ai, Replicate…)
│   ├── tasks/           # 34 ML tasks (chat, image, audio, video…)
│   ├── tgi.ex           # Text Generation Inference server client
│   ├── sse.ex           # Server-Sent Events streaming
│   └── ...
├── hub/                 # 🧠 Hub Core Platform
│   ├── repositories/    # repos, commits, files, snapshots, tags
│   ├── models/          # Models Hub
│   ├── datasets/        # Datasets Hub + Dataset Viewer API
│   ├── spaces/          # Spaces (secrets, hardware, dev mode)
│   ├── discovery/       # search, collections, papers, trending
│   ├── collaboration/   # discussions, PRs, webhooks
│   ├── storage/         # buckets, cache, hf:// filesystem
│   ├── compute/         # jobs (GPU/TPU), AutoTrain
│   ├── deployment/      # inference endpoints
│   ├── enterprise/      # organizations, gated repos, OAuth
│   ├── community/       # user profiles
│   ├── metadata/        # model cards
│   └── evaluation/      # metrics, leaderboards
├── jinja/               # Jinja2 chat template engine
└── agent/               # MCP agentic loop
```

## Installation

```elixir
def deps do
  [{:huggingface_client, "~> 0.1"}]
end
```

## Quick Start

```elixir
# ── Inference ────────────────────────────────────────────────────────────────

client = HuggingfaceClient.client("hf_your_token", provider: "groq")

{:ok, resp} = HuggingfaceClient.chat_completion(client, %{
  model:    "meta-llama/Llama-3.1-8B-Instruct",
  messages: [%{"role" => "user", "content" => "Hello!"}]
})

# Streaming
HuggingfaceClient.chat_completion_stream(client, %{model: "...", messages: [...]})
|> HuggingfaceClient.content_stream()
|> Enum.each(&IO.write/1)

# ── Hub ──────────────────────────────────────────────────────────────────────

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

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

# Jobs (GPU compute)
{:ok, job} = HuggingfaceClient.Hub.run_job(
  image:   "pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel",
  command: ["python", "train.py"],
  flavor:  "a10g-small", timeout: "4h", access_token: "hf_..."
)
HuggingfaceClient.Hub.fetch_job_logs(job["id"], access_token: "hf_...")
|> Enum.each(&IO.puts/1)

# Buckets (S3-like)
{:ok, _} = HuggingfaceClient.Hub.create_bucket("checkpoints", private: true, access_token: "hf_...")
:ok = HuggingfaceClient.Hub.upload_bucket_file("user/checkpoints",
  source: "./step-1000.bin", destination: "runs/exp1/step-1000.bin", access_token: "hf_...")

# AutoTrain
{:ok, project} = HuggingfaceClient.Hub.autotrain_create(
  project_name: "my-classifier", task: "text-classification",
  base_model: "bert-base-uncased", access_token: "hf_..."
)

# TGI server
client = HuggingfaceClient.Inference.TGI.new("http://localhost:8080")
{:ok, r} = HuggingfaceClient.Inference.TGI.generate(client, inputs: "Hello!", max_new_tokens: 50)

# Jinja2 templates
{:ok, prompt} = HuggingfaceClient.Jinja.apply_chat_template(template, messages)
```

## All Services Covered

| HF Service | Module | Key Functions |
|------------|--------|--------------|
| Inference API (34 tasks) | `HuggingfaceClient.Inference` | chat_completion, text_to_image, asr… |
| Text Generation Inference | `HuggingfaceClient.Inference.TGI` | generate, generate_stream, chat_completion |
| Inference Endpoints | `HuggingfaceClient.Hub.Endpoints` | create, pause, resume, scale_to_zero |
| Models Hub | `HuggingfaceClient.Hub` | search_models, model_info |
| Datasets Hub | `HuggingfaceClient.Hub` | search_datasets, dataset_info |
| Dataset Viewer | `HuggingfaceClient.Hub` | dataset_viewer_rows, statistics, parquet |
| Spaces | `HuggingfaceClient.Hub` | pause_space, add_space_secret, hardware |
| Jobs (GPU compute) | `HuggingfaceClient.Hub` | run_job, fetch_job_logs, wait_for_job |
| AutoTrain | `HuggingfaceClient.Hub` | autotrain_create, autotrain_status |
| Buckets (S3-like) | `HuggingfaceClient.Hub` | create_bucket, upload_bucket_file |
| Discussions & PRs | `HuggingfaceClient.Hub` | create_discussion, merge_pull_request |
| Webhooks | `HuggingfaceClient.Hub` | create_webhook, WebhooksServer |
| Collections | `HuggingfaceClient.Hub` | create_collection, add_collection_item |
| Papers | `HuggingfaceClient.Hub` | list_papers, search_papers |
| Leaderboards | `HuggingfaceClient.Hub` | get_leaderboard, open_llm_leaderboard |
| Evaluate metrics | `HuggingfaceClient.Hub` | compute_metric, evaluate_model |
| Gated repos | `HuggingfaceClient.Hub` | accept_access_request, grant_access |
| Organizations | `HuggingfaceClient.Hub` | list_org_members, invite_org_member |
| Cache | `HuggingfaceClient.Hub` | scan_cache, delete_cached_revision |
| FileSystem (hf://) | `HuggingfaceClient.Hub.FileSystem` | ls, read, write, glob, cp |
| Jinja2 templates | `HuggingfaceClient.Jinja` | render, apply_chat_template |
| MCP Agent | `HuggingfaceClient.Agent` | new, load_tools, run |
| Config/env vars | `HuggingfaceClient.Config` | token, cache_dir, save_token |

## License

MIT