usearch 0.2.3 → 0.4.0

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,90 @@
+name: Report a bug
+description: Something doesn't work as expected?
+title: "Bug: "
+labels: ["bug", "invalid"]
+assignees:
+  - octocat
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+        If you have a small question, it may be faster to ask the maintainers on [Discord](https://discord.gg/4mxGrenbNt).
+  - type: textarea
+    id: what
+    attributes:
+      label: Describe the bug
+      placeholder: A short description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: Detail the steps taken to reproduce the behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      placeholder: A clear and concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: USearch version
+      placeholder: v0.4.X
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: Ubuntu 22.04
+    validations:
+      required: true
+  - type: dropdown
+    id: hardware
+    attributes:
+      label: Hardware architecture
+      options:
+        - x86
+        - Arm
+    validations:
+      required: true
+  - type: dropdown
+    id: frontend
+    attributes:
+      label: Which interface are you using?
+      options:
+        - C++ implementation
+        - Python bindings
+        - Other bindings
+    validations:
+      required: true
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we get in touch with you if we need more info?
+      placeholder: email@example.com
+    validations:
+      required: false
+  - type: checkboxes
+    id: duplicate
+    attributes:
+      label: Is there an existing issue for this?
+      description: Please search [our issues](https://github.com/unum-cloud/usearch/issues) to see if this bug already exists.
+      options:
+        - label: I have searched the existing issues
+          required: true
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/unum-cloud/usearch/blob/main/CODE_OF_CONDUCT.md)
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Ask on Discord
+    url: https://discord.gg/A6wxt6dS9j
+    about: Real-time communication with maintainers, contributors, and broader community

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,64 @@
+name: Request a feature
+description: Something we haven't implemented yet?
+title: "Feature: "
+labels: ["enhancement"]
+assignees:
+  - octocat
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this feature request!
+        We have already scheduled a few features for our [next milestone](https://github.com/unum-cloud/usearch/milestones).
+        Still, if it is something we have yet to think about, we will happily extend our [roadmap](https://github.com/orgs/unum-cloud/projects/2).
+        It is also worth noting that choosing between speed and functionality, we generally prefer the former.
+        So in some cases, it makes more sense to build something on top of USearch rather than patch it 🤗
+  - type: textarea
+    id: what
+    attributes:
+      label: Describe what you are looking for
+      placeholder: A short description of what the feature would look like, ideally with code examples.
+    validations:
+      required: true
+  - type: checkboxes
+    id: check
+    attributes:
+      label: Can you contribute to the implementation?
+      options:
+        - label: I can contribute
+  - type: dropdown
+    id: interface
+    attributes:
+      label: Is your feature request specific to a certain interface?
+      options:
+        - It applies to everything
+        - C++ implementation
+        - Python bindings
+        - Other bindings
+        - Other
+    validations:
+      required: true
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we get in touch with you if we need more info?
+      placeholder: email@example.com
+    validations:
+      required: false
+  - type: checkboxes
+    id: duplicate
+    attributes:
+      label: Is there an existing issue for this?
+      description: Please search [our issues](https://github.com/unum-cloud/usearch/issues) to see if this bug already exists.
+      options:
+        - label: I have searched the existing issues
+          required: true
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/unum-cloud/usearch/blob/main/CODE_OF_CONDUCT.md)
+      options:
+        - label: I agree to follow this project's Code of Conduct
+          required: true

package/.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 env:
   BUILD_TYPE: Release
   GH_TOKEN: ${{ secrets.SEMANTIC_RELEASE_TOKEN }}
+  PYTHONUTF8: 1
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -16,40 +17,51 @@ permissions:
 
 jobs:
 
-#   versioning:
-#     name: Semantic Release
-#     runs-on: ubuntu-latest
-#     steps:
-#     - uses: actions/checkout@v3
-#       with:
-#         persist-credentials: false
-#     - uses: actions/setup-node@v3
-#     - run: cp .github/workflows/package.json . && npm install && npx semantic-release
+  versioning:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        persist-credentials: false
+    - uses: actions/setup-node@v3
+    - run: npm install --save-dev @semantic-release/exec @semantic-release/git conventional-changelog-eslint semantic-release && npx semantic-release
 
   build_wheels:
     name: Build Wheels for ${{ matrix.os }}
+    needs: versioning
     runs-on: ${{ matrix.os }}
-#     needs: versioning
     strategy:
       matrix:
-        os: [ubuntu-20.04, macOS-11]
+        os: [ubuntu-20.04, macOS-11, windows-2022]
 
     steps:
       - uses: actions/checkout@v3
         with:
           ref: 'main'      
       - uses: actions/setup-python@v3
-      - uses: crazy-max/ghaction-setup-docker@v1.0.0
+      
+      - name: Setup Docker
+        if: matrix.os != 'windows-2022'
+        uses: crazy-max/ghaction-setup-docker@v1.0.0
         with:
           version: 23.0.1
-      - uses: docker/setup-qemu-action@v2.1.0
+
+      - name: Setup QEMU
+        if: matrix.os != 'windows-2022'
+        uses: docker/setup-qemu-action@v2.1.0
 
       - name: Install CIBuildWheel
         run: python -m pip install cibuildwheel
 
-      - name: Build wheels
+      - name: Build wheels for Windows
+        if: matrix.os == 'windows-2022'
+        run: python -m cibuildwheel
+
+      - name: Build wheels for POSIX
+        if: matrix.os != 'windows-2022'
         run: python -m cibuildwheel
-        
+
       - uses: actions/upload-artifact@v3
         with:
           path: ./wheelhouse/*.whl
@@ -57,8 +69,8 @@ jobs:
   
   publish_python:
     name: Publish Python
-    runs-on: ubuntu-20.04
     needs: build_wheels
+    runs-on: ubuntu-20.04
     environment:
       name: pypi
       url: https://pypi.org/p/usearch
@@ -74,15 +86,18 @@ jobs:
       - name: Publish to PyPi
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          packages_dir: ./dist/artifact
+          packages-dir: ./dist/artifact
           verbose: true
-          print_hash: true
+          print-hash: true
 
   publish_javascript:
     name: Publish JavaScript
+    needs: versioning
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
+        with:
+          ref: 'main'  
       - run: git submodule update --init --recursive
       - uses: actions/setup-node@v3
         with:
@@ -96,9 +111,12 @@ jobs:
 
   publish_rust:
     name: Publish Rust
+    needs: versioning
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
+      with:
+        ref: 'main'  
     - run: git submodule update --init --recursive
     - uses: actions-rs/toolchain@v1
       with:
@@ -110,19 +128,22 @@ jobs:
 
   publish_java:
     name: Publish Java
+    needs: versioning
     runs-on: ubuntu-latest
     permissions:
       contents: read
       packages: write
     steps:
     - uses: actions/checkout@v3
+      with:
+        ref: 'main'  
     - run: git submodule update --init --recursive
     - uses: actions/setup-java@v3
       with:
         java-version: '11'
         distribution: 'adopt'
     - name: Setup Gradle
-      uses: gradle/gradle-build-action@v2    
+      uses: gradle/gradle-build-action@v2.4.2
     - name: Execute Gradle build
       run: gradle clean build
     - name: Publish package
@@ -132,9 +153,12 @@ jobs:
 
   publish_swift:
     name: Publish ObjC & Swift
+    needs: versioning
     runs-on: macos-latest
     steps:
     - uses: actions/checkout@v3
+      with:
+        ref: 'main'  
     - run: git submodule update --init --recursive
     - name: Build
       run: swift build
@@ -147,7 +171,8 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-22.04
-    needs: publish_python
+    if: ${{ always() }}
+    needs: [publish_python, publish_javascript, publish_rust, publish_java, publish_swift]
     steps:
       - name: Checkout
         uses: actions/checkout@v3

package/.github/workflows/update_version.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+echo $1 > VERSION && 
+    sed -i "s/\"version\": \".*\"/\"version\": \"$1\"/" package.json &&
+    sed -i "s/version = \".*\"/version = \"$1\"/" Cargo.toml &&
+    sed -i "s/version = '.*'/version = '$1'/" conanfile.py

package/.releaserc

@@ -0,0 +1,77 @@
+{
+    "branches": [
+        "main"
+    ],
+    "debug": true,
+    "ci": true,
+    "dryRun": false,
+    "plugins": [
+        [
+            "@semantic-release/commit-analyzer",
+            {
+                "preset": "eslint",
+                "releaseRules": [
+                    {
+                        "tag": "Add",
+                        "release": "minor"
+                    },
+                    {
+                        "tag": "Improve",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Make",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Refactor",
+                        "release": false
+                    }
+                ]
+            }
+        ],
+        [
+            "@semantic-release/release-notes-generator",
+            {
+                "preset": "eslint",
+                "releaseRules": [
+                    {
+                        "tag": "Add",
+                        "release": "minor"
+                    },
+                    {
+                        "tag": "Improve",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Make",
+                        "release": "patch"
+                    },
+                    {
+                        "tag": "Refactor",
+                        "release": false
+                    }
+                ]
+            }
+        ],
+        "@semantic-release/github",
+        [
+            "@semantic-release/exec",
+            {
+                "prepareCmd": "bash .github/workflows/update_version.sh '${nextRelease.version}'"
+            }
+        ],
+        [
+            "@semantic-release/git",
+            {
+                "assets": [
+                    "VERSION",
+                    "conanfile.py",
+                    "package.json",
+                    "Cargo.toml",
+                ],
+                "message": "Build: Released ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+            }
+        ]
+    ]
+}

package/.vscode/settings.json

@@ -98,20 +98,32 @@
         "filesystem": "cpp",
         "__availability": "cpp",
         "version": "cpp",
-        "future": "cpp"
+        "future": "cpp",
+        "__verbose_abort": "cpp"
     },
     "cSpell.words": [
         "astype",
+        "BLAS",
+        "cflags",
+        "downcasted",
+        "Downcasting",
         "dtype",
         "equidimensional",
+        "FAISS",
         "hashable",
+        "HNSW",
         "jaccard",
         "longlong",
         "memmap",
+        "Napi",
         "ndim",
+        "Numba",
         "preprocess",
+        "Quickstart",
         "simsimd",
-        "usearch"
+        "SLOC",
+        "usearch",
+        "usecases"
     ],
     "java.configuration.updateBuildConfiguration": "interactive"
 }

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+info@unum.cloud.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contribution Guide
+
+Thank you for even opening this page!
+It's always nice to have third-party contributors!
+
+---
+
+To keep the quality of the code high, we have a set of guidelines common to all Unum projects.
+
+- Whats the procedure? [answered](https://github.com/unum-cloud/awesome/blob/main/Workflow.md#organizing-software-development)
+- How to organize branches? [answered](https://github.com/unum-cloud/awesome/blob/main/Workflow.md#branches)
+- How to style commits? [answered](https://github.com/unum-cloud/awesome/blob/main/Workflow.md#commits)

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "0.2.3"
+version = "0.4.0"
 authors = ["Ashot Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"