oix 0.0.1__tar.gz

oix-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main, release]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --extra fastapi
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q
+      - run: uv build
+      - run: uv run twine check dist/*

oix-0.0.1/.github/workflows/pypi.yml

@@ -0,0 +1,224 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [release]
+  workflow_dispatch:
+
+concurrency:
+  group: pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.pkg.outputs.version }}
+      publish_needed: ${{ steps.pypi.outputs.publish_needed }}
+      release_assets_needed: ${{ steps.release.outputs.release_assets_needed }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Read version
+        id: pkg
+        run: |
+          VERSION=$(python3 -c "
+          import re, pathlib
+          text = pathlib.Path('pyproject.toml').read_text()
+          m = re.search(r'^version\s*=\s*\"([^\"]+)\"', text, re.M)
+          print(m.group(1))
+          ")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Check PyPI
+        id: pypi
+        env:
+          VERSION: ${{ steps.pkg.outputs.version }}
+        run: |
+          python3 - <<'PY'
+          import os
+          import urllib.error
+          import urllib.request
+
+          version = os.environ["VERSION"]
+          exists = False
+          try:
+              with urllib.request.urlopen(f"https://pypi.org/pypi/oix/{version}/json", timeout=15):
+                  exists = True
+          except urllib.error.HTTPError as exc:
+              if exc.code != 404:
+                  raise
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+              output.write(f"publish_needed={'false' if exists else 'true'}\n")
+          print(f"Version {version} {'already exists on PyPI' if exists else 'is not on PyPI'}")
+          PY
+
+      - name: Check GitHub release assets
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          VERSION: ${{ steps.pkg.outputs.version }}
+        run: |
+          set -euo pipefail
+          expected=(
+            "oix-${VERSION}-py3-none-any.whl"
+            "oix-${VERSION}.tar.gz"
+            "SHA256SUMS"
+          )
+
+          assets="$(gh release view "v${VERSION}" --json assets --jq '.assets[].name' 2>/dev/null || true)"
+          missing=false
+          for name in "${expected[@]}"; do
+            if ! grep -Fx "$name" <<< "$assets" >/dev/null; then
+              missing=true
+              echo "Missing release asset: $name"
+            fi
+          done
+
+          echo "release_assets_needed=$missing" >> "$GITHUB_OUTPUT"
+
+  build:
+    needs: preflight
+    if: github.ref == 'refs/heads/release' && (needs.preflight.outputs.publish_needed == 'true' || needs.preflight.outputs.release_assets_needed == 'true')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Test
+        run: |
+          uv sync --locked --extra fastapi
+          uv run ruff check .
+          uv run ruff format --check .
+          uv run pytest -q
+
+      - name: Build package
+        run: |
+          uv build
+          uv run twine check dist/*
+
+      - name: Generate checksums
+        run: |
+          mkdir -p release-assets
+          cp dist/* release-assets/
+          cd release-assets
+          sha256sum *.whl *.tar.gz > SHA256SUMS
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-assets
+          path: release-assets/
+
+  publish:
+    needs: [preflight, build]
+    if: github.ref == 'refs/heads/release' && needs.preflight.outputs.publish_needed == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Check if version already on PyPI
+        id: check
+        env:
+          VERSION: ${{ needs.preflight.outputs.version }}
+        run: |
+          python3 - <<'PY'
+          import os
+          import urllib.error
+          import urllib.request
+
+          version = os.environ["VERSION"]
+          exists = False
+          try:
+              with urllib.request.urlopen(f"https://pypi.org/pypi/oix/{version}/json", timeout=15):
+                  exists = True
+          except urllib.error.HTTPError as exc:
+              if exc.code != 404:
+                  raise
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+              output.write(f"skip={'true' if exists else 'false'}\n")
+          print(f"Version {version} {'already exists on PyPI, skipping publish' if exists else 'is not on PyPI'}")
+          PY
+
+      - name: Publish to PyPI
+        if: steps.check.outputs.skip != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No API token needed - uses OIDC trusted publishing.
+        # Configure at: https://pypi.org/manage/project/oix/settings/publishing/
+
+  github-release-assets:
+    needs: [preflight, build]
+    if: github.ref == 'refs/heads/release' && needs.preflight.outputs.release_assets_needed == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release-assets
+          path: release-assets/
+
+      - name: Attach GitHub release artifacts
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          VERSION: ${{ needs.preflight.outputs.version }}
+        run: |
+          set -euo pipefail
+          ls -lah release-assets
+          mapfile -t files < <(find release-assets -maxdepth 1 -type f -print | sort)
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No release asset files found" >&2
+            exit 1
+          fi
+
+          for attempt in {1..60}; do
+            if gh release view "v${VERSION}" >/dev/null 2>&1; then
+              gh release upload "v${VERSION}" "${files[@]}" --clobber
+
+              assets="$(gh release view "v${VERSION}" --json assets --jq '.assets[].name')"
+              for expected in \
+                "oix-${VERSION}-py3-none-any.whl" \
+                "oix-${VERSION}.tar.gz" \
+                "SHA256SUMS"
+              do
+                if ! grep -Fx "$expected" <<< "$assets" >/dev/null; then
+                  echo "Missing release asset after upload: $expected" >&2
+                  exit 1
+                fi
+              done
+              exit 0
+            fi
+            sleep 10
+          done
+          echo "GitHub release v${VERSION} was not found" >&2
+          exit 1

oix-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+# -----------------------------------------------------------------------------
+# Release - Create GitHub release from CHANGELOG
+# Runs on pushes to the release branch when version changes.
+# -----------------------------------------------------------------------------
+name: Release
+
+on:
+  push:
+    branches: [release]
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # Create the release used by pypi.yml for package assets.
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Read version
+        id: pkg
+        run: |
+          VERSION=$(python3 -c "
+          import re, pathlib
+          text = pathlib.Path('pyproject.toml').read_text()
+          m = re.search(r'^version\s*=\s*\"([^\"]+)\"', text, re.M)
+          print(m.group(1))
+          ")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Extract release notes from CHANGELOG
+        run: |
+          VER="${{ steps.pkg.outputs.version }}"
+          awk "/^## \[${VER}\]/{found=1; next} /^## \[/{if(found) exit} found{print}" \
+            CHANGELOG.md > /tmp/release-notes.md
+
+      - name: Publish GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if gh release view "v${{ steps.pkg.outputs.version }}" &>/dev/null; then
+            echo "Release v${{ steps.pkg.outputs.version }} already exists - skipping creation"
+          else
+            gh release create "v${{ steps.pkg.outputs.version }}" \
+              --target "$GITHUB_SHA" \
+              --title "v${{ steps.pkg.outputs.version }}" \
+              --notes-file /tmp/release-notes.md
+          fi

oix-0.0.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+*.pem

oix-0.0.1/.python-version

@@ -0,0 +1 @@
+3.11

oix-0.0.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [0.0.1] - 2026-10-12
+
+- Initial external app SDK: authenticated events, signed runtime client, Markdown replies and actions.
+- Optional FastAPI adapter and manifest discovery.
+- uv packaging, CI, GitHub releases and PyPI trusted publishing.

oix-0.0.1/LICENSE

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

oix-0.0.1/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: oix
+Version: 0.0.1
+Summary: Build external apps for Open WebUI
+Author-email: Tim Baek <tim@openwebui.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiohttp<4,>=3.12
+Requires-Dist: cryptography>=44
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyjwt<3,>=2.10
+Provides-Extra: fastapi
+Requires-Dist: fastapi<1,>=0.115; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# oix — Open WebUI SDK
+
+A small Python SDK for building external apps for Open WebUI. Version **0.0.1** targets the current external-app protocol in the accompanying Open WebUI implementation; older WebUI releases without that API are not supported.
+
+Python 3.11+. The SDK handles authentication, connection proofs, verified events, and signed runtime requests. Your app handles its own business logic and authorization.
+
+## Install
+
+Once published:
+
+```sh
+uv add 'oix[fastapi]'
+```
+
+For local development against this checkout:
+
+```sh
+uv add --editable '../sdk[fastapi]'
+```
+
+The FastAPI extra is optional. The core SDK does not require a web framework.
+
+## A minimal app
+
+```python
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from oix import App, AppReply, Client, Event
+from oix.fastapi import create_router
+
+app = App(
+    id="hello",
+    name="Hello",
+    api_key=os.environ["API_KEY"],
+    private_key=Path(os.environ["APP_PRIVATE_KEY_FILE"]).read_text(),
+    scopes=["mentions:read"],
+)
+
+
+@app.on("mention")
+async def hello(event: Event, client: Client) -> AppReply:
+    return AppReply(content="Hello! Only you can see this reply.")
+
+
+server = FastAPI()
+server.include_router(create_router(app, path="/events"))
+```
+
+Generate an Ed25519 key once and keep it in persistent deployment secrets:
+
+```sh
+umask 077
+openssl genpkey -algorithm ED25519 -out app-private-key.pem
+export APP_PRIVATE_KEY_FILE="$PWD/app-private-key.pem"
+export API_KEY="$(uv run python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+uv run --extra fastapi uvicorn examples.hello:server --port 8001
+```
+
+Persist the API key too; do not regenerate either secret on each startup. The example reads `APP_PRIVATE_KEY_FILE`; the SDK itself takes values explicitly and does not read environment variables.
+
+In WebUI, enable Apps, add your public HTTPS event URL and the API key, approve the scopes, then connect. Invite the app into a channel. GET on the event URL provides the public manifest; POST receives authenticated events. The public key is intentionally public.
+
+Any route is valid, including `/manifest`. Pass `manifest=False` to `create_router` for a POST-only endpoint and enter the app details manually in WebUI. `app.manifest` supplies those details.
+
+For localhost development, pass the exact WebUI origin in `allowed_private_origins=("http://127.0.0.1:8080",)`. The example accepts the comma-separated `OPEN_WEBUI_ALLOWED_PRIVATE_ORIGINS` setting. Separately configure WebUI's `APP_ALLOWED_PRIVATE_ORIGINS` to allow your app origin. Production callbacks require HTTPS and public destinations by default; DNS results, IP literals, redirects, response size and timeouts are checked.
+
+## Events and replies
+
+Register async handlers with `@app.on(...)` for:
+
+- `mention`: explicit app mentions; text is in `event.data["text"]`.
+- `action`: a saved message button; `event.data` contains `message_id`, `action_id`, and `context`.
+- `operation_status`: a status request for deferred work.
+- `message.created`, `message.updated`, `message.deleted`: ordinary channel events, including messages without mentions. Request `messages:read` for these.
+
+All callbacks receive `(event, client)`. Events are verified against the originating WebUI **before** your handler runs. For interactions, the actor's admin status comes from current authorization, not the incoming payload. Unsigned source metadata is not exposed. Ordinary message events do not authorize commands on behalf of their authors.
+
+Return `AppReply(content="...")` for an inline private reply, or set `visibility="channel"` to post publicly in the channel. `AppReply` also supports `update`, `download`, `error`, and `deferred`. `Action(action_id="...", label="...", context={...})` buttons are supported only on saved channel messages. Button handlers must enforce any operation-specific rules themselves.
+
+Return `AppReply(type="deferred", operation_id=event.id)` for background work and implement an `operation_status` handler. Keep status replies private. Your app owns job storage and restart recovery; the SDK does not start a worker or persist jobs. Recheck `await client.authorize(event.execution_context)` before later sensitive work, and apply your app's own permissions.
+
+Ordinary channel-event handlers return `None`; use the runtime client to send a message. A mention can produce both a channel event and a mention interaction. Check `event.message["author"]` to avoid responding to your own messages. Delivery is best effort, can arrive out of order, and has no replay guarantee.
+
+## Runtime client
+
+```python
+from oix import AppChannelMessage
+
+message = await client.create_message(
+    event.channel["id"], AppChannelMessage(content="Working on it...")
+)
+await client.update_message(
+    message["id"], AppChannelMessage(content="Done."), etag=message["etag"]
+)
+```
+
+Available methods: `get_me()`, `list_channels()`, `list_messages(channel_id, limit=50, before=None, parent_id=None)`, `create_message(...)`, `update_message(...)`, `authorize(execution_context)`, and `verify_event(event_context)`. Responses are WebUI JSON dictionaries/lists. `APIError.status` exposes HTTP failures, including `412` for stale edits. Transport failures use aiohttp exceptions or `TimeoutError`. Message creation is never automatically retried.
+
+One `App` can serve multiple independent WebUI instances. Each event supplies its WebUI origin and local installation ID; its client is bound to that pair. There is no required installation registry or single `OPEN_WEBUI_URL`. For proactive messages, save the destination URL and app ID alongside your own subscription, then call `app.client(webui_url, app_id)` after restart. API-key holders are trusted to connect instances; a shared key does not provide tenant-specific business authorization.
+
+For another web framework, call `app.authenticate(authorization)` before reading a body, enforce a 256 KiB body limit, parse JSON, then `await app.handle_event(payload, authorization=authorization)`. Return the resulting JSON. No SDK is required on the WebUI server.
+
+## Development and publishing
+
+```sh
+uv sync --extra fastapi
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+`uv.lock` locks development/CI dependencies. Wheels retain normal library dependency ranges. No sibling repository is needed to build or install the package.
+
+The GitHub workflows are adapted from the sibling **oikb** repository:
+
+- `ci.yml`: lint, tests and package builds on PRs and pushes to `main`/`release`.
+- `release.yml`: a push to `release` creates `v<version>` at that commit, with notes from `CHANGELOG.md`.
+- `pypi.yml`: a push to `release` (or manual run on that branch) tests/builds, publishes missing versions with PyPI trusted publishing, and attaches the wheel, source archive and checksums to the GitHub release. Existing PyPI versions are skipped.
+
+Before the first release, configure a PyPI pending/trusted publisher for **oix**, your GitHub owner/repository, workflow **pypi.yml**, and environment **pypi**. Create that GitHub environment and restrict publishing to the `release` branch. No long-lived PyPI API token is required. The SDK does not need oikb's Docker builds or dependency wheelhouse.
+
+To release, update the version in `pyproject.toml`, update the changelog and lockfile, then push the reviewed commit to your `release` branch. You can instead build locally and run `uv publish` with your own publishing credentials. This checkout has not been published.

oix-0.0.1/README.md

@@ -0,0 +1,126 @@
+# oix — Open WebUI SDK
+
+A small Python SDK for building external apps for Open WebUI. Version **0.0.1** targets the current external-app protocol in the accompanying Open WebUI implementation; older WebUI releases without that API are not supported.
+
+Python 3.11+. The SDK handles authentication, connection proofs, verified events, and signed runtime requests. Your app handles its own business logic and authorization.
+
+## Install
+
+Once published:
+
+```sh
+uv add 'oix[fastapi]'
+```
+
+For local development against this checkout:
+
+```sh
+uv add --editable '../sdk[fastapi]'
+```
+
+The FastAPI extra is optional. The core SDK does not require a web framework.
+
+## A minimal app
+
+```python
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from oix import App, AppReply, Client, Event
+from oix.fastapi import create_router
+
+app = App(
+    id="hello",
+    name="Hello",
+    api_key=os.environ["API_KEY"],
+    private_key=Path(os.environ["APP_PRIVATE_KEY_FILE"]).read_text(),
+    scopes=["mentions:read"],
+)
+
+
+@app.on("mention")
+async def hello(event: Event, client: Client) -> AppReply:
+    return AppReply(content="Hello! Only you can see this reply.")
+
+
+server = FastAPI()
+server.include_router(create_router(app, path="/events"))
+```
+
+Generate an Ed25519 key once and keep it in persistent deployment secrets:
+
+```sh
+umask 077
+openssl genpkey -algorithm ED25519 -out app-private-key.pem
+export APP_PRIVATE_KEY_FILE="$PWD/app-private-key.pem"
+export API_KEY="$(uv run python -c 'import secrets; print(secrets.token_urlsafe(32))')"
+uv run --extra fastapi uvicorn examples.hello:server --port 8001
+```
+
+Persist the API key too; do not regenerate either secret on each startup. The example reads `APP_PRIVATE_KEY_FILE`; the SDK itself takes values explicitly and does not read environment variables.
+
+In WebUI, enable Apps, add your public HTTPS event URL and the API key, approve the scopes, then connect. Invite the app into a channel. GET on the event URL provides the public manifest; POST receives authenticated events. The public key is intentionally public.
+
+Any route is valid, including `/manifest`. Pass `manifest=False` to `create_router` for a POST-only endpoint and enter the app details manually in WebUI. `app.manifest` supplies those details.
+
+For localhost development, pass the exact WebUI origin in `allowed_private_origins=("http://127.0.0.1:8080",)`. The example accepts the comma-separated `OPEN_WEBUI_ALLOWED_PRIVATE_ORIGINS` setting. Separately configure WebUI's `APP_ALLOWED_PRIVATE_ORIGINS` to allow your app origin. Production callbacks require HTTPS and public destinations by default; DNS results, IP literals, redirects, response size and timeouts are checked.
+
+## Events and replies
+
+Register async handlers with `@app.on(...)` for:
+
+- `mention`: explicit app mentions; text is in `event.data["text"]`.
+- `action`: a saved message button; `event.data` contains `message_id`, `action_id`, and `context`.
+- `operation_status`: a status request for deferred work.
+- `message.created`, `message.updated`, `message.deleted`: ordinary channel events, including messages without mentions. Request `messages:read` for these.
+
+All callbacks receive `(event, client)`. Events are verified against the originating WebUI **before** your handler runs. For interactions, the actor's admin status comes from current authorization, not the incoming payload. Unsigned source metadata is not exposed. Ordinary message events do not authorize commands on behalf of their authors.
+
+Return `AppReply(content="...")` for an inline private reply, or set `visibility="channel"` to post publicly in the channel. `AppReply` also supports `update`, `download`, `error`, and `deferred`. `Action(action_id="...", label="...", context={...})` buttons are supported only on saved channel messages. Button handlers must enforce any operation-specific rules themselves.
+
+Return `AppReply(type="deferred", operation_id=event.id)` for background work and implement an `operation_status` handler. Keep status replies private. Your app owns job storage and restart recovery; the SDK does not start a worker or persist jobs. Recheck `await client.authorize(event.execution_context)` before later sensitive work, and apply your app's own permissions.
+
+Ordinary channel-event handlers return `None`; use the runtime client to send a message. A mention can produce both a channel event and a mention interaction. Check `event.message["author"]` to avoid responding to your own messages. Delivery is best effort, can arrive out of order, and has no replay guarantee.
+
+## Runtime client
+
+```python
+from oix import AppChannelMessage
+
+message = await client.create_message(
+    event.channel["id"], AppChannelMessage(content="Working on it...")
+)
+await client.update_message(
+    message["id"], AppChannelMessage(content="Done."), etag=message["etag"]
+)
+```
+
+Available methods: `get_me()`, `list_channels()`, `list_messages(channel_id, limit=50, before=None, parent_id=None)`, `create_message(...)`, `update_message(...)`, `authorize(execution_context)`, and `verify_event(event_context)`. Responses are WebUI JSON dictionaries/lists. `APIError.status` exposes HTTP failures, including `412` for stale edits. Transport failures use aiohttp exceptions or `TimeoutError`. Message creation is never automatically retried.
+
+One `App` can serve multiple independent WebUI instances. Each event supplies its WebUI origin and local installation ID; its client is bound to that pair. There is no required installation registry or single `OPEN_WEBUI_URL`. For proactive messages, save the destination URL and app ID alongside your own subscription, then call `app.client(webui_url, app_id)` after restart. API-key holders are trusted to connect instances; a shared key does not provide tenant-specific business authorization.
+
+For another web framework, call `app.authenticate(authorization)` before reading a body, enforce a 256 KiB body limit, parse JSON, then `await app.handle_event(payload, authorization=authorization)`. Return the resulting JSON. No SDK is required on the WebUI server.
+
+## Development and publishing
+
+```sh
+uv sync --extra fastapi
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+uv build
+uv run twine check dist/*
+```
+
+`uv.lock` locks development/CI dependencies. Wheels retain normal library dependency ranges. No sibling repository is needed to build or install the package.
+
+The GitHub workflows are adapted from the sibling **oikb** repository:
+
+- `ci.yml`: lint, tests and package builds on PRs and pushes to `main`/`release`.
+- `release.yml`: a push to `release` creates `v<version>` at that commit, with notes from `CHANGELOG.md`.
+- `pypi.yml`: a push to `release` (or manual run on that branch) tests/builds, publishes missing versions with PyPI trusted publishing, and attaches the wheel, source archive and checksums to the GitHub release. Existing PyPI versions are skipped.
+
+Before the first release, configure a PyPI pending/trusted publisher for **oix**, your GitHub owner/repository, workflow **pypi.yml**, and environment **pypi**. Create that GitHub environment and restrict publishing to the `release` branch. No long-lived PyPI API token is required. The SDK does not need oikb's Docker builds or dependency wheelhouse.
+
+To release, update the version in `pyproject.toml`, update the changelog and lockfile, then push the reviewed commit to your `release` branch. You can instead build locally and run `uv publish` with your own publishing credentials. This checkout has not been published.

oix-0.0.1/examples/hello.py

@@ -0,0 +1,35 @@
+"""Run: uv run --extra fastapi uvicorn examples.hello:server --port 8001"""
+
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from oix import App, AppReply, Client, Event
+from oix.fastapi import create_router
+
+app = App(
+    id="hello",
+    name="Hello",
+    api_key=os.environ["API_KEY"],
+    private_key=Path(os.environ["APP_PRIVATE_KEY_FILE"]).read_text(),
+    scopes=["mentions:read"],
+    allowed_private_origins=tuple(
+        filter(
+            None,
+            os.getenv(
+                "OPEN_WEBUI_ALLOWED_PRIVATE_ORIGINS",
+                "",
+            ).split(","),
+        )
+    ),
+)
+
+
+@app.on("mention")
+async def hello(event: Event, client: Client) -> AppReply:
+    return AppReply(content="Hello! This reply is only visible to you.")
+
+
+server = FastAPI()
+server.include_router(create_router(app))