vedika-agent-sdk 0.2.0__tar.gz

vedika_agent_sdk-0.2.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 XALEN Technology Private Limited
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

vedika_agent_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: vedika-agent-sdk
+Version: 0.2.0
+Summary: Python client for the Vedika agent harness.
+Author: XALEN Technology Private Limited
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/vedika-io/vedika-kit
+Project-URL: Source, https://github.com/vedika-io/vedika-kit/tree/main/packages/agent-sdk-py
+Project-URL: Issues, https://github.com/vedika-io/vedika-kit/issues
+Keywords: vedika,agent,sdk,streaming,ui-message-stream
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Typing :: Typed
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Dynamic: license-file
+
+# vedika-agent-sdk
+
+Python client for the Vedika agent harness. Streams turns over the UI Message
+Stream v1 wire, resumes with `Last-Event-ID`, and surfaces typed errors.
+
+This client is **server-side only**: it authenticates with your tenant key
+(`vk_live_...` or `vk_ent_...`), which must never reach a browser or app.
+
+## Install
+
+```bash
+pip install vedika-agent-sdk
+```
+
+Python 3.10 or newer. `httpx` is installed with it and backs the default
+transport.
+
+## Quickstart (10 lines)
+
+```python
+import asyncio
+from vedika_agent import create_agent
+
+async def main():
+    agent = create_agent("https://harness.example.com", api_key="...")
+    thread = await agent.threads.create()
+    turn = await agent.threads.send_turn(thread.id, {"kind": "text", "text": "Show my kundli for 1990-06-15."})
+    async for chunk in turn:
+        if chunk.type == "text-delta":
+            print(chunk.delta, end="")
+        if chunk.type == "data-vedika-artifact" and chunk.data.kind == "kundli":
+            print("kundli ready:", chunk.data.id)
+    await turn.done()
+
+asyncio.run(main())
+```
+
+## Exchanging your key for a browser token
+
+A browser gets a short-lived `vt_` token from your backend, never your key.
+Register the page's exact origin first (`PUT /api/v1/admin/embed/origins`, with an admin session token, not your
+tenant key).
+
+```python
+import os
+import httpx
+
+# Your backend only. Never run this in a browser.
+response = httpx.post(
+    f"{os.environ['VEDIKA_HARNESS_URL']}/api/v1/embed/tokens",
+    headers={"authorization": f"Bearer {os.environ['VEDIKA_TENANT_KEY']}"},
+    json={"end_user": "visitor:abc", "origin": "https://shop.example", "ttl_s": 600},
+)
+response.raise_for_status()  # 201
+minted = response.json()  # token, tenant_id, expires_in_seconds
+```
+
+The token lives at most 15 minutes. To put the chat on a page, see
+`mountWidget` in `@vedika-io/embed-loader`.
+
+## API
+
+### `create_agent(base_url, api_key, *, default_headers=None, transport=None)`
+
+Returns a `VedikaAgent` with a `.threads` namespace.
+
+- `await agent.threads.create(opts=None)` — `POST /api/v1/agent/threads`. Returns a `Thread`.
+- `await agent.threads.send_turn(thread_id, input, opts=None)` — `POST /threads/{id}/turns` with `Accept: text/event-stream`. Returns a `Turn` you can iterate.
+- `await agent.threads.resume_turn(turn_id, *, last_event_id)` — `GET /turns/{id}/events` with `Last-Event-ID`.
+- `await agent.threads.cancel_turn(turn_id)` — `POST /turns/{id}/cancel`.
+
+### `Turn`
+
+- `async for chunk in turn` — async iterator over every chunk.
+- `await turn.done()` — resolves on `finish` / `abort`, raises on `error`.
+- `await turn.cancel()` — calls the cancel endpoint.
+- `await turn.message_id()` — resolves to the `start.messageId` when seen.
+
+### Chunk allowlist
+
+`start`, `start-step`, `finish-step`, `reset-step`, `text-start` / `-delta` /
+`-end`, `data-vedika-artifact`, `data-vedika-stage`, `data-vedika-tool-call`,
+`data-vedika-tool-result`, `message-metadata`, `source-document`, `finish`,
+`abort`, `error`. Anything else raises `ProtocolError`.
+
+### Errors
+
+`VedikaAgentError`, `AuthenticationError`, `NotFoundError`, `RateLimitError`
+(with `retry_after_seconds`), `InvalidRequestError`, `ServerError`,
+`TurnCancelledError`, `StreamError`, `ProtocolError`. Use
+`is_vedika_agent_error(e)` to discriminate.
+
+## Memory toggles
+
+Pass `memory=MemoryToggles(old_memory=..., sensitive_info=...)` to
+`send_turn`. They are sent as `x-vedika-memory-old` and
+`x-vedika-memory-sensitive` request headers.
+
+## Idempotency
+
+Every `create` and `send_turn` carries an `Idempotency-Key` header. A fresh
+UUID v4 is generated when you don't pass one; pass your own to retry safely.
+
+## Version warnings
+
+The server can tell the SDK that it is older than the minimum supported
+version (the `X-Harness-Min-Sdk` response header). When that happens the SDK
+emits one `UserWarning` per process through the standard `warnings` module,
+naming the version to upgrade to, and keeps working. Nothing breaks: calls,
+retries and errors behave exactly as before.
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Most tests inject a `FakeTransport` that speaks the documented wire. A few
+run the default `httpx` transport against a local server to prove that a turn
+streams chunk by chunk.
+
+## Changelog
+
+- **0.2.0**: fixes the default transport, which failed with `httpx.StreamConsumed`
+  and buffered the whole turn before yielding anything. `httpx` is now a declared
+  dependency (0.1.0 declared none, so the default transport could not run after
+  `pip install`). License metadata uses an SPDX expression.
+- **0.1.0**: first version.
+
+## Licence
+
+Apache-2.0. See `LICENSE`.

