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.

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

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

Quick Start

# ── 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

License

MIT