bandit_machines 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,157 @@
1
+ module BanditMachines
2
+ VERSION: String
3
+
4
+ type tie_break = :lowest_index | :highest_index | :least_tried | :draw
5
+ type reason = :cold_start | :explore | :exploit | :upper_bound
6
+ # Every symbol that means "this call was not honoured and changed nothing":
7
+ # one per variant of the core's `Refusal`. Each method below lists exactly
8
+ # the ones it can answer.
9
+ type refusal = :unknown_arm | :no_open_arm | :tickets_full | :exhausted | :stale_ticket | :unknown_ticket
10
+ | :reward_out_of_range | :saturated
11
+
12
+ # `0 < max_reward`, `prior <= max_reward`, both in 0..2**32-1; anything else
13
+ # raises TypeError or RangeError, and so does an unknown tie_break
14
+ # (TypeError for a non-Symbol, RangeError for an unknown Symbol).
15
+ class Config < Data
16
+ attr_reader max_reward: Integer
17
+ attr_reader prior: Integer
18
+ attr_reader tie_break: tie_break
19
+ def self.new: (Integer max_reward, Integer prior, tie_break tie_break) -> Config
20
+ | (max_reward: Integer, prior: Integer, tie_break: tie_break) -> Config
21
+ # Native: re-checks every field through the core constructor; raises
22
+ # TypeError or RangeError, nil when valid.
23
+ private def __validate: () -> nil
24
+ end
25
+
26
+ # `numerator <= denominator`, `denominator > 0`, both in 0..2**32-1.
27
+ class Ratio < Data
28
+ ZERO: Ratio
29
+ ONE: Ratio
30
+ attr_reader numerator: Integer
31
+ attr_reader denominator: Integer
32
+ def self.new: (Integer numerator, Integer denominator) -> Ratio
33
+ | (numerator: Integer, denominator: Integer) -> Ratio
34
+ # Native: re-checks every field through the core constructor; raises
35
+ # TypeError or RangeError, nil when valid.
36
+ private def __validate: () -> nil
37
+ end
38
+
39
+ # Two uniform draws, each in 0..2**64-1.
40
+ class Draws < Data
41
+ attr_reader gate: Integer
42
+ attr_reader pick: Integer
43
+ def self.new: (Integer gate, Integer pick) -> Draws
44
+ | (gate: Integer, pick: Integer) -> Draws
45
+ # Native: re-checks every field through the core constructor; raises
46
+ # TypeError or RangeError, nil when valid.
47
+ private def __validate: () -> nil
48
+ end
49
+
50
+ # Mirrors the core's `Ticket`. Opaque; it cannot be built or copied by hand.
51
+ # Only the bandit that issued it honours it.
52
+ class Ticket
53
+ def arm: () -> Integer
54
+ def generation: () -> Integer
55
+ # The scoped id: the issuing bandit's scope in the top 16 bits, the
56
+ # position in its selection order (from one) in the low 48.
57
+ def serial: () -> Integer
58
+ # The scope of the bandit that issued it, 0..65535.
59
+ def scope: () -> Integer
60
+ end
61
+
62
+ # `ticket` a Ticket and `reason` a Symbol (TypeError otherwise); an unknown
63
+ # reason Symbol raises RangeError.
64
+ class Selection < Data
65
+ attr_reader ticket: Ticket
66
+ attr_reader reason: reason
67
+ def self.new: (Ticket ticket, reason reason) -> Selection
68
+ | (ticket: Ticket, reason: reason) -> Selection
69
+ def arm: () -> Integer
70
+ # Native: re-checks every field through the core constructor; raises
71
+ # TypeError or RangeError, nil when valid.
72
+ private def __validate: () -> nil
73
+ end
74
+
75
+ # `open` true or false (TypeError otherwise), every count an Integer
76
+ # (TypeError otherwise) in 0..2**64-1 (RangeError otherwise).
77
+ class ArmStats < Data
78
+ attr_reader open: bool
79
+ attr_reader generation: Integer
80
+ attr_reader rewarded: Integer
81
+ attr_reader reward_sum: Integer
82
+ attr_reader pending: Integer
83
+ def self.new: (bool open, Integer generation, Integer rewarded, Integer reward_sum, Integer pending) -> ArmStats
84
+ | (open: bool, generation: Integer, rewarded: Integer, reward_sum: Integer, pending: Integer) -> ArmStats
85
+ def tries: () -> Integer
86
+ # Native: re-checks every field through the core constructor; raises
87
+ # TypeError or RangeError, nil when valid.
88
+ private def __validate: () -> nil
89
+ end
90
+
91
+ # The core's `math` module: unsigned Q8.56 fixed point, integers in and out.
92
+ module Math
93
+ FRACTION_BITS: Integer
94
+ ONE: Integer
95
+ def self.log2_q56: (Integer value) -> Integer
96
+ def self.ln_q56: (Integer value) -> Integer
97
+ def self.bonus_q56: (Integer total, Integer tries) -> Integer
98
+ def self.mean_q56: (Integer sum, Integer count, Integer range) -> Integer
99
+ end
100
+
101
+ # An arm index is any Integer in 0..2**64-1. One that names no arm
102
+ # (Bandit::ARMS or above) is answered, not raised: :unknown_arm from the
103
+ # mutating methods, nil from `stats` and `ucb1_index_q56`.
104
+ class Bandit
105
+ # The core's `Bandit::ARMS`: compiled number of arms.
106
+ ARMS: Integer
107
+ # The core's `Bandit::TICKETS`: compiled number of outstanding tickets.
108
+ TICKETS: Integer
109
+ # Scope zero.
110
+ def self.new: (Config config) -> Bandit
111
+ # `scope` is an Integer in 0..65535: TypeError otherwise, RangeError
112
+ # outside the range.
113
+ def self.with_scope: (Config config, Integer scope) -> Bandit
114
+ # Continues `scope` after a restart from a saved `issued` count. Restores
115
+ # only the serial sequence: every arm is closed and nothing is outstanding.
116
+ # RangeError when `issued` is above 2**48 - 1.
117
+ def self.resumed: (Config config, Integer scope, Integer issued) -> Bandit
118
+ def config: () -> Config
119
+ # The scope carried by every Ticket this bandit issues.
120
+ def scope: () -> Integer
121
+ # Serials issued in this scope so far: the count to save for `resumed`.
122
+ def issued: () -> Integer
123
+ def outstanding: () -> Integer
124
+ # nil once every serial of the scope has been issued.
125
+ def next_serial: () -> Integer?
126
+ def stats: (Integer arm) -> ArmStats?
127
+ # Honoured: :opened, or the repeat :already_open. Refused: :unknown_arm.
128
+ def open: (Integer arm) -> (:opened | :already_open | :unknown_arm)
129
+ # Honoured: :closed, or the repeat :already_closed. Refused: :unknown_arm.
130
+ def close: (Integer arm) -> (:closed | :already_closed | :unknown_arm)
131
+ # Honoured: a Selection. Refused: :no_open_arm, :tickets_full, :exhausted.
132
+ def select_ucb1: (Integer pick) -> (Selection | :no_open_arm | :tickets_full | :exhausted)
133
+ def select_epsilon_greedy: (Ratio epsilon, Draws draws) -> (Selection | :no_open_arm | :tickets_full | :exhausted)
134
+ # nil for an unknown, closed or cold arm.
135
+ def ucb1_index_q56: (Integer arm) -> Integer?
136
+ # Honoured: :rewarded. Refused: :stale_ticket, :unknown_ticket (a Ticket
137
+ # from a bandit in another scope included), :reward_out_of_range,
138
+ # :saturated.
139
+ def reward: (Ticket ticket, Integer reward) -> (:rewarded | :stale_ticket | :unknown_ticket | :reward_out_of_range | :saturated)
140
+ # Honoured: :abandoned. Refused: :stale_ticket, :unknown_ticket.
141
+ def abandon: (Ticket ticket) -> (:abandoned | :stale_ticket | :unknown_ticket)
142
+ # Honoured: the number of tickets revoked. Refused: :unknown_ticket, for a
143
+ # serial of another scope.
144
+ def revoke_before: (Integer serial) -> (Integer | :unknown_ticket)
145
+ # The number of tickets revoked: every outstanding one. Never refuses;
146
+ # arm statistics and generations are kept.
147
+ def revoke_all: () -> Integer
148
+ # Honoured: the number of tickets voided. Refused: :unknown_arm, :exhausted.
149
+ def reset: (Integer arm) -> (Integer | :unknown_arm | :exhausted)
150
+ # Honoured: the number of tickets voided. Refused: :exhausted.
151
+ def reset_all: () -> (Integer | :exhausted)
152
+ # Honoured: :decayed. Refused: :unknown_arm.
153
+ def decay: (Integer arm, Ratio keep) -> (:decayed | :unknown_arm)
154
+ # Always honoured.
155
+ def decay_all: (Ratio keep) -> :decayed
156
+ end
157
+ end
metadata ADDED
@@ -0,0 +1,87 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: bandit_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.7.2
5
+ platform: ruby
6
+ authors:
7
+ - Abdelkader Boudih
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: rb_sys
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '0.9'
19
+ - - ">="
20
+ - !ruby/object:Gem::Version
21
+ version: 0.9.130
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - "~>"
27
+ - !ruby/object:Gem::Version
28
+ version: '0.9'
29
+ - - ">="
30
+ - !ruby/object:Gem::Version
31
+ version: 0.9.130
32
+ description: UCB1 and epsilon-greedy arm selection with ticketed rewards; not an experiment
33
+ platform.
34
+ email:
35
+ - oss@seuros.com
36
+ executables: []
37
+ extensions:
38
+ - ext/bandit_machines_native/extconf.rb
39
+ extra_rdoc_files: []
40
+ files:
41
+ - CHANGELOG.md
42
+ - Cargo.lock
43
+ - Cargo.toml
44
+ - LICENSE.txt
45
+ - README.md
46
+ - ext/bandit_machines_native/core/CHANGELOG.md
47
+ - ext/bandit_machines_native/core/Cargo.toml
48
+ - ext/bandit_machines_native/core/README.md
49
+ - ext/bandit_machines_native/core/src/bandit.rs
50
+ - ext/bandit_machines_native/core/src/lib.rs
51
+ - ext/bandit_machines_native/core/src/math.rs
52
+ - ext/bandit_machines_native/core/src/pick.rs
53
+ - ext/bandit_machines_native/extconf.rb
54
+ - ext/bandit_machines_native/ffi/Cargo.toml
55
+ - ext/bandit_machines_native/ffi/extconf.rb
56
+ - ext/bandit_machines_native/ffi/src/convert.rs
57
+ - ext/bandit_machines_native/ffi/src/init.rs
58
+ - ext/bandit_machines_native/ffi/src/lib.rs
59
+ - lib/bandit_machines.rb
60
+ - lib/bandit_machines/version.rb
61
+ - sig/bandit_machines.rbs
62
+ homepage: https://github.com/seuros/bandit_machines
63
+ licenses:
64
+ - MIT
65
+ metadata:
66
+ source_code_uri: https://github.com/seuros/bandit_machines
67
+ rubygems_mfa_required: 'true'
68
+ cargo_crate_name: bandit_machines_native
69
+ cargo_manifest_path: ext/bandit_machines_native/ffi/Cargo.toml
70
+ rdoc_options: []
71
+ require_paths:
72
+ - lib
73
+ required_ruby_version: !ruby/object:Gem::Requirement
74
+ requirements:
75
+ - - ">="
76
+ - !ruby/object:Gem::Version
77
+ version: 4.0.0
78
+ required_rubygems_version: !ruby/object:Gem::Requirement
79
+ requirements:
80
+ - - ">="
81
+ - !ruby/object:Gem::Version
82
+ version: '0'
83
+ requirements: []
84
+ rubygems_version: 4.0.20
85
+ specification_version: 4
86
+ summary: Bounded multi-armed bandit policies with a native Rust core
87
+ test_files: []