khai-sdk 0.1.0__tar.gz

khai_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,166 @@
+name: Release
+
+# Publish flow for the khai-sdk package. Triggered only by version tags (v1.2.3).
+#
+#   build ─► publish-testpypi ─► smoke-testpypi ─► publish-pypi ─► github-release
+#
+# Both publish jobs use PyPI Trusted Publishing: the job requests a short-lived
+# OIDC token (permissions: id-token: write) and PyPI accepts it because a
+# publisher for owner KHAI-BE / repo khai-python / workflow release.yml /
+# environment {testpypi,pypi} is registered there. No API token exists to leak.
+# The `pypi` environment requires a human reviewer, so a real release always
+# has an explicit approval step after the TestPyPI rehearsal has passed.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+env:
+  PACKAGE: khai-sdk
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check tag matches package version
+        id: version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg="$(python -c 'import re,pathlib; print(re.search(r"__version__\s*=\s*\"([^\"]+)\"", pathlib.Path("src/khai/_version.py").read_text()).group(1))')"
+          echo "tag=$tag package=$pkg"
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::Tag v$tag does not match src/khai/_version.py ($pkg)"; exit 1
+          fi
+          echo "version=$pkg" >> "$GITHUB_OUTPUT"
+
+      - name: Run tests
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pytest -q
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+          ls -l dist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/khai-sdk/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  smoke-testpypi:
+    name: Install from TestPyPI and import
+    needs: [build, publish-testpypi]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install the just-published version
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          # The TestPyPI simple index can lag the upload by a minute; retry.
+          for i in 1 2 3 4 5 6 7 8 9 10; do
+            if pip install --no-cache-dir \
+                 --index-url https://test.pypi.org/simple/ \
+                 --extra-index-url https://pypi.org/simple/ \
+                 "${PACKAGE}==${VERSION}"; then
+              break
+            fi
+            echo "not indexed yet, retry $i"; sleep 20
+          done
+      - name: Import and sanity-check
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          python - <<'PY'
+          import os
+          import khai
+          from khai import KhaiClient, KhaiConfigError, IngestTurn
+          assert khai.__version__ == os.environ["VERSION"], khai.__version__
+          t = IngestTurn("q", "a", "s")
+          assert t.response_id and t.timestamp
+          try:
+              KhaiClient(api_key="x", base_url="http://api.getkhai.ai")
+          except KhaiConfigError:
+              pass
+          else:
+              raise SystemExit("http base_url should be rejected")
+          print("ok", khai.__version__)
+          PY
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build, smoke-testpypi]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/khai-sdk/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: [build, publish-pypi]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create release with artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            --verify-tag

khai_sdk-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q
+      - name: Build sdist and wheel
+        run: pip install build && python -m build

khai_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.venv/
+.idea/
+.vscode/
+.DS_Store

khai_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to the Khai Python SDK. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow SemVer.
+
+## [Unreleased]
+
+### Added
+- Release pipeline (`.github/workflows/release.yml`): a `v*` tag builds once,
+  publishes to TestPyPI, smoke-installs from there, then publishes to PyPI via
+  trusted publishing (OIDC, no stored tokens) behind a required reviewer, and
+  creates a GitHub Release with the artifacts.
+- `IngestTurn` now fills `response_id` (UUID4) and `timestamp` (UTC ISO-8601) at
+  creation when the caller omits them, so retries are deduplicated server-side
+  instead of stored twice.
+- `KHAI_API_KEY` and `KHAI_BASE_URL` environment fallbacks; `api_key` and
+  `base_url` are optional constructor arguments.
+- `max_queue_size` (default 10,000) bounds the fire-and-forget queue and the
+  retry buffer. Drops are reported via `on_error` as the new `KhaiQueueFullError`.
+- Open clients are flushed once at interpreter exit.
+- `khai.__version__` is the single source of the version (hatch dynamic
+  version from `src/khai/_version.py`) and is stamped into the `User-Agent`.
+
+### Changed
+- Distribution name is `khai-sdk` (install with `pip install khai-sdk`, then
+  `import khai`). PyPI rejects `khai` as confusable with the existing `khal`
+  project, so the shorter name is not available.
+- `base_url` must be `https://`; `http://` is accepted only for localhost.
+- `close()` is idempotent.
+
+### Fixed
+- Error messages from the backend's auth and rate-limit layer were lost: those
+  responses use FastAPI's `{"detail": ...}` envelope, and the SDK only read
+  `{"error": ...}`. A rejected key surfaced as "request failed"; it now
+  surfaces as "Invalid or inactive API key." 422 validation lists are
+  flattened into one message.
+
+## [0.1.0] - 2026-08-04
+
+Initial hand-written SDK: `ingest_turn`, `ingest_batch`, `ingest_turn_async`,
+`set_redactor`, typed errors, retries with exponential backoff.

khai_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brise.ai
+
+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.

