kiori-ai 2.0.0__tar.gz

kiori_ai-2.0.0/.gitignore

@@ -0,0 +1,8 @@
+data/local/
+.env
+node_modules/
+.DS_Store
+*.log
+# the static site (kiori site)
+dist/
+__pycache__/

kiori_ai-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aras Aktas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kiori_ai-2.0.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.5
+Name: kiori-ai
+Version: 2.0.0
+Summary: The Python client for Kiori, brains for characters: memory, personality and who-knows-what for character AI. No dependencies.
+Project-URL: Homepage, https://kiori.io
+Project-URL: Documentation, https://kiori.io/docs
+Project-URL: Source, https://github.com/kiori-ai/kiori/tree/main/sdk
+Project-URL: Issues, https://github.com/kiori-ai/kiori/issues
+Author: Kiori
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai characters,character ai,character card,chatbot,kiori,llm,llm memory,long-term memory,memory,npc,personality,roleplay,sillytavern
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Kiori for JavaScript and Python
+
+**Brains for characters.** Kiori gives every character in your app a mind of its own: a past, a personality, people they love and resent, memories that fade or stay, and a strict sense of what they could possibly know.
+
+These are Kiori's official clients. Each is one file with no dependencies.
+
+| | Install | Import |
+|---|---|---|
+| JavaScript: Node 18+ and browsers, types included | `npm install kiori` | `import { Kiori } from 'kiori'` |
+| Python 3.8+ | `pip install kiori-ai` | `from kiori import Kiori` |
+
+On PyPI the package is called **kiori-ai**, because the name `kiori` there belongs to an unrelated project. The module you import is still `kiori`. Don't install that other `kiori` package in the same environment: its `kiori` package would hide this module, and `from kiori import Kiori` would fail.
+
+If you don't use a package manager, copy the single file instead: [kiori.mjs](https://kiori.io/sdk/kiori.mjs) with its types [kiori.d.ts](https://kiori.io/sdk/kiori.d.ts), or [kiori.py](https://kiori.io/sdk/kiori.py).
+
+## How it works
+
+Kiori stores no brains and no chats. A brain is a JSON object you keep, in your database or on your player's device. You send it with each call, and calls that change it give it back.
+
+- **create**: once per character, a brain from its card. Keep it as the character's template, and start each new conversation from a copy.
+- **recall**: every turn, what the character knows right now, as a ready-to-use block for your prompt.
+- **organize**: after each reply, the brain learns from the chat. Keep the brain that comes back.
+- **check** (optional): the auditor reads your model's draft against what the character really knows, and fixes leaks, contradictions and invented pasts.
+
+## Before you start
+
+1. Ask for access on [kiori.io](https://kiori.io/#access). Your sign-in link opens the console.
+2. In the console, paste your **brain API key** (OpenRouter, OpenAI or Gemini) and create a **Kiori key** for your app. Kiori builds and updates brains on your brain API key, and you pay your provider directly.
+3. Keep the Kiori key on your server, for example in `KIORI_API_KEY`.
+
+## Quickstart: JavaScript
+
+```js
+import { Kiori } from 'kiori';
+
+const kiori = new Kiori({ apiKey: process.env.KIORI_API_KEY });
+
+// Once per character: a brain from its card (a Tavern/SillyTavern card, or name and description)
+let brain = await kiori.create({ character_card: card });
+
+// Every turn: what the character knows right now, for your prompt (the recent messages are enough)
+const recent = messages.slice(-60);
+const { text, check_recommended } = await kiori.recall({ brain, messages: recent });
+let reply = await yourModel({ system: `${yourCharacterPrompt}\n\n${text}`, messages });
+
+// Optional: when the player brings up the past, check the draft before it's shown
+if (check_recommended) reply = (await kiori.check({ brain, messages: recent, draft: reply })).fixed;
+
+// After the reply: the brain learns from the chat. Keep the brain that comes back
+messages.push({ role: 'assistant', content: reply });
+({ brain } = await kiori.organize({ brain, messages: messages.slice(-60) }));
+```
+
+The package is ESM only. From CommonJS, load it with `const { Kiori } = await import('kiori')`.
+
+The client also runs in a browser, since all it needs is `fetch`. But a Kiori key inside a public web page is a key anyone can take: call Kiori from your server, or use a key that belongs to the person using the page, the way the SillyTavern extension does.
+
+## Quickstart: Python
+
+```python
+import os
+from kiori import Kiori
+
+kiori = Kiori(os.environ["KIORI_API_KEY"])
+
+# Once per character: a brain from its card (a dict, or a card PNG in base64)
+brain = kiori.create(character_card=card)
+
+# Every turn: what the character knows right now, for your prompt (the recent messages are enough)
+recent = messages[-60:]
+context = kiori.recall(brain=brain, messages=recent)
+reply = your_model(system=your_character_prompt + "\n\n" + context["text"], messages=messages)
+
+# Optional: when the player brings up the past, check the draft before it's shown
+if context["check_recommended"]:
+    reply = kiori.check(draft=reply, brain=brain, messages=recent)["fixed"]
+
+# After the reply: the brain learns from the chat. Keep the brain that comes back
+messages.append({"role": "assistant", "content": reply})
+brain = kiori.organize(brain=brain, messages=messages[-60:])["brain"]
+```
+
+The Python calls take keyword arguments named like the API's fields, and return plain dicts.
+
+## Messages
+
+Messages are OpenAI-style: `{ "id": "m41", "role": "user", "content": "..." }`, oldest first. For `organize`, send the conversation's recent messages as they are now (the last 60 is a good amount: at least the last 30, not only the new ones, and at most 400), with your own message ids if you have them, so that edits and rerolls are noticed and unlearned. Always keep the brain that comes back, even when nothing was learned.
+
+## Group chats
+
+Send every character's brain at once: `brains` instead of `brain`. Answers come back in the same order, and each brain learns only the scenes its character was in. Messages from characters carry their name: `{ role: "assistant", name: "Rook", content: "..." }`.
+
+```js
+[mira, rook] = (await kiori.organize({ brains: [mira, rook], messages, player: 'Leo' })).brains;
+```
+
+```python
+mira, rook = kiori.organize(brains=[mira, rook], messages=messages, player="Leo")["brains"]
+```
+
+## All calls
+
+| JavaScript | Python | |
+|---|---|---|
+| `create({...})` | `create(...)` | a new brain: from `character_card`, or from `name`, `description` and `lore`. `depth: "full"` (default; a whole past, about a minute, on your brain API key) or `"light"` (from the card alone, free, at once) |
+| `recall({...})` | `recall(...)` | what each character knows right now: `text` (one brain), `characters`, `check_recommended` |
+| `organize({...})` | `organize(...)` | the brain learns from the chat: `brain` (or `brains`), `learned`, `rewound`, `waiting` |
+| `check({...})` | `check(draft, ...)` | a draft reply checked against what each character knows: `ok`, `issues`, `fixed` |
+| `exportObsidian(brain)` | `export_obsidian(brain)` | the brain as an Obsidian vault, as zip bytes |
+| `personality()` | `personality()` | the 41 personality dimensions and the archetypes |
+| `project.get()`, `project.update({...})`, `project.models()`, `project.usage(days)` | `project.get()`, `project.update(...)`, `project.models()`, `project.usage(days)` | your project, its brain API key and model, its usage |
+| `project.keys.create(label)`, `project.keys.revoke(prefix)` | `project.create_key(label)`, `project.revoke_key(prefix)` | Kiori keys |
+
+Changing the project (`project.update`, and making or revoking keys) takes an owner key: the one the console makes when you sign in with your link. The keys you make for your app can do everything else, so a key that leaks from your app can't move the project's calls elsewhere or take your keys away.
+
+## Options
+
+| JavaScript | Python | Default | |
+|---|---|---|---|
+| `apiKey` | `api_key` (the first argument) | | your Kiori key |
+| `baseUrl` | `base_url` | `https://api.kiori.io` | another Kiori, for example one you host yourself |
+| `timeout` | `timeout` | 150000 ms in JavaScript, 150 s in Python | per request; building a full brain takes about a minute |
+| `maxRetries` | `max_retries` | `2` | see Retries; `0` turns them off |
+
+## Retries
+
+Every brain call is safe to repeat, since Kiori keeps nothing between calls. So both clients ask again on their own, twice at most, when Kiori or your model provider is briefly unavailable or out of reach (408, 429, 502, 503 and the like, or a network error): after `Retry-After` when Kiori sends one (up to 20 s), else after about 1 s, then 2 s.
+
+They don't ask again after a timeout (a full brain may still be building), for a missing or refused brain API key, when your provider is out of credits, or when the model's answers stayed unusable after Kiori's own tries (`INCOMPLETE`). Nor when Kiori asks to wait longer than 20 s: the error then carries the wait as `retryAfter` (JavaScript) or `retry_after` (Python).
+
+`maxRetries` (JavaScript) or `max_retries` (Python) changes how many times; `0` turns retries off:
+
+```js
+const kiori = new Kiori({ apiKey: process.env.KIORI_API_KEY, maxRetries: 0 });
+```
+
+```python
+kiori = Kiori(os.environ["KIORI_API_KEY"], max_retries=0)
+```
+
+## Errors
+
+A failed call raises `KioriError` (`import { KioriError } from 'kiori'`, `from kiori import KioriError`), with:
+
+- `status`: the HTTP status, or `0` when Kiori couldn't be reached (code `NETWORK`) or didn't answer in time (code `TIMEOUT`)
+- `code`: for example `UNAUTHORIZED` (a wrong Kiori key), `NEEDS_KEY`, `BAD_KEY` and `CREDITS` (your brain API key is missing, refused, or out of credits), `RATE_LIMITED`, `PROVIDER`, `BAD_BRAIN`, and `REDIRECT` (the address answered with a redirect, which Kiori never sends: the clients don't follow one, so your key and brains don't go where it leads; check the base URL)
+- `retryAfter` (JavaScript) or `retry_after` (Python): the seconds Kiori asked to wait, when it did
+- `requestId` (JavaScript) or `request_id` (Python): the call's id, to quote when you write to us about it
+
+A failed organize changes nothing: keep the brain you had, and the next call picks up where it left off. All the codes are in the [error table](https://kiori.io/docs/api#errors).
+
+## Learn more
+
+- [Integration guide](https://kiori.io/docs/integration): the calls, keeping brains, group chats, the drop-in, SillyTavern
+- [Concepts](https://kiori.io/docs/concepts): the brain file, presence, organizer, auditor, sleep
+- [API reference](https://kiori.io/docs/api), and [openapi.json](https://kiori.io/openapi.json) to generate a client in another language
+- [kiori.io](https://kiori.io)
+
+## License
+
+MIT. The full text is in the LICENSE file that comes with the package. The license covers these client files, not the Kiori service.

kiori_ai-2.0.0/README.md

@@ -0,0 +1,161 @@
+# Kiori for JavaScript and Python
+
+**Brains for characters.** Kiori gives every character in your app a mind of its own: a past, a personality, people they love and resent, memories that fade or stay, and a strict sense of what they could possibly know.
+
+These are Kiori's official clients. Each is one file with no dependencies.
+
+| | Install | Import |
+|---|---|---|
+| JavaScript: Node 18+ and browsers, types included | `npm install kiori` | `import { Kiori } from 'kiori'` |
+| Python 3.8+ | `pip install kiori-ai` | `from kiori import Kiori` |
+
+On PyPI the package is called **kiori-ai**, because the name `kiori` there belongs to an unrelated project. The module you import is still `kiori`. Don't install that other `kiori` package in the same environment: its `kiori` package would hide this module, and `from kiori import Kiori` would fail.
+
+If you don't use a package manager, copy the single file instead: [kiori.mjs](https://kiori.io/sdk/kiori.mjs) with its types [kiori.d.ts](https://kiori.io/sdk/kiori.d.ts), or [kiori.py](https://kiori.io/sdk/kiori.py).
+
+## How it works
+
+Kiori stores no brains and no chats. A brain is a JSON object you keep, in your database or on your player's device. You send it with each call, and calls that change it give it back.
+
+- **create**: once per character, a brain from its card. Keep it as the character's template, and start each new conversation from a copy.
+- **recall**: every turn, what the character knows right now, as a ready-to-use block for your prompt.
+- **organize**: after each reply, the brain learns from the chat. Keep the brain that comes back.
+- **check** (optional): the auditor reads your model's draft against what the character really knows, and fixes leaks, contradictions and invented pasts.
+
+## Before you start
+
+1. Ask for access on [kiori.io](https://kiori.io/#access). Your sign-in link opens the console.
+2. In the console, paste your **brain API key** (OpenRouter, OpenAI or Gemini) and create a **Kiori key** for your app. Kiori builds and updates brains on your brain API key, and you pay your provider directly.
+3. Keep the Kiori key on your server, for example in `KIORI_API_KEY`.
+
+## Quickstart: JavaScript
+
+```js
+import { Kiori } from 'kiori';
+
+const kiori = new Kiori({ apiKey: process.env.KIORI_API_KEY });
+
+// Once per character: a brain from its card (a Tavern/SillyTavern card, or name and description)
+let brain = await kiori.create({ character_card: card });
+
+// Every turn: what the character knows right now, for your prompt (the recent messages are enough)
+const recent = messages.slice(-60);
+const { text, check_recommended } = await kiori.recall({ brain, messages: recent });
+let reply = await yourModel({ system: `${yourCharacterPrompt}\n\n${text}`, messages });
+
+// Optional: when the player brings up the past, check the draft before it's shown
+if (check_recommended) reply = (await kiori.check({ brain, messages: recent, draft: reply })).fixed;
+
+// After the reply: the brain learns from the chat. Keep the brain that comes back
+messages.push({ role: 'assistant', content: reply });
+({ brain } = await kiori.organize({ brain, messages: messages.slice(-60) }));
+```
+
+The package is ESM only. From CommonJS, load it with `const { Kiori } = await import('kiori')`.
+
+The client also runs in a browser, since all it needs is `fetch`. But a Kiori key inside a public web page is a key anyone can take: call Kiori from your server, or use a key that belongs to the person using the page, the way the SillyTavern extension does.
+
+## Quickstart: Python
+
+```python
+import os
+from kiori import Kiori
+
+kiori = Kiori(os.environ["KIORI_API_KEY"])
+
+# Once per character: a brain from its card (a dict, or a card PNG in base64)
+brain = kiori.create(character_card=card)
+
+# Every turn: what the character knows right now, for your prompt (the recent messages are enough)
+recent = messages[-60:]
+context = kiori.recall(brain=brain, messages=recent)
+reply = your_model(system=your_character_prompt + "\n\n" + context["text"], messages=messages)
+
+# Optional: when the player brings up the past, check the draft before it's shown
+if context["check_recommended"]:
+    reply = kiori.check(draft=reply, brain=brain, messages=recent)["fixed"]
+
+# After the reply: the brain learns from the chat. Keep the brain that comes back
+messages.append({"role": "assistant", "content": reply})
+brain = kiori.organize(brain=brain, messages=messages[-60:])["brain"]
+```
+
+The Python calls take keyword arguments named like the API's fields, and return plain dicts.
+
+## Messages
+
+Messages are OpenAI-style: `{ "id": "m41", "role": "user", "content": "..." }`, oldest first. For `organize`, send the conversation's recent messages as they are now (the last 60 is a good amount: at least the last 30, not only the new ones, and at most 400), with your own message ids if you have them, so that edits and rerolls are noticed and unlearned. Always keep the brain that comes back, even when nothing was learned.
+
+## Group chats
+
+Send every character's brain at once: `brains` instead of `brain`. Answers come back in the same order, and each brain learns only the scenes its character was in. Messages from characters carry their name: `{ role: "assistant", name: "Rook", content: "..." }`.
+
+```js
+[mira, rook] = (await kiori.organize({ brains: [mira, rook], messages, player: 'Leo' })).brains;
+```
+
+```python
+mira, rook = kiori.organize(brains=[mira, rook], messages=messages, player="Leo")["brains"]
+```
+
+## All calls
+
+| JavaScript | Python | |
+|---|---|---|
+| `create({...})` | `create(...)` | a new brain: from `character_card`, or from `name`, `description` and `lore`. `depth: "full"` (default; a whole past, about a minute, on your brain API key) or `"light"` (from the card alone, free, at once) |
+| `recall({...})` | `recall(...)` | what each character knows right now: `text` (one brain), `characters`, `check_recommended` |
+| `organize({...})` | `organize(...)` | the brain learns from the chat: `brain` (or `brains`), `learned`, `rewound`, `waiting` |
+| `check({...})` | `check(draft, ...)` | a draft reply checked against what each character knows: `ok`, `issues`, `fixed` |
+| `exportObsidian(brain)` | `export_obsidian(brain)` | the brain as an Obsidian vault, as zip bytes |
+| `personality()` | `personality()` | the 41 personality dimensions and the archetypes |
+| `project.get()`, `project.update({...})`, `project.models()`, `project.usage(days)` | `project.get()`, `project.update(...)`, `project.models()`, `project.usage(days)` | your project, its brain API key and model, its usage |
+| `project.keys.create(label)`, `project.keys.revoke(prefix)` | `project.create_key(label)`, `project.revoke_key(prefix)` | Kiori keys |
+
+Changing the project (`project.update`, and making or revoking keys) takes an owner key: the one the console makes when you sign in with your link. The keys you make for your app can do everything else, so a key that leaks from your app can't move the project's calls elsewhere or take your keys away.
+
+## Options
+
+| JavaScript | Python | Default | |
+|---|---|---|---|
+| `apiKey` | `api_key` (the first argument) | | your Kiori key |
+| `baseUrl` | `base_url` | `https://api.kiori.io` | another Kiori, for example one you host yourself |
+| `timeout` | `timeout` | 150000 ms in JavaScript, 150 s in Python | per request; building a full brain takes about a minute |
+| `maxRetries` | `max_retries` | `2` | see Retries; `0` turns them off |
+
+## Retries
+
+Every brain call is safe to repeat, since Kiori keeps nothing between calls. So both clients ask again on their own, twice at most, when Kiori or your model provider is briefly unavailable or out of reach (408, 429, 502, 503 and the like, or a network error): after `Retry-After` when Kiori sends one (up to 20 s), else after about 1 s, then 2 s.
+
+They don't ask again after a timeout (a full brain may still be building), for a missing or refused brain API key, when your provider is out of credits, or when the model's answers stayed unusable after Kiori's own tries (`INCOMPLETE`). Nor when Kiori asks to wait longer than 20 s: the error then carries the wait as `retryAfter` (JavaScript) or `retry_after` (Python).
+
+`maxRetries` (JavaScript) or `max_retries` (Python) changes how many times; `0` turns retries off:
+
+```js
+const kiori = new Kiori({ apiKey: process.env.KIORI_API_KEY, maxRetries: 0 });
+```
+
+```python
+kiori = Kiori(os.environ["KIORI_API_KEY"], max_retries=0)
+```
+
+## Errors
+
+A failed call raises `KioriError` (`import { KioriError } from 'kiori'`, `from kiori import KioriError`), with:
+
+- `status`: the HTTP status, or `0` when Kiori couldn't be reached (code `NETWORK`) or didn't answer in time (code `TIMEOUT`)
+- `code`: for example `UNAUTHORIZED` (a wrong Kiori key), `NEEDS_KEY`, `BAD_KEY` and `CREDITS` (your brain API key is missing, refused, or out of credits), `RATE_LIMITED`, `PROVIDER`, `BAD_BRAIN`, and `REDIRECT` (the address answered with a redirect, which Kiori never sends: the clients don't follow one, so your key and brains don't go where it leads; check the base URL)
+- `retryAfter` (JavaScript) or `retry_after` (Python): the seconds Kiori asked to wait, when it did
+- `requestId` (JavaScript) or `request_id` (Python): the call's id, to quote when you write to us about it
+
+A failed organize changes nothing: keep the brain you had, and the next call picks up where it left off. All the codes are in the [error table](https://kiori.io/docs/api#errors).
+
+## Learn more
+
+- [Integration guide](https://kiori.io/docs/integration): the calls, keeping brains, group chats, the drop-in, SillyTavern
+- [Concepts](https://kiori.io/docs/concepts): the brain file, presence, organizer, auditor, sleep
+- [API reference](https://kiori.io/docs/api), and [openapi.json](https://kiori.io/openapi.json) to generate a client in another language
+- [kiori.io](https://kiori.io)
+
+## License
+
+MIT. The full text is in the LICENSE file that comes with the package. The license covers these client files, not the Kiori service.

kiori_ai-2.0.0/kiori.py

@@ -0,0 +1,226 @@
+"""Kiori Python client. Python 3.8+, no dependencies.
+
+Kiori stores no brains and no chats. A brain is a dict you keep (in your database, or on your player's device) and
+send with each call; calls that change it give it back.
+
+    from kiori import Kiori
+    kiori = Kiori(os.environ["KIORI_API_KEY"])
+
+    # once per character: a brain from its card; keep it, and start each new conversation from a copy of it
+    brain = kiori.create(character_card=card)
+
+    # every turn: what the character knows right now, for your prompt (messages OpenAI-style, with your ids; the
+    # recent ones are enough)
+    recent = messages[-60:]
+    context = kiori.recall(brain=brain, messages=recent)
+    system_prompt += "\\n\\n" + context["text"]
+
+    # after the reply: the brain learns from the chat; keep the brain that comes back
+    brain = kiori.organize(brain=brain, messages=messages[-60:])["brain"]
+
+    # optionally, when context["check_recommended"]: let the auditor check your model's draft
+    verdict = kiori.check(brain=brain, messages=recent, draft=reply)
+
+A call is asked again on its own (twice at most) when Kiori or the model provider is briefly unavailable or out of
+reach. That's safe: Kiori keeps nothing between calls, so the same brain in gives the same kind of brain out.
+"""
+import email.utils
+import http.client
+import json
+import random
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__all__ = ["Kiori", "KioriError"]
+
+
+class KioriError(Exception):
+    """status is the HTTP status, or 0 when Kiori couldn't be reached (code NETWORK) or didn't answer in time (TIMEOUT);
+    retry_after is the seconds Kiori asked to wait (Retry-After), when it did; request_id is the call's id, to quote
+    when you write to us about it."""
+
+    def __init__(self, status, message, code=None, retry_after=None, request_id=None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+        self.request_id = request_id
+
+
+def _seconds_after(value):
+    """Retry-After in seconds (it's seconds, or a date); None when there is none."""
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        return max(0.0, email.utils.parsedate_to_datetime(value).timestamp() - time.time())
+    except (TypeError, ValueError):
+        return None
+
+
+# Asked again: Kiori or the model provider was busy or briefly down (or a gateway in front of them failed), or Kiori
+# was out of reach. Not a timeout (the work may still be going on), not a key or credit problem, not answers that
+# stayed unusable after Kiori's own tries (INCOMPLETE), and not when Kiori asks to wait more than 20 seconds. A call
+# that isn't safe to repeat (a new key) is asked again only after a 429.
+_AGAIN = {408, 429, 502, 503, 520, 521, 522, 523, 530}
+_FINAL = {"NEEDS_KEY", "NO_KEY", "BAD_KEY", "CREDITS", "INCOMPLETE"}
+
+
+def _retry_delay(e, attempt, safe):
+    if e.code == "NETWORK":
+        again = safe
+    else:
+        again = e.status in _AGAIN and e.code not in _FINAL and (safe or e.status == 429)
+    if not again:
+        return None
+    if e.retry_after is not None:
+        return e.retry_after if e.retry_after <= 20 else None
+    return 2 ** attempt * random.uniform(0.75, 1.25)
+
+
+def _id(value):
+    return urllib.parse.quote(str(value), safe="")
+
+
+def _q(**params):
+    pairs = {k: v for k, v in params.items() if v is not None}
+    return "?" + urllib.parse.urlencode(pairs) if pairs else ""
+
+
+class _Project:
+    def __init__(self, client):
+        self._c = client
+
+    def get(self):
+        return self._c.request("GET", "/v1/project")
+
+    def update(self, **body):
+        """name=..., llm={"key": ...} (your brain API key: the provider is recognized from it), llm={"model": ...}."""
+        return self._c.request("PATCH", "/v1/project", body)
+
+    def models(self):
+        """The models your brain API key can use, the suggested one first."""
+        return self._c.request("GET", "/v1/project/models")
+
+    def usage(self, days=None):
+        return self._c.request("GET", "/v1/usage" + _q(days=days))
+
+    def create_key(self, label=None):
+        """A new API key for this project (shown once)."""
+        return self._c.request("POST", "/v1/project/keys", {"label": label}, safe=False)
+
+    def revoke_key(self, prefix):
+        return self._c.request("DELETE", "/v1/project/keys/" + _id(prefix))
+
+
+def _brains(brain, brains):
+    if (brain is None) == (brains is None):
+        raise ValueError("Kiori: send brain= (one) or brains= (a group chat)")
+    return {"brain": brain} if brain is not None else {"brains": brains}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # Kiori never redirects: a redirect means base_url leads somewhere else, and following it would send the key (and
+    # the brain) there. Turned down, it comes back as the HTTPError of its status.
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+_open = urllib.request.build_opener(_NoRedirect).open
+
+
+class Kiori:
+    def __init__(self, api_key, base_url="https://api.kiori.io", timeout=150, max_retries=2):
+        """timeout: seconds per request before giving up (code TIMEOUT); building a full brain takes about a minute.
+        max_retries: how many times a call is asked again when Kiori or the model provider is briefly unavailable
+        (after Retry-After, else about 1 s, then 2 s); 0 never."""
+        if not api_key:
+            raise ValueError("Kiori: api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.project = _Project(self)
+
+    def create(self, **body):
+        """A new brain. character_card= takes a Tavern v1/v2/v3 card (dict, or a PNG in base64); or name=,
+        description=, lore=. depth="full" (a whole past, about a minute, on your brain API key) or "light" (free)."""
+        return self.request("POST", "/v1/brains", body)["brain"]
+
+    def recall(self, brain=None, brains=None, messages=None, **options):
+        """What each character knows right now: {"text" (one brain), "characters", "check_recommended"}."""
+        return self.request("POST", "/v1/brains/recall", dict(options, messages=messages, **_brains(brain, brains)))
+
+    def organize(self, messages, brain=None, brains=None, **options):
+        """The chat moved on: {"brain" (or "brains"), "learned", "rewound", "waiting"}. Send the recent messages as
+        they are now, oldest first, with your message ids if you have them, and keep what comes back.
+        Options: player=, hold= (newest messages left for later, default 4), every= (learn once this many settled
+        messages are new, default 12), now=True."""
+        return self.request("POST", "/v1/brains/organize", dict(options, messages=messages, **_brains(brain, brains)))
+
+    def check(self, draft, brain=None, brains=None, messages=None, **options):
+        """A draft reply checked against what each character knows: {"ok", "issues", "fixed"}."""
+        return self.request("POST", "/v1/brains/check", dict(options, draft=draft, messages=messages, **_brains(brain, brains)))
+
+    def export_obsidian(self, brain):
+        """A brain as an Obsidian vault: the zip's bytes."""
+        return self.request("POST", "/v1/brains/export", {"brain": brain}, raw=True)
+
+    def personality(self):
+        """The 41 personality dimensions and the archetypes."""
+        return self.request("GET", "/v1/personality")
+
+    def request(self, method, path, body=None, raw=False, safe=True):
+        """safe=False for a call that isn't safe to repeat (see _retry_delay)."""
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        attempt = 0
+        while True:
+            try:
+                payload = self._send(method, path, data)
+                break
+            except KioriError as e:
+                wait = _retry_delay(e, attempt, safe) if attempt < self.max_retries else None
+                if wait is None:
+                    raise
+                time.sleep(wait)
+                attempt += 1
+        if raw:
+            return payload
+        return json.loads(payload.decode("utf-8")) if payload else None
+
+    def _send(self, method, path, data):
+        req = urllib.request.Request(self.base_url + path, data=data, method=method)
+        req.add_header("Authorization", "Bearer " + self.api_key)
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with _open(req, timeout=self.timeout) as res:
+                return res.read()
+        except urllib.error.HTTPError as e:
+            if 300 <= e.code < 400:
+                raise KioriError(e.code, "%s answered with a redirect, and Kiori never redirects: check base_url"
+                                 % self.base_url, "REDIRECT") from None
+            try:
+                err = json.loads(e.read().decode("utf-8")).get("error") or {}
+            except Exception:
+                err = {}
+            if not isinstance(err, dict):
+                err = {}
+            message = err.get("message") or "HTTP %d" % e.code
+            raise KioriError(e.code, message, err.get("code"), _seconds_after(e.headers.get("Retry-After")),
+                             err.get("request_id") or e.headers.get("X-Request-Id")) from None
+        except (socket.timeout, TimeoutError):
+            raise KioriError(0, "Kiori did not answer within %ss" % self.timeout, "TIMEOUT") from None
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, (socket.timeout, TimeoutError)):
+                raise KioriError(0, "Kiori did not answer within %ss" % self.timeout, "TIMEOUT") from None
+            raise KioriError(0, "Can't reach Kiori at %s (%s)" % (self.base_url, e.reason), "NETWORK") from None
+        except (http.client.HTTPException, OSError) as e:
+            # The connection dropped after the request went out, or the answer was cut off halfway
+            raise KioriError(0, "Can't reach Kiori at %s (%s)" % (self.base_url, type(e).__name__), "NETWORK") from None

kiori_ai-2.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+# Kiori's Python client on PyPI. The distribution is "kiori-ai" (the name "kiori" on PyPI belongs to an unrelated
+# project); the module stays kiori.py, so it's `pip install kiori-ai`, then `from kiori import Kiori`.
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kiori-ai"
+version = "2.0.0"
+description = "The Python client for Kiori, brains for characters: memory, personality and who-knows-what for character AI. No dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kiori" }]
+keywords = [
+    "kiori",
+    "character ai",
+    "ai characters",
+    "memory",
+    "llm memory",
+    "long-term memory",
+    "personality",
+    "roleplay",
+    "npc",
+    "chatbot",
+    "llm",
+    "sillytavern",
+    "character card",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Games/Entertainment :: Role-Playing",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://kiori.io"
+Documentation = "https://kiori.io/docs"
+Source = "https://github.com/kiori-ai/kiori/tree/main/sdk"
+Issues = "https://github.com/kiori-ai/kiori/issues"
+
+# One module, kiori.py. The JavaScript files next to it belong to the npm package and stay out of the wheel and the
+# sdist (the sdist also always carries pyproject.toml, the readme and the license).
+[tool.hatch.build.targets.wheel]
+only-include = ["kiori.py"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["kiori.py"]