ikc-open-platform-sdk 0.1.0__tar.gz

ikc_open_platform_sdk-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# Runtime data
+data/
+logs/
+*.db
+*.sqlite3
+uploads/
+
+# Secrets
+.env
+*.pem
+*.key
+
+# Frontend (portal)
+portal/node_modules/
+portal/dist/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

ikc_open_platform_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: ikc-open-platform-sdk
+Version: 0.1.0
+Summary: ikc-open-platform 第三方开发者 SDK：API Key 认证 + 统一壳解包 + 四类业务域（知识库/文档/解析/检索），业务模型复用 ikc-sdk-lib
+Author: SITECH-iKM
+Requires-Python: >=3.12
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: ikc-sdk-lib==0.6.1
+Requires-Dist: pydantic<3.0,>=2.7
+Description-Content-Type: text/markdown
+
+# ikc-open-platform-sdk
+
+ikc-open-platform 第三方开发者 SDK（导入包 `ikc_open_platform_sdk`）。
+
+- 认证：应用 API Key（`Authorization: Bearer <api-key>`，由管理面 `/admin/apps/{appId}/keys` 创建）。
+- 协议：统一响应壳 `errCode/errMsg/data/traceId/reqId` 解包；业务模型一律复用 `ikc-sdk-lib`（本 SDK 不自定义业务模型）。
+- 追踪：每请求注入 23 位纯数字 `X-Request-Id`；`reqId` 可显式传入，缺省 SDK 生成 `req_` 前缀值并随壳回显。
+- 能力面（四类业务域）：
+  - `client.knowledge_bases`：create / update / query / get
+  - `client.documents`：ingest / ingest_and_parse / upload / get
+  - `client.parse`：parse / parse_direct / query_result / issue_download_ticket / download
+  - `client.search`：universal_search / deep_search / query（兼容别名）
+- 错误模型：`OpenPlatformAPIError`（errCode/errMsg/traceId/reqId）、`OpenPlatformConnectionError`、`OpenPlatformTimeoutError`、`OpenPlatformProtocolError`。
+
+## 安装
+
+```bash
+pip install ikc-open-platform-sdk          # PyPI（发布后）
+pip install sdk/python/                    # 或本地源码
+```
+
+## 快速开始
+
+```python
+from ikc_open_platform_sdk import OpenPlatformClient
+from ikc_sdk.core.api.search.universal import SearchQueryRequest
+
+with OpenPlatformClient("http://localhost:18000", api_key="<app-api-key>") as client:
+    result = client.search.universal_search(SearchQueryRequest(query="IKC 平台"))
+    for hit in result.hits:
+        print(hit)
+```
+
+## 测试
+
+```bash
+python -m pytest sdk/python/tests -q
+```

ikc_open_platform_sdk-0.1.0/README.md

@@ -0,0 +1,38 @@
+# ikc-open-platform-sdk
+
+ikc-open-platform 第三方开发者 SDK（导入包 `ikc_open_platform_sdk`）。
+
+- 认证：应用 API Key（`Authorization: Bearer <api-key>`，由管理面 `/admin/apps/{appId}/keys` 创建）。
+- 协议：统一响应壳 `errCode/errMsg/data/traceId/reqId` 解包；业务模型一律复用 `ikc-sdk-lib`（本 SDK 不自定义业务模型）。
+- 追踪：每请求注入 23 位纯数字 `X-Request-Id`；`reqId` 可显式传入，缺省 SDK 生成 `req_` 前缀值并随壳回显。
+- 能力面（四类业务域）：
+  - `client.knowledge_bases`：create / update / query / get
+  - `client.documents`：ingest / ingest_and_parse / upload / get
+  - `client.parse`：parse / parse_direct / query_result / issue_download_ticket / download
+  - `client.search`：universal_search / deep_search / query（兼容别名）
+- 错误模型：`OpenPlatformAPIError`（errCode/errMsg/traceId/reqId）、`OpenPlatformConnectionError`、`OpenPlatformTimeoutError`、`OpenPlatformProtocolError`。
+
+## 安装
+
+```bash
+pip install ikc-open-platform-sdk          # PyPI（发布后）
+pip install sdk/python/                    # 或本地源码
+```
+
+## 快速开始
+
+```python
+from ikc_open_platform_sdk import OpenPlatformClient
+from ikc_sdk.core.api.search.universal import SearchQueryRequest
+
+with OpenPlatformClient("http://localhost:18000", api_key="<app-api-key>") as client:
+    result = client.search.universal_search(SearchQueryRequest(query="IKC 平台"))
+    for hit in result.hits:
+        print(hit)
+```
+
+## 测试
+
+```bash
+python -m pytest sdk/python/tests -q
+```

ikc_open_platform_sdk-0.1.0/ikc_open_platform_sdk/__init__.py

