Skip to content

fix: pin version specifier and add warning to docs #202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
drbh wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: pin version specifier and add warning to docs #202

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ import torch
from kernels import get_kernel

# Download optimized kernels from the Hugging Face hub
activation = get_kernel("kernels-community/activation")
activation = get_kernel("kernels-community/activation", version=">=0.1.0,<0.2.0")
Copy link
Member

@danieldk danieldk Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should hold off a bit, since the channel proposal may also make version specifiers obsolete.


# Random tensor
x = torch.randn((10, 10), dtype=torch.float16, device="cuda")
Expand All @@ -51,6 +51,11 @@ activation.gelu_fast(y, x)
print(y)
```

> [!WARNING] Strongly recommended to specify version bounds
> Loading kernels without specifying a version will fetch from the `main` branch.
> The `main` branch may contain breaking changes or incompatible updates at any time.
> Always specify version bounds to ensure reproducible builds and avoid unexpected issues.

You can [search for kernels](https://huggingface.co/models?other=kernels) on
the Hub.

Expand Down
11 changes: 8 additions & 3 deletions docs/source/basic-usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import torch
from kernels import get_kernel

# Download optimized kernels from the Hugging Face hub
activation = get_kernel("kernels-community/activation")
activation = get_kernel("kernels-community/activation", version=">=0.1.0,<0.2.0")

# Create a random tensor
x = torch.randn((10, 10), dtype=torch.float16, device="cuda")
Expand All @@ -21,6 +21,11 @@ activation.gelu_fast(y, x)
print(y)
```

> [!WARNING] Strongly recommended to specify version bounds
> Loading kernels without specifying a version will fetch from the `main` branch.
> The `main` branch may contain breaking changes or incompatible updates at any time.
> Always specify version bounds to ensure reproducible builds and avoid unexpected issues.

### Using version bounds

Kernels are versioned using tags of the form `v<major>.<minor>.<patch>`.
Expand All @@ -30,10 +35,10 @@ You can specify which version to download using Python version specifiers:
import torch
from kernels import get_kernel

activation = get_kernel("kernels-community/activation", version=">=0.0.4,<0.1.0")
activation = get_kernel("kernels-community/activation", version=">=0.1.0,<0.2.0")
```

This will get the latest kernel tagged `v0.0.z` where `z` is at least 4. It
This will get the latest kernel tagged `v0.1.z` where `z` is at least 0. It
is strongly recommended to specify a version bound, since a kernel author
might push incompatible changes to the `main` branch.

Expand Down
16 changes: 12 additions & 4 deletions docs/source/layers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,15 +159,22 @@ kernel_layer_mapping = {
"cuda": LayerRepository(
repo_id="kernels-community/activation",
layer_name="SiluAndMul",
version=">=0.1.0,<0.2.0",
),
"rocm": LayerRepository(
repo_id="kernels-community/activation",
layer_name="SiluAndMul",
version=">=0.1.0,<0.2.0",
)
}
}
```

> [!WARNING] Strongly recommended to specify version bounds
> Loading kernels without specifying a version will fetch from the `main` branch.
> The `main` branch may contain breaking changes or incompatible updates at any time.
> Always specify version bounds to ensure reproducible builds and avoid unexpected issues.

You can register such a mapping using `register_kernel_mapping`:

```python
Expand Down Expand Up @@ -197,6 +204,7 @@ kernel_layer_mapping = {
"cuda": FuncRepository(
repo_id="kernels-community/activation",
func_name="silu_and_mul",
version=">=0.1.0,<0.2.0",
),
}
}
Expand All @@ -214,19 +222,19 @@ kernel_layer_mapping = {
"cuda": LayerRepository(
repo_id="kernels-community/activation",
layer_name="SiluAndMul",
version=">=0.0.4,<0.1.0",
version=">=0.1.0,<0.2.0",
),
"rocm": LayerRepository(
repo_id="kernels-community/activation",
layer_name="SiluAndMul",
version=">=0.0.4,<0.1.0",
version=">=0.1.0,<0.2.0",
)
}
}
```

This will get the layer from latest kernel tagged `v0.0.z` where `z` is at
least 4. It is strongly recommended to specify a version bound, since a
This will get the layer from the latest kernel tagged `v0.1.z` where `z` is at
least 0. It is strongly recommended to specify a version bound, since a
kernel author might push incompatible changes to the `main` branch.

### Registering kernels for specific modes
Expand Down
Loading