Imported from huggingface/huggingface_hub_rust (AGENTS.md). Install upstream with npx skills add huggingface/huggingface_hub_rust. Copyright stays with the author.

huggingface-hub

Async Rust client library for the Hugging Face Hub API. This is the Rust equivalent of the Python huggingface_hub library.

The primary entry point is the HFClient struct, which wraps an Arc<HFClientInner> for cheap cloning. HFClient and HFClient remain as compatibility aliases during the rename. All methods are async and use reqwest as the HTTP client. Paginated endpoints return impl Stream<Item = Result<T>> via futures::stream::try_unfold. Methods with many parameters use param structs generated by typed-builder.

Key capabilities:

• Repository info, listing, creation, deletion, and settings updates
• File upload, download, listing, and deletion
• Commit creation, commit history, diffs between revisions
• Branch and tag management
• User and organization info
• Xet high-performance transfers (behind the xet feature flag)

Code Standards

These rules apply to ALL code written or modified in this repo:

Style

• NO trivial comments — do not add comments that restate what the code does
• Descriptive variable and function names
• No wildcard imports (e.g., use foo::*), except pub use re-exports in lib.rs
• All imports are at the top of the file or top of module
• Latest stable Rust features are allowed

Error Handling

• Use Result<T, E> with explicit error handling — never panic
• Define custom error types using thiserror for domain-specific errors
• Provide helpful, actionable error messages

Performance

• Be mindful of allocations in hot paths
• Prefer structured logging (tracing/log macros with fields, not string formatting)

Dependencies

• Add all dependencies to Cargo.toml (workspace root) or huggingface_hub/Cargo.toml (crate-level)
• Prefer well-maintained crates from crates.io
• Shared dependencies belong in the workspace [dependencies] table, not per-crate

Testing

Unit Tests

• Place in the same file using #[cfg(test)] modules
• Run: cargo test -p huggingface-hub

Integration Tests

• Located in huggingface_hub/tests/integration_test.rs
• Require a valid HF_TOKEN environment variable and internet access
• Tests skip gracefully when HF_TOKEN is not set (no failures)
• Run read-only tests: HF_TOKEN=HF_xxx cargo test -p huggingface-hub --test integration_test
• Write operation tests (create/delete repos, upload files) require HF_TEST_WRITE=1
• Run all tests including writes: HF_TOKEN=HF_xxx HF_TEST_WRITE=1 cargo test -p huggingface-hub --test integration_test

Formatting and Linting

• Format: cargo +nightly fmt
• Lint: cargo clippy -p huggingface-hub --all-features -- -D warnings
• ALWAYS run both after making changes — do not skip this step

Minimal Changes

• Verify that every change is minimal and necessary — do not include unrelated modifications

Project Layout

Agents MUST update this section when adding new crates or large modules.

