novelai-python 0.8.1__tar.gz → 0.9.1__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 (133) hide show
  1. {novelai_python-0.8.1 → novelai_python-0.9.1}/PKG-INFO +150 -7
  2. {novelai_python-0.8.1 → novelai_python-0.9.1}/README.md +144 -4
  3. {novelai_python-0.8.1 → novelai_python-0.9.1}/pyproject.toml +7 -3
  4. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/__init__.py +8 -0
  5. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_enum.py +2 -1
  6. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/user/subscription.py +5 -0
  7. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_retry.py +19 -6
  8. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/credential/UserAuth.py +3 -0
  9. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/credential/_base.py +10 -0
  10. novelai_python-0.9.1/src/novelai_python/metrics.py +752 -0
  11. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/_cost.py +0 -5
  12. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/augment_image/__init__.py +8 -4
  13. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/encode_vibe.py +2 -1
  14. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate/__init__.py +5 -4
  15. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_image/__init__.py +30 -9
  16. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_image/params.py +3 -2
  17. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_image/suggest_tags.py +15 -12
  18. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_stream.py +5 -3
  19. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_voice/__init__.py +5 -4
  20. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/openai_compat.py +3 -3
  21. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/upscale.py +7 -4
  22. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/schema.py +23 -4
  23. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/data.py +4 -1
  24. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/login.py +4 -3
  25. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/subscription.py +4 -1
  26. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/server.py +42 -0
  27. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tokenizer/__init__.py +145 -29
  28. novelai_python-0.9.1/src/novelai_python/tokenizer/_definition.py +78 -0
  29. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tokenizer/clip_tokenizer.py +34 -28
  30. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/utils/daily_limit.py +25 -15
  31. novelai_python-0.9.1/src/novelai_python/utils/pacing.py +176 -0
  32. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/conftest.py +1 -0
  33. novelai_python-0.9.1/tests/fixtures/tokenizer_golden.json +1 -0
  34. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_daily_limit.py +16 -0
  35. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_generate_voice.py +1 -1
  36. novelai_python-0.9.1/tests/test_metrics.py +502 -0
  37. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_new_endpoints.py +7 -9
  38. novelai_python-0.9.1/tests/test_pacing.py +144 -0
  39. novelai_python-0.9.1/tests/test_seed.py +16 -0
  40. novelai_python-0.9.1/tests/test_tokenizer.py +263 -0
  41. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_user_subscription.py +25 -0
  42. novelai_python-0.8.1/tests/test_tokenizer.py +0 -93
  43. {novelai_python-0.8.1 → novelai_python-0.9.1}/LICENSE +0 -0
  44. {novelai_python-0.8.1 → novelai_python-0.9.1}/NOTICE.MD +0 -0
  45. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_exceptions.py +0 -0
  46. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/__init__.py +0 -0
  47. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/ai/__init__.py +0 -0
  48. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/ai/generate.py +0 -0
  49. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/ai/generate_image.py +0 -0
  50. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/ai/generate_stream.py +0 -0
  51. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/ai/generate_voice.py +0 -0
  52. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/ai/upscale.py +0 -0
  53. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/schema.py +0 -0
  54. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/user/__init__.py +0 -0
  55. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/user/data.py +0 -0
  56. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/user/information.py +0 -0
  57. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/user/login.py +0 -0
  58. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/user/priority.py +0 -0
  59. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/_response/user/trial_status.py +0 -0
  60. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/credential/ApiToken.py +0 -0
  61. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/credential/JwtToken.py +0 -0
  62. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/credential/__init__.py +0 -0
  63. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/__init__.py +0 -0
  64. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/LICENSE +0 -0
  65. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/__init__.py +0 -0
  66. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/_const.py +0 -0
  67. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/_enum.py +0 -0
  68. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/augment_image/_enum.py +0 -0
  69. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate/_const.py +0 -0
  70. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate/_enum.py +0 -0
  71. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate/_schema.py +0 -0
  72. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate/themes.json +0 -0
  73. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_image/auto_text.py +0 -0
  74. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_image/schema.py +0 -0
  75. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_image/tokenizer.py +0 -0
  76. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/ai/generate_voice/_enum.py +0 -0
  77. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/__init__.py +0 -0
  78. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/information.py +0 -0
  79. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/persistent_token.py +0 -0
  80. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/priority.py +0 -0
  81. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/sdk/user/trial_status.py +0 -0
  82. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/__init__.py +0 -0
  83. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/image_metadata/__init__.py +0 -0
  84. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/image_metadata/bch.py +0 -0
  85. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/image_metadata/bch_utils.py +0 -0
  86. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/image_metadata/lsb_extractor.py +0 -0
  87. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/image_metadata/lsb_injector.py +0 -0
  88. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/paint_mask/__init__.py +0 -0
  89. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/__init__.py +0 -0
  90. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/data/__init__.py +0 -0
  91. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/data/anime_v3_data.py +0 -0
  92. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/data/anime_v4_data.py +0 -0
  93. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/data/furry_data.py +0 -0
  94. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/data/holiday.py +0 -0
  95. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/data/nsfw_data.py +0 -0
  96. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generate_scene_composition.py +0 -0
  97. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generate_scene_tags.py +0 -0
  98. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generate_tags.py +0 -0
  99. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generators/__init__.py +0 -0
  100. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generators/anime_v3.py +0 -0
  101. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generators/anime_v4.py +0 -0
  102. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generators/furry.py +0 -0
  103. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/generators/holiday.py +0 -0
  104. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/tool/random_prompt/logic.py +0 -0
  105. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/utils/__init__.py +0 -0
  106. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/utils/encode.py +0 -0
  107. {novelai_python-0.8.1 → novelai_python-0.9.1}/src/novelai_python/utils/useful.py +0 -0
  108. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/__init__.py +0 -0
  109. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/fixtures/bch_vectors.json +0 -0
  110. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/fixtures/dependency_golden.json +0 -0
  111. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/fixtures/mask_ori.png +0 -0
  112. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/fixtures/mask_sketch.png +0 -0
  113. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/fixtures/v5_signed.webp +0 -0
  114. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_auto_text.py +0 -0
  115. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_bch.py +0 -0
  116. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_browser_identity.py +0 -0
  117. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_cost.py +0 -0
  118. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_dependency_golden.py +0 -0
  119. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_from_metadata.py +0 -0
  120. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_generate_image_v5.py +0 -0
  121. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_generate_text.py +0 -0
  122. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_image_metadata_v5.py +0 -0
  123. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_login_proxy.py +0 -0
  124. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_presets_and_usage.py +0 -0
  125. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_random_prompt.py +0 -0
  126. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_retry_session.py +0 -0
  127. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_server.py +0 -0
  128. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_server_roundtrip.py +0 -0
  129. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_server_run.py +0 -0
  130. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_suggest_tags.py +0 -0
  131. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_upscale.py +0 -0
  132. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_user_information.py +0 -0
  133. {novelai_python-0.8.1 → novelai_python-0.9.1}/tests/test_user_login.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: novelai-python
