ikc-sdk-lib

IKC SDK 家族仓库（Python 模型层），与 /home/open-ikc 对外接口一脉相承、独立维护。 当前整个 SDK 定义为 core：docs/RAG SDK接口v1.1.xlsx 中的 4 个免知识库接口 的请求/响应模型（Pydantic v2）。 后续新增 SDK 以 ikc_sdk.<sdk_name> 兄弟子包扩展，不进入 core。

安装

PyPI（推荐）

pip install ikc-sdk-lib                # 最新版（已发布至 PyPI）
pip install "ikc-sdk-lib==0.7.0"       # 固定版本（推荐）

• 运行环境：Python >=3.10；依赖 pydantic>=2.7（自动安装）。
• 源码开发态：pip install -e . 后可使用 src/examples/ 中的示例。

内网仓库安装（不依赖 PyPI）

仓库 dist/ 保存每次发版的 wheel 与 sdist，历史版本全部保留并打对应标签（v0.1.0、v0.2.0、v0.3.0、v0.4.0、v0.4.1、v0.4.2、v0.5.0、v0.5.1、v0.6.0、v0.6.1、v0.7.0）； 内网环境克隆仓库后安装任一历史版本的 wheel（仓库地址向内部索取）：

git clone <ikc-sdk-lib 内部仓库地址>
pip install ikc-sdk-lib/dist/ikc_sdk_lib-0.7.0-py3-none-any.whl   # 可指定任意历史版本

安装后 import ikc_sdk 行为与 PyPI 安装一致。

当前接口范围（core）

跨层共享契约（非 Excel 面，按归位批次增量落地）

图谱资产归位的提炼/不提炼清单与字段口径差异见 docs/提案_graph资产模型归位_sdk-lib.md。

任务状态判定（is_terminal() / is_success() 等）内置于模型层； Task 管理、端到端任务链路（client → 网关 → TaskServiceManagement → celery）与扩展设计 （取消 / 列表 / 定时任务 / 优先级）见 docs/Task管理与任务链路设计.md。

目录结构

docs/
  RAG SDK接口v1.1.xlsx   # 当前接口契约唯一定义源（v1.1，含 ParsingEngine）
  RAG SDK接口.xlsx       # v1.0 归档
  开发手册.md            # 四接口开发手册（pip 安装 / 流程 / 字段 / 端到端 / 发布）
  Task管理与任务链路设计.md  # Task 管理与任务链路（独立章节：链路 / SDK 设计 / 扩展草案）
src/ikc_sdk/
  __init__.py            # 命名空间门面：re-export core 公开 API
  _version.py            # 版本号（分发级）
  core/                  # 核心 SDK（当前整个 SDK）
    __init__.py          # core 公开导出
    enums.py             # 契约枚举（取值以 Excel 为准）
    exceptions.py        # SDK 异常体系（IkcSdkError 基类；契约校验 / 引擎目录异常）
    headers.py           # 跨层线缆头常量（trace 透传头 / 身份信任头）
    trace.py             # traceId 纯函数：生成 / 校验 / 归一 / 从请求头提取
    models/              # 共享模型：响应壳 / 来源 / 解析 / 分段 / 输出 / 任务 / 图谱资产 / Wiki 资产
    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
      graph/             # 图谱域（v0.7）：stat / nodes / edges / neighbors / paths / export
      wiki/              # Wiki 域（v0.8）：tree / page / stat / export
  <future_sdk>/          # 后续新增 SDK：兄弟子包（如 client 等），不进入 core
src/examples/            # 4 接口开发示例（非包、不参与打包）
scripts/publish-pypi.sh  # PyPI 发布脚本
config/pypi.env.example  # PyPI 凭据模板（真实凭据 pypi.env 不入库）
dist/                    # 发布产物（wheel + sdist，随仓库提交，对应标签 v0.8.0）
AGENTS.md                # 设计与实现契约
pyproject.toml / README.md

使用

规范导入路径为 ikc_sdk.core；顶层 ikc_sdk 门面 re-export core，两种写法等价：

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/（请求构建、契约校验、序列化、响应解析）：

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接口v1.1.xlsx 增补后定义 （参考 open-ikc V2 接口清单占位），在契约落定前不定义模型：

版本与发布

• 发布到 PyPI：bash scripts/publish-pypi.sh（参考 /home/ikc-log-center）；选项 --test、--skip-build、--no-skip-existing、IKC_SDK_VERSION=<ver>。
• 仓库直装：见「安装」章节 git 标签 / dist wheel 两种方式，不依赖 PyPI。
• 发版约定：每次发版更新版本号 → 构建产物入 dist/（保留历史，不清理旧版本）→ 提交推送 → 打标签 vX.Y.Z → 发布 PyPI。
• 分支约定：main 为发布基线；功能在 dev_* 分支开发，合并后打版本标签（如 v0.4.1）。
• 凭据：config/pypi.env（gitignored，勿提交），模板见 config/pypi.env.example。

契约约定

• 字段命名（camelCase）与枚举值一律以 docs/RAG SDK接口v1.1.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（能力域地图、目录/命名规范、落地工作流、硬性约束）。