{"id":50841021,"url":"https://github.com/tetherto/qvac-bare-addon-example","last_synced_at":"2026-06-14T06:35:11.940Z","repository":{"id":358051959,"uuid":"1239666644","full_name":"tetherto/qvac-bare-addon-example","owner":"tetherto","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-15T12:24:05.000Z","size":247,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T14:11:12.053Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tetherto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T10:14:02.000Z","updated_at":"2026-05-15T12:24:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tetherto/qvac-bare-addon-example","commit_stats":null,"previous_names":["tetherto/qvac-bare-addon-example"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tetherto/qvac-bare-addon-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fqvac-bare-addon-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fqvac-bare-addon-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fqvac-bare-addon-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fqvac-bare-addon-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tetherto","download_url":"https://codeload.github.com/tetherto/qvac-bare-addon-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fqvac-bare-addon-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34312072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-14T06:35:11.333Z","updated_at":"2026-06-14T06:35:11.922Z","avatar_url":"https://github.com/tetherto.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Building an AI Add-on for Bare\n\nThis repository is a compact example of building a native AI add-on for the Bare JavaScript runtime. It pairs a JavaScript-facing API with a C++ logistic regression model, showing how to keep application code ergonomic while moving inference work into a native module.\n\nBare is designed for small, embeddable JavaScript runtimes with first-class native addon support. That makes it a good fit for AI modules running on mobile devices, edge nodes, or other environments where runtime size and local execution matter.\n\n## What This Example Shows\n\nThe add-on exposes a small classifier API from C++ to JavaScript. The native side owns model construction, non-blocking inference, training, runtime stats, and cleanup. The JavaScript wrapper turns those low-level bindings into a Promise-based interface that application code can consume naturally.\n\nThe example model is intentionally simple: a binary logistic regression classifier trained on synthetic age and income data. The same pattern can be used for larger engines, such as neural networks, transformers, or production QVAC inference backends.\n\n## Architecture\n\nA Bare add-on is a shared library loaded by the runtime. The C++ side exports functions through Bare's `libjs` C API, while JavaScript calls those functions through the native binding.\n\nThe core lifecycle is:\n\n- `createInstance` allocates the model and connects the output callback pipeline.\n- `runJob` submits input for non-blocking inference.\n- `destroyInstance` frees native resources.\n- `train` is specific to this example and produces logistic regression weights.\n\nThe add-on uses `qvac-lib-inference-addon-cpp` to avoid most of the repetitive native-addon plumbing. That library handles instance tracking, JavaScript argument parsing, type conversion, output callbacks, thread management, runtime stats, and exception propagation across the C++/JavaScript boundary. Bridge functions use `JSCATCH` to convert C++ exceptions into JavaScript errors through Bare's `libjs` API, so validation or inference failures surface as normal JavaScript errors instead of crashing the process.\n\n## Non-Blocking Inference\n\nInference runs on a background thread. `runJob` returns immediately with whether the job was accepted, and the result is delivered back to JavaScript through the output callback queue. This keeps the JavaScript thread responsive even when native work is expensive.\n\nThe callback can emit multiple events for a single job. In this classifier, one event carries the prediction and another carries runtime stats to signal completion. The same event-based design also works for streaming models, where outputs may arrive incrementally.\n\n## JavaScript Wrapper\n\nThe JavaScript wrapper exposes a `ClassifierInterface` class. It accepts trained parameters, creates a native instance, and provides a Promise-based `predict` method. Calls are serialized with `exclusiveRunQueue` so only one prediction is in flight per classifier instance, avoiding races around shared callback state.\n\nTraining is exposed as a static method that forwards data to the native implementation and returns learned parameters suitable for a new classifier instance.\n\n## Build And Run\n\nThe project uses CMake through `cmake-bare`, with vcpkg integration handled by `cmake-vcpkg`. Native dependencies are declared in `vcpkg.json`; the key dependency is `qvac-lib-inference-addon-cpp`.\n\nTo run the example, install dependencies, build the native add-on, generate the synthetic dataset, and run the Bare example script. The example trains on 50,000 synthetic samples and predicts purchase likelihood for several sample users.\n\n```sh\nnpm install\nnpm run build\nbare generate_synthetic_dataset.js\nnpm run example\n```\n\nThe repository also includes a pure JavaScript baseline implementation. It is useful for comparing the native C++ path with a self-contained JavaScript version of the same logistic regression algorithm. On the referenced Linux benchmark, the Bare/native version ran about 2.18 times faster than the Node.js pure JavaScript version, though exact results depend on hardware, dataset size, compiler settings, and runtime versions.\n\n## Mobile And Production Notes\n\n`bare-make` supports cross-compilation for Android and iOS. Built artifacts are placed under platform-specific `prebuilds` directories and loaded automatically by `require.addon()` at runtime.\n\nFor production add-ons, the same structure can support multiple native libraries, such as GPU backends plus a CPU fallback.\n\n## Source\n\nThe broader QVAC ecosystem is available at https://github.com/tetherto/qvac.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fqvac-bare-addon-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftetherto%2Fqvac-bare-addon-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fqvac-bare-addon-example/lists"}