gittins 1.0.3__tar.gz

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.
Files changed (32) hide show
  1. gittins-1.0.3/LICENSE +21 -0
  2. gittins-1.0.3/PKG-INFO +119 -0
  3. gittins-1.0.3/README.md +93 -0
  4. gittins-1.0.3/bindings/python/Cargo.lock +178 -0
  5. gittins-1.0.3/bindings/python/Cargo.toml +23 -0
  6. gittins-1.0.3/bindings/python/LICENSE +21 -0
  7. gittins-1.0.3/bindings/python/README.md +93 -0
  8. gittins-1.0.3/bindings/python/bench.py +321 -0
  9. gittins-1.0.3/bindings/python/src/lib.rs +389 -0
  10. gittins-1.0.3/bindings/python/tests/test_binding.py +367 -0
  11. gittins-1.0.3/core/Cargo.lock +7 -0
  12. gittins-1.0.3/core/Cargo.toml +16 -0
  13. gittins-1.0.3/core/src/api.rs +294 -0
  14. gittins-1.0.3/core/src/bin/bench.rs +106 -0
  15. gittins-1.0.3/core/src/bin/sim/environments.rs +513 -0
  16. gittins-1.0.3/core/src/bin/sim/main.rs +119 -0
  17. gittins-1.0.3/core/src/bin/sim/metrics.rs +105 -0
  18. gittins-1.0.3/core/src/bin/sim/policies.rs +225 -0
  19. gittins-1.0.3/core/src/bin/sim/rand.rs +46 -0
  20. gittins-1.0.3/core/src/bin/sim/runner.rs +49 -0
  21. gittins-1.0.3/core/src/decide.rs +286 -0
  22. gittins-1.0.3/core/src/encoding.rs +144 -0
  23. gittins-1.0.3/core/src/error.rs +34 -0
  24. gittins-1.0.3/core/src/exploration.rs +53 -0
  25. gittins-1.0.3/core/src/ledger.rs +139 -0
  26. gittins-1.0.3/core/src/lib.rs +23 -0
  27. gittins-1.0.3/core/src/model.rs +177 -0
  28. gittins-1.0.3/core/src/rng.rs +67 -0
  29. gittins-1.0.3/core/src/state.rs +325 -0
  30. gittins-1.0.3/core/tests/golden/json.rs +242 -0
  31. gittins-1.0.3/core/tests/golden/main.rs +540 -0
  32. gittins-1.0.3/pyproject.toml +45 -0
