liyaengine 0.1.0__py3-none-any.whl

liyaengine/__init__.py

@@ -0,0 +1,12 @@
+from .client import LiyaEngine
+from .errors import LiyaEngineAPIError, LiyaEngineNetworkError
+from .resources.collections import Collection
+
+__all__ = [
+    "LiyaEngine",
+    "LiyaEngineAPIError",
+    "LiyaEngineNetworkError",
+    "Collection",
+]
+
+__version__ = "0.1.0"

liyaengine/_http.py

@@ -0,0 +1,96 @@
+"""Thin httpx wrapper: bearer auth, JSON in/out, the {success,data} /
+{success,error} envelope unwrapped into a return value or a raised
+LiyaEngineAPIError, and retry-with-backoff on 429/5xx (not on 4xx, which
+are the caller's own mistake and won't succeed on retry).
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import LiyaEngineAPIError, LiyaEngineNetworkError
+
+_DEFAULT_TIMEOUT_S = 30.0
+_DEFAULT_MAX_RETRIES = 2
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout_s: float = _DEFAULT_TIMEOUT_S,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._max_retries = max_retries
+        self._client = client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout_s,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    def request(self, method: str, path: str, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        last_error: Optional[BaseException] = None
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._client.request(method, path, json=json_body)
+            except httpx.TimeoutException as exc:
+                last_error = LiyaEngineNetworkError(f"Request timed out: {exc}", exc)
+                if attempt >= self._max_retries:
+                    raise last_error from exc
+                time.sleep(2**attempt * 0.25)
+                continue
+            except httpx.RequestError as exc:
+                last_error = LiyaEngineNetworkError(f"Network request failed: {exc}", exc)
+                if attempt >= self._max_retries:
+                    raise last_error from exc
+                time.sleep(2**attempt * 0.25)
+                continue
+
+            if response.status_code in _RETRYABLE_STATUS and attempt < self._max_retries:
+                time.sleep(2**attempt * 0.25)
+                continue
+
+            try:
+                payload = response.json()
+            except ValueError as exc:
+                raise LiyaEngineNetworkError(
+                    f"Invalid JSON response (status {response.status_code})", exc
+                ) from exc
+
+            if not payload.get("success"):
+                error = payload.get("error", {})
+                raise LiyaEngineAPIError(
+                    response.status_code,
+                    error.get("code", "UNKNOWN_ERROR"),
+                    error.get("message", "Unknown error"),
+                    error.get("details"),
+                )
+            return payload.get("data")
+
+        if last_error is not None:
+            raise last_error
+        raise LiyaEngineNetworkError("Request failed")
+
+    def get(self, path: str) -> Any:
+        return self.request("GET", path)
+
+    def post(self, path: str, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("POST", path, json_body)
+
+    def patch(self, path: str, json_body: Optional[Dict[str, Any]] = None) -> Any:
+        return self.request("PATCH", path, json_body)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    def close(self) -> None:
+        self._client.close()

liyaengine/client.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from ._http import HttpClient
+from .resources.collections import CollectionsResource
+
+_DEFAULT_BASE_URL = "https://api.liyaengine.ai"
+
+
+class LiyaEngine:
+    """Client for the Liya Engine public API.
+
+    Example:
+        >>> client = LiyaEngine(api_key="liya_...")
+        >>> collection = client.collections.create(
+        ...     slug="contracts", label="Contracts", domain_keys=["legal-ops"]
+        ... )
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout_s: float = 30.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("LiyaEngine: api_key is required.")
+
+        self._http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_s=timeout_s,
+            max_retries=max_retries,
+            client=http_client,
+        )
+        self.collections = CollectionsResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "LiyaEngine":
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()

liyaengine/errors.py

@@ -0,0 +1,29 @@
+"""Every non-2xx /v1 response carries {"success": false, "error": {"code", "message"}}
+(see liyaengine-api's ErrorEnvelope in openapi.yaml). This maps that envelope onto
+real exceptions instead of a plain dict, so callers can `except LiyaEngineAPIError`.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class LiyaEngineAPIError(Exception):
+    """The API returned a well-formed error envelope."""
+
+    def __init__(self, status: int, code: str, message: str, details: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"LiyaEngineAPIError(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+class LiyaEngineNetworkError(Exception):
+    """The request never reached the server, timed out, or the response wasn't valid JSON."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None) -> None:
+        super().__init__(message)
+        self.cause = cause

