Initial commit

.github/workflows/build-and-publish.yml

@@ -0,0 +1,41 @@
+---
+
+name: Publish Python distributions to PyPI and TestPyPI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  validate:
+    name: Run static analysis on the code
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Lint with flake8
+        run: |
+          pip install flake8
+          # stop the build if there are Python syntax errors or undefined names
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          # exit-zero treats all errors as warnings.
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
+  build-and-publish:
+    name: Build and publish Python distribution
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@main
+      - name: Initialize Python 3.11
+        uses: actions/setup-python@v1
+        with:
+          python-version: 3.11
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip build
+      - name: Build binary wheel and a source tarball
+        run: python -m build 
+      - name: Publish distribution to PyPI
+        uses: pypa/[email protected] 
+        with:
+          password: ${{ secrets.PIPY_PASSWORD }}
+

README.md

@@ -0,0 +1,31 @@
+# Kaginawa
+
+![project icon](project_icon.png)
+
+An *unofficial* client to Kagi APIs
+
+## Installation
+
+```bash
+pip install kaginawa
+```
+
+## Usage
+
+```python
+from kaginawa.client import Kaginawa
+
+client = Kaginawa(token="YOUR_API_TOKEN")
+
+response: KaginawaResponse = client.generate(
+    "Write a logstash pipeline file to send a heartbeat to a server "
+    "https://example.com/heartbeat every 30 seconds"
+)
+
+print(response.output)
+
+for reference in response.references:
+    print(reference.title)
+    print(reference.snippet)
+    print(reference.url)
+```

kaginawa/__init__.py

@@ -0,0 +1,4 @@
+from pkg_resources import parse_version
+
+
+__version__ = parse_version("0.0.1")

kaginawa/client.py

@@ -0,0 +1,74 @@
+from typing import List
+from dataclasses import dataclass
+from datetime import timedelta
+
+import requests
+
+from kaginawa.exceptions import KaginawaError
+
+@dataclass
+class KaginawaReference:
+    title: str
+    snippet: str
+    url: str
+
+
+@dataclass
+class KaginawaResponse:
+    id: str
+    node: str
+    ms: timedelta
+    api_balance: float
+    output: str
+    tokens: int
+    references: List[KaginawaReference]
+
+
+class Kaginawa:
+    def __init__(
+        self,
+        token: str,
+        session: requests.Session | None = None,
+        api_base: str = "https://kagi.com/api",
+    ):
+        self.token = token
+        self.api_base = api_base
+
+        if not session:
+            session = requests.Session()
+
+        self.session = session
+
+        self.session.headers = {
+            "Authorization": f"Bot {self.token}"
+        }
+
+
+    def generate(self, query: str, cache: bool = True):
+        try:
+            res = self.session.post(
+                f"{self.api_base}/v0/fastgpt",
+                json={
+                    "query": query,
+                    "cache": cache,
+                },
+            )
+
+            print(res.json())
+            res.raise_for_status()
+
+            raw_response = res.json()
+        except requests.RequestException as e:
+            raise KaginawaError("Error calling /v0/fastgpt") from e
+
+        references = [
+            KaginawaReference(**ref)
+            for ref in raw_response["data"]["references"]
+        ]
+
+        raw_response["data"].pop("references")
+
+        return KaginawaResponse(
+            references=references,
+            **(raw_response["meta"] | raw_response["data"])
+        )

kaginawa/exceptions.py

@@ -0,0 +1,2 @@
+class KaginawaError(Exception):
+    pass

pyproject.toml

@@ -0,0 +1,50 @@
+# pyproject.toml
+# https://packaging.python.org/en/latest/specifications/declaring-project-metadata
+# https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml
+
+[build-system]
+requires = ["setuptools", "setuptools-scm", "build"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "kaginawa"
+description = "*Unofficial* client for the Kagi API"
+authors = [
+	{name = "Estelle Poulin", email = "[email protected]"},
+]
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = ["kaginawa"]
+license = {text = "GPLv3"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+dynamic = ["version", "dependencies"]
+
+
+[project.urls]
+homepage = "https://github.com/estheruary/kaginawa"
+repository = "https://github.com/estheruary/kaginawa"
+changelog = "https://github.com/estheruary/kaginawa/-/blob/main/CHANGELOG.md"
+
+
+[tool.setuptools]
+packages = ["kaginawa"]
+
+
+[tool.setuptools.dynamic]
+version = {attr = "kaginawa.__version__"}
+dependencies = {file = ["requirements.txt"]}
+
+
+[tool.black]
+line-length = 100
+
+
+[tool.isort]
+profile = "black"
+
+
+[tool.vulture]
+ignore_names = ["self", "cls"]

requirements.txt

@@ -0,0 +1,5 @@
+certifi==2023.7.22
+charset-normalizer==3.3.2
+idna==3.4
+requests==2.31.0
+urllib3==2.0.7