vedika_agent_sdk-0.2.0/README.md

@@ -0,0 +1,133 @@
+# vedika-agent-sdk
+
+Python client for the Vedika agent harness. Streams turns over the UI Message
+Stream v1 wire, resumes with `Last-Event-ID`, and surfaces typed errors.
+
+This client is **server-side only**: it authenticates with your tenant key
+(`vk_live_...` or `vk_ent_...`), which must never reach a browser or app.
+
+## Install
+
+```bash
+pip install vedika-agent-sdk
+```
+
+Python 3.10 or newer. `httpx` is installed with it and backs the default
+transport.
+
+## Quickstart (10 lines)
+
+```python
+import asyncio
+from vedika_agent import create_agent
+
+async def main():
+    agent = create_agent("https://harness.example.com", api_key="...")
+    thread = await agent.threads.create()
+    turn = await agent.threads.send_turn(thread.id, {"kind": "text", "text": "Show my kundli for 1990-06-15."})
+    async for chunk in turn:
+        if chunk.type == "text-delta":
+            print(chunk.delta, end="")
+        if chunk.type == "data-vedika-artifact" and chunk.data.kind == "kundli":
+            print("kundli ready:", chunk.data.id)
+    await turn.done()
+
+asyncio.run(main())
+```
+
+## Exchanging your key for a browser token
+
+A browser gets a short-lived `vt_` token from your backend, never your key.
+Register the page's exact origin first (`PUT /api/v1/admin/embed/origins`, with an admin session token, not your
+tenant key).
+
+```python
+import os
+import httpx
+
+# Your backend only. Never run this in a browser.
+response = httpx.post(
+    f"{os.environ['VEDIKA_HARNESS_URL']}/api/v1/embed/tokens",
+    headers={"authorization": f"Bearer {os.environ['VEDIKA_TENANT_KEY']}"},
+    json={"end_user": "visitor:abc", "origin": "https://shop.example", "ttl_s": 600},
+)
+response.raise_for_status()  # 201
+minted = response.json()  # token, tenant_id, expires_in_seconds
+```
+
+The token lives at most 15 minutes. To put the chat on a page, see
+`mountWidget` in `@vedika-io/embed-loader`.
+
+## API
+
+### `create_agent(base_url, api_key, *, default_headers=None, transport=None)`
+
+Returns a `VedikaAgent` with a `.threads` namespace.
+
+- `await agent.threads.create(opts=None)` — `POST /api/v1/agent/threads`. Returns a `Thread`.
+- `await agent.threads.send_turn(thread_id, input, opts=None)` — `POST /threads/{id}/turns` with `Accept: text/event-stream`. Returns a `Turn` you can iterate.
+- `await agent.threads.resume_turn(turn_id, *, last_event_id)` — `GET /turns/{id}/events` with `Last-Event-ID`.
+- `await agent.threads.cancel_turn(turn_id)` — `POST /turns/{id}/cancel`.
+
+### `Turn`
+
+- `async for chunk in turn` — async iterator over every chunk.
+- `await turn.done()` — resolves on `finish` / `abort`, raises on `error`.
+- `await turn.cancel()` — calls the cancel endpoint.
+- `await turn.message_id()` — resolves to the `start.messageId` when seen.
+
+### Chunk allowlist
+
+`start`, `start-step`, `finish-step`, `reset-step`, `text-start` / `-delta` /
+`-end`, `data-vedika-artifact`, `data-vedika-stage`, `data-vedika-tool-call`,
+`data-vedika-tool-result`, `message-metadata`, `source-document`, `finish`,
+`abort`, `error`. Anything else raises `ProtocolError`.
+
+### Errors
+
+`VedikaAgentError`, `AuthenticationError`, `NotFoundError`, `RateLimitError`
+(with `retry_after_seconds`), `InvalidRequestError`, `ServerError`,
+`TurnCancelledError`, `StreamError`, `ProtocolError`. Use
+`is_vedika_agent_error(e)` to discriminate.
+
+## Memory toggles
+
+Pass `memory=MemoryToggles(old_memory=..., sensitive_info=...)` to
+`send_turn`. They are sent as `x-vedika-memory-old` and
+`x-vedika-memory-sensitive` request headers.
+
+## Idempotency
+
+Every `create` and `send_turn` carries an `Idempotency-Key` header. A fresh
+UUID v4 is generated when you don't pass one; pass your own to retry safely.
+
+## Version warnings
+
+The server can tell the SDK that it is older than the minimum supported
+version (the `X-Harness-Min-Sdk` response header). When that happens the SDK
+emits one `UserWarning` per process through the standard `warnings` module,
+naming the version to upgrade to, and keeps working. Nothing breaks: calls,
+retries and errors behave exactly as before.
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+Most tests inject a `FakeTransport` that speaks the documented wire. A few
+run the default `httpx` transport against a local server to prove that a turn
+streams chunk by chunk.
+
+## Changelog
+
+- **0.2.0**: fixes the default transport, which failed with `httpx.StreamConsumed`
+  and buffered the whole turn before yielding anything. `httpx` is now a declared
+  dependency (0.1.0 declared none, so the default transport could not run after
+  `pip install`). License metadata uses an SPDX expression.
+- **0.1.0**: first version.
+
+## Licence
+
+Apache-2.0. See `LICENSE`.

