ikc-sdk-lib 0.1.0__tar.gz

ikc_sdk_lib-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: ikc-sdk-lib
+Version: 0.1.0
+Summary: IKC RAG 对外接口 SDK（独立解析 / 查询解析结果 / 下载解析结果）
+Author-email: shark8848 <admin@sharky-ai.com>
+Keywords: ikc,rag,sdk,parse,knowledge-base,retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# ikc-sdk-lib
+
+IKC SDK 家族仓库（Python 模型层），与 `/home/open-ikc` 对外接口一脉相承、独立维护。
+当前整个 SDK 定义为 **core**：`docs/RAG SDK接口.xlsx` 中的 **4 个免知识库接口** 的请求/响应模型（Pydantic v2）。
+后续新增 SDK 以 `ikc_sdk.<sdk_name>` 兄弟子包扩展，不进入 core。
+
+## 当前接口范围（core）
+
+| # | 接口（Excel Sheet） | 请求 | 响应 | 实现位置 |
+| --- | --- | --- | --- | --- |
+| 1 | 解析—独立解析（免知识库）SERVICE | `ServiceParseDirectRequest` | `ParseResponse` | `ikc_sdk/core/api/parse/direct.py` |
+| 2 | 解析—独立解析（免知识库）SDK | `SdkParseDirectRequest` | `ParseResponse` | `ikc_sdk/core/api/parse/direct.py` |
+| 3 | 查询解析结果（免知识库）SDK | `QueryParseResultRequest` | `QueryParseResultResponse` | `ikc_sdk/core/api/parse/query.py` |
+| 4 | 下载解析结果（免知识库）SDK | `DownloadParseResultRequest` | `DownloadParseResultResponse` | `ikc_sdk/core/api/parse/download.py` |
+
+## 目录结构
+
+```
+src/ikc_sdk/
+  __init__.py            # 命名空间门面：re-export core 公开 API
+  _version.py            # 版本号（分发级）
+  core/                  # 核心 SDK（当前整个 SDK）
+    __init__.py          # core 公开导出
+    enums.py             # 契约枚举（取值以 Excel 为准）
+    models/              # 共享模型：响应壳 / 来源 / 解析 / 分段 / 输出 / 任务
+    api/                 # 按能力域组织的接口定义
+      parse/             # 解析域（已定义）：direct（独立解析 SERVICE/SDK）/ query / download
+      knowledge_base/    # 知识库域（占位）：create / update / get / query
+      document/          # 文档域（占位）：ingest / parse / ingest_and_parse / upload / get / parse_result/
+      search/            # 检索域（占位）：universal / deep / query
+  <future_sdk>/          # 后续新增 SDK：兄弟子包（如 client 等），不进入 core
+```
+
+## 使用
+
+规范导入路径为 `ikc_sdk.core`；顶层 `ikc_sdk` 门面 re-export core，两种写法等价：
+
+```python
+from ikc_sdk import SdkParseDirectRequest          # 门面（兼容）
+from ikc_sdk.core import SdkParseDirectRequest     # 规范路径
+from ikc_sdk.core import (
+    DeclaredSource, SourceMetadata, ParsingOptions, OutputOptions,
+    SourceType, DocumentFormat, OutputFormat,
+)
+
+req = SdkParseDirectRequest(
+    processingOperation="EXTRACT_CHUNK",
+    source=DeclaredSource(
+        type=SourceType.URL,
+        url="https://example.com/doc.pdf",
+        metadata=SourceMetadata(docTitle="示例文档"),
+    ),
+    parsing=ParsingOptions(docFormat=DocumentFormat.PDF),
+    output=OutputOptions(formats={OutputFormat.MARKDOWN}),
+)
+print(req.model_dump_json())
+```
+
+## 开发手册
+
+面向开发者的四接口完整开发手册（总体流程、公共契约、每个接口的请求/响应字段与代码示例、
+端到端链路、错误码、类索引）见 `docs/开发手册.md`。
+
+## 开发示例
+
+4 个接口的可运行示例位于 `src/examples/`（请求构建、契约校验、序列化、响应解析）：
+
+```bash
+cd /home/sharkyai/ikc-sdk-lib
+PYTHONPATH=src python3 src/examples/parse_direct_sdk.py
+PYTHONPATH=src python3 src/examples/parse_direct_service.py
+PYTHONPATH=src python3 src/examples/query_parse_result.py
+PYTHONPATH=src python3 src/examples/download_parse_result.py
+```
+
+## 占位目录（契约待定义）
+
+知识库 / 文档 / 检索三个域目前仅有目录骨架，接口契约待 `docs/RAG SDK接口.xlsx` 增补后定义
+（参考 open-ikc V2 接口清单占位），在契约落定前**不定义模型**：
+
+| 域 | 计划接口 | 参考 |
+| --- | --- | --- |
+| 知识库 | `create` / `update` / `get` / `query` | open-ikc A-01~A-04 |
+| 文档 | `ingest` / `parse` / `ingest_and_parse` / `upload` / `get` / `parse_result/{query,issue_ticket,download}` | open-ikc B-01~B-07 |
+| 检索 | `universal` / `deep` / `query` | open-ikc D-01/D-02 |
+
+## 契约约定
+
+- 字段命名（camelCase）与枚举值一律以 `docs/RAG SDK接口.xlsx` 为准，含 Excel 原文拼写（如 `keyswordNum`、`docMetadataPormpt`），不得“顺手修正”。
+- 统一响应壳：`errCode / errMsg / data / traceId`（独立解析与下载接口额外带 `taskId`）。
+- SDK 版请求面向 API 调用方（source 自声明），SERVICE 版为 API 之后调用后端 service（source 指向已登记文档）；两版以 `ParseDirectRequestBase` 为基类派生，类名严格遵循 Excel Sheet 定义。
+- Excel 引用的对象类型均有对应模型类（映射见 `AGENTS.md` §3.4，如 `ModelConfig`）；`ModelReferences` 各字段为 `ModelConfig` 的 DES 加密串。
+- 完整的设计与实现契约见 `AGENTS.md`（能力域地图、目录/命名规范、落地工作流、硬性约束）。