khai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: khai-sdk
+Version: 0.1.0
+Summary: Official Python SDK for streaming chatbot turns to Khai for evaluation.
+Project-URL: Homepage, https://getkhai.ai
+Project-URL: Source, https://github.com/KHAI-BE/khai-python
+Project-URL: Changelog, https://github.com/KHAI-BE/khai-python/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/KHAI-BE/khai-python/issues
+Author-email: Khai <support@getkhai.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chatbot,evaluation,khai,llm,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Khai Python SDK
+
+Stream chatbot turns to Khai for evaluation from any cloud — no access granted to Khai.
+
+## Install
+
+```bash
+pip install khai-sdk
+```
+
+## Quickstart
+
+Set your key in the environment rather than in source:
+
+```bash
+export KHAI_API_KEY="khai_..."
+```
+
+```python
+from khai import KhaiClient
+
+khai = KhaiClient()  # reads KHAI_API_KEY; base_url defaults to https://api.getkhai.ai
+
+resp = khai.ingest_turn(
+    user_query="How do I pay my bill?",
+    agent_response="You can pay online at ...",
+    session_id="chat-123",
+    agent_id="YOUR_AGENT_ID",
+)
+print(resp.status, resp.result.trust_score if resp.evaluated else resp.reason)
+```
+
+## Every turn is idempotent
+
+You do not have to think about retries. When you omit them, the SDK fills in a
+`timestamp` (UTC, ISO-8601) and a UUID `response_id` **when the turn is created**,
+and keeps them for every retry. The backend deduplicates on `response_id`, so a
+turn resent after a timeout, a 5xx, or a network outage is answered with
+`status: duplicate` instead of being stored twice.
+
+If your platform already has a per-reply id (Dialogflow `responseId`, Lex,
+Copilot Studio), pass it as `response_id` and the same guarantee holds even
+across restarts of your own process.
+
+## Fire-and-forget
+
+`ingest_turn_async` queues the turn and returns immediately, so it never blocks
+your chatbot's response path. Failed deliveries are buffered and retried. Both
+the queue and the buffer are capped at `max_queue_size` (default 10,000 turns);
+when full, the SDK drops a turn and reports it through `on_error` as
+`KhaiQueueFullError` rather than growing memory during an outage. Open clients
+are flushed once at interpreter exit.
+
+```python
+with KhaiClient() as khai:
+    khai.ingest_turn_async(
+        user_query=user_msg,
+        agent_response=bot_reply,
+        session_id=session_id,
+        agent_id="YOUR_AGENT_ID",
+    )
+    # ... keep serving; turns flush in the background, and on close().
+```
+
+## Batch
+
+```python
+from khai import IngestTurn
+
+khai.ingest_batch([
+    IngestTurn(user_query="...", agent_response="...", session_id="s1", agent_id="a1"),
+    IngestTurn(user_query="...", agent_response="...", session_id="s1", agent_id="a1"),
+])
+```
+
+## Redact PII before sending
+
+```python
+def redact(payload: dict) -> dict:
+    payload["user_query"] = mask_emails(payload["user_query"])
+    return payload
+
+khai.set_redactor(redact)
+```
+
+## Errors
+
+All errors derive from `KhaiError`:
+
+| Error | Meaning |
+|---|---|
+| `KhaiAuthError` | API key missing/invalid (401/403) |
+| `KhaiRateLimitError` | Per-key rate limit exceeded (429) |
+| `KhaiAPIError` | Other non-success status |
+| `KhaiConnectionError` | Network/timeout (already retried) |
+| `KhaiQueueFullError` | Fire-and-forget queue/buffer full; a turn was dropped (via `on_error`) |
+| `KhaiConfigError` | Bad client configuration (missing key, non-HTTPS base URL) |
+
+## Configuration
+
+| Setting | Argument | Environment variable | Default |
+|---|---|---|---|
+| API key | `api_key` | `KHAI_API_KEY` | required |
+| Base URL | `base_url` | `KHAI_BASE_URL` | `https://api.getkhai.ai` |
+| Request timeout (s) | `timeout` | — | `10.0` |
+| Retries on 429/5xx/network | `max_retries` | — | `3` |
+| Queue / buffer cap | `max_queue_size` | — | `10000` |
+
+`base_url` must be `https://`; plain `http://` is accepted only for `localhost`.
+
+## Releasing (maintainers)
+
+Releases are cut from tags and published by CI through PyPI trusted publishing;
+no one uploads from a laptop and no API token is stored anywhere.
+
+1. Bump `__version__` in `src/khai/_version.py` and move the `Unreleased`
+   entries in `CHANGELOG.md` under the new version. Merge via pull request.
+2. Tag the merged commit and push the tag:
+
+   ```bash
+   git tag v0.1.0 && git push origin v0.1.0
+   ```
+
+3. The `Release` workflow builds the sdist and wheel, publishes to TestPyPI,
+   installs from TestPyPI and imports the package, then waits for a reviewer to
+   approve the `pypi` environment before publishing to PyPI and creating the
+   GitHub Release. A tag whose version does not match `__version__` fails fast.