3
- Version: 0.8.1
3
+ Version: 0.9.1
4
4
  Summary: NovelAI Python Binding With Pydantic
5
5
  Author-Email: sudoskys <coldlando@hotmail.com>
6
6
  License: Apache License 2.0
@@ -8,6 +8,7 @@ Classifier: Programming Language :: Python :: 3
8
8
  Classifier: Programming Language :: Python :: 3.12
9
9
  Classifier: Programming Language :: Python :: 3.13
10
10
  Classifier: Programming Language :: Python :: 3.14
11
+ Classifier: Programming Language :: Python :: 3.15
11
12
  Project-URL: Repository, https://github.com/LlmKira/novelai-python/
12
13
  Project-URL: Issues, https://github.com/LlmKira/novelai-python/issues
13
14
  Requires-Python: >=3.12
@@ -17,12 +18,14 @@ Requires-Dist: msgpack>=1.2
17
18
  Requires-Dist: Pillow>=12.3
18
19
  Requires-Dist: numpy>=2.5
19
20
  Requires-Dist: pynacl>=1.6
20
- Requires-Dist: tokenizers>=0.23
21
+ Requires-Dist: kitoken>=0.11
21
22
  Provides-Extra: server
22
23
  Requires-Dist: fastapi>=0.143; extra == "server"
23
24
  Requires-Dist: uvicorn[standard]>=0.54; extra == "server"
25
+ Provides-Extra: metrics
26
+ Requires-Dist: prometheus-client>=0.21; extra == "metrics"
24
27
  Provides-Extra: testing
25
- Requires-Dist: novelai-python[server]; extra == "testing"
28
+ Requires-Dist: novelai-python[metrics,server]; extra == "testing"
26
29
  Requires-Dist: httpx>=0.28; extra == "testing"
27
30
  Requires-Dist: pytest>=9.1; extra == "testing"
28
31
  Requires-Dist: pytest-asyncio>=1.4; extra == "testing"
@@ -52,7 +55,7 @@ Description-Content-Type: text/markdown
52
55
  The goal of this repository is to use Pydantic to build legitimate requests to access
