# `polars-candle`
A [`polars`](https://pola.rs/) extension for running [`candle`](https://github.com/huggingface/candle) ML
models on `polars` DataFrames.
# Example
Pull any applicable model from Huggingface, such as the recently released
[Snowflake model](https://huggingface.co/Snowflake/snowflake-arctic-embed-xs), and embed text using a simple API.
```python
import polars as pl
import polars_candle # ignore: F401
df = pl.DataFrame({"s": ["This is a sentence", "This is another sentence"]})
embed_kwargs = {
"model_repo": "Snowflake/snowflake-arctic-embed-xs",
"pooling": "mean",
}
df = df.with_columns(
pl.col("s").candle.embed_text(**embed_kwargs).alias("s_embedding")
)
print(df)
# ┌──────────────────────────┬───────────────────────────────────┐
# │ s ┆ s_embedding │
# │ --- ┆ --- │
# │ str ┆ array[f32, 384] │
# ╞══════════════════════════╪═══════════════════════════════════╡
# │ This is a sentence ┆ [-0.056457, 0.559411, … -0.20403… │
# │ This is another sentence ┆ [-0.117206, 0.336827, … 0.174078… │
# └──────────────────────────┴───────────────────────────────────┘
```
Currently, Bert, JinaBert, and Distilbert models are supported. More models will be added in the future. Check
my other repository [`wdoppenberg/glowrs`](https://github.com/wdoppenberg/glowrs) to learn more about the underlying
implementation for sentence embedding.
# Installation
Make sure you have `polars` installed. If not, install it using `pip install polars`. Then, install `polars-candle` using
```bash
pip install polars-candle
```
_Note:_ The macOS ARM wheels of this library come with Metal support out of the box. For CUDA, check the below
instructions on how to build from source.
If you want to install the latest version from the repository, you can use:
```bash
pip install git+https://github.com/wdoppenberg/polars-candle.git
```
_Note:_ You need to have the Rust toolchain installed on your system to compile the library. See
[here](https://www.rust-lang.org/tools/install) for instructions on how to install Rust.
You can set build features using `maturin`:
```bash
maturin develop --release -F <feature>
```
Where `<feature>` can be one of the following:
* `metal` Install with Metal acceleration.
* `cuda` Install with CUDA acceleration. Might require additional setup such as installing CUDA libraries.
* `accelerate` Install with the Accelerate framework.
# Roadmap
- [x] Embed text using Bert, JinaBert, and Distilbert models.
- [ ] Add more models.
- [ ] More configuration options for embedding (e.g. pooling strategy, device selection, etc.).
- [ ] Support & test streaming workloads.
# Credits
- Massive thanks to [`polars`](https://pola.rs/) & their contributors for providing a blazing fast DataFrame library
with the ability to extend it with custom functions using [`pyo3-polars`](https://github.com/pola-rs/pyo3-polars).
- Great work so far by Huggingface on [`candle`](https://github.com/huggingface/candle) for providing a simple
interface to run ML models.
# Note
This is a work in progress and the API might change in the future. Feel free to open an issue if you have any
suggestions or improvements.
Raw data
{
"_id": null,
"home_page": null,
"name": "polars-candle",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "polars, dataframe, embedding, nlp, candle",
"author": "Wouter Doppenberg <wouterdoppenberg@gmail.com>",
"author_email": "Wouter Doppenberg <wouterdoppenberg@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/31/1670ae4e5ba0b2b528a84ef1f7fe6e9fc8381f43f8df41e05d3636e7b042/polars_candle-0.1.7.tar.gz",
"platform": null,
"description": "# `polars-candle`\n\nA [`polars`](https://pola.rs/) extension for running [`candle`](https://github.com/huggingface/candle) ML\nmodels on `polars` DataFrames. \n\n# Example\n\nPull any applicable model from Huggingface, such as the recently released \n[Snowflake model](https://huggingface.co/Snowflake/snowflake-arctic-embed-xs), and embed text using a simple API.\n\n```python\nimport polars as pl\nimport polars_candle # ignore: F401\n\ndf = pl.DataFrame({\"s\": [\"This is a sentence\", \"This is another sentence\"]})\n\nembed_kwargs = {\n \"model_repo\": \"Snowflake/snowflake-arctic-embed-xs\",\n \"pooling\": \"mean\", \n}\n\ndf = df.with_columns(\n pl.col(\"s\").candle.embed_text(**embed_kwargs).alias(\"s_embedding\")\n)\nprint(df)\n# \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n# \u2502 s \u2506 s_embedding \u2502\n# \u2502 --- \u2506 --- \u2502\n# \u2502 str \u2506 array[f32, 384] \u2502\n# \u255e\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561\n# \u2502 This is a sentence \u2506 [-0.056457, 0.559411, \u2026 -0.20403\u2026 \u2502\n# \u2502 This is another sentence \u2506 [-0.117206, 0.336827, \u2026 0.174078\u2026 \u2502\n# \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nCurrently, Bert, JinaBert, and Distilbert models are supported. More models will be added in the future. Check \nmy other repository [`wdoppenberg/glowrs`](https://github.com/wdoppenberg/glowrs) to learn more about the underlying \nimplementation for sentence embedding.\n\n# Installation\n\nMake sure you have `polars` installed. If not, install it using `pip install polars`. Then, install `polars-candle` using\n\n```bash\npip install polars-candle\n```\n\n_Note:_ The macOS ARM wheels of this library come with Metal support out of the box. For CUDA, check the below \ninstructions on how to build from source. \n\nIf you want to install the latest version from the repository, you can use:\n\n```bash\npip install git+https://github.com/wdoppenberg/polars-candle.git\n```\n\n_Note:_ You need to have the Rust toolchain installed on your system to compile the library. See \n[here](https://www.rust-lang.org/tools/install) for instructions on how to install Rust.\n\nYou can set build features using `maturin`:\n\n```bash\nmaturin develop --release -F <feature>\n```\n\nWhere `<feature>` can be one of the following:\n* `metal` Install with Metal acceleration. \n* `cuda` Install with CUDA acceleration. Might require additional setup such as installing CUDA libraries.\n* `accelerate` Install with the Accelerate framework.\n\n\n# Roadmap\n\n- [x] Embed text using Bert, JinaBert, and Distilbert models.\n- [ ] Add more models.\n- [ ] More configuration options for embedding (e.g. pooling strategy, device selection, etc.).\n- [ ] Support & test streaming workloads.\n\n\n# Credits\n\n- Massive thanks to [`polars`](https://pola.rs/) & their contributors for providing a blazing fast DataFrame library \nwith the ability to extend it with custom functions using [`pyo3-polars`](https://github.com/pola-rs/pyo3-polars).\n- Great work so far by Huggingface on [`candle`](https://github.com/huggingface/candle) for providing a simple\ninterface to run ML models.\n\n\n# Note\n\nThis is a work in progress and the API might change in the future. Feel free to open an issue if you have any\nsuggestions or improvements.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A text embedding extension for the Polars Dataframe library.",
"version": "0.1.7",
"project_urls": {
"repository": "https://github.com/wdoppenberg/polars-candle"
},
"split_keywords": [
"polars",
" dataframe",
" embedding",
" nlp",
" candle"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fd993d0425e2b86d4684bdeaf458e52727e252835b29f809333e4bff64df0465",
"md5": "1b0c0347e87fe54d8a7940a4f198ec2d",
"sha256": "2cc4db47365b2bbf429ac2fa7495797313711df5128a2506cb4802d41873f2f8"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp310-cp310-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "1b0c0347e87fe54d8a7940a4f198ec2d",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 5979337,
"upload_time": "2024-04-26T15:50:15",
"upload_time_iso_8601": "2024-04-26T15:50:15.560542Z",
"url": "https://files.pythonhosted.org/packages/fd/99/3d0425e2b86d4684bdeaf458e52727e252835b29f809333e4bff64df0465/polars_candle-0.1.7-cp310-cp310-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0630e85f5103bc1f1d05ceb1a475cfc43634162ae67f37e11f89eae0c9ced895",
"md5": "524bf2c75f1dc6fd0b62eb7df7c639bf",
"sha256": "f9ae245dbfbbb674d235f3df04bac322ef6c5bfad97206a2d4c5cf50f8cce62c"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp310-cp310-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "524bf2c75f1dc6fd0b62eb7df7c639bf",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 6935146,
"upload_time": "2024-04-26T15:50:18",
"upload_time_iso_8601": "2024-04-26T15:50:18.627738Z",
"url": "https://files.pythonhosted.org/packages/06/30/e85f5103bc1f1d05ceb1a475cfc43634162ae67f37e11f89eae0c9ced895/polars_candle-0.1.7-cp310-cp310-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "22e04b93d9a09c25811ce3b5b4311b6e1344b513afa37ea4ad68242a92edd214",
"md5": "0d8d245e4a1db04920101000e63bd124",
"sha256": "c2deeee33b7cf06539a386400e8d5a9f9fed4fd4469f8f353df20e56c4cec3ca"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp310-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "0d8d245e4a1db04920101000e63bd124",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 6310009,
"upload_time": "2024-04-26T15:50:22",
"upload_time_iso_8601": "2024-04-26T15:50:22.160060Z",
"url": "https://files.pythonhosted.org/packages/22/e0/4b93d9a09c25811ce3b5b4311b6e1344b513afa37ea4ad68242a92edd214/polars_candle-0.1.7-cp310-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9d646e96d0d5396c73a0a14f51eb9fdade733da31daf2c7b11deb95239e4f1ce",
"md5": "7a4ab4705b857240edc60017d197e363",
"sha256": "26ea7c7f6773ef58d44663914ecd54bd77b2640cd1537f29035b2a24ed6a6e32"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp311-cp311-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "7a4ab4705b857240edc60017d197e363",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 5979333,
"upload_time": "2024-04-26T15:50:26",
"upload_time_iso_8601": "2024-04-26T15:50:26.961813Z",
"url": "https://files.pythonhosted.org/packages/9d/64/6e96d0d5396c73a0a14f51eb9fdade733da31daf2c7b11deb95239e4f1ce/polars_candle-0.1.7-cp311-cp311-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "36ed8fc33ef07f4224eebd09cd56a2cee93671142da61039c5ef6bbddd46872e",
"md5": "e6f1c143f317fa2029ba40f126bc3d9c",
"sha256": "fedd44c085217ed7a2320690371360e46c6ce885e13194cdf67700f8ade4e0d2"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp311-cp311-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "e6f1c143f317fa2029ba40f126bc3d9c",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 6935136,
"upload_time": "2024-04-26T15:50:29",
"upload_time_iso_8601": "2024-04-26T15:50:29.262437Z",
"url": "https://files.pythonhosted.org/packages/36/ed/8fc33ef07f4224eebd09cd56a2cee93671142da61039c5ef6bbddd46872e/polars_candle-0.1.7-cp311-cp311-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d01dcee526471859088985c2893ad0048107511d7f6fa8f31f944b74918b6c54",
"md5": "ccc07930d80ae06c3ecd2f02513809c6",
"sha256": "dc4f2e57b6b0f4fc297e82e75564034bfe5dfe6ee540679a156392d0796bc469"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp311-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "ccc07930d80ae06c3ecd2f02513809c6",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 6310003,
"upload_time": "2024-04-26T15:50:32",
"upload_time_iso_8601": "2024-04-26T15:50:32.394857Z",
"url": "https://files.pythonhosted.org/packages/d0/1d/cee526471859088985c2893ad0048107511d7f6fa8f31f944b74918b6c54/polars_candle-0.1.7-cp311-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9b717c18c00a56811824b1fdb7c940f58b70eba69b3a5498fa5e55d4bebab761",
"md5": "66569b34a00e76e6b238dcdfb400e5af",
"sha256": "30305c4eaac82771551f2609fc4c7669c739c77a9491a2c0d650fc85218133b7"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp312-cp312-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "66569b34a00e76e6b238dcdfb400e5af",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.9",
"size": 5978975,
"upload_time": "2024-04-26T15:50:34",
"upload_time_iso_8601": "2024-04-26T15:50:34.985824Z",
"url": "https://files.pythonhosted.org/packages/9b/71/7c18c00a56811824b1fdb7c940f58b70eba69b3a5498fa5e55d4bebab761/polars_candle-0.1.7-cp312-cp312-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0b4906d845f3faa246b91ea4282a7092638e8c418f7c0fd849f0f24877c04daa",
"md5": "7084ad89f14bacffba21be1b8d054a6f",
"sha256": "838f908197e65e7d072528a7e172d20981aa0bff8fe23148f40dd3e2e5856252"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp312-cp312-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "7084ad89f14bacffba21be1b8d054a6f",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.9",
"size": 6934969,
"upload_time": "2024-04-26T15:50:37",
"upload_time_iso_8601": "2024-04-26T15:50:37.636526Z",
"url": "https://files.pythonhosted.org/packages/0b/49/06d845f3faa246b91ea4282a7092638e8c418f7c0fd849f0f24877c04daa/polars_candle-0.1.7-cp312-cp312-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c5cfbb78811777e0dd5c4099a45099ff65cb3ccbd6b7c888e907630f9a244bc4",
"md5": "42cbfa910972630058f0e5c5400a90eb",
"sha256": "da69a8aceff91b16130467bb641d3176b9f5a80f531692c15498d1b202b0c48d"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp312-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "42cbfa910972630058f0e5c5400a90eb",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.9",
"size": 6310032,
"upload_time": "2024-04-26T15:50:40",
"upload_time_iso_8601": "2024-04-26T15:50:40.166950Z",
"url": "https://files.pythonhosted.org/packages/c5/cf/bb78811777e0dd5c4099a45099ff65cb3ccbd6b7c888e907630f9a244bc4/polars_candle-0.1.7-cp312-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1989544a9c0ed8fd4161f9dcef4f5bafbadf9ab1675ff3e012bd69b8c8ecc859",
"md5": "c8d632673990f1ff05c3ac08823b75c4",
"sha256": "51da3b23e88beaec7ccc778db830624b548f7e187d6a84072f355cd971e68e11"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp39-cp39-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "c8d632673990f1ff05c3ac08823b75c4",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 5979034,
"upload_time": "2024-04-26T15:50:43",
"upload_time_iso_8601": "2024-04-26T15:50:43.251748Z",
"url": "https://files.pythonhosted.org/packages/19/89/544a9c0ed8fd4161f9dcef4f5bafbadf9ab1675ff3e012bd69b8c8ecc859/polars_candle-0.1.7-cp39-cp39-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e913b2a5da0bf7db969378d0bf8f6997aa20b8a2f29eb67f57e58f14b94cccb8",
"md5": "74125c00b4fc9110c73e3d05ed44bccb",
"sha256": "e00daee55dbce06316d6e0830db02b79377054e1565513a3c6b31f5322eabb92"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp39-cp39-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "74125c00b4fc9110c73e3d05ed44bccb",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 6935047,
"upload_time": "2024-04-26T15:50:46",
"upload_time_iso_8601": "2024-04-26T15:50:46.272779Z",
"url": "https://files.pythonhosted.org/packages/e9/13/b2a5da0bf7db969378d0bf8f6997aa20b8a2f29eb67f57e58f14b94cccb8/polars_candle-0.1.7-cp39-cp39-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "15e71f5f2d98cfdc8aab187ef310112b8943c41f3dbcb66df92ac7f03c27262d",
"md5": "c8e1c37d87e37fe63f7f644f18137343",
"sha256": "0b7facdc7610bda4093ca4cca1e705d27b13a1d38318d2b546dac485a2f7da46"
},
"downloads": -1,
"filename": "polars_candle-0.1.7-cp39-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "c8e1c37d87e37fe63f7f644f18137343",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 6310029,
"upload_time": "2024-04-26T15:50:49",
"upload_time_iso_8601": "2024-04-26T15:50:49.155400Z",
"url": "https://files.pythonhosted.org/packages/15/e7/1f5f2d98cfdc8aab187ef310112b8943c41f3dbcb66df92ac7f03c27262d/polars_candle-0.1.7-cp39-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd311670ae4e5ba0b2b528a84ef1f7fe6e9fc8381f43f8df41e05d3636e7b042",
"md5": "1a32a78d4b7afcb3c74cdf8cb9a9619a",
"sha256": "65bf42e02e1db6130d79f3925c6ef96926a6ee49a5c71a5d9434e54cef21acab"
},
"downloads": -1,
"filename": "polars_candle-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "1a32a78d4b7afcb3c74cdf8cb9a9619a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 42988,
"upload_time": "2024-04-26T15:50:51",
"upload_time_iso_8601": "2024-04-26T15:50:51.133048Z",
"url": "https://files.pythonhosted.org/packages/dd/31/1670ae4e5ba0b2b528a84ef1f7fe6e9fc8381f43f8df41e05d3636e7b042/polars_candle-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-26 15:50:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wdoppenberg",
"github_project": "polars-candle",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "polars-candle"
}
JSON