khai_sdk-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Khai Python SDK
+
+Stream chatbot turns to Khai for evaluation from any cloud — no access granted to Khai.
+
+## Install
+
+```bash
+pip install khai-sdk
+```
+
+## Quickstart
+
+Set your key in the environment rather than in source:
+
+```bash
+export KHAI_API_KEY="khai_..."
+```
+
+```python
+from khai import KhaiClient
+
+khai = KhaiClient()  # reads KHAI_API_KEY; base_url defaults to https://api.getkhai.ai
+
+resp = khai.ingest_turn(
+    user_query="How do I pay my bill?",
+    agent_response="You can pay online at ...",
+    session_id="chat-123",
+    agent_id="YOUR_AGENT_ID",
+)
+print(resp.status, resp.result.trust_score if resp.evaluated else resp.reason)
+```
+
+## Every turn is idempotent
+
+You do not have to think about retries. When you omit them, the SDK fills in a
+`timestamp` (UTC, ISO-8601) and a UUID `response_id` **when the turn is created**,
+and keeps them for every retry. The backend deduplicates on `response_id`, so a
+turn resent after a timeout, a 5xx, or a network outage is answered with
+`status: duplicate` instead of being stored twice.
+
+If your platform already has a per-reply id (Dialogflow `responseId`, Lex,
+Copilot Studio), pass it as `response_id` and the same guarantee holds even
+across restarts of your own process.
+
+## Fire-and-forget
+
+`ingest_turn_async` queues the turn and returns immediately, so it never blocks
+your chatbot's response path. Failed deliveries are buffered and retried. Both
+the queue and the buffer are capped at `max_queue_size` (default 10,000 turns);
+when full, the SDK drops a turn and reports it through `on_error` as
+`KhaiQueueFullError` rather than growing memory during an outage. Open clients
+are flushed once at interpreter exit.
+
+```python
+with KhaiClient() as khai:
+    khai.ingest_turn_async(
+        user_query=user_msg,
+        agent_response=bot_reply,
+        session_id=session_id,
+        agent_id="YOUR_AGENT_ID",
+    )
+    # ... keep serving; turns flush in the background, and on close().
+```
+
+## Batch
+
+```python
+from khai import IngestTurn
+
+khai.ingest_batch([
+    IngestTurn(user_query="...", agent_response="...", session_id="s1", agent_id="a1"),
+    IngestTurn(user_query="...", agent_response="...", session_id="s1", agent_id="a1"),
+])
+```
+
+## Redact PII before sending
+
+```python
+def redact(payload: dict) -> dict:
+    payload["user_query"] = mask_emails(payload["user_query"])
+    return payload
+
+khai.set_redactor(redact)
+```
+
+## Errors
+
+All errors derive from `KhaiError`:
+
+| Error | Meaning |
+|---|---|
+| `KhaiAuthError` | API key missing/invalid (401/403) |
+| `KhaiRateLimitError` | Per-key rate limit exceeded (429) |
+| `KhaiAPIError` | Other non-success status |
+| `KhaiConnectionError` | Network/timeout (already retried) |
+| `KhaiQueueFullError` | Fire-and-forget queue/buffer full; a turn was dropped (via `on_error`) |
+| `KhaiConfigError` | Bad client configuration (missing key, non-HTTPS base URL) |
+
+## Configuration
+
+| Setting | Argument | Environment variable | Default |
+|---|---|---|---|
+| API key | `api_key` | `KHAI_API_KEY` | required |
+| Base URL | `base_url` | `KHAI_BASE_URL` | `https://api.getkhai.ai` |
+| Request timeout (s) | `timeout` | — | `10.0` |
+| Retries on 429/5xx/network | `max_retries` | — | `3` |
+| Queue / buffer cap | `max_queue_size` | — | `10000` |
+
+`base_url` must be `https://`; plain `http://` is accepted only for `localhost`.
+
+## Releasing (maintainers)
+
+Releases are cut from tags and published by CI through PyPI trusted publishing;
+no one uploads from a laptop and no API token is stored anywhere.
+
+1. Bump `__version__` in `src/khai/_version.py` and move the `Unreleased`
+   entries in `CHANGELOG.md` under the new version. Merge via pull request.
+2. Tag the merged commit and push the tag:
+
+   ```bash
+   git tag v0.1.0 && git push origin v0.1.0
+   ```
+
+3. The `Release` workflow builds the sdist and wheel, publishes to TestPyPI,
+   installs from TestPyPI and imports the package, then waits for a reviewer to
+   approve the `pypi` environment before publishing to PyPI and creating the
+   GitHub Release. A tag whose version does not match `__version__` fails fast.

khai_sdk-0.1.0/SECURITY.md

@@ -0,0 +1,10 @@
+# Security policy
+
+Report vulnerabilities in this SDK privately to admin@brise.ai. Do not open
+a public issue for security reports. We acknowledge reports within three
+business days.
+
+Only the latest minor release receives security fixes.
+
+The SDK never logs or prints your API key. Pass it via the `KHAI_API_KEY`
+environment variable rather than embedding it in source.