api_huggingface 0.4.1

HuggingFace's API for accessing large language models (LLMs) and embeddings.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

// src/lib.rs
//! `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
//!
//! - Vision APIs (classification, detection, captioning) - `src/vision/`
//! - Audio APIs (ASR, TTS, classification, transformation) - `src/audio/`
//!
//! ## 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.

#![ cfg_attr( feature = "enabled", deny( missing_docs ) ) ]
#![ cfg_attr( not( feature = "enabled" ), allow( unused ) ) ]

use mod_interface::mod_interface;

mod private {}

// Core modules (always available)
pub mod error;
pub mod components;
pub mod validation;
pub mod diagnostics;

// Token counting (available with client feature)
#[ cfg( feature = "client" ) ]
pub mod token_counter;

// Content caching (available with client feature)
#[ cfg( feature = "client" ) ]
pub mod cache;

// Performance metrics (available with client feature)
#[ cfg( feature = "client" ) ]
pub mod performance;

// Enterprise reliability features — sub-features: circuit-breaker, rate-limiting, failover, health-checks
#[ cfg( feature = "reliability" ) ]
pub mod reliability;

// Configuration management
#[ cfg( feature = "reliability" ) ]
pub mod config;

// Client module (available with client feature)
#[ cfg( feature = "client" ) ]
pub mod client;

// Environment and secret management
#[ cfg( feature = "env-config" ) ]
pub mod environment;
pub mod secret;

// API endpoint modules (feature-gated)
#[ cfg( feature = "inference" ) ]
pub mod inference;
#[ cfg( feature = "embeddings" ) ]
pub mod embeddings;
#[ cfg( feature = "models" ) ]
pub mod models;
#[ cfg( feature = "inference" ) ]
pub mod providers;

// Vision API module (available with vision feature)
#[ cfg( feature = "vision" ) ]
pub mod vision;

// Audio API module (available with audio feature)
#[ cfg( feature = "audio" ) ]
pub mod audio;

// Sync API module (available with sync feature)
#[ cfg( feature = "sync" ) ]
pub mod sync;

// Streaming control module (available with streaming-control feature; requires inference-streaming)
#[ cfg( feature = "streaming-control" ) ]
pub mod streaming_control;

crate::mod_interface!
{
  // Re-export key types at crate root for convenience
  #[ cfg( feature = "client" ) ]
  exposed use client::Client;
  exposed use secret::Secret;
  #[ cfg( feature = "env-config" ) ]
  exposed use environment::HuggingFaceEnvironmentImpl;
  #[ cfg( feature = "client" ) ]
  exposed use client::ExplicitRetryConfig;
}