liyaengine 0.1.0__tar.gz

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

@@ -0,0 +1,151 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Job 1 — Test & Typecheck
+  # ─────────────────────────────────────────────────────────────────────────────
+  test:
+    name: Test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.12']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package + dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Typecheck
+        run: mypy src
+
+      - name: Run tests
+        run: pytest
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Job 2 — Build
+  # Validates the package builds a real sdist + wheel, uploads them so the
+  # release job (below) doesn't need to rebuild.
+  # ─────────────────────────────────────────────────────────────────────────────
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: test
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tooling
+        run: pip install build
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 1
+
+  # ─────────────────────────────────────────────────────────────────────────────
+  # Job 3 — Release & Publish
+  # Creates a GitHub Release and publishes to PyPI on every push to main when
+  # the version in pyproject.toml changes. Uses PyPI Trusted Publishing (OIDC)
+  # — no long-lived API token to manage, but the PyPI project "liyaengine"
+  # needs a trusted-publisher entry configured for this repo + workflow
+  # before the first publish will succeed (pypi.org → project → Publishing).
+  # ─────────────────────────────────────────────────────────────────────────────
+  release:
+    name: Release & Publish
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    timeout-minutes: 10
+
+    permissions:
+      contents: write
+      id-token: write  # required for PyPI Trusted Publishing
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/liyaengine/
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      # Read the version from pyproject.toml and check, independently,
+      # whether (a) the release tag already exists and (b) this version is
+      # actually on PyPI. These can disagree — e.g. the tag/release gets
+      # created, then the publish step fails (auth, network) — so a re-run
+      # must not treat "tag exists" as "PyPI publish also happened" or a
+      # partial-failure release becomes permanently stuck (the tag blocks
+      # re-creating the release, while nothing actually retries the publish).
+      - name: Check release + publish status
+        id: version_check
+        run: |
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$PKG_VERSION" >> $GITHUB_OUTPUT
+
+          if git ls-remote --tags origin "refs/tags/v$PKG_VERSION" | grep -q .; then
+            echo "tag_exists=true" >> $GITHUB_OUTPUT
+            echo "⏭️  v$PKG_VERSION tag already exists — skipping release creation"
+          else
+            echo "tag_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+          HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/liyaengine/$PKG_VERSION/json")
+          if [ "$HTTP_STATUS" = "200" ]; then
+            echo "published=true" >> $GITHUB_OUTPUT
+            echo "⏭️  $PKG_VERSION already on PyPI — skipping publish"
+          else
+            echo "published=false" >> $GITHUB_OUTPUT
+            echo "🚀 $PKG_VERSION not yet on PyPI — publishing"
+          fi
+
+      - name: Download dist artifact
+        if: steps.version_check.outputs.tag_exists == 'false' || steps.version_check.outputs.published == 'false'
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        if: steps.version_check.outputs.tag_exists == 'false'
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version_check.outputs.version }}
+          name: "liyaengine v${{ steps.version_check.outputs.version }}"
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(steps.version_check.outputs.version, '-') }}
+
+      - name: Publish to PyPI
+        if: steps.version_check.outputs.published == 'false'
+        uses: pypa/gh-action-pypi-publish@release/v1

liyaengine-0.1.0/.gitignore

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

liyaengine-0.1.0/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.

liyaengine-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,90 @@
+# 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/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "liyaengine"
+version = "0.1.0"
+description = "Official Python client for the Liya Engine public API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+  { name = "Liya Engine", email = "support@liyaengine.ai" },
+]
+keywords = ["liyaengine", "ai", "sdk", "client"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+]
+
+[project.urls]
+Homepage = "https://liyaengine.ai"
+Documentation = "https://liyaengine.ai/docs/sdks/python"
+Repository = "https://github.com/liyaengine/sdk-python"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "mypy>=1.10",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/liyaengine"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+# mypy's simulated-version floor is 3.10 even though this package still
+# supports 3.9 at runtime (see project.requires-python) — mypy dropped 3.9
+# simulation, this doesn't change what actually runs.
+python_version = "3.10"

liyaengine-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_collections.py

