Metadata-Version: 2.4
Name: ikc-sdk-lib
Version: 0.3.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接口v1.1.xlsx` 中的 **4 个免知识库接口** 的请求/响应模型（Pydantic v2）。
后续新增 SDK 以 `ikc_sdk.<sdk_name>` 兄弟子包扩展，不进入 core。

## 安装

**PyPI（推荐）**

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

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

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

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

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

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

## 当前接口范围（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` |

## 目录结构

```
docs/
  RAG SDK接口v1.1.xlsx   # 当前接口契约唯一定义源（v1.1，含 ParsingEngine）
  RAG SDK接口.xlsx       # v1.0 归档
  开发手册.md            # 四接口开发手册（pip 安装 / 流程 / 字段 / 端到端 / 发布）
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
src/examples/            # 4 接口开发示例（非包、不参与打包）
scripts/publish-pypi.sh  # PyPI 发布脚本
config/pypi.env.example  # PyPI 凭据模板（真实凭据 pypi.env 不入库）
dist/                    # 发布产物（wheel + sdist，随仓库提交，对应标签 v0.3.0）
AGENTS.md                # 设计与实现契约
pyproject.toml / README.md
```

## 使用

规范导入路径为 `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接口v1.1.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 |

## 版本与发布

| 项 | 值 |
| --- | --- |
| 当前版本 | `0.3.0`（历史：`0.1.0`、`0.2.0`） |
| PyPI 项目页 | `https://pypi.org/project/ikc-sdk-lib/` |
| 仓库版本标签 | `v0.1.0`、`v0.2.0`、`v0.3.0`（annotated） |
| 仓库发布产物 | `dist/` 保留全部历史版本：`ikc_sdk_lib-0.1.0` / `-0.2.0` / `-0.3.0`（wheel + sdist），索引见 `dist/README.md` |

- 发布到 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.3.0`）。
- 凭据：`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`（能力域地图、目录/命名规范、落地工作流、硬性约束）。
