klavi-experts 0.1.0__tar.gz

klavi_experts-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Point the live test suite (pytest tests/live) at an install.
+EXPERTS_BASE_URL=http://localhost:5003
+EXPERTS_TEST_KEY=sk-...
+# Optional: an expert uid to exercise, and an origin registered against the key.
+EXPERTS_TEST_EXPERT=
+EXPERTS_TEST_ORIGIN=

klavi_experts-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,38 @@
+name: Bug report
+description: Something the SDK does wrong
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead.
+    validations: { required: true }
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: The smallest snippet that shows it. Redact your API key.
+      render: python
+    validations: { required: true }
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: SDK version, Python version, and the install's build pack version.
+      placeholder: "klavi-experts 0.1.0, Python 3.12, pack 1.0.49"
+    validations: { required: true }
+  - type: dropdown
+    id: client
+    attributes:
+      label: Which client
+      options: [ExpertsClient (sync), AsyncExpertsClient (async), both]
+    validations: { required: true }
+  - type: textarea
+    id: raw
+    attributes:
+      label: Raw request and response
+      description: >
+        If the API itself looks wrong, paste the request and response. Some
+        problems are fixed on the server rather than in the SDK, and this is
+        how we tell which.

klavi_experts-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/klv-ai/experts-python-sdk/security/advisories/new
+    about: Report privately. Please do not open a public issue.

klavi_experts-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## What this changes
+
+<!-- And why. If it fixes a bug, say what the wrong behaviour was. -->
+
+## Checklist
+
+- [ ] A test that fails without this change
+- [ ] `ruff check`, `mypy src` and `pytest` pass
+- [ ] No new runtime dependencies (httpx is the only one)
+- [ ] Sync and async halves still agree (`tests/test_async_parity.py`)
+- [ ] Comments explain *why*, where the reason is not obvious from the code

klavi_experts-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.10 is the floor (PEP 604 unions in annotations); 3.13 catches
+        # what is coming.
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: mypy src
+      - run: pytest -q
+
+  # The unit suite stubs the transport, so it cannot see the SDK drifting from
+  # the services it wraps. This can. It needs a live install, so it only runs
+  # where the secret exists — never on a fork's pull request.
+  live:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - name: Integration tests
+        env:
+          EXPERTS_BASE_URL: ${{ secrets.EXPERTS_BASE_URL }}
+          EXPERTS_TEST_KEY: ${{ secrets.EXPERTS_TEST_KEY }}
+        run: |
+          if [ -z "$EXPERTS_TEST_KEY" ]; then
+            echo "::notice::No EXPERTS_TEST_KEY configured; skipping live tests."
+            exit 0
+          fi
+          pytest tests/live -q

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

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      # PyPI trusted publishing: PyPI verifies this workflow's OIDC identity
+      # instead of us storing a long-lived API token. Same purpose as npm
+      # provenance on the Node SDK.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" build
+      - run: ruff check src tests
+      - run: mypy src
+      - run: pytest -q
+      - name: Check the tag matches the package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "Tag $TAG does not match pyproject version $PKG" >&2
+            exit 1
+          fi
+          # __version__ is what a user prints at runtime; a disagreement there
+          # is how a bug report ends up naming the wrong release.
+          MOD=$(python -c "import re,pathlib; print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('src/klavi_experts/__init__.py').read_text()).group(1))")
+          if [ "$TAG" != "$MOD" ]; then
+            echo "Tag $TAG does not match __version__ $MOD" >&2
+            exit 1
+          fi
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

klavi_experts-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+.env
+.env.*
+!.env.example

klavi_experts-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of Conduct
+
+## Our pledge
+
+We want participation in this project to be a harassment-free experience for
+everyone, regardless of age, body size, visible or invisible disability,
+ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Things that help: empathy and kindness, respect for differing opinions and
+experiences, graceful acceptance of constructive feedback, taking
+responsibility for our mistakes, and focusing on what is best for the community
+rather than for ourselves.
+
+Things that do not: sexualised language or imagery, trolling, insulting or
+derogatory comments, personal or political attacks, public or private
+harassment, publishing others' private information without permission, and
+other conduct that would reasonably be considered inappropriate in a
+professional setting.
+
+## Enforcement
+
+Report unacceptable behaviour to **conduct@klavi.ai**. All complaints will be
+reviewed and investigated promptly and fairly, and the privacy and security of
+the reporter will be respected.
+
+Maintainers are responsible for clarifying and enforcing these standards, and
+may remove, edit or reject contributions that do not align with them.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1.

