Crate api_huggingface

Crate api_huggingface 

Source
Expand description

HuggingFace API client for Rust

This library provides a comprehensive HTTP client for interacting with HuggingFace's Inference API. It handles authentication, request/response serialization, streaming support, and opt-in reliability features for production deployments.

§Design Philosophy : “Thin Client, Rich API”

This library provides comprehensive opt-in features with explicit developer control. No automatic behaviors occur without explicit configuration.

§Opt-In Enterprise Features

All features require explicit cargo feature flags and developer configuration:

  • Circuit Breaker: Opt-in failure detection with explicit configuration (developer must enable and configure)
  • Rate Limiting: Token bucket rate limiting (developer must explicitly call rate_limiter.acquire().await)
  • Failover: Multi-endpoint failover (developer configures and controls failover strategy)
  • Health Checks: Background endpoint health monitoring (developer must explicitly enable and configure)
  • Caching: Intelligent content caching (developer must explicitly enable and use cache)
  • Performance Metrics: Request tracking (developer must explicitly enable metrics collection)
  • Dynamic Configuration: Runtime config updates (developer must explicitly set up watchers)

§Why Explicit Control Matters

  • Predictability: Features only activate when explicitly configured
  • Transparency: No hidden behaviors or automatic decision-making
  • Flexibility: Choose which features to use (if any)
  • Performance: Zero overhead from unused features

§Implemented APIs

Core Functionality:

  • Text Generation (Inference API) - /models/{model_id} endpoint
  • Embeddings (Feature Extraction) - Embedding generation and similarity
  • Model Information - Model metadata and status checking
  • Inference Providers - Pro plan models via chat completions
  • Function Calling - Tool/function calling support for chat completions
  • Streaming - Server-sent events for real-time responses

Planned Expansion:

  • Computer Vision APIs : Image classification, object detection, text-to-image, etc.
  • Audio APIs : ASR, audio classification, text-to-speech
  • Multimodal APIs : Document QA, visual QA, video-text-to-text

§Historical Context

2024-10-19: Architecture decision to add opt-in enterprise reliability features. All features require explicit cargo feature flags and developer configuration to maintain the “Thin Client, Rich API” governing principle.

Modules§

audio
Audio Processing API Implementation
cache
Content Caching Implementation
client
This module defines the Client structure for interacting with the HuggingFace API. It provides methods for making various API requests, handling authentication, and managing HTTP communication.
components
This module defines shared data structures and components used across various HuggingFace API groups. It includes common types for requests, responses, and specific components like inference, embeddings, and model-related structures.
config
Configuration Management
diagnostics
Diagnostics module for debugging and development tools
embeddings
Embedding generation and feature extraction operations for HuggingFace API.
environment
Environment configuration and management for HuggingFace API.
error
Error types and handling for HuggingFace API interactions.
exposed
Exposed namespace of the module.
inference
Text generation and inference operations for HuggingFace API.
models
Model information and management operations for HuggingFace API.
orphan
Orphan namespace of the module.
own
Own namespace of the module.
performance
Performance Metrics Implementation
prelude
Prelude to use essentials: use my_module ::prelude :: *.
providers
HuggingFace Inference Providers API for Pro plan model access
reliability
Enterprise Reliability Features
secret
Secret management for HuggingFace API keys and sensitive data.
streaming_control
Streaming control for pause, resume, and cancel operations.
sync
Synchronous API wrappers for HuggingFace client
token_counter
Token Counting Implementation
validation
Request validation functionality for HuggingFace API
vision
Vision and Multimodal API Implementation

Structs§

Client
The main client for interacting with the HuggingFace API.
ExplicitRetryConfig
Configuration for explicit retry behavior
HuggingFaceEnvironmentImpl
Default implementation of HuggingFace environment
Secret
Secure wrapper for API keys and other sensitive data