usearch 0.2.4 → 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

@@ -86,9 +86,9 @@ 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
@@ -143,7 +143,7 @@ jobs:
         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
@@ -171,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/.vscode/settings.json

@@ -98,11 +98,13 @@
         "filesystem": "cpp",
         "__availability": "cpp",
         "version": "cpp",
-        "future": "cpp"
+        "future": "cpp",
+        "__verbose_abort": "cpp"
     },
     "cSpell.words": [
         "astype",
         "BLAS",
+        "cflags",
         "downcasted",
         "Downcasting",
         "dtype",
@@ -113,6 +115,7 @@
         "jaccard",
         "longlong",
         "memmap",
+        "Napi",
         "ndim",
         "Numba",
         "preprocess",

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.4"
+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"

package/README.md

@@ -82,7 +82,7 @@ USearch is designed to be compact and broadly compatible without sacrificing per
 > Jump to the [Performance Tuning][benchmarking] section to read about the effects of those hyper-parameters.
 
 [sloc]: https://en.wikipedia.org/wiki/Source_lines_of_code
-[benchmarking]: https://github.com/unum-cloud/usearch
+[benchmarking]: https://github.com/unum-cloud/usearch/blob/main/docs/benchmarks.md
 
 ## User-Defined Functions
 
@@ -92,7 +92,7 @@ A good example would be the rare [Haversine][haversine] distance, used to comput
 Another example would be designing a custom metric for **composite embeddings** concatenated from multiple AI models in real-world applications. 
 USearch supports that: [Python](#user-defined-functions-in-python) and [C++](#user-defined-functions-in-c) examples.
 
-![USearch: Vector Search Approaches](assets/usearch-approaches-white.png)
+![USearch: Vector Search Approaches](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-approaches-white.png?raw=true)
 
 Unlike older approaches indexing high-dimensional spaces, like KD-Trees and Locality Sensitive Hashing, HNSW doesn't require vectors to be identical in length.
 They only have to be comparable.
@@ -106,7 +106,7 @@ So you can apply it in [obscure][obscure] applications, like searching for simil
 Training a quantization model and dimension-reduction is a common approach to accelerate vector search.
 Those, however, are only sometimes reliable, can significantly affect the statistical properties of your data, and require regular adjustments if your distribution shifts.
 
-![USearch uint40_t support](assets/usearch-neighbor-types.png)
+![USearch uint40_t support](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-neighbor-types.png?raw=true)
 
 Instead, we have focused on high-precision arithmetic over low-precision downcasted vectors.
 The same index, and `add` and `search` operations will automatically down-cast or up-cast between `f32_t`, `f16_t`, `f64_t`, and `f8_t` representations, even if the hardware doesn't natively support it.
@@ -205,7 +205,7 @@ The following distances are pre-packaged:
 - `pearson_correlation_gt<scalar_t>` for "Pearson" correlation between probability distributions.
 - `haversine_gt<scalar_t>` for "Haversine" or "Great Circle" distance between coordinates.
 
-#### Bring your Threads
+#### Multi-Threading
 
 Most AI, HPC, or Big Data packages use some form of a thread pool.
 Instead of spawning additional threads within USearch, we focus on the thread safety of `add()` function, simplifying resource management.
@@ -213,7 +213,7 @@ Instead of spawning additional threads within USearch, we focus on the thread sa
 ```cpp
 #pragma omp parallel for
     for (std::size_t i = 0; i < n; ++i)
-        native.add(label, span_t{vector, dims}, omp_get_thread_num());
+        native.add(label, span_t{vector, dims}, add_config_t { .thread = omp_get_thread_num() });
 ```
 
 During initialization, we allocate enough temporary memory for all the cores on the machine.
@@ -383,6 +383,14 @@ let results = index.search(&first, 10).unwrap();
 assert_eq!(results.count, 2);
 ```
 
+#### Multi-Threading
+
+```rust
+assert!(index.add_in_thread(42, &first, 0).is_ok());
+assert!(index.add_in_thread(43, &second, 0).is_ok());
+let results = index.search_in_thread(&first, 10, 0).unwrap();
+```
+
 Being a systems-programming language, Rust has better control over memory management and concurrency but lacks function overloading.
 Aside from the `add` and `search`, USearch Rust binding also provides `add_in_thread` and `search_in_thread`, which let users identify the calling thread to use underlying temporary memory more efficiently.
 

package/VERSION

@@ -1 +1 @@
-0.2.4
+0.4.0

package/binding.gyp

@@ -15,15 +15,19 @@
             "dependencies": [
                 "<!(node -p \"require('node-addon-api').gyp\")"
             ],
-            "cflags!": ["-fno-exceptions", "-Wunknown-pragmas"],
-            "cflags_cc!": ["-fno-exceptions", "-Wunknown-pragmas"],
-            "conditions": [
-                ["OS==\"mac\"", {
-                    "xcode_settings": {
-                        "GCC_ENABLE_CPP_EXCEPTIONS": "YES"
-                    }
-                }]
-            ]
+            "cflags": ["-fexceptions", "-Wunknown-pragmas", "-std=c99"],
+            "cflags_cc": ["-fexceptions", "-Wunknown-pragmas", "-std=c++11"],
+            "xcode_settings": {
+                "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+                "CLANG_CXX_LIBRARY": "libc++",
+                "MACOSX_DEPLOYMENT_TARGET": "10.15"
+            },
+            "msvs_settings": {
+                "VCCLCompilerTool": { 
+                    "ExceptionHandling": 1, 
+                    "AdditionalOptions": [ "-std:c++11" ]
+                }
+            }
         }
     ]
 }

package/build.rs

@@ -2,6 +2,7 @@ fn main() {
     cxx_build::bridge("rust/lib.rs")
         .file("rust/lib.cpp")
         .flag_if_supported("-std=c++11")
+        .flag_if_supported("-Wunknown-pragmas")
         .include("include")
         .include("rust")
         .include("src")

package/conanfile.py

@@ -4,7 +4,7 @@ from conans import ConanFile
 class USearchConan(ConanFile):
 
     name = 'USearch'
-    version = '0.2.4'
+    version = '0.4.0'
     license = 'Apache 2.0'
     url = 'https://github.com/unum-cloud/usearch'
     description = 'Smaller & Faster Single-File Vector Search Engine from Unum'

package/docs/benchmarks.rst

@@ -0,0 +1,5 @@
+========================
+Benchmarks
+========================
+
+.. mdinclude:: benchmarks.md

package/docs/compilation.rst

@@ -0,0 +1,5 @@
+========================
+Compilation
+========================
+
+.. mdinclude:: compilation.md