liyaengine/resources/collections.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .._http import HttpClient
+
+
+@dataclass(frozen=True)
+class Collection:
+    id: str
+    slug: str
+    label: str
+    color: str
+    created_at: str
+    domain_keys: List[str]
+    tags: List[str]
+    visibility: str
+    last_synced_at: Optional[str]
+    retrieval_config: Optional[Dict[str, Any]]
+    default_embedding_model: Optional[str]
+    default_chunking_strategy: Optional[str]
+    default_chunk_size: Optional[int]
+    default_chunk_overlap: Optional[int]
+
+    @classmethod
+    def _from_dict(cls, data: Dict[str, Any]) -> "Collection":
+        return cls(
+            id=data["id"],
+            slug=data["slug"],
+            label=data["label"],
+            color=data["color"],
+            created_at=data["created_at"],
+            domain_keys=data.get("domain_keys", []),
+            tags=data.get("tags", []),
+            visibility=data.get("visibility", "workspace"),
+            last_synced_at=data.get("last_synced_at"),
+            retrieval_config=data.get("retrieval_config"),
+            default_embedding_model=data.get("default_embedding_model"),
+            default_chunking_strategy=data.get("default_chunking_strategy"),
+            default_chunk_size=data.get("default_chunk_size"),
+            default_chunk_overlap=data.get("default_chunk_overlap"),
+        )
+
+
+class CollectionsResource:
+    """Tenant-wide knowledge collections — organize documents, scope
+    retrieval, attach to one or many domains. Mirrors GET/POST
+    /v1/collections and GET/PATCH/DELETE /v1/collections/{id} exactly
+    (see liyaengine-api's openapi.yaml).
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> List[Collection]:
+        data = self._http.get("/v1/collections")
+        return [Collection._from_dict(c) for c in data["collections"]]
+
+    def get(self, id: str) -> Collection:
+        data = self._http.get(f"/v1/collections/{id}")
+        return Collection._from_dict(data["collection"])
+
+    def create(
+        self,
+        *,
+        slug: str,
+        label: str,
+        domain_keys: List[str],
+        color: Optional[str] = None,
+        default_embedding_model: Optional[str] = None,
+        default_chunking_strategy: Optional[str] = None,
+        default_chunk_size: Optional[int] = None,
+        default_chunk_overlap: Optional[int] = None,
+    ) -> Collection:
+        body: Dict[str, Any] = {"slug": slug, "label": label, "domain_keys": domain_keys}
+        if color is not None:
+            body["color"] = color
+        if default_embedding_model is not None:
+            body["default_embedding_model"] = default_embedding_model
+        if default_chunking_strategy is not None:
+            body["default_chunking_strategy"] = default_chunking_strategy
+        if default_chunk_size is not None:
+            body["default_chunk_size"] = default_chunk_size
+        if default_chunk_overlap is not None:
+            body["default_chunk_overlap"] = default_chunk_overlap
+
+        data = self._http.post("/v1/collections", body)
+        return Collection._from_dict(data["collection"])
+
+    def update(
+        self,
+        id: str,
+        *,
+        label: Optional[str] = None,
+        color: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        visibility: Optional[str] = None,
+        retrieval_config: Optional[Dict[str, Any]] = None,
+        default_embedding_model: Optional[str] = None,
+        default_chunking_strategy: Optional[str] = None,
+        default_chunk_size: Optional[int] = None,
+        default_chunk_overlap: Optional[int] = None,
+    ) -> Collection:
+        body: Dict[str, Any] = {}
+        if label is not None:
+            body["label"] = label
+        if color is not None:
+            body["color"] = color
+        if tags is not None:
+            body["tags"] = tags
+        if visibility is not None:
+            body["visibility"] = visibility
+        if retrieval_config is not None:
+            body["retrieval_config"] = retrieval_config
+        if default_embedding_model is not None:
+            body["default_embedding_model"] = default_embedding_model
+        if default_chunking_strategy is not None:
+            body["default_chunking_strategy"] = default_chunking_strategy
+        if default_chunk_size is not None:
+            body["default_chunk_size"] = default_chunk_size
+        if default_chunk_overlap is not None:
+            body["default_chunk_overlap"] = default_chunk_overlap
+
+        data = self._http.patch(f"/v1/collections/{id}", body)
+        return Collection._from_dict(data["collection"])
+
+    def delete(self, id: str) -> None:
+        self._http.delete(f"/v1/collections/{id}")

liyaengine-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: liyaengine
+Version: 0.1.0
+Summary: Official Python client for the Liya Engine public API
+Project-URL: Homepage, https://liyaengine.ai
+Project-URL: Documentation, https://liyaengine.ai/docs/sdks/python
+Project-URL: Repository, https://github.com/liyaengine/sdk-python
+Author-email: Liya Engine <support@liyaengine.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,client,liyaengine,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# liyaengine
+
+Official Python client for the [Liya Engine](https://liyaengine.ai) public API.
+
+> **Status: early access.** This SDK currently covers the Collections resource. More resources (Domains, Run, Agents, Workflows, Evals) ship incrementally — see [Roadmap](#roadmap).
+
+## Install
+
+```bash
+pip install liyaengine
+```
+
+## Quickstart
+
+```python
+from liyaengine import LiyaEngine
+
+client = LiyaEngine(api_key="liya_...")
+
+collection = client.collections.create(
+    slug="contracts",
+    label="Contracts",
+    domain_keys=["legal-ops"],
+)
+
+collections = client.collections.list()
+```
+
+Or as a context manager (closes the underlying HTTP connection pool automatically):
+
+```python
+with LiyaEngine(api_key="liya_...") as client:
+    collections = client.collections.list()
+```
+
+Get an API key from your [Liya Engine dashboard](https://app.liyaengine.ai) under Settings → API Keys.
+
+## Error handling
+
+Every failed request raises `LiyaEngineAPIError`, carrying the API's `code`, `message`, and HTTP `status`:
+
+```python
+from liyaengine import LiyaEngineAPIError
+
+try:
+    client.collections.create(slug="contracts", label="Contracts", domain_keys=["legal-ops"])
+except LiyaEngineAPIError as err:
+    if err.code == "SLUG_CONFLICT":
+        # handle the conflict
+        pass
+    raise
+```
+
+Network failures and timeouts raise `LiyaEngineNetworkError` instead. Requests are retried automatically on `429`/`5xx` responses and transient network errors (2 retries by default).
+
+## Configuration
+
+```python
+LiyaEngine(
+    api_key="liya_...",
+    base_url="https://api.liyaengine.ai",  # override for local/staging
+    timeout_s=30.0,
+    max_retries=2,
+)
+```
+
+## Roadmap
+
+- [x] Collections
+- [ ] Domains (custom domain + intent CRUD)
+- [ ] Run / Run (streaming)
+- [ ] Agents
+- [ ] Workflows
+- [ ] Evaluations
+- [ ] Async client
+
+Full docs: https://liyaengine.ai/docs/sdks/python
+
+## Development
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+mypy src
+pytest
+```
+
+## License
+
+MIT

liyaengine-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+liyaengine/__init__.py,sha256=ZG04UwwHSSPSBBcwfcFT298C9LUZWKJowicv9DXw3DQ,270
+liyaengine/_http.py,sha256=RuKGyJSZ5pVo5PLUaPCxOPKp_EEuH3_MgcrVxdiyXSQ,3431
+liyaengine/client.py,sha256=zruIS37du-SGQLSy4VS9ZdFpkXAYd5w55opW_n1mtw4,1272
+liyaengine/errors.py,sha256=2809-O2vM05FueoMfSlrm24kBBNpI7u10MR6bkd9g1E,1097
+liyaengine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+liyaengine/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+liyaengine/resources/collections.py,sha256=2TkB4ToCkWFZO97buxliU_IUHj8XT69jdvhVzeAsqi0,4774
+liyaengine-0.1.0.dist-info/METADATA,sha256=M0SEpdoSM0KF7w0hKcWOrB2ti361OqRX2KMbzBs8pnM,3157
+liyaengine-0.1.0.dist-info/WHEEL,sha256=6zicbvgMWfHSD_sSydPAPL1UNY8-QHIQA4J8fOxyAc8,87
+liyaengine-0.1.0.dist-info/licenses/LICENSE,sha256=C8CsX4Wo9A3N2HP3EiDgH1PLS4NBBiogtEuXVas6lMA,1067
+liyaengine-0.1.0.dist-info/RECORD,,

liyaengine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.1
+Root-Is-Purelib: true
+Tag: py3-none-any

liyaengine-0.1.0.dist-info/licenses/LICENSE

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