msai-client 0.1.0__tar.gz

msai_client-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# ===== Secrets / môi trường máy (KHÔNG commit) =====
+.env
+.env.*
+!.env.example
+!.env.production.example
+*.pem
+*.key
+
+# ===== Python =====
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.import_linter_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.egg-info/
+dist/
+build/
+
+# ===== Node / Frontend =====
+node_modules/
+apps/web/dist/
+*.local
+.vite/
+
+# ===== Dữ liệu runtime (volume local, upload) =====
+data/
+knowledge/*
+!knowledge/.gitkeep
+!knowledge/README.md
+!knowledge/samples/
+
+# ===== IDE / OS =====
+.idea/
+.vscode/*
+!.vscode/extensions.json
+.DS_Store
+Thumbs.db
+*.swp

msai_client-0.1.0/LICENSE

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

msai_client-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: msai-client
+Version: 0.1.0
+Summary: Client Python cho public API của MS AI Platform — sinh từ OpenAPI public, có Idempotency-Key + kiểm chữ ký webhook
+Project-URL: Homepage, https://msai.manhhao.com/developers
+Project-URL: Documentation, https://msai.manhhao.com/developers
+Project-URL: API reference, https://msai.manhhao.com/api/v1/public/docs
+Author: Manh Nguyen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,iot,msai,openapi,robotics,webhooks
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: attrs>=23.2
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
+# msai-client — SDK Python cho public API MS AI Platform
+
+Sinh từ OpenAPI public (`/api/v1/public/openapi.json`) bằng `openapi-python-client` + phần viết tay:
+client có `Idempotency-Key` tự động + gửi lại an toàn, kiểm chữ ký webhook (Standard Webhooks). Python ≥ 3.11.
+
+```bash
+pip install msai-client        # hoặc uv add msai-client
+```
+
+Hướng dẫn tích hợp đầy đủ (tài khoản dịch vụ, API key, webhook, hạn mức): https://msai.manhhao.com/developers ·
+tài liệu API: https://msai.manhhao.com/api/v1/public/docs. License MIT.
+
+## Gọi API
+
+```python
+import os
+
+from msai_client import create_client
+from msai_client.generated.api.module_robotics import (
+    create_command_api_v1_modules_robotics_devices_device_id_commands_post as create_command,
+    list_workspaces_api_v1_modules_robotics_workspaces_get as list_workspaces,
+)
+from msai_client.generated.models import CommandIn
+
+msai = create_client("https://msai.manhhao.com", os.environ["MSAI_API_KEY"])
+workspaces = list_workspaces.sync(client=msai)            # model đã parse, None nếu mã lạ
+response = create_command.sync_detailed(device_id, client=msai, body=CommandIn(...))
+print(response.status_code, response.parsed)
+```
+
+- Key gửi qua header `X-API-Key`, không bao giờ qua query string.
+- Request ghi (POST / PUT / PATCH / DELETE) tự có `Idempotency-Key`; lỗi mạng / 502 / 503 / 504 → gửi lại **cùng
+  khóa** (mặc định 2 lần) — server trả lại kết quả cũ nên không tạo lệnh trùng. Chỉnh: `create_client(..., retry=
+  RetryPolicy(max_retries=0))`.
+- Mỗi hàm có `sync`, `sync_detailed`, `asyncio`, `asyncio_detailed`.
+- Cần `Idempotency-Key` tự chọn (vd. mã đơn của hệ thống mình): gọi qua `msai.get_httpx_client().post(path, json=...,
+  headers={"Idempotency-Key": "order-42"})` — transport giữ nguyên khóa đó. Không dùng `with_headers()` (tạo client mới
+  mất transport idempotency).
+- Endpoint trả / nhận nhị phân (ảnh snapshot, audio, upload frame camera) không có trong code sinh — gọi trực tiếp
+  `msai.get_httpx_client().get(...)`.
+
+## Nhận webhook
+
+```python
+from msai_client import WebhookVerificationError, verify_webhook
+
+try:
+    verified = verify_webhook(os.environ["MSAI_WEBHOOK_SECRET"], request.headers, raw_body)
+except WebhookVerificationError:
+    return 400
+# verified.id trùng với lần nhận trước → bỏ qua (at-least-once)
+```
+
+## Sinh lại (người bảo trì)
+
+Không sửa tay `src/msai_client/generated/`. Sau khi đổi route public:
+
+```bash
+uv run python scripts/export_public_openapi.py   # cập nhật snapshot
+uv run python scripts/sdk/generate.py            # sinh lại 2 SDK
+uv run python scripts/sdk/generate.py --check    # CI: SDK khớp OpenAPI public
+```

msai_client-0.1.0/README.md

@@ -0,0 +1,62 @@
+# msai-client — SDK Python cho public API MS AI Platform
+
+Sinh từ OpenAPI public (`/api/v1/public/openapi.json`) bằng `openapi-python-client` + phần viết tay:
+client có `Idempotency-Key` tự động + gửi lại an toàn, kiểm chữ ký webhook (Standard Webhooks). Python ≥ 3.11.
+
+```bash
+pip install msai-client        # hoặc uv add msai-client
+```
+
+Hướng dẫn tích hợp đầy đủ (tài khoản dịch vụ, API key, webhook, hạn mức): https://msai.manhhao.com/developers ·
+tài liệu API: https://msai.manhhao.com/api/v1/public/docs. License MIT.
+
+## Gọi API
+
+```python
+import os
+
+from msai_client import create_client
+from msai_client.generated.api.module_robotics import (
+    create_command_api_v1_modules_robotics_devices_device_id_commands_post as create_command,
+    list_workspaces_api_v1_modules_robotics_workspaces_get as list_workspaces,
+)
+from msai_client.generated.models import CommandIn
+
+msai = create_client("https://msai.manhhao.com", os.environ["MSAI_API_KEY"])
+workspaces = list_workspaces.sync(client=msai)            # model đã parse, None nếu mã lạ
+response = create_command.sync_detailed(device_id, client=msai, body=CommandIn(...))
+print(response.status_code, response.parsed)
+```
+
+- Key gửi qua header `X-API-Key`, không bao giờ qua query string.
+- Request ghi (POST / PUT / PATCH / DELETE) tự có `Idempotency-Key`; lỗi mạng / 502 / 503 / 504 → gửi lại **cùng
+  khóa** (mặc định 2 lần) — server trả lại kết quả cũ nên không tạo lệnh trùng. Chỉnh: `create_client(..., retry=
+  RetryPolicy(max_retries=0))`.
+- Mỗi hàm có `sync`, `sync_detailed`, `asyncio`, `asyncio_detailed`.
+- Cần `Idempotency-Key` tự chọn (vd. mã đơn của hệ thống mình): gọi qua `msai.get_httpx_client().post(path, json=...,
+  headers={"Idempotency-Key": "order-42"})` — transport giữ nguyên khóa đó. Không dùng `with_headers()` (tạo client mới
+  mất transport idempotency).
+- Endpoint trả / nhận nhị phân (ảnh snapshot, audio, upload frame camera) không có trong code sinh — gọi trực tiếp
+  `msai.get_httpx_client().get(...)`.
+
+## Nhận webhook
+
+```python
+from msai_client import WebhookVerificationError, verify_webhook
+
+try:
+    verified = verify_webhook(os.environ["MSAI_WEBHOOK_SECRET"], request.headers, raw_body)
+except WebhookVerificationError:
+    return 400
+# verified.id trùng với lần nhận trước → bỏ qua (at-least-once)
+```
+
+## Sinh lại (người bảo trì)
+
+Không sửa tay `src/msai_client/generated/`. Sau khi đổi route public:
+
+```bash
+uv run python scripts/export_public_openapi.py   # cập nhật snapshot
+uv run python scripts/sdk/generate.py            # sinh lại 2 SDK
+uv run python scripts/sdk/generate.py --check    # CI: SDK khớp OpenAPI public
+```

msai_client-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "msai-client"
+version = "0.1.0"
+description = "Client Python cho public API của MS AI Platform — sinh từ OpenAPI public, có Idempotency-Key + kiểm chữ ký webhook"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Manh Nguyen" }]
+keywords = ["msai", "api-client", "openapi", "webhooks", "robotics", "iot"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+dependencies = [
+  # Runtime của code sinh (openapi-python-client) — đều đã có trong lock của nền tảng.
+  "httpx>=0.28",
+  "attrs>=23.2",
+]
+
+[project.urls]
+Homepage = "https://msai.manhhao.com/developers"
+Documentation = "https://msai.manhhao.com/developers"
+"API reference" = "https://msai.manhhao.com/api/v1/public/docs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/msai_client"]
+
+# sdist cho PyPI: chỉ code + README + LICENSE (test của repo dùng package nội bộ msai_webhooks).
+[tool.hatch.build.targets.sdist]
+include = ["src/msai_client", "README.md", "LICENSE"]

msai_client-0.1.0/src/msai_client/__init__.py

@@ -0,0 +1,40 @@
+"""Client Python cho public API của MS AI Platform (P93, ADR-0072 mục 6).
+
+- ``create_client`` — client dùng API key, tự ``Idempotency-Key`` + gửi lại an toàn.
+- ``msai_client.generated.api.<nhóm>.<operation>`` — hàm gọi từng endpoint (sinh từ OpenAPI public, không sửa tay).
+- ``verify_webhook`` — kiểm chữ ký webhook (Standard Webhooks).
+"""
+
+from msai_client.client import (
+    IDEMPOTENCY_HEADER,
+    AsyncIdempotentTransport,
+    IdempotentTransport,
+    RetryPolicy,
+    create_client,
+    new_idempotency_key,
+)
+from msai_client.generated.client import AuthenticatedClient
+from msai_client.generated.errors import UnexpectedStatus
+from msai_client.webhooks import (
+    VerifiedWebhook,
+    WebhookVerificationError,
+    sign_webhook,
+    verify_webhook,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "IDEMPOTENCY_HEADER",
+    "AsyncIdempotentTransport",
+    "AuthenticatedClient",
+    "IdempotentTransport",
+    "RetryPolicy",
+    "UnexpectedStatus",
+    "VerifiedWebhook",
+    "WebhookVerificationError",
+    "create_client",
+    "new_idempotency_key",
+    "sign_webhook",
+    "verify_webhook",
+]

msai_client-0.1.0/src/msai_client/client.py

@@ -0,0 +1,143 @@
+"""Tạo client MSAI dùng API key: gắn ``X-API-Key``, tự sinh ``Idempotency-Key`` cho request ghi và gửi lại an toàn
+khi lỗi mạng / 502 / 503 / 504 với **cùng khóa** (ADR-0072 mục 3, BR-API-19) — server trả lại response cũ nếu lần
+trước đã chạy, nên không tạo lệnh / tài nguyên trùng.
+
+Client trả về là ``AuthenticatedClient`` của code sinh → dùng trực tiếp với mọi hàm trong ``msai_client.generated.api``.
+"""
+
+import asyncio
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Final
+
+import httpx
+
+from msai_client.generated.client import AuthenticatedClient
+
+IDEMPOTENCY_HEADER: Final = "Idempotency-Key"
+API_KEY_HEADER: Final = "X-API-Key"
+DEFAULT_MAX_RETRIES: Final = 2
+DEFAULT_RETRY_DELAY_SECONDS: Final = 0.3
+DEFAULT_TIMEOUT_SECONDS: Final = 30.0
+_MUTATING_METHODS: Final = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+_RETRYABLE_STATUSES: Final = frozenset({502, 503, 504})
+
+
+def new_idempotency_key() -> str:
+    """Khóa ngẫu nhiên hợp lệ (``[A-Za-z0-9_-]``, ≤ 64 ký tự)."""
+    return str(uuid.uuid4())
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    max_retries: int = DEFAULT_MAX_RETRIES
+    retry_delay_seconds: float = DEFAULT_RETRY_DELAY_SECONDS
+
+    def delay(self, attempt: int) -> float:
+        return float(self.retry_delay_seconds * 2**attempt)
+
+
+def _ensure_idempotency_key(request: httpx.Request) -> None:
+    if request.method in _MUTATING_METHODS and IDEMPOTENCY_HEADER not in request.headers:
+        request.headers[IDEMPOTENCY_HEADER] = new_idempotency_key()
+
+
+class IdempotentTransport(httpx.BaseTransport):
+    def __init__(
+        self,
+        inner: httpx.BaseTransport,
+        policy: RetryPolicy,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._inner = inner
+        self._policy = policy
+        self._sleep = sleep
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        _ensure_idempotency_key(request)
+        request.read()
+        for attempt in range(self._policy.max_retries + 1):
+            is_last = attempt == self._policy.max_retries
+            try:
+                response = self._inner.handle_request(request)
+            except httpx.TransportError:
+                if is_last:
+                    raise
+            else:
+                if is_last or response.status_code not in _RETRYABLE_STATUSES:
+                    return response
+                response.close()
+            self._sleep(self._policy.delay(attempt))
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    def close(self) -> None:
+        self._inner.close()
+
+
+class AsyncIdempotentTransport(httpx.AsyncBaseTransport):
+    def __init__(self, inner: httpx.AsyncBaseTransport, policy: RetryPolicy) -> None:
+        self._inner = inner
+        self._policy = policy
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        _ensure_idempotency_key(request)
+        await request.aread()
+        for attempt in range(self._policy.max_retries + 1):
+            is_last = attempt == self._policy.max_retries
+            try:
+                response = await self._inner.handle_async_request(request)
+            except httpx.TransportError:
+                if is_last:
+                    raise
+            else:
+                if is_last or response.status_code not in _RETRYABLE_STATUSES:
+                    return response
+                await response.aclose()
+            await asyncio.sleep(self._policy.delay(attempt))
+        raise AssertionError("unreachable")  # pragma: no cover
+
+    async def aclose(self) -> None:
+        await self._inner.aclose()
+
+
+def create_client(
+    base_url: str,
+    api_key: str,
+    *,
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+    retry: RetryPolicy | None = None,
+    transport: httpx.BaseTransport | None = None,
+    async_transport: httpx.AsyncBaseTransport | None = None,
+) -> AuthenticatedClient:
+    """``base_url``: gốc máy chủ MSAI (vd. ``https://ai.example.com``, không gồm ``/api/v1``).
+
+    ``transport`` / ``async_transport``: thay transport mạng (test với ``httpx.MockTransport``, proxy).
+    """
+    policy = retry or RetryPolicy()
+    base = base_url.rstrip("/")
+    timeout = httpx.Timeout(timeout_seconds)
+    headers = {API_KEY_HEADER: api_key}
+    client = AuthenticatedClient(
+        base_url=base, token=api_key, auth_header_name=API_KEY_HEADER, prefix="", timeout=timeout
+    )
+    client.set_httpx_client(
+        httpx.Client(
+            base_url=base,
+            headers=headers,
+            timeout=timeout,
+            transport=IdempotentTransport(transport or httpx.HTTPTransport(), policy),
+        )
+    )
+    client.set_async_httpx_client(
+        httpx.AsyncClient(
+            base_url=base,
+            headers=headers,
+            timeout=timeout,
+            transport=AsyncIdempotentTransport(
+                async_transport or httpx.AsyncHTTPTransport(), policy
+            ),
+        )
+    )
+    return client

msai_client-0.1.0/src/msai_client/generated/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing MSAI Public API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

msai_client-0.1.0/src/msai_client/generated/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

msai_client-0.1.0/src/msai_client/generated/api/agent/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""

msai_client-0.1.0/src/msai_client/generated/api/agent/cancel_run_api_v1_agent_runs_run_id_cancel_post.py

@@ -0,0 +1,176 @@
+from http import HTTPStatus
+from typing import Any, cast
+from urllib.parse import quote
+
+import httpx
+
+from ...client import AuthenticatedClient, Client
+from ...types import Response, UNSET
+from ... import errors
+
+from ...models.agent_run_out import AgentRunOut
+from ...models.http_validation_error import HTTPValidationError
+from typing import cast
+from uuid import UUID
+
+
+def _get_kwargs(
+    run_id: UUID,
+) -> dict[str, Any]:
+
+    _kwargs: dict[str, Any] = {
+        "method": "post",
+        "url": "/api/v1/agent/runs/{run_id}/cancel".format(
+            run_id=quote(str(run_id), safe=""),
+        ),
+    }
+
+    return _kwargs
+
+
+def _parse_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> AgentRunOut | HTTPValidationError | None:
+    if response.status_code == 200:
+        response_200 = AgentRunOut.from_dict(response.json())
+
+        return response_200
+
+    if response.status_code == 422:
+        response_422 = HTTPValidationError.from_dict(response.json())
+
+        return response_422
+
+    if client.raise_on_unexpected_status:
+        raise errors.UnexpectedStatus(response.status_code, response.content)
+    else:
+        return None
+
+
+def _build_response(
+    *, client: AuthenticatedClient | Client, response: httpx.Response
+) -> Response[AgentRunOut | HTTPValidationError]:
+    return Response(
+        status_code=HTTPStatus(response.status_code),
+        content=response.content,
+        headers=response.headers,
+        parsed=_parse_response(client=client, response=response),
+    )
+
+
+def sync_detailed(
+    run_id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> Response[AgentRunOut | HTTPValidationError]:
+    """Cancel Run
+
+     Run đang chạy: trả ``cancel_requested=true``, worker dừng trong ~1 s (event ``status`` cancelled).
+    409 ``agent_run_finished`` nếu run đã kết thúc.
+
+    Args:
+        run_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AgentRunOut | HTTPValidationError]
+    """
+
+    kwargs = _get_kwargs(
+        run_id=run_id,
+    )
+
+    response = client.get_httpx_client().request(
+        **kwargs,
+    )
+
+    return _build_response(client=client, response=response)
+
+
+def sync(
+    run_id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> AgentRunOut | HTTPValidationError | None:
+    """Cancel Run
+
+     Run đang chạy: trả ``cancel_requested=true``, worker dừng trong ~1 s (event ``status`` cancelled).
+    409 ``agent_run_finished`` nếu run đã kết thúc.
+
+    Args:
+        run_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AgentRunOut | HTTPValidationError
+    """
+
+    return sync_detailed(
+        run_id=run_id,
+        client=client,
+    ).parsed
+
+
+async def asyncio_detailed(
+    run_id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> Response[AgentRunOut | HTTPValidationError]:
+    """Cancel Run
+
+     Run đang chạy: trả ``cancel_requested=true``, worker dừng trong ~1 s (event ``status`` cancelled).
+    409 ``agent_run_finished`` nếu run đã kết thúc.
+
+    Args:
+        run_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        Response[AgentRunOut | HTTPValidationError]
+    """
+
+    kwargs = _get_kwargs(
+        run_id=run_id,
+    )
+
+    response = await client.get_async_httpx_client().request(**kwargs)
+
+    return _build_response(client=client, response=response)
+
+
+async def asyncio(
+    run_id: UUID,
+    *,
+    client: AuthenticatedClient,
+) -> AgentRunOut | HTTPValidationError | None:
+    """Cancel Run
+
+     Run đang chạy: trả ``cancel_requested=true``, worker dừng trong ~1 s (event ``status`` cancelled).
+    409 ``agent_run_finished`` nếu run đã kết thúc.
+
+    Args:
+        run_id (UUID):
+
+    Raises:
+        errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
+        httpx.TimeoutException: If the request takes longer than Client.timeout.
+
+    Returns:
+        AgentRunOut | HTTPValidationError
+    """
+
+    return (
+        await asyncio_detailed(
+            run_id=run_id,
+            client=client,
+        )
+    ).parsed