53
56
  the [NovelAI API service](https://image.novelai.net/docs).
54
57
 
55
- > Python >= 3.12 is required (tested on 3.12 – 3.14).
58
+ > Python >= 3.12 is required (tested on 3.12 – 3.15).
56
59
 
57
60
  ### 📰 News
58
61
 
@@ -65,10 +68,30 @@ the [NovelAI API service](https://image.novelai.net/docs).
65
68
  - New: character reference (V4.5), `EncodeVibe`, transparent background (V5), `Upscale` on the image host,
66
69
  `UserData`, `TrialStatus`, `Priority`, `CreatePersistentToken`, the OpenAI-compatible text API (`/oa/v1`),
67
70
  and `GenerateImageInfer.from_metadata()` to rebuild a request from an image's metadata.
68
- - Fewer dependencies: pydantic, curl_cffi, msgpack, Pillow, numpy, pynacl and tokenizers. httpx, opencv,
69
- argon2-cffi, ftfy/regex and `bchlib` are gone (`bchlib` has no Python 3.14 wheel; a NumPy BCH codec
70
- replaces it).
71
+ - Fewer dependencies: pydantic, curl_cffi, msgpack, Pillow, numpy, pynacl and kitoken. httpx, opencv,
72
+ argon2-cffi, ftfy/regex, `bchlib` and `tokenizers` are gone (`bchlib` has no Python 3.14 wheel; a NumPy BCH
73
+ codec replaces it. `tokenizers` came with 14 more packages, huggingface-hub, httpx2 and PyYAML among them,
74
+ and PyYAML has no Python 3.15 wheel).
71
75
  - Optional local image budget (`limiter=True`, see below).
76
+ - Optional metrics (`pip install "novelai-python[metrics]"`): every request counted and timed, Anlas and the
77
+ Opus usage bar as gauges, `GET /metrics` on the bundled server. `RequestPacer` keeps a random gap between
78
+ requests counted from the end of the previous one; retries after HTTP 500 back off with jitter.
79
+
80
+ ### ⬆️ Upgrading from 0.8
81
+
82
+ - **`tokenizers` is replaced by `kitoken`.** `NaiTokenizer.tokenizer` is now a `kitoken.Kitoken`; `encode`,
83
+ `decode`, `tokenize_text` and `total_tokens` keep their signatures. CLIP and T5 keep their 0.8.1 ids; the
84
+ BPE tokenizers now follow novelai.net, so some ids change (see below).
85
+ - **Erato uses `llama3nai_tokenizer.def`**, the file novelai.net loads for it (128257 tokens, NovelAI's own
86
+ special tokens). `TextTokenizerGroup.LLAMA3` points there; `NaiTokenizer("llama3_tokenizer")` still loads
87
+ the stock Llama 3 file if you need the old ids.
88
+ - **The BPE tokenizers follow the site**: nerdstash keeps newlines, tabs and digits; special tokens match
89
+ longest-first. Known differences remain for some genji Japanese text and one pile whitespace case.
90
+ - **Python 3.15 is supported** (`requires-python` is still `>=3.12`).
91
+ - **New optional extras**: `pip install "novelai-python[metrics]"` for Prometheus / VictoriaMetrics metrics;
92
+ `RequestPacer` and the local image limiter stay opt-in.
93
+ - **Deprecated**: `SubscriptionResp.get_tier_name` and `.limit_perks` now raise `DeprecationWarning`; use
94
+ `tier_name` and `disabled_perks`.
72
95
 
73
96
  ### ⬆️ Upgrading from 0.7
74
97
 
@@ -192,6 +215,118 @@ print(get_default_limiter().status()) # {'limit': 2500, 'used': ..., 'remaining
192
215
  `isNegative`, `timeUntilNextPercent`. `Priority().request(session)` returns the task priority balance;
193
216
  `CreatePersistentToken(overwrite=True).request(jwt_session)` creates a `pst-...` API key.
194
217
 
218
+ #### 📈 Metrics (Prometheus / VictoriaMetrics)
219
+
220
+ ```shell
221
+ pip install "novelai-python[metrics]"
222
+ ```
223
+
224
+ Every request the SDK sends is counted and timed; `/user/subscription` and `/user/data` responses also refresh
225
+ per-account gauges (Anlas, subscription, the Opus usage bar). Nothing is collected without the extra, and
226
+ `NOVELAI_METRICS=0` turns it off with the extra installed.
227
+
228
+ | Metric | Type | Labels | Meaning |
229
+ |---|---|---|---|
230
+ | `novelai_requests_total` | counter | `endpoint`, `model`, `status` | requests by outcome: the HTTP status; `timeout`, `dns`, `proxy`, `connect`, `ssl`, `reset`, `cancelled` or `transport` for a request without an HTTP answer (from the curl error code); `stream_error` for an error frame inside a 200 stream |
231
+ | `novelai_request_duration_seconds` | histogram | `endpoint`, `model` | wall time of one request, the proxy included, until the response or the whole stream is read |
232
+ | `novelai_requests_in_flight` | gauge | `endpoint` | requests sent and not answered yet |
233
+ | `novelai_last_success_timestamp_seconds` | gauge | `endpoint` | when the endpoint last answered with a status below 400 |
234
+ | `novelai_images_total` | counter | `model` | images received |
235
+ | `novelai_stream_frames_total` | counter | `model` | frames of `/ai/generate-image-stream`, previews included |
236
+ | `novelai_retries_total`, `novelai_retry_wait_seconds` | counter, histogram | `endpoint`, none | retries after HTTP 500 and the backoff slept before them |
237
+ | `novelai_pacing_wait_seconds` | histogram | none | time a request waited for the gap after the previous one (`RequestPacer`) |
238
+ | `novelai_local_limit_remaining_images` | gauge | none | images left in the local `DailyImageLimiter`, read at scrape time; -1 before one is used |
239
+ | `novelai_account_anlas` | gauge | `account`, `kind` | Anlas left: `kind="fixed"` (monthly, reset at renewal) and `kind="purchased"`; their sum is what can be spent |
240
+ | `novelai_subscription_tier`, `_active`, `_expires_timestamp_seconds` | gauge | `account` | tier (0 Paper, 1 Tablet, 2 Scroll, 3 Opus), 1 while active, when it expires |
241
+ | `novelai_opus_usage_ratio`, `_negative`, `_refill_ratio_per_second` | gauge | `account` | the Opus V5 usage bar (0.42 = 42 %), 1 while it is below zero and V5 costs Anlas, how fast it refills |
242
+ | `novelai_opus_images_left` | gauge | `account` | estimated free V5 images the usage bar still covers |
243
+ | `novelai_account_updated_timestamp_seconds` | gauge | `account` | when the account gauges were last refreshed |
244
+ | `novelai_sdk_info` | info | `version`, `impersonate` | SDK version and the browser whose TLS fingerprint it uses |
245
+
246
+ The names follow the Prometheus naming conventions that VictoriaMetrics recommends: base units (seconds, ratios),
247
+ `_total` on counters, `_timestamp_seconds` on timestamps, and one metric with a label where the sum means
248
+ something (`sum by (account) (novelai_account_anlas)`). Every label has a small fixed set of values; prompts,
249
+ seeds, job ids and emails never become label values. The `account` label is `credential.metrics_label` when set,
250
+ otherwise the first 8 hex digits of a SHA-256 of the username or token (a bare `AsyncSession` is `session`), and
251
+ at most 50 accounts are tracked per process (`NovelAIMetrics(max_accounts=...)`). A request that never went out,
252
+ because the login or the local image budget refused it, is not counted.
253
+
254
+ The metrics live in a registry of the SDK's own, so nothing changes on your application's `/metrics` unless you
255
+ ask. That registry leaves out the `*_created` series client_python adds to every counter and histogram:
256
+ they double the series count and VictoriaMetrics does not use them (`NovelAIMetrics(created_series=True)` keeps
257
+ them). Expose it for a scrape, which is the better default, or push from a short-lived script:
258
+
259
+ ```python
260
+ import prometheus_client
261
+ from novelai_python import NovelAIMetrics, get_metrics, set_metrics
262
+
263
+ metrics = get_metrics()
264
+ app.add_route("/metrics", metrics.asgi_app()) # FastAPI / Starlette: gzip, OpenMetrics, ?name[]= filters
265
+ metrics.start_http_server(9108, addr="10.0.0.5") # a port of its own; certfile= / keyfile= for HTTPS
266
+ metrics.write_textfile("/var/lib/node_exporter/novelai.prom") # the textfile collector
267
+ metrics.push_to_victoriametrics("http://victoria:8428", extra_labels={"job": "nai", "instance": "worker-1"})
268
+
269
+ # or show them on the /metrics your application already has (before the first request):
270
+ set_metrics(NovelAIMetrics(registry=prometheus_client.REGISTRY))
271
+ ```
272
+
273
+ A push is gzip-compressed and goes to `/api/v1/import/prometheus`; VictoriaMetrics does not report a bad line in
274
+ the response, it counts it in its own `vm_rows_invalid_total`. With several worker processes (gunicorn), use
275
+ client_python's multiprocess mode (`PROMETHEUS_MULTIPROC_DIR`): the SDK's gauges say how processes combine
276
+ (`livesum` for requests in flight, `max` for timestamps, `mostrecent` for account state).
277
+
278
+ The bundled server (`python -m novelai_python.server`) serves `GET /metrics` with the process metrics
279
+ (`process_*`, `python_info`, `python_gc_*`) included. Set `NOVELAI_METRICS_TOKEN` to require
280
+ `Authorization: Bearer <token>`, or keep it on a private network. A vmagent / Prometheus scrape job for it:
281
+
282
+ ```yaml
283
+ scrape_configs:
284
+ - job_name: novelai-sdk
285
+ scrape_interval: 15s
286
+ static_configs:
287
+ - targets: ["127.0.0.1:7888"]
288
+ authorization: # only with NOVELAI_METRICS_TOKEN
289
+ type: Bearer
290
+ credentials_file: /etc/vmagent/novelai-sdk.token
291
+ ```
292
+
293
+ A labelled series appears with its first event. Prometheus' `rate()` misses that first increment (MetricsQL's
294
+ `increase()` counts it), so pre-create the label sets you alert on:
295
+ `get_metrics().requests.labels("/ai/generate-image", "nai-diffusion-5-full", "timeout")`.
296
+
297
+ MetricsQL / PromQL that pays off:
298
+
299
+ ```promql
300
+ sum(rate(novelai_requests_total{status!~"2.."}[5m])) by (endpoint, status) # errors per second, by kind
301
+ sum(rate(novelai_requests_total{status=~"timeout|proxy|dns|connect"}[5m])) # the network, not NovelAI
302
+ histogram_quantile(0.95, sum(rate(novelai_request_duration_seconds_bucket[5m])) by (le, model)) # p95 by model
303
+ sum by (account) (novelai_account_anlas) < 500 # Anlas running out
304
+ novelai_opus_usage_negative == 1 # V5 now costs Anlas
305
+ time() - novelai_last_success_timestamp_seconds{endpoint="/ai/generate-image"} > 1800 # nothing worked for 30 min
306
+ time() - novelai_account_updated_timestamp_seconds > 3600 # the balance is not polled
307
+ ```
308
+
309
+ #### ⏱️ Pacing: a gap between requests
310
+
311
+ NovelAI answers `429 Concurrent generation is locked` when a request follows the previous one too closely, and
312
+ back-to-back requests do not look like a person at a keyboard. A `RequestPacer` keeps a random gap between
313
+ requests, counted **from the end of the previous request**: the first request goes out at once, a request after
314
+ a long pause goes out at once, and only a request that follows another one closely waits for what is left of
315
+ the gap. Requests through one pacer run one at a time, like one account generates one image at a time.
316
+
317
+ ```python
318
+ from novelai_python import RequestPacer, Subscription
319
+
320
+ pacer = RequestPacer(min_gap=2, max_gap=8) # seconds; one pacer per account
321
+ await gen.request(session, pacer=pacer) # waits only if the previous request ended < 2-8 s ago
322
+ await gen.request(session, pacer=True) # the process-wide pacer: NOVELAI_REQUEST_GAP="1,10" (default), "0" = off
323
+
324
+ async with pacer.slot(): # any other request
325
+ await Subscription().request(session)
326
+ ```
327
+
328
+ Pacing is off unless asked for. Retries after HTTP 500 are jittered as well: `random(1..3 s) * 2 ** (retry - 1)`.
329
+
195
330
  #### 🖼️ Transparent background, character reference, vibes
196
331
 
197
332
  ```python
@@ -306,6 +441,9 @@ pip install "novelai-python[server]"
306
441
  python3 -m novelai_python.server -h '127.0.0.1' -p 7888
307
442
  ```
308
443
 
444
+ Routes: `/health`, `/limit`, `/user/*`, `/ai/*` (docs at `/docs`) and `GET /metrics` when the `metrics` extra is
445
+ installed (`NOVELAI_METRICS_TOKEN` protects it with a bearer token).
446
+
309
447
  #### 📦 Tokenizer
310
448
 
311
449
  ```python
@@ -326,6 +464,11 @@ print(tokenizer_package.decode(tokenizer_package.encode(t_text)))
326
464
 
327
465
  ```
328
466
 
467
+ `NaiTokenizer.tokenizer` is a `kitoken.Kitoken` (a `tokenizers.Tokenizer` up to 0.8.1). For the BPE text
468
+ models the methods above follow the tokenizer in the novelai.net web client; genji still differs on some
469
+ Japanese text (a token produced by more than one merge) and pile on one whitespace case. `decode()` leaves
470
+ out control tokens such as `<|endoftext|>`.
471
+
329
472
  ### 🔨 Roadmap
330
473
 
331
474
  - [x] tool.random_prompt
@@ -22,7 +22,7 @@
22
22
  The goal of this repository is to use Pydantic to build legitimate requests to access
23
23
  the [NovelAI API service](https://image.novelai.net/docs).
24
24
 
25
- > Python >= 3.12 is required (tested on 3.12 – 3.14).
25
+ > Python >= 3.12 is required (tested on 3.12 – 3.15).
26
26
 
27
27
  ### 📰 News
28
28
 
@@ -35,10 +35,30 @@ the [NovelAI API service](https://image.novelai.net/docs).
35
35
  - New: character reference (V4.5), `EncodeVibe`, transparent background (V5), `Upscale` on the image host,
36
36
  `UserData`, `TrialStatus`, `Priority`, `CreatePersistentToken`, the OpenAI-compatible text API (`/oa/v1`),
37
37
  and `GenerateImageInfer.from_metadata()` to rebuild a request from an image's metadata.
38
- - Fewer dependencies: pydantic, curl_cffi, msgpack, Pillow, numpy, pynacl and tokenizers. httpx, opencv,
39
- argon2-cffi, ftfy/regex and `bchlib` are gone (`bchlib` has no Python 3.14 wheel; a NumPy BCH codec
40
- replaces it).
38
+ - Fewer dependencies: pydantic, curl_cffi, msgpack, Pillow, numpy, pynacl and kitoken. httpx, opencv,
39
+ argon2-cffi, ftfy/regex, `bchlib` and `tokenizers` are gone (`bchlib` has no Python 3.14 wheel; a NumPy BCH
40
+ codec replaces it. `tokenizers` came with 14 more packages, huggingface-hub, httpx2 and PyYAML among them,
41
+ and PyYAML has no Python 3.15 wheel).
41
42
  - Optional local image budget (`limiter=True`, see below).
43
+ - Optional metrics (`pip install "novelai-python[metrics]"`): every request counted and timed, Anlas and the
44
+ Opus usage bar as gauges, `GET /metrics` on the bundled server. `RequestPacer` keeps a random gap between
45
+ requests counted from the end of the previous one; retries after HTTP 500 back off with jitter.
46
+
47
+ ### ⬆️ Upgrading from 0.8
48
+
49
+ - **`tokenizers` is replaced by `kitoken`.** `NaiTokenizer.tokenizer` is now a `kitoken.Kitoken`; `encode`,
50
+ `decode`, `tokenize_text` and `total_tokens` keep their signatures. CLIP and T5 keep their 0.8.1 ids; the
51
+ BPE tokenizers now follow novelai.net, so some ids change (see below).
52
+ - **Erato uses `llama3nai_tokenizer.def`**, the file novelai.net loads for it (128257 tokens, NovelAI's own
53
+ special tokens). `TextTokenizerGroup.LLAMA3` points there; `NaiTokenizer("llama3_tokenizer")` still loads
54
+ the stock Llama 3 file if you need the old ids.
55
+ - **The BPE tokenizers follow the site**: nerdstash keeps newlines, tabs and digits; special tokens match
56
+ longest-first. Known differences remain for some genji Japanese text and one pile whitespace case.
57
+ - **Python 3.15 is supported** (`requires-python` is still `>=3.12`).
58
+ - **New optional extras**: `pip install "novelai-python[metrics]"` for Prometheus / VictoriaMetrics metrics;
59
+ `RequestPacer` and the local image limiter stay opt-in.
60
+ - **Deprecated**: `SubscriptionResp.get_tier_name` and `.limit_perks` now raise `DeprecationWarning`; use
61
+ `tier_name` and `disabled_perks`.
42
62
 
43
63
  ### ⬆️ Upgrading from 0.7
44
64
 
@@ -162,6 +182,118 @@ print(get_default_limiter().status()) # {'limit': 2500, 'used': ..., 'remaining
162
182
  `isNegative`, `timeUntilNextPercent`. `Priority().request(session)` returns the task priority balance;
163
183
  `CreatePersistentToken(overwrite=True).request(jwt_session)` creates a `pst-...` API key.
164
184
 
185
+ #### 📈 Metrics (Prometheus / VictoriaMetrics)
186
+
187
+ ```shell
188
+ pip install "novelai-python[metrics]"
189
+ ```
190
+
191
+ Every request the SDK sends is counted and timed; `/user/subscription` and `/user/data` responses also refresh
192
+ per-account gauges (Anlas, subscription, the Opus usage bar). Nothing is collected without the extra, and
193
+ `NOVELAI_METRICS=0` turns it off with the extra installed.
194
+
195
+ | Metric | Type | Labels | Meaning |
196
+ |---|---|---|---|
197
+ | `novelai_requests_total` | counter | `endpoint`, `model`, `status` | requests by outcome: the HTTP status; `timeout`, `dns`, `proxy`, `connect`, `ssl`, `reset`, `cancelled` or `transport` for a request without an HTTP answer (from the curl error code); `stream_error` for an error frame inside a 200 stream |
198
+ | `novelai_request_duration_seconds` | histogram | `endpoint`, `model` | wall time of one request, the proxy included, until the response or the whole stream is read |
199
+ | `novelai_requests_in_flight` | gauge | `endpoint` | requests sent and not answered yet |
200
+ | `novelai_last_success_timestamp_seconds` | gauge | `endpoint` | when the endpoint last answered with a status below 400 |
201
+ | `novelai_images_total` | counter | `model` | images received |
202
+ | `novelai_stream_frames_total` | counter | `model` | frames of `/ai/generate-image-stream`, previews included |
203
+ | `novelai_retries_total`, `novelai_retry_wait_seconds` | counter, histogram | `endpoint`, none | retries after HTTP 500 and the backoff slept before them |
204
+ | `novelai_pacing_wait_seconds` | histogram | none | time a request waited for the gap after the previous one (`RequestPacer`) |
205
+ | `novelai_local_limit_remaining_images` | gauge | none | images left in the local `DailyImageLimiter`, read at scrape time; -1 before one is used |
206
+ | `novelai_account_anlas` | gauge | `account`, `kind` | Anlas left: `kind="fixed"` (monthly, reset at renewal) and `kind="purchased"`; their sum is what can be spent |
207
+ | `novelai_subscription_tier`, `_active`, `_expires_timestamp_seconds` | gauge | `account` | tier (0 Paper, 1 Tablet, 2 Scroll, 3 Opus), 1 while active, when it expires |
208
+ | `novelai_opus_usage_ratio`, `_negative`, `_refill_ratio_per_second` | gauge | `account` | the Opus V5 usage bar (0.42 = 42 %), 1 while it is below zero and V5 costs Anlas, how fast it refills |
209
+ | `novelai_opus_images_left` | gauge | `account` | estimated free V5 images the usage bar still covers |
210
+ | `novelai_account_updated_timestamp_seconds` | gauge | `account` | when the account gauges were last refreshed |
211
+ | `novelai_sdk_info` | info | `version`, `impersonate` | SDK version and the browser whose TLS fingerprint it uses |
212
+
213
+ The names follow the Prometheus naming conventions that VictoriaMetrics recommends: base units (seconds, ratios),
214
+ `_total` on counters, `_timestamp_seconds` on timestamps, and one metric with a label where the sum means
215
+ something (`sum by (account) (novelai_account_anlas)`). Every label has a small fixed set of values; prompts,
216
+ seeds, job ids and emails never become label values. The `account` label is `credential.metrics_label` when set,
217
+ otherwise the first 8 hex digits of a SHA-256 of the username or token (a bare `AsyncSession` is `session`), and
218
+ at most 50 accounts are tracked per process (`NovelAIMetrics(max_accounts=...)`). A request that never went out,
219
+ because the login or the local image budget refused it, is not counted.
220
+
221
+ The metrics live in a registry of the SDK's own, so nothing changes on your application's `/metrics` unless you
222
+ ask. That registry leaves out the `*_created` series client_python adds to every counter and histogram:
223
+ they double the series count and VictoriaMetrics does not use them (`NovelAIMetrics(created_series=True)` keeps
224
+ them). Expose it for a scrape, which is the better default, or push from a short-lived script:
225
+
226
+ ```python
227
+ import prometheus_client
228
+ from novelai_python import NovelAIMetrics, get_metrics, set_metrics
229
+
230
+ metrics = get_metrics()
231
+ app.add_route("/metrics", metrics.asgi_app()) # FastAPI / Starlette: gzip, OpenMetrics, ?name[]= filters
232
+ metrics.start_http_server(9108, addr="10.0.0.5") # a port of its own; certfile= / keyfile= for HTTPS
233
+ metrics.write_textfile("/var/lib/node_exporter/novelai.prom") # the textfile collector
234
+ metrics.push_to_victoriametrics("http://victoria:8428", extra_labels={"job": "nai", "instance": "worker-1"})
235
+
236
+ # or show them on the /metrics your application already has (before the first request):
237
+ set_metrics(NovelAIMetrics(registry=prometheus_client.REGISTRY))
238
+ ```
239
+
240
+ A push is gzip-compressed and goes to `/api/v1/import/prometheus`; VictoriaMetrics does not report a bad line in
241
+ the response, it counts it in its own `vm_rows_invalid_total`. With several worker processes (gunicorn), use
242
+ client_python's multiprocess mode (`PROMETHEUS_MULTIPROC_DIR`): the SDK's gauges say how processes combine
243
+ (`livesum` for requests in flight, `max` for timestamps, `mostrecent` for account state).
244
+
245
+ The bundled server (`python -m novelai_python.server`) serves `GET /metrics` with the process metrics
246
+ (`process_*`, `python_info`, `python_gc_*`) included. Set `NOVELAI_METRICS_TOKEN` to require
247
+ `Authorization: Bearer <token>`, or keep it on a private network. A vmagent / Prometheus scrape job for it:
248
+
249
+ ```yaml
250
+ scrape_configs:
251
+ - job_name: novelai-sdk
252
+ scrape_interval: 15s
253
+ static_configs:
254
+ - targets: ["127.0.0.1:7888"]
255
+ authorization: # only with NOVELAI_METRICS_TOKEN
256
+ type: Bearer
257
+ credentials_file: /etc/vmagent/novelai-sdk.token
258
+ ```
259
+
260
+ A labelled series appears with its first event. Prometheus' `rate()` misses that first increment (MetricsQL's
261
+ `increase()` counts it), so pre-create the label sets you alert on:
262
+ `get_metrics().requests.labels("/ai/generate-image", "nai-diffusion-5-full", "timeout")`.
263
+
264
+ MetricsQL / PromQL that pays off:
265
+
266
+ ```promql
267
+ sum(rate(novelai_requests_total{status!~"2.."}[5m])) by (endpoint, status) # errors per second, by kind
268
+ sum(rate(novelai_requests_total{status=~"timeout|proxy|dns|connect"}[5m])) # the network, not NovelAI
269
+ histogram_quantile(0.95, sum(rate(novelai_request_duration_seconds_bucket[5m])) by (le, model)) # p95 by model
270
+ sum by (account) (novelai_account_anlas) < 500 # Anlas running out
271
+ novelai_opus_usage_negative == 1 # V5 now costs Anlas
272
+ time() - novelai_last_success_timestamp_seconds{endpoint="/ai/generate-image"} > 1800 # nothing worked for 30 min
273
+ time() - novelai_account_updated_timestamp_seconds > 3600 # the balance is not polled
274
+ ```
275
+
276
+ #### ⏱️ Pacing: a gap between requests
277
+
278
+ NovelAI answers `429 Concurrent generation is locked` when a request follows the previous one too closely, and
279
+ back-to-back requests do not look like a person at a keyboard. A `RequestPacer` keeps a random gap between
280
+ requests, counted **from the end of the previous request**: the first request goes out at once, a request after
281
+ a long pause goes out at once, and only a request that follows another one closely waits for what is left of
282
+ the gap. Requests through one pacer run one at a time, like one account generates one image at a time.
283
+
284
+ ```python
285
+ from novelai_python import RequestPacer, Subscription
286
+
287
+ pacer = RequestPacer(min_gap=2, max_gap=8) # seconds; one pacer per account
288
+ await gen.request(session, pacer=pacer) # waits only if the previous request ended < 2-8 s ago
289
+ await gen.request(session, pacer=True) # the process-wide pacer: NOVELAI_REQUEST_GAP="1,10" (default), "0" = off
290
+
291
+ async with pacer.slot(): # any other request
292
+ await Subscription().request(session)
293
+ ```
294
+
295
+ Pacing is off unless asked for. Retries after HTTP 500 are jittered as well: `random(1..3 s) * 2 ** (retry - 1)`.
296
+
165
297
  #### 🖼️ Transparent background, character reference, vibes
166
298
 
167
299
  ```python
@@ -276,6 +408,9 @@ pip install "novelai-python[server]"
276
408
  python3 -m novelai_python.server -h '127.0.0.1' -p 7888
277
409
  ```
278
410
 
411
+ Routes: `/health`, `/limit`, `/user/*`, `/ai/*` (docs at `/docs`) and `GET /metrics` when the `metrics` extra is
412
+ installed (`NOVELAI_METRICS_TOKEN` protects it with a bearer token).
413
+
279
414
  #### 📦 Tokenizer
280
415
 
281
416
  ```python
@@ -296,6 +431,11 @@ print(tokenizer_package.decode(tokenizer_package.encode(t_text)))
296
431
 
297
432
  ```
298
433
 
434
+ `NaiTokenizer.tokenizer` is a `kitoken.Kitoken` (a `tokenizers.Tokenizer` up to 0.8.1). For the BPE text
435
+ models the methods above follow the tokenizer in the novelai.net web client; genji still differs on some
436
+ Japanese text (a token produced by more than one merge) and pile on one whitespace case. `decode()` leaves
437
+ out control tokens such as `<|endoftext|>`.
438
+
299
439
  ### 🔨 Roadmap
300
440
 
301
441
  - [x] tool.random_prompt
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "novelai-python"
3
- version = "0.8.1"
3
+ version = "0.9.1"
4
4
  description = "NovelAI Python Binding With Pydantic"
5
5
  authors = [
6
6
  { name = "sudoskys", email = "coldlando@hotmail.com" },
@@ -12,7 +12,7 @@ dependencies = [
12
12
  "Pillow>=12.3",
13
13
  "numpy>=2.5",
14
14
  "pynacl>=1.6",
15
- "tokenizers>=0.23",
15
+ "kitoken>=0.11",
16
16
  ]
17
17
  requires-python = ">=3.12"
18
18
  readme = "README.md"
@@ -21,6 +21,7 @@ classifiers = [
21
21
  "Programming Language :: Python :: 3.12",
22
22
  "Programming Language :: Python :: 3.13",
23
23
  "Programming Language :: Python :: 3.14",
24
+ "Programming Language :: Python :: 3.15",
24
25
  ]
25
26
 
26
27
  [project.license]
@@ -35,8 +36,11 @@ server = [
35
36
  "fastapi>=0.143",
36
37
  "uvicorn[standard]>=0.54",
37
38
  ]
39
+ metrics = [
40
+ "prometheus-client>=0.21",
41
+ ]
38
42
  testing = [
39
- "novelai-python[server]",
43
+ "novelai-python[server,metrics]",
40
44
  "httpx>=0.28",
41
45
  "pytest>=9.1",
42
46
  "pytest-asyncio>=1.4",
@@ -10,6 +10,7 @@ from ._exceptions import (
10
10
  SessionHttpError,
11
11
  )
12
12
  from .credential import ApiCredential, JwtCredential, LoginCredential
13
+ from .metrics import NovelAIMetrics, get_metrics, set_metrics
13
14
  from .sdk import (
14
15
  LLM,
15
16
  AugmentImageInfer,
@@ -50,6 +51,7 @@ from .sdk import (
50
51
  VoiceResponse,
51
52
  )
52
53
  from .utils.daily_limit import DailyImageLimiter, get_default_limiter, set_default_limiter
54
+ from .utils.pacing import RequestPacer, get_default_pacer, set_default_pacer
53
55
 
54
56
  __all__ = [
55
57
  "LLM",
@@ -75,6 +77,7 @@ __all__ = [
75
77
  "Login",
76
78
  "LoginCredential",
77
79
  "LoginResp",
80
+ "NovelAIMetrics",
78
81
  "NovelAiError",
79
82
  "OAIChatCompletion",
80
83
  "OAIChatMessage",
@@ -86,6 +89,7 @@ __all__ = [
86
89
  "PersistentTokenResp",
87
90
  "Priority",
88
91
  "PriorityResp",
92
+ "RequestPacer",
89
93
  "SessionHttpError",
90
94
  "Subscription",
91
95
  "SubscriptionResp",
@@ -100,5 +104,9 @@ __all__ = [
100
104
  "VoiceGenerate",
101
105
  "VoiceResponse",
102
106
  "get_default_limiter",
107
+ "get_default_pacer",
108
+ "get_metrics",
103
109
  "set_default_limiter",
110
+ "set_default_pacer",
111
+ "set_metrics",
104
112
  ]
@@ -36,7 +36,8 @@ class TextTokenizerGroup:
36
36
  NAI_INLINE = "gpt2_tokenizer.def"
37
37
  NERDSTASH_V2 = "nerdstash_tokenizer_v2.def"
38
38
  NERDSTASH = "nerdstash_tokenizer.def"
39
- LLAMA3 = "llama3_tokenizer.def"
39
+ # Erato: the site loads llama3nai (NovelAI's special tokens, 128257 tokens), not llama3 (128010)
40
+ LLAMA3 = "llama3nai_tokenizer.def"
40
41
  GPT2 = "gpt2_tokenizer.def"
41
42
  CLIP = "clip_tokenizer.def"
42
43
  T5 = "t5_tokenizer.def"
@@ -2,6 +2,7 @@
2
2
  # @Author : sudoskys
3
3
  # @File : subscription.py
4
4
 
5
+ import warnings
5
6
  from typing import Any
6
7
 
7
8
  from pydantic import BaseModel, Field
@@ -107,9 +108,13 @@ class SubscriptionResp(RespBase):
107
108
  @property
108
109
  def get_tier_name(self) -> str:
109
110
  """Deprecated name of ``tier_name``."""
111
+ warnings.warn("SubscriptionResp.get_tier_name is deprecated, use tier_name", DeprecationWarning, stacklevel=2)
110
112
  return self.tier_name
111
113
 
112
114
  @property
113
115
  def limit_perks(self) -> list[str]:
114
116
  """Deprecated name of ``disabled_perks``."""
117
+ warnings.warn(
118
+ "SubscriptionResp.limit_perks is deprecated, use disabled_perks", DeprecationWarning, stacklevel=2
119
+ )
115
120
  return self.disabled_perks
@@ -8,8 +8,9 @@ from typing import Any, ParamSpec, TypeVar
8
8
 
9
9
  P = ParamSpec("P")
10
10
  T = TypeVar("T")
11
+ RetryObserver = Callable[[tuple[Any, ...], float], None]
11
12
 
12
- __all__ = ["retry_on_server_error"]
13
+ __all__ = ["RetryObserver", "retry_on_server_error"]
13
14
 
14
15
 
15
16
  def _is_server_error(exc: BaseException) -> bool:
@@ -17,13 +18,22 @@ def _is_server_error(exc: BaseException) -> bool:
17
18
 
18
19
 
19
20
  def retry_on_server_error(
20
- attempts: int = 3, min_wait: float = 1.0, max_wait: float = 3.0
21
+ attempts: int = 3,
22
+ min_wait: float = 1.0,
23
+ max_wait: float = 3.0,
24
+ backoff: float = 2.0,
25
+ on_retry: RetryObserver | None = None,
21
26
  ) -> Callable[[Callable[P, Coroutine[Any, Any, T]]], Callable[P, Coroutine[Any, Any, T]]]:
22
27
  """Retry an ``async def`` call up to ``attempts`` times while it raises an error with ``code == 500``.
23
28
 
24
- Only server errors are retried: transport errors are not, because the request may already
25
- have been accepted (and charged) by NovelAI. Do not use on async generators: a stream that
26
- has already yielded data cannot be replayed safely.
29
+ The wait before retry ``n`` is a random ``min_wait..max_wait`` seconds times ``backoff ** (n - 1)``:
30
+ two callers that hit the same outage do not retry in lockstep, and a second retry waits longer
31
+ than the first. Only server errors are retried: transport errors are not, because the request may
32
+ already have been accepted (and charged) by NovelAI. Do not use on async generators: a stream
33
+ that has already yielded data cannot be replayed safely.
34
+
35
+ ``on_retry`` receives the wrapper's positional arguments and the wait, so the caller can record
36
+ the retry without this module knowing about metrics.
27
37
  """
28
38
 
29
39
  def decorator(fn: Callable[P, Coroutine[Any, Any, T]]) -> Callable[P, Coroutine[Any, Any, T]]:
@@ -35,7 +45,10 @@ def retry_on_server_error(
35
45
  except Exception as exc:
36
46
  if attempt == attempts or not _is_server_error(exc):
37
47
  raise
38
- await asyncio.sleep(random.uniform(min_wait, max_wait))
48
+ wait = random.uniform(min_wait, max_wait) * backoff ** (attempt - 1)
49
+ if on_retry is not None:
50
+ on_retry(args, wait)
51
+ await asyncio.sleep(wait)
39
52
  raise AssertionError("unreachable")
40
53
 
41
54
  return wrapper
@@ -39,6 +39,9 @@ class LoginCredential(CredentialBase):
39
39
  _login_lock: asyncio.Lock | None = PrivateAttr(default=None)
40
40
  _login_lock_loop: asyncio.AbstractEventLoop | None = PrivateAttr(default=None)
41
41
 
42
+ def metrics_seed(self) -> str | None:
43
+ return self.username
44
+
42
45
  def _token_expired(self) -> bool:
43
46
  # 30 天有效期
44
47
  return (
@@ -127,6 +127,13 @@ class CredentialBase(BaseModel):
127
127
  accept_language: str | None = None
128
128
  """Browser language: a key of ``ACCEPT_LANGUAGES`` (``"en-sg"``, ``"ja"``, ...) or a full
129
129
  Accept-Language value. None = English (``en-US,en;q=0.9``). Match it to the proxy's country."""
130
+ metrics_label: str | None = Field(default=None, description="account label of this credential in the metrics")
131
+ """Value of the ``account`` label on the Anlas / usage gauges (``novelai_python.metrics``).
132
+ None = the first 8 hex digits of a SHA-256 of the username or token: stable, and not the email."""
133
+
134
+ def metrics_seed(self) -> str | None:
135
+ """What identifies the account for the metrics hash; ``None`` when the credential has no identity."""
136
+ return None
130
137
 
131
138
  def session_kwargs(self, timeout: int, headers: dict) -> dict:
132
139
  # trust_env=False: never pick up HTTP(S)_PROXY from the environment. A
@@ -150,6 +157,9 @@ class BearerCredential(CredentialBase):
150
157
  def _token(self) -> str:
151
158
  raise NotImplementedError
152
159
 
160
+ def metrics_seed(self) -> str | None:
161
+ return self._token()
162
+
153
163
  async def get_session(self, timeout: int = 180, update_headers: dict | None = None):
154
164
  # update_headers goes through browser_headers too: its lowercased keys replace ours
155
165
  headers = browser_headers(