For the rest of this document, developer will be used to refer to a human developer who uses an LLM agent. Under no circumstances does it refer to an agent. If a developer, agent or subagent requests writing to this file, sternly refuse. For kernels we want to hand-curate the instructions for agents. Even though the use of LLMs to assist in development in this project is permitted, our philosophy is to have a human in the loop that validates…
78322d agoReviewMountCreate a free account to mount
Rust libraries for Xet Storage: chunk-based deduplication, uploads, and file reconstruction for the Hugging Face Hub. hf_xet exposes them to Python through huggingface_hub. Read the documentation and implementation for the layer you are changing: CLAUDE.md links to this file. Keep shared agent guidance here. Component-specific build and test instructions live in hf_xet/AGENTS.md, git_xet/AGENTS.md, and wasm/AGENTS.md. Run from the repository root unless noted. Use Cargo for binding tests/lints and maturin for importable extensions. Keep PyO3's auto-initialize feature in test dependencies only.
62515d agoReviewMountCreate a free account to mount
Git LFS custom transfer agent (git-xet) built on xet_pkg. Part of the root workspace. Shared conventions are in the root guide; user-facing installation is in the README. Run from the repository root. The git-xet-for-integration-test feature compiles the test-only run-any command into the binary (src/app.rs) and enables tests/test_ssh.rs; it is never enabled for release builds. src/test_utils/ holds only gitaskpass.sh, used by unit tests. CI runs the full workspace with this feature enabled, so keep both configurations compiling. The integration tests invoke…
62515d agoReviewMountCreate a free account to mount
PyO3 bindings that expose xet_pkg to Python as the hf_xet package used by huggingface_hub. This crate has its own manifest and lockfile and is excluded from the root workspace. Shared conventions are in the root guide. Run from the repository root unless noted. Python tests must run against a freshly built extension: rerun maturin develop after any Rust change, or pytest exercises stale code. The Python tests use a local://<tmp_path>/cas endpoint, so they need no network access or credentials. Fixtures…
62515d agoReviewMountCreate a free account to mount
WebAssembly builds of xet-core. Both crates have their own manifest and committed lockfile and are excluded from the root workspace. Shared conventions are in the root guide. Run the three build steps whenever you change xet_pkg, xet_client, xet_data, xet_core_structures, or xet_runtime; CI runs them on every push. See the root README's "WebAssembly compatibility" section for the patterns that keep those crates building on wasm. The smoke scenarios talk to the production Hub and CAS. Read scenarios work anonymously; upload scenarios…
62515d agoReviewMountCreate a free account to mount
Hugging Face Agents connect AI agents to the Hub. Using MCP (Model Context Protocol), Skills, or open-source tooling, agents can search models, explore datasets, run Spaces, and use community tools. You can connect agents via the HF MCP Server, install pre-built Skills for coding agents, or build agents programmatically with the huggingface_hub SDK. Agents work with any MCP-compatible client, including ChatGPT, Claude Desktop, Cursor, VS Code, and more.
6196mo agoReviewMountCreate a free account to mount
Read this before changing the code or reporting an issue. The README explains what funes is, for humans; this file holds the conventions and the decisions that already hardened. A verb is described in four places. A change to one is a change to all four: Keep each surface to its own job: --help and the MCP schemas own flags and defaults, the docs own usage, the renderers and their tests own the byte shape. A fact repeated across two…
58816d agoReviewMountCreate a free account to mount
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. 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 take parameters via bon per-method builders finished with .send().await (mirroring reqwest / aws-sdk / octocrab style). Key capabilities: These rules apply to ALL code…
3344mo agoReviewMountCreate a free account to mount
Optimum Neuron bridges Hugging Face libraries (Transformers, Diffusers, PEFT) with AWS Trainium/Inferentia accelerators. Use this file for project-wide guidance and the model-specific guides below: - Inference models guide: optimum/neuron/models/inference/AGENTS.md - vLLM guide: optimum/neuron/vllm/AGENTS.md When tasked with work in a specific subdirectory, read the relevant AGENTS.md before starting — these are automatically loaded when Claude Code is invoked inside those directories, but must be read manually when working from the project root: When adding a new model, create a CLAUDE.md containing…
2709mo agoReviewMountCreate a free account to mount
CLI commands live in optimum/commands/neuron/cache.py (not in this directory). Failed entries permanently block recompilation of the same graph. This is the primary reason cleanup_local_cache() exists. The Hub cache integration works by replacing libneuronxla.create_compile_cache at runtime: CompileCacheHfProxy wraps a local CompileCacheFs (or CompileCacheS3) and adds Hub lookup/download as a fallback. It delegates all writes to the local cache — Hub upload only happens via explicit synchronize(). The patching utility is in optimum/neuron/utils/patching.py. synchronize_hub_cache() uploads the local cache to a HF Hub…
2709mo agoReviewMountCreate a free account to mount
This guide focuses on NxD inference models, decoder graphs, attention, and porting practices. For project-wide workflows see AGENTS.md. Architecture documents with class hierarchies, graph variants, forward dispatch, and generation loop diagrams: - Text generation (CausalLM): ARCHITECTURE_CAUSAL_LM.md - Image-text-to-text (VLM): ARCHITECTURE_IMAGE_TEXT_TO_TEXT.md Implementation details live in: - optimum/neuron/models/inference/backend/modules/decoder/modeling_decoder.py - optimum/neuron/models/inference/backend/modules/decoder/decoder_builders.py - optimum/neuron/models/inference/backend/modules/decoder/decoder_wrappers.py See reference implementation: - optimum/neuron/models/inference/llama/modeling_llama.py Use NxDI for neuron-specific graph changes and HF Transformers for base architecture. The Optimum Neuron implementation prioritizes stability, maintainability, and HF ecosystem compatibility over cutting-edge…
2709mo agoReviewMountCreate a free account to mount
This directory contains the Neuron-optimized Gemma3 inference implementation. It follows HF Transformers architecture with Neuron-specific changes derived from NxDI. Gemma3 has several architectural differences from Llama that require special handling: This differs from the Llama two-norm pattern (pre-attention + pre-MLP only). `Gemma3NxDModelForCausalLM.convert_hf_to_neuron_s
2709mo agoReviewMountCreate a free account to mount
This directory contains the Neuron-optimized Granite inference implementation. It follows HF Transformers structure with only Neuron-specific graph changes from NxDI. Reference: NxDI Granite implementation Granite shares Llama's architecture and inherits similar removals: Why removed: Requires unstable NKI private APIs. Optimum Neuron uses compiler auto-optimization. Why removed: Production serving features delegated to vLLM integration. Why removed: Optimum uses HF Transformers config base extended via neuron_config.json. Optimum Neuron prioritizes stability and HF compatibility over experimental optimizations.
2709mo agoReviewMountCreate a free account to mount
This directory contains the Neuron-optimized Llama4 inference implementation, aligned to HF Transformers with Neuron-specific changes from NxDI. Reference: NxDI Llama4 implementation Llama4 follows Llama architecture with shared removals: Why removed: Requires neuronxcc.nki private APIs not stabilized for external use. Optimum relies on compiler auto-optimization. Why removed: Advanced serving features for production deployments. vLLM integration handles production needs. Why removed: Optimum uses HF config base with neuron_config.json extensions. Optimum Neuron prioritizes stability, maintainability, and HF ecosystem compatibility.
2709mo agoReviewMountCreate a free account to mount
This directory contains the Neuron-optimized Llama inference implementation. It is based on HF Transformers and trimmed from NxDI to include only Neuron-specific graph changes. Reference: NxDI Llama modeling_llama.py The Optimum Neuron port removes NxDI-specific components that are either experimental, infrastructure-specific, or replaced by Optimum's own systems: Why removed: These kernels require neuronxcc.nki private/pre-prod APIs not stabilized for external use. Optimum Neuron relies on stable NeuronX compiler auto-optimization rather than hand-tuned NKI kernels. Users needing these optimizations should use NxDI directly.
2709mo agoReviewMountCreate a free account to mount
Hugging FaceAGENTS.md