vedika_agent_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vedika-agent-sdk"
+version = "0.2.0"
+description = "Python client for the Vedika agent harness."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "XALEN Technology Private Limited" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+keywords = ["vedika", "agent", "sdk", "streaming", "ui-message-stream"]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.urls]
+Homepage = "https://github.com/vedika-io/vedika-kit"
+Source = "https://github.com/vedika-io/vedika-kit/tree/main/packages/agent-sdk-py"
+Issues = "https://github.com/vedika-io/vedika-kit/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7.4", "pytest-asyncio>=0.23"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"vedika_agent" = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+asyncio_mode = "auto"

vedika_agent_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vedika_agent_sdk-0.2.0/src/vedika_agent/__init__.py

@@ -0,0 +1,65 @@
+"""Public entry point for the Vedika agent SDK."""
+
+from .client import Transport, VedikaAgent, create_agent
+from .errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    NotFoundError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    StreamError,
+    VedikaAgentError,
+    is_vedika_agent_error,
+)
+from .stream import (
+    Turn,
+    format_last_event_id,
+    parse_chunk,
+    parse_sse_chunk,
+    UI_MESSAGE_STREAM_HEADER,
+)
+from .types import (
+    Artifact,
+    CancelTurnOptions,
+    CreateThreadOptions,
+    Json,
+    MemoryToggles,
+    ResumeTurnOptions,
+    SendTurnOptions,
+    Thread,
+    TurnInput,
+    TurnOutcome,
+    UIMessageStreamChunk,
+)
+
+__all__ = [
+    "VedikaAgent",
+    "create_agent",
+    "Transport",
+    "VedikaAgentError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InvalidRequestError",
+    "ServerError",
+    "StreamError",
+    "ProtocolError",
+    "is_vedika_agent_error",
+    "parse_chunk",
+    "parse_sse_chunk",
+    "format_last_event_id",
+    "UI_MESSAGE_STREAM_HEADER",
+    "Artifact",
+    "CancelTurnOptions",
+    "CreateThreadOptions",
+    "Json",
+    "MemoryToggles",
+    "ResumeTurnOptions",
+    "SendTurnOptions",
+    "Thread",
+    "Turn",
+    "TurnInput",
+    "TurnOutcome",
+    "UIMessageStreamChunk",
+]

vedika_agent_sdk-0.2.0/src/vedika_agent/_min_sdk.py

