|
1
|
--- |
|
2
|
name: sdk-ruby-gem |
|
3
|
description: Build and publish the onde-inference Ruby gem (Magnus-based native extension). Use when working on the Ruby SDK under sdk/gem/, adding Ruby-exposed functions, or publishing to RubyGems. |
|
4
|
allowed-tools: Read, Write, Edit, Glob, Grep, Bash |
|
5
|
user-invocable: true |
|
6
|
--- |
|
7
|
|
|
8
|
# Skill: Ruby Gem SDK (`sdk/gem/`) |
|
9
|
|
|
10
|
## What This Is |
|
11
|
|
|
12
|
A Magnus-based Ruby native extension that exposes Onde's HuggingFace cache management and model metadata to Ruby. The gem is named `onde-inference` on RubyGems. It does **not** expose the `ChatEngine` / `OndeChatEngine` — it is a cache + model metadata utility layer. |
|
13
|
|
|
14
|
## Source Layout |
|
15
|
|
|
16
|
``` |
|
17
|
sdk/gem/ |
|
18
|
├── Cargo.toml # Rust extension crate (magnus + onde dep) |
|
19
|
├── Gemfile |
|
20
|
├── Rakefile # `rake compile` → builds the .so via rb-sys-dock |
|
21
|
├── onde-inference.gemspec |
|
22
|
├── bin/ |
|
23
|
│ ├── console # irb + require 'onde' |
|
24
|
│ └── setup # bundle install + rake compile |
|
25
|
├── ext/onde/ # Rust extension source |
|
26
|
│ ├── Cargo.toml |
|
27
|
│ └── src/ |
|
28
|
│ └── lib.rs # #[magnus::init] entry point |
|
29
|
└── lib/ |
|
30
|
└── onde/ |
|
31
|
└── version.rb |
|
32
|
``` |
|
33
|
|
|
34
|
## Build Commands |
|
35
|
|
|
36
|
```bash |
|
37
|
cd sdk/gem |
|
38
|
|
|
39
|
# First-time setup |
|
40
|
bin/setup # bundle install + rake compile |
|
41
|
|
|
42
|
# Recompile after Rust changes |
|
43
|
bundle exec rake compile |
|
44
|
|
|
45
|
# Interactive console |
|
46
|
bin/console |
|
47
|
|
|
48
|
# Verify |
|
49
|
bundle exec ruby -e "require 'onde'; puts Onde::VERSION; puts Onde::SUPPORTED_MODELS" |
|
50
|
``` |
|
51
|
|
|
52
|
## Key Facts |
|
53
|
|
|
54
|
- **Magnus** is the Rust↔Ruby binding layer (`magnus` crate). All Ruby-visible types are wrapped with `#[magnus::init]` and `wrap_class!` / `rb_class!` macros. |
|
55
|
- The gem depends on `onde` as a relative path in `sdk/gem/ext/onde/Cargo.toml` — never use a published git ref here during development. |
|
56
|
- **`rb-sys`** drives `rake compile` — it invokes `cargo build` with the correct Ruby extension flags. |
|
57
|
- The gem is published as `onde-inference` on RubyGems (`gem push onde-inference-*.gem`). |
|
58
|
- `Onde::SUPPORTED_MODELS` is a Ruby Array of model ID strings matching `onde::inference::models::SUPPORTED_MODELS`. |
|
59
|
- Cache functions (`list_local_models`, `list_supported_models`, `delete_model`, `diagnose_cache`, `repair_symlinks`) are exposed as module-level methods under the `Onde` namespace. |
|
60
|
|
|
61
|
## Pitfalls |
|
62
|
|
|
63
|
- `rake compile` must be re-run after any change to Rust source under `ext/onde/src/` — the gem does not hot-reload. |
|
64
|
- On macOS, `LIBRARY_PATH` and `DYLD_LIBRARY_PATH` must include the Ruby lib path if linking fails at test time. |
|
65
|
- Magnus `Value` / `RArray` / `RHash` types are **not** `Send` — do not store them across Ruby GC boundaries. |
|
66
|
- `bundle exec` is required for all rake/ruby invocations so the correct gem/ruby version is used. |
|
67
|
- `onde-inference` (hyphen) on RubyGems; `require 'onde'` (no hyphen, no suffix) in Ruby code. |