mykitt 0.1.0__tar.gz

mykitt-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+node_modules
+dist
+dist-ssr
+*.local
+.DS_Store
+.vite
+*.log
+
+# Local secrets
+.env
+.env.local
+.env.*.local
+
+# Test results
+test-results
+playwright-report
+
+# Python
+__pycache__
+*.egg-info

mykitt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PT Aplikasi Naratifs Indonesia
+
+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.

mykitt-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: mykitt
+Version: 0.1.0
+Summary: Kitt's own library for Kitt Platform: Kitt 1 Mini, Kitt 1 and Kitt Auto from Python.
+Project-URL: Homepage, https://platform.mykitt.id
+Project-URL: Documentation, https://platform.mykitt.id/#docs
+Project-URL: Source, https://github.com/Naratifs/My-Kitt/tree/main/sdk/python
+Author-email: PT Aplikasi Naratifs Indonesia <corporate@naratifs.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,chat completions,kitt,llm,mykitt,naratifs
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# mykitt
+
+Kitt's own library for [Kitt Platform](https://platform.mykitt.id): Kitt 1 Mini, Kitt 1 and Kitt Auto from Python.
+It uses only Python's own library (3.8+).
+
+```sh
+pip install mykitt
+```
+
+```python
+from mykitt import Kitt
+
+kitt = Kitt()  # reads KITT_API_KEY
+
+answer = kitt.chat.completions.create(
+    model="kitt-1-mini",
+    messages=[{"role": "user", "content": "Halo, Kitt!"}],
+)
+print(answer.choices[0].message.content)
+```
+
+Make a key under API Keys at [platform.mykitt.id](https://platform.mykitt.id) and keep it on your server, never in a
+web page or a phone app.
+
+## Streaming
+
+```python
+stream = kitt.chat.completions.create(
+    model="kitt-1-mini",
+    messages=[{"role": "user", "content": "Tell me about Naratifs."}],
+    stream=True,
+)
+for chunk in stream:
+    if chunk.choices:
+        print(chunk.choices[0].delta.get("content") or "", end="")
+```
+
+The last chunk carries the usage. `stream.close()` stops it.
+
+## Models
+
+```python
+for model in kitt.models.list().data:
+    print(model.id, model.name)
+```
+
+| Model       | ID            | What it is for                                                       |
+| ----------- | ------------- | -------------------------------------------------------------------- |
+| Kitt 1 Mini | `kitt-1-mini` | Does everything Kitt does, quickly and at the lowest price.          |
+| Kitt 1      | `kitt-1`      | Reasons more for heavy work; an answer takes about 20 times the credits. |
+| Kitt Auto   | `kitt-auto`   | Picks the model for each request; the answer names the one it ran on. |
+
+Prices are listed by `models.list()` and on [platform.mykitt.id](https://platform.mykitt.id), taken from your Kitt credits.
+
+## Errors
+
+A failed call raises `KittError` with `status`, `code` (such as `invalid_api_key` or `insufficient_credits`) and
+`request_id`, to quote when you write to us. A 429 or 5xx is tried again twice, waiting longer each time
+(`max_retries`).
+
+```python
+from mykitt import Kitt, KittError
+
+try:
+    kitt.chat.completions.create(model="kitt-1-mini", messages=messages)
+except KittError as e:
+    print(e.status, e.code, e.request_id, e.message)
+```
+
+## Options
+
+`Kitt(api_key=None, base_url=None, timeout=600, max_retries=2, headers=None)`. The base URL is
+`https://api.mykitt.id/v1`. Answers read as attributes or as dicts (`answer.to_dict()`).
+
+Already using another library that speaks Chat Completions? Point it at the same base URL with your Kitt key.
+
+MIT licence, © PT Aplikasi Naratifs Indonesia.

mykitt-0.1.0/README.md

@@ -0,0 +1,77 @@
+# mykitt
+
+Kitt's own library for [Kitt Platform](https://platform.mykitt.id): Kitt 1 Mini, Kitt 1 and Kitt Auto from Python.
+It uses only Python's own library (3.8+).
+
+```sh
+pip install mykitt
+```
+
+```python
+from mykitt import Kitt
+
+kitt = Kitt()  # reads KITT_API_KEY
+
+answer = kitt.chat.completions.create(
+    model="kitt-1-mini",
+    messages=[{"role": "user", "content": "Halo, Kitt!"}],
+)
+print(answer.choices[0].message.content)
+```
+
+Make a key under API Keys at [platform.mykitt.id](https://platform.mykitt.id) and keep it on your server, never in a
+web page or a phone app.
+
+## Streaming
+
+```python
+stream = kitt.chat.completions.create(
+    model="kitt-1-mini",
+    messages=[{"role": "user", "content": "Tell me about Naratifs."}],
+    stream=True,
+)
+for chunk in stream:
+    if chunk.choices:
+        print(chunk.choices[0].delta.get("content") or "", end="")
+```
+
+The last chunk carries the usage. `stream.close()` stops it.
+
+## Models
+
+```python
+for model in kitt.models.list().data:
+    print(model.id, model.name)
+```
+
+| Model       | ID            | What it is for                                                       |
+| ----------- | ------------- | -------------------------------------------------------------------- |
+| Kitt 1 Mini | `kitt-1-mini` | Does everything Kitt does, quickly and at the lowest price.          |
+| Kitt 1      | `kitt-1`      | Reasons more for heavy work; an answer takes about 20 times the credits. |
+| Kitt Auto   | `kitt-auto`   | Picks the model for each request; the answer names the one it ran on. |
+
+Prices are listed by `models.list()` and on [platform.mykitt.id](https://platform.mykitt.id), taken from your Kitt credits.
+
+## Errors
+
+A failed call raises `KittError` with `status`, `code` (such as `invalid_api_key` or `insufficient_credits`) and
+`request_id`, to quote when you write to us. A 429 or 5xx is tried again twice, waiting longer each time
+(`max_retries`).
+
+```python
+from mykitt import Kitt, KittError
+
+try:
+    kitt.chat.completions.create(model="kitt-1-mini", messages=messages)
+except KittError as e:
+    print(e.status, e.code, e.request_id, e.message)
+```
+
+## Options
+
+`Kitt(api_key=None, base_url=None, timeout=600, max_retries=2, headers=None)`. The base URL is
+`https://api.mykitt.id/v1`. Answers read as attributes or as dicts (`answer.to_dict()`).
+
+Already using another library that speaks Chat Completions? Point it at the same base URL with your Kitt key.
+
+MIT licence, © PT Aplikasi Naratifs Indonesia.

mykitt-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mykitt"
+version = "0.1.0"
+description = "Kitt's own library for Kitt Platform: Kitt 1 Mini, Kitt 1 and Kitt Auto from Python."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.8"
+authors = [{ name = "PT Aplikasi Naratifs Indonesia", email = "corporate@naratifs.com" }]
+keywords = ["kitt", "mykitt", "naratifs", "ai", "llm", "chat completions"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://platform.mykitt.id"
+Documentation = "https://platform.mykitt.id/#docs"
+Source = "https://github.com/Naratifs/My-Kitt/tree/main/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mykitt"]

mykitt-0.1.0/src/mykitt/__init__.py

@@ -0,0 +1,18 @@
+"""mykitt: Kitt's own library for Kitt Platform (https://platform.mykitt.id).
+
+    from mykitt import Kitt
+
+    kitt = Kitt()  # reads KITT_API_KEY
+    answer = kitt.chat.completions.create(
+        model="kitt-1-mini",
+        messages=[{"role": "user", "content": "Halo, Kitt!"}],
+    )
+    print(answer.choices[0].message.content)
+
+Only Python's own library is used.
+"""
+
+from ._client import DEFAULT_BASE_URL, Kitt, KittError, Stream, KittObject
+
+__version__ = "0.1.0"
+__all__ = ["Kitt", "KittError", "Stream", "KittObject", "DEFAULT_BASE_URL", "__version__"]

mykitt-0.1.0/src/mykitt/_client.py

@@ -0,0 +1,187 @@
+"""The client: Chat Completions and the models, over Python's own urllib."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Iterator, List, Optional
+
+DEFAULT_BASE_URL = "https://api.mykitt.id/v1"
+_VERSION = "0.1.0"
+
+
+class KittObject(dict):
+    """An answer from the API: read it as attributes (answer.choices[0].message.content) or as a dict."""
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return json.loads(json.dumps(self))
+
+
+def _wrap(value: Any) -> Any:
+    if isinstance(value, dict):
+        return KittObject({k: _wrap(v) for k, v in value.items()})
+    if isinstance(value, list):
+        return [_wrap(v) for v in value]
+    return value
+
+
+class KittError(Exception):
+    """What the API said went wrong, with its status, code and the request's id to quote."""
+
+    def __init__(self, status: int, message: str, code: str, request_id: Optional[str]) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.message = message
+
+
+def _error_of(status: int, text: str, request_id: Optional[str]) -> KittError:
+    message = text or f"Kitt's API answered {status}."
+    code = "api_error"
+    try:
+        said = json.loads(text)
+        error = said.get("error") if isinstance(said, dict) else None
+        if isinstance(error, str):
+            message = error
+        elif isinstance(error, dict):
+            message = error.get("message") or message
+            code = error.get("code") or error.get("type") or code
+    except ValueError:
+        pass
+    return KittError(status, message, code, request_id)
+
+
+class Stream:
+    """A streamed answer: read it with a for loop, or stop it with close()."""
+
+    def __init__(self, response: Any) -> None:
+        self._response = response
+        self.request_id: Optional[str] = response.headers.get("x-request-id")
+        # The model that answers: for kitt-auto, the one it picked.
+        self.model: Optional[str] = response.headers.get("x-kitt-model")
+
+    def __iter__(self) -> Iterator[KittObject]:
+        try:
+            for raw in self._response:
+                line = raw.decode("utf-8").rstrip("\r\n")
+                if not line.startswith("data:"):
+                    continue
+                event = line[5:].strip()
+                if event == "[DONE]":
+                    return
+                yield _wrap(json.loads(event))
+        finally:
+            self.close()
+
+    def close(self) -> None:
+        self._response.close()
+
+    def __enter__(self) -> "Stream":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+
+class Kitt:
+    """Kitt Platform's client.
+
+    api_key: your key from platform.mykitt.id; read from KITT_API_KEY when left out.
+    timeout: seconds before a request gives up (default 600).
+    max_retries: tries after a 429 or a 5xx, waiting longer each time (default 2).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 600.0,
+        max_retries: int = 2,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        key = api_key or os.environ.get("KITT_API_KEY")
+        if not key:
+            raise KittError(401, "No API key: pass api_key or set KITT_API_KEY. Make one at https://platform.mykitt.id.", "invalid_api_key", None)
+        self._key = key
+        self.base_url = (base_url or os.environ.get("KITT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._headers = headers or {}
+        self.chat = _Chat(self)
+        self.models = _Models(self)
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None) -> Any:
+        """One call to the API, tried again after a 429 or a 5xx; answers the open response once it is ok."""
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        attempt = 0
+        while True:
+            request = urllib.request.Request(
+                self.base_url + path,
+                data=data,
+                method=method,
+                headers={
+                    "Authorization": f"Bearer {self._key}",
+                    "Content-Type": "application/json",
+                    "User-Agent": f"mykitt-python/{_VERSION}",
+                    **self._headers,
+                },
+            )
+            try:
+                return urllib.request.urlopen(request, timeout=timeout or self.timeout)
+            except urllib.error.HTTPError as e:
+                if (e.code == 429 or e.code >= 500) and attempt < self.max_retries:
+                    after = e.headers.get("retry-after")
+                    e.close()
+                    time.sleep(min(float(after), 30.0) if after and after.replace(".", "", 1).isdigit() and float(after) > 0 else 0.5 * 2**attempt)
+                    attempt += 1
+                    continue
+                text = e.read().decode("utf-8", "replace")
+                raise _error_of(e.code, text, e.headers.get("x-request-id")) from None
+            except (urllib.error.URLError, TimeoutError, OSError) as e:
+                if attempt < self.max_retries:
+                    time.sleep(0.5 * 2**attempt)
+                    attempt += 1
+                    continue
+                raise KittError(0, f"Kitt's API could not be reached: {e}", "connection_error", None) from None
+
+
+class _Completions:
+    def __init__(self, kitt: Kitt) -> None:
+        self._kitt = kitt
+
+    def create(self, *, model: str, messages: List[Dict[str, Any]], stream: bool = False, timeout: Optional[float] = None, **fields: Any) -> Any:
+        """Ask a Kitt model. With stream=True, a Stream of chunks, its usage on the last one."""
+        body: Dict[str, Any] = {"model": model, "messages": messages, **fields}
+        if stream:
+            body["stream"] = True
+            body.setdefault("stream_options", {"include_usage": True})
+        response = self._kitt._request("POST", "/chat/completions", body, timeout)
+        if stream:
+            return Stream(response)
+        with response:
+            return _wrap(json.loads(response.read().decode("utf-8")))
+
+
+class _Chat:
+    def __init__(self, kitt: Kitt) -> None:
+        self.completions = _Completions(kitt)
+
+
+class _Models:
+    def __init__(self, kitt: Kitt) -> None:
+        self._kitt = kitt
+
+    def list(self) -> KittObject:
+        """Kitt's models, with what each is for and its price."""
+        with self._kitt._request("GET", "/models") as response:
+            return _wrap(json.loads(response.read().decode("utf-8")))

mykitt-0.1.0/tests/test_client.py

@@ -0,0 +1,121 @@
+"""The library against a stand-in for Kitt's API on this machine."""
+
+import json
+import os
+import sys
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from mykitt import Kitt, KittError  # noqa: E402
+
+SEEN = []
+BUSY = {"left": 1}
+
+
+class FakeApi(BaseHTTPRequestHandler):
+    def log_message(self, *_):
+        pass
+
+    def send(self, status, body, kind="application/json", extra=None):
+        self.send_response(status)
+        self.send_header("Content-Type", kind)
+        self.send_header("x-request-id", "req_test")
+        for k, v in (extra or {}).items():
+            self.send_header(k, v)
+        self.end_headers()
+        self.wfile.write(body.encode("utf-8"))
+
+    def do_GET(self):
+        SEEN.append({"path": self.path, "auth": self.headers.get("Authorization")})
+        self.send(200, json.dumps({"object": "list", "data": [{"id": "kitt-1-mini", "object": "model", "name": "Kitt 1 Mini"}]}))
+
+    def do_POST(self):
+        ask = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+        SEEN.append({"path": self.path, "auth": self.headers.get("Authorization"), "body": ask})
+        if self.headers.get("Authorization") != "Bearer sk-kitt-good":
+            return self.send(401, json.dumps({"error": {"message": "The key is missing, wrong or revoked.", "type": "invalid_api_key", "code": "invalid_api_key"}}))
+        if ask["messages"][0]["content"] == "busy" and BUSY["left"] > 0:
+            BUSY["left"] -= 1
+            return self.send(503, '{"error":{"message":"busy","code":"upstream_error"}}', extra={"retry-after": "0"})
+        if ask.get("stream"):
+            chunks = [
+                {"id": "c1", "object": "chat.completion.chunk", "model": "kitt-1-mini", "choices": [{"index": 0, "delta": {"content": w}, "finish_reason": None}]}
+                for w in ("Ha", "lo")
+            ]
+            chunks.append({"id": "c1", "object": "chat.completion.chunk", "model": "kitt-1-mini", "choices": [], "usage": {"prompt_tokens": 3, "completion_tokens": 2, "total_tokens": 5}})
+            body = "".join(f"data: {json.dumps(c)}\n\n" for c in chunks) + "data: [DONE]\n\n"
+            return self.send(200, body, "text/event-stream", {"x-kitt-model": "kitt-1-mini"})
+        model = "kitt-1-mini" if ask["model"] == "kitt-auto" else ask["model"]
+        self.send(200, json.dumps({
+            "id": "c1", "object": "chat.completion", "created": 1, "model": model,
+            "choices": [{"index": 0, "message": {"role": "assistant", "content": "Halo!"}, "finish_reason": "stop"}],
+            "usage": {"prompt_tokens": 3, "completion_tokens": 2, "total_tokens": 5},
+        }))
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), FakeApi)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_address[1]}/v1"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def kitt(self, key="sk-kitt-good"):
+        return Kitt(api_key=key, base_url=self.base)
+
+    def test_answers_a_message(self):
+        answer = self.kitt().chat.completions.create(model="kitt-auto", messages=[{"role": "user", "content": "Halo, Kitt!"}])
+        self.assertEqual(answer.choices[0].message.content, "Halo!")
+        self.assertEqual(answer["model"], "kitt-1-mini")
+        self.assertEqual(SEEN[-1]["path"], "/v1/chat/completions")
+        self.assertEqual(SEEN[-1]["auth"], "Bearer sk-kitt-good")
+
+    def test_streams_an_answer_with_its_usage(self):
+        stream = self.kitt().chat.completions.create(model="kitt-1-mini", messages=[{"role": "user", "content": "Halo"}], stream=True)
+        self.assertEqual(stream.model, "kitt-1-mini")
+        text, usage = "", None
+        for chunk in stream:
+            if chunk.choices:
+                text += chunk.choices[0].delta.get("content", "")
+            if chunk.get("usage"):
+                usage = chunk.usage
+        self.assertEqual(text, "Halo")
+        self.assertEqual(usage.total_tokens, 5)
+        self.assertEqual(SEEN[-1]["body"]["stream_options"], {"include_usage": True})
+
+    def test_lists_the_models(self):
+        self.assertEqual(self.kitt().models.list().data[0].id, "kitt-1-mini")
+
+    def test_says_what_went_wrong(self):
+        with self.assertRaises(KittError) as caught:
+            self.kitt("sk-kitt-bad").chat.completions.create(model="kitt-1-mini", messages=[{"role": "user", "content": "x"}])
+        self.assertEqual(caught.exception.status, 401)
+        self.assertEqual(caught.exception.code, "invalid_api_key")
+        self.assertEqual(caught.exception.request_id, "req_test")
+
+    def test_tries_again_when_busy(self):
+        answer = self.kitt().chat.completions.create(model="kitt-1-mini", messages=[{"role": "user", "content": "busy"}])
+        self.assertEqual(answer.choices[0].message.content, "Halo!")
+
+    def test_needs_a_key(self):
+        kept = os.environ.pop("KITT_API_KEY", None)
+        try:
+            with self.assertRaises(KittError):
+                Kitt(base_url=self.base)
+            os.environ["KITT_API_KEY"] = "sk-kitt-good"
+            Kitt(base_url=self.base)
+        finally:
+            os.environ.pop("KITT_API_KEY", None)
+            if kept is not None:
+                os.environ["KITT_API_KEY"] = kept
+
+
+if __name__ == "__main__":
+    unittest.main()