@@ -0,0 +1,138 @@
+"""The "server says your SDK is too old" warning.
+
+Every harness response may carry ``X-Harness-Min-Sdk: <major.minor.patch>``.
+When this SDK's own version is lower, one ``SdkVersionWarning`` is emitted per
+process and the SDK keeps working. The check only ever warns: it never raises,
+never delays a call and never changes retry or error behaviour.
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+import threading
+import warnings
+from typing import Any, Mapping, Optional, Tuple
+
+#: Response header (lower-case; header names are case-insensitive).
+MIN_SDK_HEADER = "x-harness-min-sdk"
+
+#: Distribution name from ``pyproject.toml``.
+PACKAGE_NAME = "vedika-agent-sdk"
+
+# Three dot-separated groups of 1 to 9 ASCII digits. Written as [0-9], not \d,
+# because \d also matches non-ASCII digits in Python.
+_VERSION_CORE = re.compile(r"[0-9]{1,9}\.[0-9]{1,9}\.[0-9]{1,9}")
+
+Version = Tuple[int, int, int]
+
+
+class SdkVersionWarning(UserWarning):
+    """This SDK is older than the minimum version the server supports."""
+
+
+def parse_version(value: Any) -> Optional[Version]:
+    """Parse ``major.minor.patch``, ignoring a prerelease or build suffix.
+
+    Returns ``None`` for anything that is not exactly three dot-separated
+    digit groups of at most nine digits each.
+    """
+    if not isinstance(value, str):
+        return None
+    core = re.split(r"[-+]", value.strip(), maxsplit=1)[0]
+    if _VERSION_CORE.fullmatch(core) is None:
+        return None
+    major, minor, patch = core.split(".")
+    return int(major), int(minor), int(patch)
+
+
+def compare_versions(own: Any, minimum: Any) -> Optional[int]:
+    """Compare two versions numerically.
+
+    Returns -1 when ``own`` is lower than ``minimum``, 0 when equal, 1 when
+    higher, and ``None`` when either side cannot be compared.
+    """
+    a = parse_version(own)
+    b = parse_version(minimum)
+    if a is None or b is None:
+        return None
+    return (a > b) - (a < b)
+
+
+def warning_message(package_name: str, own_version: str, min_version: str) -> str:
+    return (
+        f"{package_name} {own_version} is older than the minimum supported version "
+        f"{min_version}. Upgrade to {min_version} or later."
+    )
+
+
+@functools.lru_cache(maxsize=1)
+def _own_version() -> Optional[str]:
+    try:
+        from importlib.metadata import version
+
+        return version(PACKAGE_NAME)
+    except Exception:
+        return None
+
+
+def _header_value(headers: Optional[Mapping[str, Any]]) -> Optional[str]:
+    if not headers:
+        return None
+    value = headers.get(MIN_SDK_HEADER)
+    if value is None:
+        for key, candidate in headers.items():
+            if isinstance(key, str) and key.lower() == MIN_SDK_HEADER:
+                value = candidate
+                break
+    if isinstance(value, bytes):
+        value = value.decode("ascii", errors="replace")
+    return value if isinstance(value, str) else None
+
+
+_lock = threading.Lock()
+_warned = False
+
+
+def _reset_min_sdk_warning_for_tests() -> None:
+    """Test-only: allow the once-per-process warning to fire again."""
+    global _warned
+    with _lock:
+        _warned = False
+
+
+def check_min_sdk_header(
+    headers: Optional[Mapping[str, Any]],
+    *,
+    own_version: Optional[str] = None,
+    stacklevel: int = 4,
+) -> None:
+    """Warn once per process when the server's minimum SDK is above ours.
+
+    ``stacklevel`` counts from this function: 2 is the caller, so the default
+    of 4 points at the code that called ``agent.threads.<method>()``.
+    Swallows every failure, including a warnings filter set to ``error``.
+    """
+    global _warned
+    if _warned:
+        return
+    try:
+        minimum = parse_version(_header_value(headers))
+        if minimum is None:
+            return
+        own_text = own_version if own_version is not None else _own_version()
+        own = parse_version(own_text)
+        if own is None or own >= minimum:
+            return
+        with _lock:
+            if _warned:
+                return
+            _warned = True
+        warnings.warn(
+            warning_message(PACKAGE_NAME, str(own_text), ".".join(map(str, minimum))),
+            SdkVersionWarning,
+            stacklevel=stacklevel,
+        )
+    except Exception:
+        # The check must never affect the call that triggered it.
+        pass