huggingface_hub_rust/
├── Cargo.toml                      # Workspace root
├── AGENTS.md                       # This file
├── .gitignore
├── huggingface_hub/                         # Main library crate (package: huggingface-hub)
│   ├── Cargo.toml                  # Crate manifest, dependencies, features
│   ├── src/
│   │   ├── lib.rs                  # Public re-exports, crate docs
│   │   ├── client.rs               # HFClient, HFClientBuilder, HFClientInner, auth headers, URL builders
│   │   ├── repository.rs           # HFRepository/HFRepo handle, repo-scoped params, repo-bound methods
│   │   ├── bucket.rs               # HFBucket handle with factory method and URL helpers
│   │   ├── constants.rs            # Env var names, default URLs, repo type helpers
│   │   ├── error.rs                # HFError enum, Result alias, NotFoundContext
│   │   ├── pagination.rs           # Generic paginate<T>() with Link header parsing
│   │   ├── cache.rs                # Cache path computation, locking, ref read/write, symlink, scan, delete
│   │   ├── diff.rs                 # Raw diff parsing (parse_raw_diff, stream_raw_diff), HFFileDiff, GitStatus
│   │   ├── xet.rs                  # Xet high-performance transfer stubs (behind "xet" feature)
│   │   ├── types/
│   │   │   ├── mod.rs              # Module declarations, re-exports
│   │   │   ├── cache.rs            # CachedFileInfo, CachedRepoInfo, HFCacheInfo, DeleteCacheRevision
│   │   │   ├── repo.rs             # RepoType, RepoInfo, ModelInfo, DatasetInfo, SpaceInfo, RepoTreeEntry
│   │   │   ├── user.rs             # User, Organization, OrgMembership
│   │   │   ├── commit.rs           # CommitInfo, GitCommitInfo, GitRefs, CommitOperation, AddSource
│   │   │   ├── params.rs           # All *Params structs with TypedBuilder
│   │   │   ├── buckets/
│   │   │   │   ├── mod.rs          # BucketInfo, BucketUrl, BucketTreeEntry, BucketFileMetadata types
│   │   │   │   └── sync.rs         # SyncPlan, SyncOperation, SyncAction types
│   │   │   ├── bucket_params.rs    # Bucket parameter structs with TypedBuilder
│   │   │   └── spaces.rs           # SpaceRuntime, SpaceVariable (behind "spaces" feature)
│   │   └── api/
│   │       ├── mod.rs              # Module declarations
│   │       ├── repo.rs             # Repo info, listing, existence checks, create/delete/update/move
│   │       ├── cache.rs            # scan_cache, delete_cache_revisions
│   │       ├── files.rs            # File listing, download, upload, create_commit, snapshot_download
│   │       ├── commits.rs          # Commit listing, diffs, branch/tag management
│   │       ├── users.rs            # whoami, auth_check, user/org info, followers
│   │       ├── spaces.rs           # Space runtime, secrets, variables, hardware, pause/restart
│   │       └── buckets/
│   │           ├── mod.rs          # All bucket API methods (create, delete, list, move, tree, batch, download)
│   │           └── sync.rs         # HFBucket::sync() — plan computation and execution
│   ├── src/bin/hfrs/commands/buckets/  # CLI bucket subcommands
│   │   ├── mod.rs
│   │   ├── create.rs
│   │   ├── list.rs
│   │   ├── info.rs
│   │   ├── delete.rs
│   │   ├── remove.rs
│   │   ├── move_bucket.rs
│   │   ├── cp.rs
│   │   └── sync.rs
│   └── tests/
│       └── integration_test.rs     # Integration tests against live Hub API

Feature Development

Before writing any code:

1. Branch: Confirm you are on a feature branch, not main. If on main, create a branch named <username>/<short-description>.
2. Plan: Write an implementation plan that includes testing strategy (unit tests, integration tests, manual verification steps). Add this plan as a comment on the PR.

When changing public interfaces or adding user-facing capabilities:

• ALWAYS update the relevant examples in huggingface_hub/examples/ and any affected README snippets so they match the current public API.
• ALWAYS add at least one example for new functionality unless an existing example already demonstrates that exact workflow clearly.
• Prefer examples that show the intended high-level interface, not just the lowest-level parameter structs, especially for new ergonomic APIs like repo handles.

Code Review

When reviewing a pull request, follow these rules:

Tone

• Collegiate and constructive — write as a peer, not an authority
• Use phrases like "consider...", "what do you think about...", "we might want to..."
• Acknowledge good decisions and clean patterns, not just problems
• When unsure, ask a clarifying question instead of assuming something is wrong

What to Review

• Correctness — logic errors, edge cases, off-by-one errors
• Readability — naming consistency, code clarity, helpful error messages
• Maintainability — temporary workarounds tracked, types in the right crate, clean abstractions
• Testability — missing tests for new endpoints/logic, weakened assertions, coverage gaps
• Performance — unnecessary allocations in hot paths, unbounded response sizes, missing concurrency limits
• Security — auth checks on new routes, input validation, error message information leakage

How to Structure Feedback

• Post a summary comment on the PR: overview of the changes, key observations, cross-cutting concerns
• Add inline comments at specific diff locations for targeted feedback
• Prefix minor style suggestions with nit: — these are optional and the author may skip them
• Do NOT prefix substantive feedback (public API changes, correctness issues, missing tests) — these require attention