klavi_experts-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for helping. This SDK wraps a HTTP API that it does not control, so the
+most valuable contributions are usually about *behaviour we got wrong* rather
+than features we are missing.
+
+## Getting set up
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest            # unit tests, no install required
+ruff check src tests
+mypy src
+```
+
+## Running against a real install
+
+The unit tests use a stubbed transport, which cannot catch drift between this
+SDK and the Python services it talks to. The live suite can:
+
+```bash
+cp .env.example .env      # fill in EXPERTS_BASE_URL and EXPERTS_TEST_KEY
+pytest tests/live
+```
+
+It creates only hidden conversations and deletes them afterwards. Point it at
+a development install, never production.
+
+## Sync and async
+
+There are two clients, and they must not drift. Everything that is not I/O —
+request building, response shaping, NDJSON framing, event mapping — is shared,
+so a change to what a call MEANS is made once. `tests/test_async_parity.py`
+compares their signatures and the requests they emit; if you add a parameter
+to one half, that suite tells you about the other.
+
+## What we look for in a change
+
+- **A test that fails without it.** For a bug, that test should describe the
+  behaviour, not the fix.
+- **Comments that explain why, not what.** Most of the surprising code here is
+  surprising because the API is, and the comment should say which part.
+- **No new runtime dependencies.** `httpx` is the only one, on purpose.
+
+## Reporting an API problem
+
+If the API itself misbehaves — a shape that does not match its documentation, a
+silent failure — open an issue with the raw request and response. Those are
+often fixed on the server rather than papered over here, and knowing which is
+the point of the report.
+
+## Security
+
+Do not open an issue for a vulnerability. See [SECURITY.md](SECURITY.md).

klavi_experts-0.1.0/LICENSE

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

klavi_experts-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: klavi-experts
+Version: 0.1.0
+Summary: Official Python SDK for the Klavi Experts API — conversations, streaming, experts, and knowledge.
+Project-URL: Homepage, https://github.com/klv-ai/experts-python-sdk
+Project-URL: Repository, https://github.com/klv-ai/experts-python-sdk
+Project-URL: Issues, https://github.com/klv-ai/experts-python-sdk/issues
+Project-URL: Changelog, https://github.com/klv-ai/experts-python-sdk/releases
+Author: Klavi AI
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,chatbot,experts,klavi,llm,rag,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# klavi-experts
+
+The official Python SDK for the [Klavi Experts](https://github.com/klv-ai) API — AI experts with retrieval over your own documents, running on your own infrastructure.
+
+Sync and async. One dependency (`httpx`). Python 3.10+.
+
+```bash
+pip install klavi-experts
+```
+
+## Thirty seconds
+
+```python
+from klavi_experts import ExpertsClient
+
+experts = ExpertsClient(
+    base_url="https://experts.acme.com",
+    api_key=os.environ["EXPERTS_API_KEY"],   # server-side only
+)
+
+for event in experts.conversations.ask("What's our refund policy?"):
+    if event.type == "token":
+        print(event.content, end="", flush=True)
+```
+
+Or, when you just want the answer:
+
+```python
+answer = experts.conversations.ask("Summarise Q3.").text()
+```
+
+Async is the same API:
+
+```python
+from klavi_experts import AsyncExpertsClient
+
+async with AsyncExpertsClient(base_url=..., api_key=...) as experts:
+    stream = await experts.conversations.ask("Summarise Q3.")
+    async for event in stream:
+        ...
+```
+
+## Why not just call the API
+
+Sending one message is three HTTP calls in a specific order, and getting it wrong fails *silently* — the model answers, the stream looks fine, and nothing is saved:
+
+```
+POST /api/v1/responses           the user's turn        {agent: False, done: True}
+POST /api/v1/responses           assistant placeholder  {agent: True, done: False}  ← keep uid
+POST /api/v1/conversations/chat  {response: <placeholder uid>, ...}
+```
+
+`conversations.send()` is that sequence. The rest of the SDK is the same idea applied to the parts of the API that are easy to get subtly wrong — see [Things worth knowing](#things-worth-knowing).
+
+## Talking to an expert
+
+```python
+experts_list = experts.experts.list()
+
+conversation = experts.conversations.create(
+    expert=experts_list[0].uid,
+    title="Support",
+)
+
+with experts.conversations.send(conversation.uid, "Hello") as stream:
+    for event in stream:
+        match event.type:
+            case "token":    print(event.content, end="", flush=True)
+            case "thinking": ...   # reasoning tokens, when the model exposes them
+            case "action":   ...   # "rag_search", "tool_call" — for a status line
+            case "done":     print(event.usage, event.source_docs)
+```
+
+Everything the answer was grounded in comes back on the terminal event:
+
+```python
+result = stream.result()
+result.text            # the full reply
+result.source_docs     # documents retrieved, with similarity scores
+result.tools_used      # e.g. ["web_search"]
+result.usage.total_ms  # milliseconds (the API speaks nanoseconds)
+result.error           # set when generation failed inside a 200 — always check
+```
+
+### Stopping
+
+```python
+stream.cancel()   # stops the model
+stream.detach()   # stop reading; let it finish and persist
+```
+
+These are genuinely different. Generation is **detached** from the HTTP request server-side, so simply walking away stops the relay, not the model — it keeps generating, keeps costing you, and still writes its answer. `cancel()` is the only thing that stops it.
+
+## A chatbox on your website
+
+An API key is a full user identity on the install, so it must never reach a browser. Instead your Python server mints a short-lived session token bound to one expert, one conversation and one origin.
+
+**Register the origin first** against your API key, in the install's admin. That registration is also what supplies CORS for this surface.
+
+```python
+# Django / Flask / FastAPI — your /api/chat/session route
+session = experts.sessions.create(expert=EXPERT_UID, origin="https://acme.com")
+return {"token": session.token}
+```
+
+The browser then talks to the install directly, using [`@klv-ai/experts/browser`](https://www.npmjs.com/package/@klv-ai/experts) or plain `fetch`. Your server is involved once, to mint — you are not proxying every token.
+
+**The expert must be guest-visible.** A session token carries the guest role, and an expert above that floor resolves to nothing server-side — the chat then answers on the site's default model with no persona and no knowledge, silently, with a normal 200. `sessions.create()` refuses such an expert up front and tells you how to fix it. `experts.experts.list_guest_visible()` gives you the ones that will work.
+
+## Knowledge
+
+```python
+collections = experts.knowledge.list_collections()
+
+with open("policy.pdf", "rb") as f:
+    doc = experts.knowledge.upload(f, collection=collections[0].uid, filename="policy.pdf")
+
+# Uploading is asynchronous: the file is accepted, then split, embedded and
+# indexed by a worker. It is NOT searchable until that finishes.
+experts.knowledge.wait_for_processing(doc.uid)
+
+hits = experts.knowledge.search("refund policy")
+```
+
+## Errors
+
+```python
+from klavi_experts import RateLimitError, LicenseError
+
+try:
+    experts.conversations.ask("hi").text()
+except RateLimitError as e:
+    time.sleep(e.retry_after or 5)
+except LicenseError:
+    # The INSTALL's licence has lapsed. Nothing about your request is wrong and
+    # no retry will help — its administrator has to renew.
+    ...
+```
+
+429 and 5xx are retried automatically with backoff that honours `Retry-After`. A 4xx never is. Neither is a chat turn — retrying one bills twice and can produce two answers.
+
+## Things worth knowing
+
+These are the parts of the API that surprise people. The SDK handles each of them; they are listed so you know what it is doing on your behalf.
+
+| | |
+|---|---|
+| **Send both credentials and the wrong one wins** | The gateway checks `Authorization` first and that check is terminal. The SDK sends exactly one. |
+| **A terminal chunk can be empty on purpose** | On the tool path the text already streamed. Appending terminal content renders tool-using answers twice. |
+| **Durations are nanoseconds** | Ollama's units, passed straight through. Normalised to `*_ms` fields here. |
+| **HTTP 200 can still be a failure** | Generation errors arrive in the terminal event, not the status code. Check `result.error`. |
+| **404 can mean "forbidden"** | A conversation you may not see answers 404 so a uid probe reveals nothing. The SDK does not guess which it was. |
+| **Casing is mixed by design** | Conversation rows are camelCase; message and expert rows are snake_case; knowledge responses are wrapped in an envelope. All normalised. |
+| **Streaming is plain HTTP** | NDJSON over `POST`. No WebSocket is required for chat, contrary to some older notes. |
+
+## OpenAI-compatible endpoint
+
+If you already have code written against OpenAI, you may not need this SDK at all. An install also speaks the OpenAI chat-completions protocol, with an expert's uid as the model:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ["EXPERTS_API_KEY"],
+    base_url="https://experts.acme.com/api/openai/v1",
+)
+
+client.chat.completions.create(
+    model=EXPERT_UID,
+    messages=[{"role": "user", "content": "Hello"}],
+    stream=True,
+)
+```
+
+Retrieval still happens; source documents come back under a `klavi` key on the final chunk. Use this SDK when you want conversations, knowledge management or browser sessions; use the OpenAI client when you want to drop an install into tooling that already speaks that protocol.
+
+## Requirements
+
+Python 3.10 or later, and an install running build pack **1.0.49** or later.
+
+## Contributing
+
+Issues and pull requests welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Security reports go to [SECURITY.md](SECURITY.md), not the issue tracker.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).