ikc_sdk_lib-0.1.0/README.md

@@ -0,0 +1,93 @@
+# ikc-sdk-lib
+
+IKC SDK 家族仓库（Python 模型层），与 `/home/open-ikc` 对外接口一脉相承、独立维护。
+当前整个 SDK 定义为 **core**：`docs/RAG SDK接口.xlsx` 中的 **4 个免知识库接口** 的请求/响应模型（Pydantic v2）。
+后续新增 SDK 以 `ikc_sdk.<sdk_name>` 兄弟子包扩展，不进入 core。
+
+## 当前接口范围（core）
+
+| # | 接口（Excel Sheet） | 请求 | 响应 | 实现位置 |
+| --- | --- | --- | --- | --- |
+| 1 | 解析—独立解析（免知识库）SERVICE | `ServiceParseDirectRequest` | `ParseResponse` | `ikc_sdk/core/api/parse/direct.py` |
+| 2 | 解析—独立解析（免知识库）SDK | `SdkParseDirectRequest` | `ParseResponse` | `ikc_sdk/core/api/parse/direct.py` |
+| 3 | 查询解析结果（免知识库）SDK | `QueryParseResultRequest` | `QueryParseResultResponse` | `ikc_sdk/core/api/parse/query.py` |
+| 4 | 下载解析结果（免知识库）SDK | `DownloadParseResultRequest` | `DownloadParseResultResponse` | `ikc_sdk/core/api/parse/download.py` |
+
+## 目录结构
+
+```
+src/ikc_sdk/
+  __init__.py            # 命名空间门面：re-export core 公开 API
+  _version.py            # 版本号（分发级）
+  core/                  # 核心 SDK（当前整个 SDK）
+    __init__.py          # core 公开导出
+    enums.py             # 契约枚举（取值以 Excel 为准）
+    models/              # 共享模型：响应壳 / 来源 / 解析 / 分段 / 输出 / 任务
+    api/                 # 按能力域组织的接口定义
+      parse/             # 解析域（已定义）：direct（独立解析 SERVICE/SDK）/ query / download
+      knowledge_base/    # 知识库域（占位）：create / update / get / query
+      document/          # 文档域（占位）：ingest / parse / ingest_and_parse / upload / get / parse_result/
+      search/            # 检索域（占位）：universal / deep / query
+  <future_sdk>/          # 后续新增 SDK：兄弟子包（如 client 等），不进入 core
+```
+
+## 使用
+
+规范导入路径为 `ikc_sdk.core`；顶层 `ikc_sdk` 门面 re-export core，两种写法等价：
+
+```python
+from ikc_sdk import SdkParseDirectRequest          # 门面（兼容）
+from ikc_sdk.core import SdkParseDirectRequest     # 规范路径
+from ikc_sdk.core import (
+    DeclaredSource, SourceMetadata, ParsingOptions, OutputOptions,
+    SourceType, DocumentFormat, OutputFormat,
+)
+
+req = SdkParseDirectRequest(
+    processingOperation="EXTRACT_CHUNK",
+    source=DeclaredSource(
+        type=SourceType.URL,
+        url="https://example.com/doc.pdf",
+        metadata=SourceMetadata(docTitle="示例文档"),
+    ),
+    parsing=ParsingOptions(docFormat=DocumentFormat.PDF),
+    output=OutputOptions(formats={OutputFormat.MARKDOWN}),
+)
+print(req.model_dump_json())
+```
+
+## 开发手册
+
+面向开发者的四接口完整开发手册（总体流程、公共契约、每个接口的请求/响应字段与代码示例、
+端到端链路、错误码、类索引）见 `docs/开发手册.md`。
+
+## 开发示例
+
+4 个接口的可运行示例位于 `src/examples/`（请求构建、契约校验、序列化、响应解析）：
+
+```bash
+cd /home/sharkyai/ikc-sdk-lib
+PYTHONPATH=src python3 src/examples/parse_direct_sdk.py
+PYTHONPATH=src python3 src/examples/parse_direct_service.py
+PYTHONPATH=src python3 src/examples/query_parse_result.py
+PYTHONPATH=src python3 src/examples/download_parse_result.py
+```
+
+## 占位目录（契约待定义）
+
+知识库 / 文档 / 检索三个域目前仅有目录骨架，接口契约待 `docs/RAG SDK接口.xlsx` 增补后定义
+（参考 open-ikc V2 接口清单占位），在契约落定前**不定义模型**：
+
+| 域 | 计划接口 | 参考 |
+| --- | --- | --- |
+| 知识库 | `create` / `update` / `get` / `query` | open-ikc A-01~A-04 |
+| 文档 | `ingest` / `parse` / `ingest_and_parse` / `upload` / `get` / `parse_result/{query,issue_ticket,download}` | open-ikc B-01~B-07 |
+| 检索 | `universal` / `deep` / `query` | open-ikc D-01/D-02 |
+
+## 契约约定
+
+- 字段命名（camelCase）与枚举值一律以 `docs/RAG SDK接口.xlsx` 为准，含 Excel 原文拼写（如 `keyswordNum`、`docMetadataPormpt`），不得“顺手修正”。
+- 统一响应壳：`errCode / errMsg / data / traceId`（独立解析与下载接口额外带 `taskId`）。
+- SDK 版请求面向 API 调用方（source 自声明），SERVICE 版为 API 之后调用后端 service（source 指向已登记文档）；两版以 `ParseDirectRequestBase` 为基类派生，类名严格遵循 Excel Sheet 定义。
+- Excel 引用的对象类型均有对应模型类（映射见 `AGENTS.md` §3.4，如 `ModelConfig`）；`ModelReferences` 各字段为 `ModelConfig` 的 DES 加密串。
+- 完整的设计与实现契约见 `AGENTS.md`（能力域地图、目录/命名规范、落地工作流、硬性约束）。