gittins-1.0.3/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Max Pagels
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
gittins-1.0.3/PKG-INFO ADDED
@@ -0,0 +1,119 @@
1
+ Metadata-Version: 2.4
2
+ Name: gittins
3
+ Version: 1.0.3
4
+ Classifier: Development Status :: 5 - Production/Stable
5
+ Classifier: Intended Audience :: Science/Research
6
+ Classifier: Intended Audience :: Developers
7
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Rust
14
+ License-File: LICENSE
15
+ Summary: An opinionated, highly optimised contextual bandit engine
16
+ Keywords: contextual bandit,multi-armed bandit,reinforcement learning,online learning,exploration,recommendation
17
+ Home-Page: https://docs.getgittins.dev
18
+ Author: Max Pagels
19
+ License-Expression: MIT
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
22
+ Project-URL: Documentation, https://docs.getgittins.dev
23
+ Project-URL: Homepage, https://docs.getgittins.dev
24
+ Project-URL: Repository, https://github.com/maxpagels/gittins
25
+
26
+ # gittins
27
+
28
+ An opinionated, highly optimised contextual bandit engine.
29
+
30
+ - **Online by nature.** Learns one observation at a time, in O(1) work and
31
+ fixed memory, as long as open decisions are regularly resolved.
32
+ - **Non-stationarity is expected.** The engine adapts as the relationship
33
+ between context and feedback drifts, and never learns anything it cannot
34
+ eventually unlearn.
35
+ - **Dynamic actions and context.** The candidate set can change on every
36
+ call; you never declare the number of actions up front.
37
+ - **Safe reward handling.** Rewards may arrive late or never. Constructing
38
+ invalid training data is made hard by design.
39
+ - **Speed and determinism.** Bit-identical results across platforms and
40
+ language bindings, enforced by a golden test corpus.
41
+ - **Bring your own model.** Swap in your own scoring or exploration and
42
+ inherit everything else.
43
+
44
+ Full documentation and user guide: **[docs.getgittins.dev](https://docs.getgittins.dev)**
45
+
46
+ ## Install
47
+
48
+ ```sh
49
+ pip install gittins
50
+ ```
51
+
52
+ ## Usage
53
+
54
+ The state is an opaque handle updated **in place** — calls return only their
55
+ result, and every alias of the handle observes the current state. Persist it
56
+ with `serialize`, which returns one plain string.
57
+
58
+ ```python
59
+ import time
60
+ import gittins
61
+
62
+ state = gittins.create(bits=8, horizon=3600.0) # model size, seconds to resolve
63
+
64
+ candidates = [
65
+ ("banner-sale", {"discount": 0.2}),
66
+ ("banner-new", {"discount": 0.0}),
67
+ ("banner-plain", {}),
68
+ ]
69
+ context = {"device": "mobile", "hour": 14}
70
+
71
+ record = gittins.decide(state, context, candidates, time.time(), "web-1")
72
+ arm_id = candidates[record.chosen][0]
73
+ # ... your code: act on the choice, then report the outcome
74
+
75
+ gittins.learn(state, record.decision_id, 1.0, time.time())
76
+ gittins.expire(state, time.time()) # resolve anything past its horizon
77
+
78
+ open("bandit.txt", "w").write(gittins.serialize(state))
79
+ ```
80
+
81
+ Feature values are typed by what you pass: strings are categorical, ints,
82
+ floats and bools numeric, `None` absent. Anything else raises `ValueError`
83
+ naming the feature.
84
+
85
+ ### Bringing your own model
86
+
87
+ `decide` takes optional `score` and `explore` callbacks, and `learn`/`expire`
88
+ take `train`. Each crosses the Python/Rust boundary once per call — with all
89
+ candidates, all estimates, or the one resolved record — never once per
90
+ candidate, so the one boundary crossing per decision is preserved.
91
+
92
+ ### Offline policy evaluation
93
+
94
+ `log_line` renders a decision record or resolution as one canonical
95
+ experience-log line. Append it verbatim; it is exactly what the `gittins`
96
+ CLI's `verify` / `eval` / `sweep` / `replay` consume.
97
+
98
+ ```python
99
+ with open("decisions.jsonl", "a") as log:
100
+ log.write(gittins.log_line(record) + "\n")
101
+ ```
102
+
103
+ ## API
104
+
105
+ | Function | Purpose |
106
+ | --- | --- |
107
+ | `create(bits, horizon, default_reward=0.0, epsilon=..., forgetfulness=...)` | New state |
108
+ | `decide(state, context, candidates, t, salt, score=None, explore=None)` | Choose; returns a `DecisionRecord` |
109
+ | `learn(state, decision_id, reward, t, train=None)` | Resolve one decision; returns a `Resolution` or `None` |
110
+ | `expire(state, t, train=None)` | Resolve everything past its horizon |
111
+ | `serialize(state)` / `deserialize(text)` | State as one plain string |
112
+ | `model_bits(state)` | The model's size in bits |
113
+ | `log_line(record_or_resolution)` | One canonical experience-log line |
114
+
115
+ ## License
116
+
117
+ MIT. Named after John Gittins, whose index (1974) established that
118
+ exploration has a precise, computable value.
119
+
gittins-1.0.3/README.md ADDED
@@ -0,0 +1,93 @@
1
+ # gittins
2
+
3
+ An opinionated, highly optimised contextual bandit engine.
4
+
5
+ - **Online by nature.** Learns one observation at a time, in O(1) work and
6
+ fixed memory, as long as open decisions are regularly resolved.
7
+ - **Non-stationarity is expected.** The engine adapts as the relationship
8
+ between context and feedback drifts, and never learns anything it cannot
9
+ eventually unlearn.
10
+ - **Dynamic actions and context.** The candidate set can change on every
11
+ call; you never declare the number of actions up front.
12
+ - **Safe reward handling.** Rewards may arrive late or never. Constructing
13
+ invalid training data is made hard by design.
14
+ - **Speed and determinism.** Bit-identical results across platforms and
15
+ language bindings, enforced by a golden test corpus.
16
+ - **Bring your own model.** Swap in your own scoring or exploration and
17
+ inherit everything else.
18
+
19
+ Full documentation and user guide: **[docs.getgittins.dev](https://docs.getgittins.dev)**
20
+
21
+ ## Install
22
+
23
+ ```sh
24
+ pip install gittins
25
+ ```
26
+
27
+ ## Usage
28
+
29
+ The state is an opaque handle updated **in place** — calls return only their
30
+ result, and every alias of the handle observes the current state. Persist it
31
+ with `serialize`, which returns one plain string.
32
+
33
+ ```python
34
+ import time
35
+ import gittins
36
+
37
+ state = gittins.create(bits=8, horizon=3600.0) # model size, seconds to resolve
38
+
39
+ candidates = [
40
+ ("banner-sale", {"discount": 0.2}),
41
+ ("banner-new", {"discount": 0.0}),
42
+ ("banner-plain", {}),
43
+ ]
44
+ context = {"device": "mobile", "hour": 14}
45
+
46
+ record = gittins.decide(state, context, candidates, time.time(), "web-1")
47
+ arm_id = candidates[record.chosen][0]
48
+ # ... your code: act on the choice, then report the outcome
49
+
50
+ gittins.learn(state, record.decision_id, 1.0, time.time())
51
+ gittins.expire(state, time.time()) # resolve anything past its horizon
52
+
53
+ open("bandit.txt", "w").write(gittins.serialize(state))
54
+ ```
55
+
56
+ Feature values are typed by what you pass: strings are categorical, ints,
57
+ floats and bools numeric, `None` absent. Anything else raises `ValueError`
58
+ naming the feature.
59
+
60
+ ### Bringing your own model
61
+
62
+ `decide` takes optional `score` and `explore` callbacks, and `learn`/`expire`
63
+ take `train`. Each crosses the Python/Rust boundary once per call — with all
64
+ candidates, all estimates, or the one resolved record — never once per
65
+ candidate, so the one boundary crossing per decision is preserved.
66
+
67
+ ### Offline policy evaluation
68
+
69
+ `log_line` renders a decision record or resolution as one canonical
70
+ experience-log line. Append it verbatim; it is exactly what the `gittins`
71
+ CLI's `verify` / `eval` / `sweep` / `replay` consume.
72
+
73
+ ```python
74
+ with open("decisions.jsonl", "a") as log:
75
+ log.write(gittins.log_line(record) + "\n")
76
+ ```
77
+
78
+ ## API
79
+
80
+ | Function | Purpose |
81
+ | --- | --- |
82
+ | `create(bits, horizon, default_reward=0.0, epsilon=..., forgetfulness=...)` | New state |
83
+ | `decide(state, context, candidates, t, salt, score=None, explore=None)` | Choose; returns a `DecisionRecord` |
84
+ | `learn(state, decision_id, reward, t, train=None)` | Resolve one decision; returns a `Resolution` or `None` |
85
+ | `expire(state, t, train=None)` | Resolve everything past its horizon |
86
+ | `serialize(state)` / `deserialize(text)` | State as one plain string |
87
+ | `model_bits(state)` | The model's size in bits |
88
+ | `log_line(record_or_resolution)` | One canonical experience-log line |
89
+
90
+ ## License
91
+
92
+ MIT. Named after John Gittins, whose index (1974) established that
93
+ exploration has a precise, computable value.
gittins-1.0.3/bindings/python/Cargo.lock ADDED
@@ -0,0 +1,178 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "autocfg"
7
+ version = "1.5.1"
8
+ source = "registry+https://github.com/rust-lang/crates.io-index"
9
+ checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
10
+
11
+ [[package]]
12
+ name = "gittins-core"
13
+ version = "1.0.3"
14
+
15
+ [[package]]
16
+ name = "gittins-python"
17
+ version = "1.0.3"
18
+ dependencies = [
19
+ "gittins-core",
20
+ "pyo3",
21
+ ]
22
+
23
+ [[package]]
24
+ name = "heck"
25
+ version = "0.5.0"
26
+ source = "registry+https://github.com/rust-lang/crates.io-index"
27
+ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
28
+
29
+ [[package]]
30
+ name = "indoc"
31
+ version = "2.0.7"
32
+ source = "registry+https://github.com/rust-lang/crates.io-index"
33
+ checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
34
+ dependencies = [
35
+ "rustversion",
36
+ ]
37
+
38
+ [[package]]
39
+ name = "libc"
40
+ version = "0.2.186"
41
+ source = "registry+https://github.com/rust-lang/crates.io-index"
42
+ checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
43
+
44
+ [[package]]
45
+ name = "memoffset"
46
+ version = "0.9.1"
47
+ source = "registry+https://github.com/rust-lang/crates.io-index"
48
+ checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
49
+ dependencies = [
50
+ "autocfg",
51
+ ]
52
+
53
+ [[package]]
54
+ name = "once_cell"
55
+ version = "1.21.4"
56
+ source = "registry+https://github.com/rust-lang/crates.io-index"
57
+ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
58
+
59
+ [[package]]
60
+ name = "portable-atomic"
61
+ version = "1.13.1"
62
+ source = "registry+https://github.com/rust-lang/crates.io-index"
63
+ checksum = "c33a9471896f1c69cecef8d20cbe2f7accd12527ce60845ff44c153bb2a21b49"
64
+
65
+ [[package]]
66
+ name = "proc-macro2"
67
+ version = "1.0.106"
68
+ source = "registry+https://github.com/rust-lang/crates.io-index"
69
+ checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
70
+ dependencies = [
71
+ "unicode-ident",
72
+ ]
73
+
74
+ [[package]]
75
+ name = "pyo3"
76
+ version = "0.25.1"
77
+ source = "registry+https://github.com/rust-lang/crates.io-index"
78
+ checksum = "8970a78afe0628a3e3430376fc5fd76b6b45c4d43360ffd6cdd40bdde72b682a"
79
+ dependencies = [
80
+ "indoc",
81
+ "libc",
82
+ "memoffset",
83
+ "once_cell",
84
+ "portable-atomic",
85
+ "pyo3-build-config",
86
+ "pyo3-ffi",
87
+ "pyo3-macros",
88
+ "unindent",
89
+ ]
90
+
91
+ [[package]]
92
+ name = "pyo3-build-config"
93
+ version = "0.25.1"
94
+ source = "registry+https://github.com/rust-lang/crates.io-index"
95
+ checksum = "458eb0c55e7ece017adeba38f2248ff3ac615e53660d7c71a238d7d2a01c7598"
96
+ dependencies = [
97
+ "once_cell",
98
+ "target-lexicon",
99
+ ]
100
+
101
+ [[package]]
102
+ name = "pyo3-ffi"
103
+ version = "0.25.1"
104
+ source = "registry+https://github.com/rust-lang/crates.io-index"
105
+ checksum = "7114fe5457c61b276ab77c5055f206295b812608083644a5c5b2640c3102565c"
106
+ dependencies = [
107
+ "libc",
108
+ "pyo3-build-config",
109
+ ]
110
+
111
+ [[package]]
112
+ name = "pyo3-macros"
113
+ version = "0.25.1"
114
+ source = "registry+https://github.com/rust-lang/crates.io-index"
115
+ checksum = "a8725c0a622b374d6cb051d11a0983786448f7785336139c3c94f5aa6bef7e50"
116
+ dependencies = [
117
+ "proc-macro2",
118
+ "pyo3-macros-backend",
119
+ "quote",
120
+ "syn",
121
+ ]
122
+
123
+ [[package]]
124
+ name = "pyo3-macros-backend"
125
+ version = "0.25.1"
126
+ source = "registry+https://github.com/rust-lang/crates.io-index"
127
+ checksum = "4109984c22491085343c05b0dbc54ddc405c3cf7b4374fc533f5c3313a572ccc"
128
+ dependencies = [
129
+ "heck",
130
+ "proc-macro2",
131
+ "pyo3-build-config",
132
+ "quote",
133
+ "syn",
134
+ ]
135
+
136
+ [[package]]
137
+ name = "quote"
138
+ version = "1.0.46"
139
+ source = "registry+https://github.com/rust-lang/crates.io-index"
140
+ checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
141
+ dependencies = [
142
+ "proc-macro2",
143
+ ]
144
+
145
+ [[package]]
146
+ name = "rustversion"
147
+ version = "1.0.23"
148
+ source = "registry+https://github.com/rust-lang/crates.io-index"
149
+ checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
150
+
151
+ [[package]]
152
+ name = "syn"
153
+ version = "2.0.119"
154
+ source = "registry+https://github.com/rust-lang/crates.io-index"
155
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
156
+ dependencies = [
157
+ "proc-macro2",
158
+ "quote",
159
+ "unicode-ident",
160
+ ]
161
+
162
+ [[package]]
163
+ name = "target-lexicon"
164
+ version = "0.13.5"
165
+ source = "registry+https://github.com/rust-lang/crates.io-index"
166
+ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
167
+
168
+ [[package]]
169
+ name = "unicode-ident"
170
+ version = "1.0.24"
171
+ source = "registry+https://github.com/rust-lang/crates.io-index"
172
+ checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
173
+
174
+ [[package]]
175
+ name = "unindent"
176
+ version = "0.2.4"
177
+ source = "registry+https://github.com/rust-lang/crates.io-index"
178
+ checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
gittins-1.0.3/bindings/python/Cargo.toml ADDED
@@ -0,0 +1,23 @@
1
+ # The Python binding: the public API (core/src/api.rs) exposed to Python
2
+ # via PyO3, one wheel per platform via maturin (abi3: one wheel covers
3
+ # CPython >= 3.10). The core crate stays zero-dependency; PyO3 lives here.
4
+ [package]
5
+ name = "gittins-python"
6
+ version = "1.0.3"
7
+ edition = "2021"
8
+ description = "Python binding for the gittins contextual bandit engine"
9
+ license = "MIT"
10
+ repository = "https://github.com/maxpagels/gittins"
11
+ homepage = "https://docs.getgittins.dev"
12
+ documentation = "https://docs.getgittins.dev"
13
+ keywords = ["bandit", "contextual-bandit", "machine-learning", "online-learning", "exploration"]
14
+ categories = ["algorithms", "science"]
15
+ readme = "README.md"
16
+
17
+ [lib]
18
+ name = "gittins"
19
+ crate-type = ["cdylib"]
20
+
21
+ [dependencies]
22
+ gittins-core = { path = "../../core" }
23
+ pyo3 = { version = "0.25", features = ["extension-module", "abi3-py310"] }
gittins-1.0.3/bindings/python/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Max Pagels
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
gittins-1.0.3/bindings/python/README.md ADDED
@@ -0,0 +1,93 @@
1
+ # gittins
2
+
3
+ An opinionated, highly optimised contextual bandit engine.
4
+
5
+ - **Online by nature.** Learns one observation at a time, in O(1) work and
6
+ fixed memory, as long as open decisions are regularly resolved.
7
+ - **Non-stationarity is expected.** The engine adapts as the relationship
8
+ between context and feedback drifts, and never learns anything it cannot
9
+ eventually unlearn.
10
+ - **Dynamic actions and context.** The candidate set can change on every
11
+ call; you never declare the number of actions up front.
12
+ - **Safe reward handling.** Rewards may arrive late or never. Constructing
13
+ invalid training data is made hard by design.
14
+ - **Speed and determinism.** Bit-identical results across platforms and
15
+ language bindings, enforced by a golden test corpus.
16
+ - **Bring your own model.** Swap in your own scoring or exploration and
17
+ inherit everything else.
18
+
19
+ Full documentation and user guide: **[docs.getgittins.dev](https://docs.getgittins.dev)**
20
+
21
+ ## Install
22
+
23
+ ```sh
24
+ pip install gittins
25
+ ```
26
+
27
+ ## Usage
28
+
29
+ The state is an opaque handle updated **in place** — calls return only their
30
+ result, and every alias of the handle observes the current state. Persist it
31
+ with `serialize`, which returns one plain string.
32
+
33
+ ```python
34
+ import time
35
+ import gittins
36
+
37
+ state = gittins.create(bits=8, horizon=3600.0) # model size, seconds to resolve
38
+
39
+ candidates = [
40
+ ("banner-sale", {"discount": 0.2}),
41
+ ("banner-new", {"discount": 0.0}),
42
+ ("banner-plain", {}),
43
+ ]
44
+ context = {"device": "mobile", "hour": 14}
45
+
46
+ record = gittins.decide(state, context, candidates, time.time(), "web-1")
47
+ arm_id = candidates[record.chosen][0]
48
+ # ... your code: act on the choice, then report the outcome
49
+
50
+ gittins.learn(state, record.decision_id, 1.0, time.time())
51
+ gittins.expire(state, time.time()) # resolve anything past its horizon
52
+
53
+ open("bandit.txt", "w").write(gittins.serialize(state))
54
+ ```
55
+
56
+ Feature values are typed by what you pass: strings are categorical, ints,
57
+ floats and bools numeric, `None` absent. Anything else raises `ValueError`
58
+ naming the feature.
59
+
60
+ ### Bringing your own model
61
+
62
+ `decide` takes optional `score` and `explore` callbacks, and `learn`/`expire`
63
+ take `train`. Each crosses the Python/Rust boundary once per call — with all
64
+ candidates, all estimates, or the one resolved record — never once per
65
+ candidate, so the one boundary crossing per decision is preserved.
66
+
67
+ ### Offline policy evaluation
68
+
69
+ `log_line` renders a decision record or resolution as one canonical
70
+ experience-log line. Append it verbatim; it is exactly what the `gittins`
71
+ CLI's `verify` / `eval` / `sweep` / `replay` consume.
72
+
73
+ ```python
74
+ with open("decisions.jsonl", "a") as log:
75
+ log.write(gittins.log_line(record) + "\n")
76
+ ```
77
+
78
+ ## API
79
+
80
+ | Function | Purpose |
81
+ | --- | --- |
82
+ | `create(bits, horizon, default_reward=0.0, epsilon=..., forgetfulness=...)` | New state |
83
+ | `decide(state, context, candidates, t, salt, score=None, explore=None)` | Choose; returns a `DecisionRecord` |
84
+ | `learn(state, decision_id, reward, t, train=None)` | Resolve one decision; returns a `Resolution` or `None` |
85
+ | `expire(state, t, train=None)` | Resolve everything past its horizon |
86
+ | `serialize(state)` / `deserialize(text)` | State as one plain string |
87
+ | `model_bits(state)` | The model's size in bits |
88
+ | `log_line(record_or_resolution)` | One canonical experience-log line |
89
+
90
+ ## License
91
+
92
+ MIT. Named after John Gittins, whose index (1974) established that
93
+ exploration has a precise, computable value.