@@ -0,0 +1,23 @@
+"""ikc-open-platform 第三方开发者 SDK。"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .client import OpenPlatformClient
+from .errors import (
+    OpenPlatformAPIError,
+    OpenPlatformConnectionError,
+    OpenPlatformError,
+    OpenPlatformProtocolError,
+    OpenPlatformTimeoutError,
+)
+
+__all__ = [
+    "__version__",
+    "OpenPlatformClient",
+    "OpenPlatformError",
+    "OpenPlatformAPIError",
+    "OpenPlatformConnectionError",
+    "OpenPlatformProtocolError",
+    "OpenPlatformTimeoutError",
+]

ikc_open_platform_sdk-0.1.0/ikc_open_platform_sdk/_version.py

@@ -0,0 +1,3 @@
+"""SDK 版本（与发行版 pyproject 保持一致）。"""
+
+__version__ = "0.1.0"

ikc_open_platform_sdk-0.1.0/ikc_open_platform_sdk/client.py

@@ -0,0 +1,289 @@
+"""ikc-open-platform 第三方开发者同步客户端。
+
+- 认证：``Authorization: Bearer <api-key>``（应用凭证，管理面创建）。
+- 追踪：每次请求注入 23 位纯数字 ``X-Request-Id``；``reqId`` 调用方可传入
+  （POST 由 ikc_sdk 请求模型承载，GET 走 query 参数），缺省由 SDK 生成。
+- 协议：统一壳 ``errCode/errMsg/data/traceId/reqId`` 解包；业务模型一律复用
+  ``ikc_sdk.core.api.*``（本 SDK 不自定义业务模型）。
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+from pydantic import BaseModel
+
+from ikc_sdk.core.api.knowledge_base.create import KnowledgeBaseCreateResult
+from ikc_sdk.core.api.search.universal import SearchQueryResponse
+from ikc_sdk.core.codes import CODE_SUCCESS
+from ikc_sdk.core.headers import TRACE_HEADER_NAMES
+
+from .errors import (
+    OpenPlatformAPIError,
+    OpenPlatformConnectionError,
+    OpenPlatformProtocolError,
+    OpenPlatformTimeoutError,
+)
+
+_TRACE_HEADER = TRACE_HEADER_NAMES[0]  # X-Request-Id
+
+
+def _new_trace_id() -> str:
+    """23 位纯数字：13 位毫秒 + 10 位随机数。"""
+    return f"{int(time.time() * 1000)}{secrets.randbelow(10**10):010d}"
+
+
+def _new_req_id() -> str:
+    return f"req_{_new_trace_id()}"
+
+
+def _dump(payload: BaseModel | dict[str, Any] | None) -> dict[str, Any] | None:
+    if payload is None:
+        return None
+    if isinstance(payload, BaseModel):
+        return payload.model_dump(mode="json", exclude_none=True)
+    return payload
+
+
+class _Transport:
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str,
+        timeout: float,
+        max_retries: int,
+        extra_headers: dict[str, str] | None,
+        http_client: httpx.Client | None,
+    ) -> None:
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(base_url=base_url.rstrip("/"), timeout=timeout)
+        self._api_key = api_key
+        self._max_retries = max_retries
+        self._extra_headers = extra_headers or {}
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        content: bytes | None = None,
+        files: dict[str, Any] | None = None,
+        req_id: str | None = None,
+    ) -> dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            _TRACE_HEADER: _new_trace_id(),
+            **self._extra_headers,
+        }
+        attempt = 0
+        while True:
+            try:
+                resp = self._client.request(
+                    method,
+                    path,
+                    json=json_body,
+                    params=params,
+                    content=content,
+                    files=files,
+                    headers=headers,
+                )
+                break
+            except httpx.TimeoutException as exc:
+                attempt += 1
+                if attempt > self._max_retries:
+                    raise OpenPlatformTimeoutError(str(exc)) from exc
+            except httpx.HTTPError as exc:
+                raise OpenPlatformConnectionError(str(exc)) from exc
+        try:
+            payload = resp.json()
+        except ValueError as exc:
+            raise OpenPlatformProtocolError(f"响应非 JSON（HTTP {resp.status_code}）") from exc
+        if not isinstance(payload, dict) or "errCode" not in payload:
+            raise OpenPlatformProtocolError(f"响应不符合统一协议（HTTP {resp.status_code}）")
+        err_code = str(payload.get("errCode"))
+        if err_code != CODE_SUCCESS:
+            raise OpenPlatformAPIError(
+                err_code,
+                str(payload.get("errMsg") or ""),
+                trace_id=payload.get("traceId"),
+                req_id=payload.get("reqId"),
+                data=payload.get("data"),
+            )
+        return payload
+
+
+class KnowledgeBaseResource:
+    """知识库域（/api/v1/knowledge-bases/*）。"""
+
+    def __init__(self, client: OpenPlatformClient) -> None:
+        self._client = client
+
+    def create(self, payload: BaseModel | dict[str, Any]) -> KnowledgeBaseCreateResult:
+        data = self._client._post("/api/v1/knowledge-bases/create", payload)
+        return KnowledgeBaseCreateResult.model_validate(data)
+
+    def update(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        return self._client._post("/api/v1/knowledge-bases/update", payload)
+
+    def query(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        return self._client._post("/api/v1/knowledge-bases/query", payload)
+
+    def get(self, kb_id: str) -> dict[str, Any]:
+        return self._client._get(f"/api/v1/knowledge-bases/{kb_id}")
+
+
+class DocumentResource:
+    """文档域（/api/v1/knowledge-documents/*）。"""
+
+    def __init__(self, client: OpenPlatformClient) -> None:
+        self._client = client
+
+    def ingest(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        return self._client._post("/api/v1/knowledge-documents/ingest", payload)
+
+    def ingest_and_parse(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        return self._client._post("/api/v1/knowledge-documents/ingest-and-parse", payload)
+
+    def upload(self, file_path: str | Path, *, req_id: str | None = None) -> dict[str, Any]:
+        path = Path(file_path)
+        with path.open("rb") as fh:
+            files = {"file": (path.name, fh)}
+            return self._client._request_data(
+                "POST", "/api/v1/knowledge-documents/upload", files=files, req_id=req_id
+            )
+
+    def get(self, doc_id: str) -> dict[str, Any]:
+        return self._client._get(f"/api/v1/knowledge-documents/{doc_id}")
+
+
+class ParseResource:
+    """解析域（/api/v1/knowledge-documents/parse*）。"""
+
+    def __init__(self, client: OpenPlatformClient) -> None:
+        self._client = client
+
+    def parse(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        return self._client._post("/api/v1/knowledge-documents/parse", payload)
+
+    def parse_direct(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        return self._client._post("/api/v1/knowledge-documents/parse-direct", payload)
+
+    def query_result(self, task_id: str, *, req_id: str | None = None) -> dict[str, Any]:
+        return self._client._get(
+            "/api/v1/knowledge-documents/parse-result/query",
+            params={"taskId": task_id},
+            req_id=req_id,
+        )
+
+    def issue_download_ticket(self) -> dict[str, Any]:
+        return self._client._get("/api/v1/knowledge-documents/parse-result/issue-download-ticket")
+
+    def download(self, task_id: str, *, req_id: str | None = None) -> dict[str, Any]:
+        return self._client._get(
+            "/api/v1/knowledge-documents/parse-result/download",
+            params={"taskId": task_id},
+            req_id=req_id,
+        )
+
+
+class SearchResource:
+    """检索域（/api/v1/knowledge-search/*）。"""
+
+    def __init__(self, client: OpenPlatformClient) -> None:
+        self._client = client
+
+    def universal_search(self, payload: BaseModel | dict[str, Any]) -> SearchQueryResponse:
+        data = self._client._post("/api/v1/knowledge-search/universal-search", payload)
+        return SearchQueryResponse.model_validate(data)
+
+    def deep_search(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        return self._client._post("/api/v1/knowledge-search/deep-search", payload)
+
+    def query(self, payload: BaseModel | dict[str, Any]) -> dict[str, Any]:
+        """兼容别名（/api/v1/knowledge-search/query）。"""
+        return self._client._post("/api/v1/knowledge-search/query", payload)
+
+
+class OpenPlatformClient:
+    """ikc-open-platform 同步客户端（第三方开发者入口）。"""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        api_key: str,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        extra_headers: dict[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = _Transport(
+            base_url,
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+            extra_headers=extra_headers,
+            http_client=http_client,
+        )
+        self.knowledge_bases = KnowledgeBaseResource(self)
+        self.documents = DocumentResource(self)
+        self.parse = ParseResource(self)
+        self.search = SearchResource(self)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> OpenPlatformClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    def _fill_req_id(self, body: dict[str, Any] | None, req_id: str | None) -> dict[str, Any] | None:
+        if body is None:
+            return None
+        if "reqId" not in body or body["reqId"] in (None, ""):
+            body["reqId"] = req_id or _new_req_id()
+        return body
+
+    def _request_data(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        req_id: str | None = None,
+    ) -> dict[str, Any]:
+        payload = self._transport.request(
+            method, path, json_body=json_body, params=params, files=files, req_id=req_id
+        )
+        data = payload.get("data")
+        return data if isinstance(data, dict) else ({} if data is None else {"value": data})
+
+    def _post(self, path: str, payload: BaseModel | dict[str, Any], *, req_id: str | None = None) -> dict[str, Any]:
+        body = self._fill_req_id(_dump(payload), req_id)
+        return self._request_data("POST", path, json_body=body)
+
+    def _get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        req_id: str | None = None,
+    ) -> dict[str, Any]:
+        query = dict(params or {})
+        query.setdefault("reqId", req_id or _new_req_id())
+        return self._request_data("GET", path, params=query)

ikc_open_platform_sdk-0.1.0/ikc_open_platform_sdk/errors.py

@@ -0,0 +1,41 @@
+"""ikc-open-platform 第三方开发者 SDK 统一异常。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OpenPlatformError(Exception):
+    """SDK 基础异常。"""
+
+
+class OpenPlatformAPIError(OpenPlatformError):
+    """平台返回业务错误（errCode != 000000）。"""
+
+    def __init__(
+        self,
+        err_code: str,
+        err_msg: str,
+        *,
+        trace_id: str | None = None,
+        req_id: str | None = None,
+        data: Any = None,
+    ) -> None:
+        super().__init__(f"[{err_code}] {err_msg}")
+        self.err_code = err_code
+        self.err_msg = err_msg
+        self.trace_id = trace_id
+        self.req_id = req_id
+        self.data = data
+
+
+class OpenPlatformConnectionError(OpenPlatformError):
+    """网络连接失败。"""
+
+
+class OpenPlatformTimeoutError(OpenPlatformError):
+    """请求超时。"""
+
+
+class OpenPlatformProtocolError(OpenPlatformError):
+    """响应不符合统一协议（缺 errCode 等非壳结构）。"""

ikc_open_platform_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ikc-open-platform-sdk"
+version = "0.1.0"
+description = "ikc-open-platform 第三方开发者 SDK：API Key 认证 + 统一壳解包 + 四类业务域（知识库/文档/解析/检索），业务模型复用 ikc-sdk-lib"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "SITECH-iKM" }]
+dependencies = [
+  "httpx>=0.27,<1.0",
+  "pydantic>=2.7,<3.0",
+  "ikc-sdk-lib==0.6.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ikc_open_platform_sdk"]

ikc_open_platform_sdk-0.1.0/tests/conftest.py

@@ -0,0 +1,8 @@
+"""SDK 测试夹具：包路径注入（不依赖安装）。"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

ikc_open_platform_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,78 @@
+"""ikc_open_platform_sdk 客户端测试（httpx MockTransport）。"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from ikc_open_platform_sdk import (
+    OpenPlatformAPIError,
+    OpenPlatformClient,
+    OpenPlatformProtocolError,
+)
+
+
+def _client(handler) -> OpenPlatformClient:
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.Client(base_url="http://platform.test", transport=transport)
+    return OpenPlatformClient("http://platform.test", api_key="k-test", http_client=http_client)
+
+
+def test_envelope_unwrap_success() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["Authorization"] == "Bearer k-test"
+        assert len(request.headers["X-Request-Id"]) == 23
+        body = json.loads(request.content.decode())
+        assert body["reqId"].startswith("req_")
+        return httpx.Response(
+            200,
+            json={"errCode": "000000", "errMsg": "success", "data": {"kbId": "kb_1", "kbType": "general", "kbMode": "private", "accessMode": "private", "scopeKey": "s1", "status": "active", "rootUnitId": "u1"}, "traceId": "1" * 23, "reqId": body["reqId"]},
+        )
+
+    client = _client(handler)
+    result = client.knowledge_bases.create({"kbName": "测试", "kbType": "general", "kbMode": "private"})
+    assert result.kbId == "kb_1"
+
+
+def test_api_error_raises_with_trace() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"errCode": "100429", "errMsg": "限流", "data": {}, "traceId": "2" * 23})
+
+    client = _client(handler)
+    with pytest.raises(OpenPlatformAPIError) as exc_info:
+        client.search.query({"query": "x"})
+    assert exc_info.value.err_code == "100429"
+    assert exc_info.value.trace_id == "2" * 23
+
+
+def test_protocol_error_on_non_envelope() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"unexpected": True})
+
+    client = _client(handler)
+    with pytest.raises(OpenPlatformProtocolError):
+        client.knowledge_bases.get("kb_1")
+
+
+def test_get_passes_req_id_param() -> None:
+    captured: dict[str, str] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["reqId"] = httpx.QueryParams(request.url.params)["reqId"]
+        captured["taskId"] = httpx.QueryParams(request.url.params)["taskId"]
+        return httpx.Response(
+            200,
+            json={
+                "errCode": "000000",
+                "errMsg": "success",
+                "data": {"taskId": "t1", "status": "done", "result": {}},
+                "traceId": "3" * 23,
+                "reqId": captured["reqId"],
+            },
+        )
+
+    client = _client(handler)
+    client.parse.query_result("t1", req_id="req_fixed")
+    assert captured == {"reqId": "req_fixed", "taskId": "t1"}