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