transformers-knn-adapter 0.2.0__tar.gz

transformers_knn_adapter-0.2.0/.devcontainer/devcontainer.json

@@ -0,0 +1,27 @@
+{
+  "name": "hf-extender",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {},
+    "ghcr.io/devcontainers/features/python:1": {},
+    "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {},
+    "ghcr.io/jsburckhardt/devcontainer-features/codex:1": {},
+    "ghcr.io/nils-geistmann/devcontainers-features/zsh:0": {}
+
+
+  },
+  "containerEnv": {
+    "UV_PROJECT_ENVIRONMENT": "/tmp/uv-venv",
+    "UV_CACHE_DIR": "/tmp/uv-cache"
+
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "openai.chatgpt",
+        "github.vscode-github-actions"
+      ]
+    }
+  }
+}

transformers_knn_adapter-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Verify distributions
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

transformers_knn_adapter-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,22 @@
+name: release-please
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run release-please
+        uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          config-file: .release-please-config.json
+          manifest-file: .release-please-manifest.json

transformers_knn_adapter-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,56 @@
+name: tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    env:
+      UV_CACHE_DIR: .uv-cache
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Cache uv downloads
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.UV_CACHE_DIR }}
+          key: uv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-${{ matrix.python-version }}-
+            uv-${{ runner.os }}-
+
+      - name: Sync dependencies
+        run: uv sync --dev
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Run pytest
+        run: uv run pytest -q
+
+      - name: Build wheel
+        run: uv build --wheel
+
+      - name: Install smoke test
+        run: |
+          uv venv --clear /tmp/install-smoke
+          uv pip install --python /tmp/install-smoke/bin/python dist/*.whl
+          /tmp/install-smoke/bin/python -c "import transformers_knn_adapter; print('install-ok')"

transformers_knn_adapter-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+*.joblib

transformers_knn_adapter-0.2.0/.release-please-config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "python",
+  "include-component-in-tag": false,
+  "packages": {
+    ".": {
+      "package-name": "transformers_knn_adapter",
+      "changelog-path": "CHANGELOG.md",
+      "extra-files": [
+        "pyproject.toml"
+      ]
+    }
+  }
+}

transformers_knn_adapter-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

transformers_knn_adapter-0.2.0/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+## Commit Convention
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for all commits and PR titles.
+
+Required format:
+
+```text
+<type>(<optional-scope>): <short imperative summary>
+```
+
+Examples:
+
+- `feat(pipeline): add stratified sampling for eval`
+- `fix(ci): run ruff before pytest`
+- `docs(readme): add train and eval usage examples`
+- `test(knn): cover grid-search parameter validation`
+- `chore(deps): bump transformers to latest compatible version`
+
+## Allowed Types
+
+- `feat`: new user-facing functionality
+- `fix`: bug fix
+- `docs`: documentation-only changes
+- `test`: add/update tests
+- `refactor`: code restructuring without behavior change
+- `perf`: performance improvement
+- `build`: packaging/build system changes
+- `ci`: CI/CD workflow changes
+- `chore`: maintenance that does not fit above
+
+## Breaking Changes
+
+For breaking changes, use either:
+
+- `feat!:` / `fix!:` syntax, or
+- `BREAKING CHANGE:` in the commit body
+
+Example:
+
+- `feat!: rename pipeline factory arguments`
+
+## Scope Guidance
+
+Prefer one of these scopes when relevant:
+
+- `pipeline`
+- `knn`
+- `tests`
+- `ci`
+- `packaging`
+- `docs`
+
+## Additional Rules
+
+- Keep subject line <= 72 characters.
+- Use imperative mood (`add`, `fix`, `remove`), not past tense.
+- Do not end subject line with a period.
+- Squash/fixup local commits before merge when practical.
+
+## Why
+
+This repository uses automated release/versioning workflows. Conventional Commits keep changelogs and semantic version bumps predictable.

transformers_knn_adapter-0.2.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This changelog is automatically managed by release-please from commits merged into `main`.
+
+## [0.2.0](https://github.com/dimidagd/transformers-knn-adapter/compare/v0.1.0...v0.2.0) (2026-03-05)
+
+
+### Features
+
+* **cli:** add infer mode for single and batched image prediction ([47a291b](https://github.com/dimidagd/transformers-knn-adapter/commit/47a291b9156ad63d9263430366aded4687a8b16b))
+
+
+### Documentation
+
+* **readme:** add infer command usage example ([6b01105](https://github.com/dimidagd/transformers-knn-adapter/commit/6b01105379de1d4edc66294eaddd460c301352de))
+
+## [Unreleased]

transformers_knn_adapter-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 transformers-knn-adapter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

transformers_knn_adapter-0.2.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: transformers_knn_adapter
+Version: 0.2.0
+Summary: Hugging Face Transformers image embedding adapter with a scikit-learn KNN classification head.
+Author: transformers-knn-adapter contributors
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: datasets
+Requires-Dist: joblib
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: scikit-learn
+Requires-Dist: torch
+Requires-Dist: tqdm
+Requires-Dist: transformers
+Description-Content-Type: text/markdown
+
+# transformers-knn-adapter
+
+`transformers_knn_adapter` extends Hugging Face image models by attaching a scikit-learn KNN classifier on top of transformer embeddings.
+
+## Requirements
+
+- Python 3.11+
+- `uv`
+
+## Setup
+
+```bash
+uv sync --dev
+```
+
+## Run Tests
+
+```bash
+uv run pytest
+```
+
+## Train
+
+```bash
+uv run python -m transformers_knn_adapter.knn_image_pipeline train \
+  --model microsoft/resnet-50 \
+  --knn-model-path /tmp/knn/dinov2_small_mini_imagenet_full.joblib \
+  --dataset timm/mini-imagenet \
+  --split train \
+  --max-samples 1000 \
+  --shuffle \
+  --grid-search \
+  --grid-search-splits 3 \
+  --grid-search-repeats 2 \
+  --grid-search-scoring f1_macro
+```
+
+## Evaluate
+
+```bash
+uv run python -m transformers_knn_adapter.knn_image_pipeline eval \
+  --model microsoft/resnet-50 \
+  --knn-model-path /tmp/knn/dinov2_small_mini_imagenet_full.joblib \
+  --dataset timm/mini-imagenet \
+  --split test \
+  --stratified \
+  --max-samples 100 \
+  --shuffle \
+  --batch-size 100
+```
+
+## Inference
+
+```bash
+uv run python -m transformers_knn_adapter.knn_image_pipeline infer \
+  --model microsoft/resnet-50 \
+  --knn-model-path /tmp/knn/dinov2_small_mini_imagenet_full.joblib \
+  --image https://picsum.photos/200 \
+  --inference-batch-size 5
+```
+
+## Python API
+
+```python
+from transformers_knn_adapter.knn_image_pipeline import pipeline
+
+clf = pipeline(
+    "image-classification",
+    model_path="microsoft/resnet-50",
+    knn_model_path="/tmp/knn/model.joblib",
+)
+```
+
+## Notes
+
+Real train/eval runs can download model and dataset artifacts from Hugging Face.

transformers_knn_adapter-0.2.0/README.md

@@ -0,0 +1,76 @@
+# transformers-knn-adapter
+
+`transformers_knn_adapter` extends Hugging Face image models by attaching a scikit-learn KNN classifier on top of transformer embeddings.
+
+## Requirements
+
+- Python 3.11+
+- `uv`
+
+## Setup
+
+```bash
+uv sync --dev
+```
+
+## Run Tests
+
+```bash
+uv run pytest
+```
+
+## Train
+
+```bash
+uv run python -m transformers_knn_adapter.knn_image_pipeline train \
+  --model microsoft/resnet-50 \
+  --knn-model-path /tmp/knn/dinov2_small_mini_imagenet_full.joblib \
+  --dataset timm/mini-imagenet \
+  --split train \
+  --max-samples 1000 \
+  --shuffle \
+  --grid-search \
+  --grid-search-splits 3 \
+  --grid-search-repeats 2 \
+  --grid-search-scoring f1_macro
+```
+
+## Evaluate
+
+```bash
+uv run python -m transformers_knn_adapter.knn_image_pipeline eval \
+  --model microsoft/resnet-50 \
+  --knn-model-path /tmp/knn/dinov2_small_mini_imagenet_full.joblib \
+  --dataset timm/mini-imagenet \
+  --split test \
+  --stratified \
+  --max-samples 100 \
+  --shuffle \
+  --batch-size 100
+```
+
+## Inference
+
+```bash
+uv run python -m transformers_knn_adapter.knn_image_pipeline infer \
+  --model microsoft/resnet-50 \
+  --knn-model-path /tmp/knn/dinov2_small_mini_imagenet_full.joblib \
+  --image https://picsum.photos/200 \
+  --inference-batch-size 5
+```
+
+## Python API
+
+```python
+from transformers_knn_adapter.knn_image_pipeline import pipeline
+
+clf = pipeline(
+    "image-classification",
+    model_path="microsoft/resnet-50",
+    knn_model_path="/tmp/knn/model.joblib",
+)
+```
+
+## Notes
+
+Real train/eval runs can download model and dataset artifacts from Hugging Face.

transformers_knn_adapter-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "transformers_knn_adapter"
+version = "0.2.0"
+description = "Hugging Face Transformers image embedding adapter with a scikit-learn KNN classification head."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "transformers-knn-adapter contributors" }]
+dependencies = [
+  "transformers",
+  "datasets",
+  "scikit-learn",
+  "numpy",
+  "torch",
+  "pillow",
+  "joblib",
+  "tqdm",
+]
+
+[dependency-groups]
+dev = [
+  "ruff",
+  "pytest",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/transformers_knn_adapter"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-q"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]

transformers_knn_adapter-0.2.0/src/transformers_knn_adapter/__init__.py

@@ -0,0 +1,19 @@
+"""Public package exports for transformers_knn_adapter."""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["KNNImageClassificationPipeline", "pipeline"]
+
+
+def __getattr__(name: str) -> Any:
+    if name in __all__:
+        from .knn_image_pipeline import KNNImageClassificationPipeline, pipeline
+
+        exports = {
+            "KNNImageClassificationPipeline": KNNImageClassificationPipeline,
+            "pipeline": pipeline,
+        }
+        return exports[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")