ikc_sdk_lib-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ikc-sdk-lib"
+version = "0.1.0"
+description = "IKC RAG 对外接口 SDK（独立解析 / 查询解析结果 / 下载解析结果）"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "shark8848", email = "admin@sharky-ai.com" }]
+keywords = ["ikc", "rag", "sdk", "parse", "knowledge-base", "retrieval"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = ["pydantic>=2.7"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["ikc_sdk*"]

ikc_sdk_lib-0.1.0/setup.cfg

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

ikc_sdk_lib-0.1.0/src/ikc_sdk/__init__.py

@@ -0,0 +1,13 @@
+"""IKC SDK 家族命名空间
+
+当前包含一个核心 SDK：
+- core：IKC RAG 对外接口请求/响应模型契约（docs/RAG SDK接口.xlsx 四接口）
+
+后续新增 SDK 以 `ikc_sdk.<sdk_name>` 兄弟子包扩展，并在本文件评估是否合并导出。
+既有的 `from ikc_sdk import <name>` 用法由 core 再导出保持兼容。
+"""
+from . import core
+from ._version import __version__
+from .core import *  # noqa: F401,F403  # 兼容既有顶层导入
+
+__all__ = list(dict.fromkeys(["core", "__version__", *core.__all__]))

ikc_sdk_lib-0.1.0/src/ikc_sdk/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/__init__.py

@@ -0,0 +1,123 @@
+"""IKC RAG 对外接口核心 SDK（core）
+
+当前范围：docs/RAG SDK接口.xlsx 定义的 4 个免知识库接口的请求/响应模型：
+1. 独立解析（免知识库）SERVICE —— ServiceParseDirectRequest / ParseResponse
+2. 独立解析（免知识库）SDK   —— SdkParseDirectRequest / ParseResponse
+3. 查询解析结果（免知识库）SDK —— QueryParseResultRequest / QueryParseResultResponse
+4. 下载解析结果（免知识库）SDK —— DownloadParseResultRequest / DownloadParseResultResponse
+
+定位：SDK 版请求面向 API 调用方（source 自声明），SERVICE 版为 API 之后调用后端
+service（source 指向已登记文档）；两版以 ParseDirectRequestBase 为基类派生，
+类名严格遵循 Excel Sheet 定义。查询 / 下载接口独立定义，严格遵循 Excel。
+契约权威：AGENTS.md + 当前代码 > docs/RAG SDK接口.xlsx；字段命名（camelCase）
+与枚举值一律以 Excel 为准（含 Excel 原文拼写，如 keyswordNum / Pormpt）。
+"""
+from ikc_sdk._version import __version__
+
+from .api.parse import (
+    DownloadParseResultRequest,
+    DownloadParseResultResponse,
+    ParseDirectRequestBase,
+    ParseResponse,
+    QueryParseResultRequest,
+    QueryParseResultResponse,
+    SdkParseDirectRequest,
+    ServiceParseDirectRequest,
+)
+from .enums import (
+    ChunkType,
+    DocumentCategory,
+    DocumentFormat,
+    ExecutionMode,
+    FinalTaskStatus,
+    ImageEncoding,
+    ImageParsingMode,
+    MetadataMode,
+    OutputFormat,
+    OwnerType,
+    ParsingFlag,
+    ProcessingOperation,
+    ProcessingStage,
+    QaScope,
+    SourceType,
+    SubTaskStatus,
+    TaskStatus,
+)
+from .models import (
+    ChunkAugmentationOptions,
+    ChunkingOptions,
+    DeclaredSource,
+    DocumentAugmentation,
+    DocumentIngestionTask,
+    Envelope,
+    ModelConfig,
+    ModelReferences,
+    ObjectStorage,
+    OutputOptions,
+    ParsingOptions,
+    ProcessingTask,
+    PromptDetail,
+    QaGenerationOptions,
+    RegisteredMetadata,
+    RegisteredSource,
+    ResultArtifact,
+    SourceMetadata,
+    StorageTarget,
+    SubTask,
+    TaskEnvelope,
+)
+
+__all__ = [
+    "__version__",
+    # 枚举
+    "ChunkType",
+    "DocumentCategory",
+    "DocumentFormat",
+    "ExecutionMode",
+    "FinalTaskStatus",
+    "ImageEncoding",
+    "ImageParsingMode",
+    "MetadataMode",
+    "OutputFormat",
+    "OwnerType",
+    "ParsingFlag",
+    "ProcessingOperation",
+    "ProcessingStage",
+    "QaScope",
+    "SourceType",
+    "SubTaskStatus",
+    "TaskStatus",
+    # 共享模型
+    "ChunkAugmentationOptions",
+    "ChunkingOptions",
+    "DeclaredSource",
+    "DocumentAugmentation",
+    "DocumentIngestionTask",
+    "Envelope",
+    "ModelConfig",
+    "ModelReferences",
+    "ObjectStorage",
+    "OutputOptions",
+    "ParsingOptions",
+    "ProcessingTask",
+    "PromptDetail",
+    "QaGenerationOptions",
+    "RegisteredMetadata",
+    "RegisteredSource",
+    "ResultArtifact",
+    "SourceMetadata",
+    "StorageTarget",
+    "SubTask",
+    "TaskEnvelope",
+    # 独立解析（免知识库）SERVICE / SDK
+    "ParseDirectRequestBase",
+    "ParseResponse",
+    "SdkParseDirectRequest",
+    "ServiceParseDirectRequest",
+    # 查询解析结果（免知识库）SDK
+    "QueryParseResultRequest",
+    "QueryParseResultResponse",
+    # 下载解析结果（免知识库）SDK
+    "DownloadParseResultRequest",
+    "DownloadParseResultResponse",
+]

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/__init__.py

@@ -0,0 +1,11 @@
+"""对外接口分包
+
+按能力域组织（一文件一接口，`<action>.py`）：
+- parse/  解析域：已定义（对应 docs/RAG SDK接口.xlsx 四张 Sheet）
+  - direct.py       独立解析（免知识库）SERVICE / SDK（基类 + 两版请求 + ParseResponse）
+  - query.py       查询解析结果（免知识库）
+  - download.py    下载解析结果（免知识库）
+- knowledge_base/  知识库域：占位，契约待定义（create/update/get/query）
+- document/        文档域：占位，契约待定义（ingest/parse/ingest_and_parse/upload/get/parse_result/）
+- search/          检索域：占位，契约待定义（universal/deep/query）
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/__init__.py

@@ -0,0 +1,10 @@
+"""文档域（占位）
+
+接口契约待 docs/RAG SDK接口.xlsx 增补后定义，当前仅目录骨架，不定义模型：
+- ingest.py            接入知识源（URL/文件/目录/压缩包）
+- parse.py             启动文档解析（需库流程）
+- ingest_and_parse.py  一体化接入并解析
+- upload.py            文档上传暂存（7 天）
+- get.py               查询文档信息
+- parse_result/        解析结果子域：query / issue_ticket / download
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/get.py

@@ -0,0 +1,5 @@
+"""按文档 ID 查询文档基础信息与接入状态
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-07，GET /knowledge-documents/{doc_id}）。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/ingest.py

@@ -0,0 +1,5 @@
+"""接入知识源（URL/文件/目录/压缩包）并登记到指定知识库
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-01，POST /knowledge-documents/ingest）。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/ingest_and_parse.py

@@ -0,0 +1,6 @@
+"""一体化快捷入口：接入并解析
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-06，POST /knowledge-documents/ingest-and-parse）。
+内部仍为「接入 + 解析」两阶段，对外一次请求。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/parse.py

@@ -0,0 +1,6 @@
+"""启动文档解析（需库流程）
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-02，POST /knowledge-documents/parse）。
+与 api/parse/direct.py（免库独立解析）区分：本接口要求文档已登记且携带 kbId。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/parse_result/__init__.py

@@ -0,0 +1,7 @@
+"""解析结果子域（需库流程，占位）
+
+契约待 docs/RAG SDK接口.xlsx 增补后定义（参考 open-ikc B-03/B-04/B-05）：
+- query.py        查询解析结果
+- issue_ticket.py 获取解析结果下载凭证
+- download.py     下载解析结果
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/parse_result/download.py

@@ -0,0 +1,6 @@
+"""下载解析结果（需库流程）
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-05，GET /knowledge-documents/parse-result/download）。
+与 api/parse/download.py（免库 SDK 版）区分：本接口以 kbId + docId + 下载凭证定位。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/parse_result/issue_ticket.py

@@ -0,0 +1,6 @@
+"""获取解析结果下载凭证
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-04，GET /knowledge-documents/parse-result/issue-download-ticket）。
+解析结果较大或要求文件下载时，先申请短时下载凭证再下载。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/parse_result/query.py

@@ -0,0 +1,6 @@
+"""查询解析结果（需库流程）
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-03，GET /knowledge-documents/parse-result/query）。
+与 api/parse/query.py（免库 SDK 版）区分：本接口以 kbId + docId 定位。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/document/upload.py

@@ -0,0 +1,6 @@
+"""文档上传暂存（7 天）
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc B-02.2）。
+上传单个文档文件，平台暂存 7 天并返回临时访问地址；不创建知识库、不登记文档。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/knowledge_base/__init__.py

@@ -0,0 +1,8 @@
+"""知识库域（占位）
+
+接口契约待 docs/RAG SDK接口.xlsx 增补后定义，当前仅目录骨架，不定义模型：
+- create.py  创建知识库
+- update.py  修改知识库信息
+- get.py     按 ID 查询知识库详情
+- query.py   分页查询知识库列表
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/knowledge_base/create.py

@@ -0,0 +1,5 @@
+"""创建知识库
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc A-01，POST /knowledge-bases/create）。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/knowledge_base/get.py

@@ -0,0 +1,5 @@
+"""按 ID 查询知识库详情
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc A-03，GET /knowledge-bases/{kb_id}）。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/knowledge_base/query.py

@@ -0,0 +1,5 @@
+"""分页查询知识库列表
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc A-04，POST /knowledge-bases/query）。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/knowledge_base/update.py

@@ -0,0 +1,5 @@
+"""修改知识库信息
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc A-02，POST /knowledge-bases/update）。
+暂不定义请求/响应模型。
+"""

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/parse/__init__.py

@@ -0,0 +1,27 @@
+"""解析域接口（独立解析 / 查询解析结果 / 下载解析结果）
+
+对应 docs/RAG SDK接口.xlsx 四张 Sheet，当前全部为免知识库场景：
+- direct.py    独立解析（免知识库）SERVICE / SDK：基类 ParseDirectRequestBase
+               + ServiceParseDirectRequest / SdkParseDirectRequest + ParseResponse
+- query.py     查询解析结果（免知识库）SDK
+- download.py  下载解析结果（免知识库）SDK
+"""
+from .direct import (
+    ParseDirectRequestBase,
+    ParseResponse,
+    SdkParseDirectRequest,
+    ServiceParseDirectRequest,
+)
+from .download import DownloadParseResultRequest, DownloadParseResultResponse
+from .query import QueryParseResultRequest, QueryParseResultResponse
+
+__all__ = [
+    "DownloadParseResultRequest",
+    "DownloadParseResultResponse",
+    "ParseDirectRequestBase",
+    "ParseResponse",
+    "QueryParseResultRequest",
+    "QueryParseResultResponse",
+    "SdkParseDirectRequest",
+    "ServiceParseDirectRequest",
+]

ikc_sdk_lib-0.1.0/src/ikc_sdk/core/api/parse/direct.py

@@ -0,0 +1,94 @@
+"""独立解析（免知识库）：SERVICE / SDK 两版请求与共用响应
+
+对应 docs/RAG SDK接口.xlsx「解析--独立解析（免知识库）SERVICE / SDK」两个 Sheet。
+两版请求以 ParseDirectRequestBase 为基类派生，仅 source 不同：
+- SdkParseDirectRequest      面向 API 调用方（source 自声明，DeclaredSource）
+- ServiceParseDirectRequest  API 之后调用后端 service（source 指向已登记文档，RegisteredSource）
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from ikc_sdk.core.enums import ExecutionMode, ProcessingOperation
+from ikc_sdk.core.models.chunking import ChunkAugmentationOptions, ChunkingOptions
+from ikc_sdk.core.models.envelope import TaskEnvelope
+from ikc_sdk.core.models.model import ModelReferences, QaGenerationOptions
+from ikc_sdk.core.models.output import OutputOptions
+from ikc_sdk.core.models.parsing import DocumentAugmentation, ParsingOptions
+from ikc_sdk.core.models.prompt import PromptDetail
+from ikc_sdk.core.models.source import DeclaredSource, RegisteredSource
+from ikc_sdk.core.models.task import DocumentIngestionTask
+
+
+class ParseDirectRequestBase(BaseModel):
+    """独立解析（免知识库）请求公共字段基类
+
+    SERVICE / SDK 两版请求均以本类为基类派生，仅 source 字段不同。
+    """
+    reqId: Optional[str] = Field(
+        None, description="请求幂等标识，如无传入网关层自动生成"
+    )
+    traceId: Optional[str] = Field(
+        None, description="请求链路追踪 ID，如无传入网关层自动生成"
+    )
+    taskId: Optional[str] = Field(
+        None, description="当前任务 ID，如无传入网关层自动生成"
+    )
+    processingOperation: ProcessingOperation = Field(..., description="处理流程选项")
+    parsing: ParsingOptions = Field(..., description="解析策略")
+    documentAugmentation: Optional[DocumentAugmentation] = Field(
+        None, description="全文增强配置"
+    )
+    models: Optional[ModelReferences] = Field(
+        None, description="模型配置，不传入时默认读取系统配置"
+    )
+    qaGeneration: Optional[QaGenerationOptions] = Field(
+        None, description="问答对提取策略"
+    )
+    chunking: Optional[ChunkingOptions] = Field(
+        None,
+        description="分段策略，processingOperation 为 EXTRACT_CHUNK / "
+        "EXTRACT_CHUNK_EMBED / EXTRACT_CHUNK_EMBED_STORE 时必选",
+    )
+    chunkAugmentation: Optional[ChunkAugmentationOptions] = Field(
+        None, description="分段增强配置"
+    )
+    executeMode: Optional[ExecutionMode] = Field(
+        ExecutionMode.ASYNC, description="执行模式，默认 ASYNC"
+    )
+    output: OutputOptions = Field(..., description="返回格式配置")
+    prompts: Optional[PromptDetail] = Field(None, description="提示词清单")
+
+
+class ServiceParseDirectRequest(ParseDirectRequestBase):
+    """SERVICE 版独立解析（免知识库）请求参数
+
+    定位：API 网关校验编排后，调用后端 service 时使用；source 指向知识管理库已登记文档。
+    与 SDK 版的强制性区别：
+    - source 为 RegisteredSource：无 type / objectStorage / uploadToken，metadata.docId 必填
+    """
+
+    source: RegisteredSource = Field(
+        ..., description="已登记文档来源（SERVICE 版：docId 必填）"
+    )
+
+
+class SdkParseDirectRequest(ParseDirectRequestBase):
+    """SDK 版独立解析（免知识库）请求参数
+
+    定位：面向 API 调用方；source 由调用方自声明。
+    与 SERVICE 版的强制性区别：
+    - source 为 DeclaredSource：type 必填，url / objectStorage / uploadToken 三选一
+    - source.metadata 不含 docId 字段
+    """
+
+    source: DeclaredSource = Field(
+        ...,
+        description="来源自声明（SDK 版：type 必填，url/objectStorage/uploadToken 三选一）",
+    )
+
+
+class ParseResponse(TaskEnvelope[DocumentIngestionTask]):
+    """独立解析（免知识库）响应（SERVICE / SDK 共用出参）"""