@@ -0,0 +1,114 @@
+import httpx
+import pytest
+import respx
+
+from liyaengine import LiyaEngine, LiyaEngineAPIError
+
+BASE_URL = "https://api.test.liyaengine.ai"
+
+FIXTURE_COLLECTION = {
+    "id": "col_123",
+    "slug": "contracts",
+    "label": "Contracts",
+    "color": "#6366f1",
+    "created_at": "2026-01-01T00:00:00.000Z",
+    "domain_keys": ["legal-ops"],
+    "tags": [],
+    "visibility": "workspace",
+    "last_synced_at": None,
+    "retrieval_config": None,
+    "default_embedding_model": None,
+    "default_chunking_strategy": None,
+    "default_chunk_size": None,
+    "default_chunk_overlap": None,
+}
+
+
+@pytest.fixture
+def client():
+    with LiyaEngine(api_key="liya_test_key", base_url=BASE_URL) as c:
+        yield c
+
+
+def test_constructor_requires_api_key():
+    with pytest.raises(ValueError, match="api_key is required"):
+        LiyaEngine(api_key="")
+
+
+@respx.mock
+def test_list_unwraps_envelope(client):
+    respx.get(f"{BASE_URL}/v1/collections").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"collections": [FIXTURE_COLLECTION]}})
+    )
+    collections = client.collections.list()
+    assert len(collections) == 1
+    assert collections[0].slug == "contracts"
+
+
+@respx.mock
+def test_get_returns_single_collection(client):
+    respx.get(f"{BASE_URL}/v1/collections/col_123").mock(
+        return_value=httpx.Response(200, json={"success": True, "data": {"collection": FIXTURE_COLLECTION}})
+    )
+    collection = client.collections.get("col_123")
+    assert collection.id == "col_123"
+
+
+@respx.mock
+def test_get_raises_typed_error_on_404(client):
+    respx.get(f"{BASE_URL}/v1/collections/missing").mock(
+        return_value=httpx.Response(
+            404, json={"success": False, "error": {"code": "NOT_FOUND", "message": "Collection not found."}}
+        )
+    )
+    with pytest.raises(LiyaEngineAPIError) as exc_info:
+        client.collections.get("missing")
+    assert exc_info.value.code == "NOT_FOUND"
+    assert exc_info.value.status == 404
+
+
+@respx.mock
+def test_create_returns_new_collection(client):
+    respx.post(f"{BASE_URL}/v1/collections").mock(
+        return_value=httpx.Response(
+            201, json={"success": True, "data": {"collection": {**FIXTURE_COLLECTION, "id": "col_new"}}}
+        )
+    )
+    collection = client.collections.create(slug="contracts", label="Contracts", domain_keys=["legal-ops"])
+    assert collection.id == "col_new"
+
+
+@respx.mock
+def test_create_raises_typed_409_on_conflict(client):
+    respx.post(f"{BASE_URL}/v1/collections").mock(
+        return_value=httpx.Response(
+            409,
+            json={
+                "success": False,
+                "error": {"code": "SLUG_CONFLICT", "message": "A collection named 'contracts' already exists."},
+            },
+        )
+    )
+    with pytest.raises(LiyaEngineAPIError) as exc_info:
+        client.collections.create(slug="contracts", label="Contracts", domain_keys=["legal-ops"])
+    assert exc_info.value.code == "SLUG_CONFLICT"
+    assert exc_info.value.status == 409
+
+
+@respx.mock
+def test_update_patches_collection(client):
+    respx.patch(f"{BASE_URL}/v1/collections/col_123").mock(
+        return_value=httpx.Response(
+            200, json={"success": True, "data": {"collection": {**FIXTURE_COLLECTION, "label": "Renamed"}}}
+        )
+    )
+    updated = client.collections.update("col_123", label="Renamed")
+    assert updated.label == "Renamed"
+
+
+@respx.mock
+def test_delete_does_not_raise(client):
+    respx.delete(f"{BASE_URL}/v1/collections/col_123").mock(
+        return_value=httpx.Response(200, json={"success": True})
+    )
+    client.collections.delete("col_123")  # no exception = pass