ikc-sdk-lib 0.1.0__py3-none-any.whl

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/_version.py

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

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/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/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/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/core/api/document/ingest.py

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

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/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/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/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/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/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/core/api/document/upload.py

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

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/core/api/knowledge_base/create.py

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

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/core/api/knowledge_base/query.py

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

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/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/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 共用出参）"""

ikc_sdk/core/api/parse/download.py

@@ -0,0 +1,24 @@
+"""下载解析结果（免知识库）
+
+对应 docs/RAG SDK接口.xlsx「下载解析结果（免知识库）SDK」Sheet。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from ikc_sdk.core.models.envelope import TaskEnvelope
+from ikc_sdk.core.models.task import DocumentIngestionTask
+
+
+class DownloadParseResultRequest(BaseModel):
+    """下载解析结果（免知识库）请求参数"""
+    reqId: Optional[str] = Field(
+        None, description="请求标识，请求时返回的经过校验的 reqId"
+    )
+    taskId: str = Field(..., description="下载任务 ID")
+
+
+class DownloadParseResultResponse(TaskEnvelope[DocumentIngestionTask]):
+    """下载解析结果（免知识库）响应"""

ikc_sdk/core/api/parse/query.py

@@ -0,0 +1,24 @@
+"""查询解析结果（免知识库）
+
+对应 docs/RAG SDK接口.xlsx「查询解析结果（免知识库）SDK」Sheet。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from ikc_sdk.core.models.envelope import Envelope
+from ikc_sdk.core.models.task import ProcessingTask
+
+
+class QueryParseResultRequest(BaseModel):
+    """查询解析结果（免知识库）请求参数"""
+    reqId: Optional[str] = Field(
+        None, description="请求标识，请求时返回的经过校验的 reqId"
+    )
+    taskId: str = Field(..., description="查询任务 ID")
+
+
+class QueryParseResultResponse(Envelope[ProcessingTask]):
+    """查询解析结果（免知识库）响应"""

ikc_sdk/core/api/search/__init__.py

@@ -0,0 +1,7 @@
+"""检索域（占位）
+
+接口契约待 docs/RAG SDK接口.xlsx 增补后定义，当前仅目录骨架，不定义模型：
+- universal.py  普通检索（证据列表）
+- deep.py       深度检索（Agentic 多轮 + 带引用回答）
+- query.py      兼容别名（指向普通检索）
+"""

ikc_sdk/core/api/search/deep.py

@@ -0,0 +1,6 @@
+"""深度检索（Agentic 多轮 + 带引用回答）
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc D-02，POST /knowledge-search/deep-search）。
+子查询规划、并行多轮召回、反思与回答生成；权限收敛与普通检索一致。
+暂不定义请求/响应模型。
+"""

ikc_sdk/core/api/search/query.py

@@ -0,0 +1,6 @@
+"""兼容别名：普通检索
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc D-01 兼容别名，POST /knowledge-search/query）。
+指向普通检索（universal），仅为兼容历史调用方保留。
+暂不定义请求/响应模型。
+"""

ikc_sdk/core/api/search/universal.py

@@ -0,0 +1,6 @@
+"""普通检索（证据列表）
+
+占位：契约待 docs/RAG SDK接口.xlsx 定义（参考 open-ikc D-01，POST /knowledge-search/universal-search）。
+支持全文/向量/混合检索、可选重排、分数阈值过滤；结果按调用方数据权限过滤。
+暂不定义请求/响应模型。
+"""

ikc_sdk/core/enums.py

@@ -0,0 +1,171 @@
+"""IKC RAG SDK 枚举类型定义
+
+取值以 docs/RAG SDK接口.xlsx 各 Sheet「取值说明」列为准，禁止私自增删改枚举值。
+"""
+from enum import Enum
+
+
+class ProcessingOperation(str, Enum):
+    """处理流程选项"""
+    EXTRACT = "EXTRACT"  # 全文解析
+    EXTRACT_CHUNK = "EXTRACT_CHUNK"  # 全文解析+全文分段
+    EXTRACT_CHUNK_EMBED_STORE = "EXTRACT_CHUNK_EMBED_STORE"  # 全文解析+全文分段+全文向量化+全文向量化入库
+    EMBED_STORE = "EMBED_STORE"  # 内容向量化+内容向量化入库
+    EXTRACT_CHUNK_EMBED = "EXTRACT_CHUNK_EMBED"  # 全文抽取+全文分段+全文向量化
+    EMBED = "EMBED"  # 内容向量化
+    EXTRACT_PAGES_TEXT = "EXTRACT_PAGES_TEXT"  # 按页提取文本
+
+
+class SourceType(str, Enum):
+    """文件来源类型"""
+    URL = "URL"  # 链接抓取
+    OBJECT_STORAGE = "OBJECT_STORAGE"  # 文件对象
+    UPLOAD_TOKEN = "UPLOAD_TOKEN"  # 文件标识
+
+
+class OwnerType(str, Enum):
+    """知识库归属类型"""
+    PERSONAL = "PERSONAL"  # 个人
+    TEAM = "TEAM"  # 团队
+    ENTERPRISE = "ENTERPRISE"  # 企业
+
+
+class DocumentFormat(str, Enum):
+    """文档类型（文件后缀）"""
+    DOC = "doc"
+    DOCX = "docx"
+    PPT = "ppt"
+    PPTX = "pptx"
+    XLS = "xls"
+    XLSX = "xlsx"
+    WPS = "wps"
+    WAV = "wav"
+    M4A = "m4a"
+    MP3 = "mp3"
+    FLV = "flv"
+    TS = "ts"
+    MP4 = "mp4"
+    GIF = "gif"
+    JPEG = "jpeg"
+    JPG = "jpg"
+    WEBP = "webp"
+    SVG = "svg"
+    PNG = "png"
+    CSV = "csv"
+    MD = "md"
+    PDF = "pdf"
+    TXT = "txt"
+    HTML = "html"
+    HTM = "htm"
+
+
+class DocumentCategory(str, Enum):
+    """文档分类"""
+    GENERAL = "GENERAL"  # 通用文档
+    CONTRACT = "CONTRACT"  # 合同文档
+    BIDDOC = "BIDDOC"  # 投标文件
+
+
+class ParsingFlag(str, Enum):
+    """解析标志位（Excel 中列名为 parsingOptions）"""
+    PARSE_IMAGE = "PARSE_IMAGE"  # 解析图片
+    PARSE_TABLE = "PARSE_TABLE"  # 解析表格
+    PARSE_ATTACHMENT = "PARSE_ATTACHMENT"  # 解析附件
+    CLEAN_HEADER_FOOTER = "CLEAN_HEADER_FOOTER"  # 清理页眉页脚
+    CLEAN_TOC = "CLEAN_TOC"  # 清理目录
+    REMOVE_WATERMARKS = "REMOVE_WATERMARKS"  # 去除水印
+    REMOVE_PASSWORD = "REMOVE_PASSWORD"  # 去除密码
+
+
+class ImageParsingMode(str, Enum):
+    """图片解析模型类型"""
+    OCR = "OCR"
+    MLLM = "MLLM"
+    PADDLE_OCR = "PADDLE_OCR"
+
+
+class ChunkType(str, Enum):
+    """分段类型"""
+    CHUNK_BY_FIXED_LENGTH = "CHUNK_BY_FIXED_LENGTH"  # 按固定长度分段
+    CHUNK_BY_SEMANTIC = "CHUNK_BY_SEMANTIC"  # 按语义边界分段
+    CHUNK_BY_SCENE = "CHUNK_BY_SCENE"  # 按场景切换分段
+    CHUNK_BY_DURATION = "CHUNK_BY_DURATION"  # 按时长间隔分段
+    CHUNK_BY_DIRECTORY_HIERARCHY = "CHUNK_BY_DIRECTORY_HIERARCHY"  # 按目录结构父子层级分段
+    CHUNK_BY_PAGE = "CHUNK_BY_PAGE"  # 按物理页分段
+    CHUNK_BY_LINE = "CHUNK_BY_LINE"  # 按行分段
+    CHUNK_BY_COLUMN = "CHUNK_BY_COLUMN"  # 按列分段
+    CHUNK_BY_MULTI_DIM = "CHUNK_BY_MULTI_DIM"  # 多维度组合分段
+
+
+class ExecutionMode(str, Enum):
+    """执行模式"""
+    SYNC = "SYNC"  # 同步执行
+    ASYNC = "ASYNC"  # 异步执行
+
+
+class OutputFormat(str, Enum):
+    """输出格式"""
+    MARKDOWN = "MARKDOWN"
+    MARKDOWN_WITH_LAYOUT = "MARKDOWN_WITH_LAYOUT"
+    INTERMEDIATE_JSON = "INTERMEDIATE_JSON"
+    CHUNKS_JSON = "CHUNKS_JSON"
+
+
+class ImageEncoding(str, Enum):
+    """图片返回格式"""
+    URL = "URL"
+    BASE64 = "BASE64"
+
+
+class QaScope(str, Enum):
+    """问答对提取方式"""
+    PER_DOCUMENT = "PER_DOCUMENT"  # 全文模式
+    PER_CHUNK = "PER_CHUNK"  # 分段模式
+
+
+class MetadataMode(str, Enum):
+    """元数据筛选方式"""
+    FILTER = "FILTER"  # 过滤模式
+    INHERIT = "INHERIT"  # 继承模式
+
+
+class TaskStatus(str, Enum):
+    """任务状态"""
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    SUCCEEDED = "SUCCEEDED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+    EXPIRED = "EXPIRED"
+
+
+class FinalTaskStatus(str, Enum):
+    """最终任务状态"""
+    PENDING = "PENDING"
+    SUCCEEDED = "SUCCEEDED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+
+
+class ProcessingStage(str, Enum):
+    """处理阶段"""
+    SOURCE_INGESTION = "SOURCE_INGESTION"  # 来源接收
+    FILE_CONVERSION = "FILE_CONVERSION"  # 文档转换
+    CONTENT_EXTRACTION = "CONTENT_EXTRACTION"  # 文档解析
+    DOCUMENT_AUGMENTATION = "DOCUMENT_AUGMENTATION"  # 文档元数据提取
+    CHUNKING = "CHUNKING"  # 文档分段
+    CHUNK_AUGMENTATION = "CHUNK_AUGMENTATION"  # 分段元数据提取
+    QA_GENERATION = "QA_GENERATION"  # 问答对生成
+    EMBEDDING = "EMBEDDING"  # 向量化
+    STORAGE = "STORAGE"  # 存储入库
+    RESULT_GENERATION = "RESULT_GENERATION"  # 结果生成
+
+
+class SubTaskStatus(str, Enum):
+    """子任务状态"""
+    WAITING = "WAITING"
+    RUNNING = "RUNNING"
+    SUCCEEDED = "SUCCEEDED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+    SKIPPED = "SKIPPED"

ikc_sdk/core/models/__init__.py

@@ -0,0 +1,45 @@
+"""共享数据模型"""
+from .chunking import ChunkAugmentationOptions, ChunkingOptions
+from .envelope import Envelope, TaskEnvelope
+from .model import ModelConfig, ModelReferences, QaGenerationOptions
+from .output import OutputOptions
+from .prompt import PromptDetail
+from .parsing import DocumentAugmentation, ParsingOptions
+from .source import (
+    DeclaredSource,
+    ObjectStorage,
+    RegisteredMetadata,
+    RegisteredSource,
+    SourceMetadata,
+    StorageTarget,
+)
+from .task import (
+    DocumentIngestionTask,
+    ProcessingTask,
+    ResultArtifact,
+    SubTask,
+)
+
+__all__ = [
+    "ChunkAugmentationOptions",
+    "ChunkingOptions",
+    "DeclaredSource",
+    "DocumentAugmentation",
+    "DocumentIngestionTask",
+    "Envelope",
+    "ModelConfig",
+    "ModelReferences",
+    "ObjectStorage",
+    "OutputOptions",
+    "ParsingOptions",
+    "ProcessingTask",
+    "PromptDetail",
+    "QaGenerationOptions",
+    "RegisteredMetadata",
+    "RegisteredSource",
+    "ResultArtifact",
+    "SourceMetadata",
+    "StorageTarget",
+    "SubTask",
+    "TaskEnvelope",
+]

ikc_sdk/core/models/chunking.py

@@ -0,0 +1,35 @@
+"""分段策略与分段增强模型"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from ikc_sdk.core.enums import ChunkType, MetadataMode
+
+
+class ChunkingOptions(BaseModel):
+    """分段策略"""
+    chunkType: ChunkType = Field(..., description="分段类型")
+    chunkSize: Optional[int] = Field(None, description="每段文本长度")
+    chunkOverlap: Optional[int] = Field(None, description="分段间重叠字符数，必需小于 chunkSize")
+    chunkExpr: Optional[str] = Field(
+        None,
+        description="自定义切分正则表达式（Excel 中类型误写为 Integer，契约语义为字符串）",
+    )
+    durationSeconds: Optional[int] = Field(None, description="每段时长（秒）")
+
+
+class ChunkAugmentationOptions(BaseModel):
+    """分段增强配置"""
+    enable: Optional[bool] = Field(False, description="分段增强开关")
+    summarySize: Optional[int] = Field(None, description="每个分段摘要提取最大长度")
+    keyswordNum: Optional[int] = Field(
+        None,
+        description="每个分段关键词提取最大个数（字段名 keyswordNum 为 Excel 契约原文，勿改）",
+    )
+    tagNum: Optional[int] = Field(None, description="每个分段标签提取最大个数")
+    questionNum: Optional[int] = Field(None, description="每个分段问题提取最大个数")
+    metadataMode: Optional[MetadataMode] = Field(
+        MetadataMode.FILTER, description="分段元数据筛选方式: FILTER/INHERIT"
+    )

ikc_sdk/core/models/envelope.py

@@ -0,0 +1,36 @@
+"""统一响应壳模型
+
+对齐 open-ikc 统一响应体约定（errCode / errMsg / data / traceId）：
+- 独立解析（SERVICE/SDK）与下载解析结果：顶层额外带 taskId
+- 查询解析结果：顶层无 taskId
+"""
+from __future__ import annotations
+
+from typing import Generic, Optional, TypeVar
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class Envelope(BaseModel, Generic[T]):
+    """统一响应壳：traceId / reqId / errCode / errMsg / data"""
+    traceId: str = Field(
+        ..., description="请求链路追踪 ID，前端有传入则直接返回，否则服务端生成"
+    )
+    reqId: str = Field(
+        ..., description="请求幂等标识，前端有传入则直接返回，否则服务端生成"
+    )
+    errCode: str = Field(
+        ...,
+        description="错误码，成功返回 000000；通用错误码 100001/100401/...；业务错误码 200xxx",
+    )
+    errMsg: str = Field(
+        ..., description='错误信息，当 errCode 为 000000 时内容为 "SUCCESS"'
+    )
+    data: Optional[T] = Field(None, description="业务数据，失败时可为空")
+
+
+class TaskEnvelope(Envelope[T]):
+    """带任务 ID 的统一响应壳（独立解析 / 下载解析结果）"""
+    taskId: str = Field(..., description="当前任务 ID")

ikc_sdk/core/models/model.py

@@ -0,0 +1,48 @@
+"""模型配置与问答对提取模型"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ikc_sdk.core.enums import QaScope
+
+
+class ModelConfig(BaseModel):
+    """模型配置对象（Excel ModelConfig）
+
+    对应 Excel「ModelReferences」各字段取值说明中的 `ModelConfig` 对象：
+    ModelReferences.* 字段为 ModelConfig 的 DES 加密串（Excel 类型 String），
+    本类用于构造明文对象，加密序列化由网关 / 服务端实现。
+    字段依据 Excel 示例定义；extraHeaders / extraBody 为可选的附加请求头/请求体（JSON 字符串）。
+    """
+    model_config = ConfigDict(extra="allow")
+
+    apiKey: str = Field(..., description="模型 API Key")
+    modelAddr: str = Field(..., description="模型服务地址")
+    modelId: str = Field(..., description="模型 ID")
+    maxTokens: int = Field(..., description="最大 Token 数")
+    model: str = Field(..., description="模型名称")
+    extraHeaders: Optional[str] = Field(None, description="附加请求头（JSON 字符串）")
+    extraBody: Optional[str] = Field(None, description="附加请求体（JSON 字符串）")
+
+
+class ModelReferences(BaseModel):
+    """模型配置集合，不传入时默认读取系统配置
+
+    各字段为对应模型 `ModelConfig` 的 DES 加密串（Excel 类型 String）。
+    """
+    ocrModel: Optional[str] = Field(None, description="OCR 模型配置（ModelConfig 的 DES 加密串）")
+    mllmModel: Optional[str] = Field(None, description="多模态模型配置（ModelConfig 的 DES 加密串）")
+    paddleOcrModel: Optional[str] = Field(None, description="Paddle OCR 模型配置（ModelConfig 的 DES 加密串）")
+    textModel: Optional[str] = Field(None, description="文本理解模型配置（ModelConfig 的 DES 加密串）")
+    audioModel: Optional[str] = Field(None, description="音频识别模型配置（ModelConfig 的 DES 加密串）")
+    embedModel: Optional[str] = Field(None, description="嵌入式模型配置（ModelConfig 的 DES 加密串）")
+    rerankModel: Optional[str] = Field(None, description="重排模型配置（ModelConfig 的 DES 加密串）")
+
+
+class QaGenerationOptions(BaseModel):
+    """问答对提取策略"""
+    enable: Optional[bool] = Field(False, description="问答对开关")
+    scope: Optional[QaScope] = Field(None, description="问答对提取方式: PER_DOCUMENT/PER_CHUNK")
+    maxPairs: Optional[int] = Field(None, description="问答对提取最大个数")

ikc_sdk/core/models/output.py

@@ -0,0 +1,20 @@
+"""输出配置模型"""
+from __future__ import annotations
+
+from typing import Optional, Set
+
+from pydantic import BaseModel, Field
+
+from ikc_sdk.core.enums import ImageEncoding, OutputFormat
+
+
+class OutputOptions(BaseModel):
+    """返回格式配置"""
+    formats: Set[OutputFormat] = Field(
+        default_factory=lambda: {OutputFormat.MARKDOWN, OutputFormat.CHUNKS_JSON},
+        description="返回文件格式，默认 {MARKDOWN, CHUNKS_JSON}",
+    )
+    includeImages: Optional[bool] = Field(None, description="解析结果文件里是否包含图片")
+    imageEncoding: Optional[ImageEncoding] = Field(
+        None, description="图片返回格式: URL/BASE64，includeImages=True 时有效"
+    )

ikc_sdk/core/models/parsing.py

@@ -0,0 +1,38 @@
+"""解析策略与全文增强模型"""
+from __future__ import annotations
+
+from typing import Optional, Set
+
+from pydantic import BaseModel, Field
+
+from ikc_sdk.core.enums import DocumentCategory, DocumentFormat, ImageParsingMode, ParsingFlag
+
+
+class ParsingOptions(BaseModel):
+    """解析策略"""
+    docFormat: DocumentFormat = Field(..., description="文档类型，填写文件后缀")
+    docCategory: Optional[DocumentCategory] = Field(
+        DocumentCategory.GENERAL, description="文档分类"
+    )
+    parsingOptions: Set[ParsingFlag] = Field(
+        default_factory=lambda: {ParsingFlag.PARSE_IMAGE, ParsingFlag.PARSE_TABLE},
+        description="解析标志位，默认 {PARSE_IMAGE, PARSE_TABLE}",
+    )
+    pageRange: Optional[list[str]] = Field(
+        None, description='解析页范围，如 ["1","3-5","10-20"]，不传或为空表示全文解析'
+    )
+    imageParseMode: Optional[ImageParsingMode] = Field(
+        ImageParsingMode.MLLM, description="图片解析模型类型"
+    )
+
+
+class DocumentAugmentation(BaseModel):
+    """全文增强配置"""
+    enabled: bool = Field(False, description="全文增强开关")
+    summarySize: Optional[int] = Field(None, description="全文摘要提取最大长度")
+    keyswordNum: Optional[int] = Field(
+        None,
+        description="全文关键词提取最大个数（字段名 keyswordNum 为 Excel 契约原文，勿改）",
+    )
+    tagNum: Optional[int] = Field(None, description="全文标签提取最大个数")
+    questionNum: Optional[int] = Field(None, description="全文问题提取最大个数")

ikc_sdk/core/models/prompt.py

@@ -0,0 +1,17 @@
+"""提示词模型
+
+字段名 docMetadataPormpt / chunkMetadataPormpt 为 Excel 契约原文拼写，勿改。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class PromptDetail(BaseModel):
+    """提示词清单"""
+    docMetadataPormpt: Optional[str] = Field(None, description="全文元数据提取提示词")
+    chunkMetadataPormpt: Optional[str] = Field(None, description="分段元数据提取提示词")
+    imageMllmPrompt: Optional[str] = Field(None, description="图片理解多模态大模型提示词")
+    pptMllmPrompt: Optional[str] = Field(None, description="PPT 理解多模态大模型提示词")

ikc_sdk/core/models/source.py

@@ -0,0 +1,124 @@
+"""文档来源相关模型
+
+SDK 与 SERVICE 两版核心差异（来源 docs/RAG SDK接口.xlsx）：
+- SDK（面向 API 调用方）：来源由调用方自声明——`DeclaredSource`
+  - type 必填，url / objectStorage / uploadToken 三选一，元信息不含 docId
+- SERVICE（API 之后调用后端 service）：来源指向已登记文档——`RegisteredSource`
+  - 无 type / objectStorage / uploadToken，元信息 docId 必填（知识管理库模块生成）
+- storageTarget 在两版中均为可选字段（落地知识库场景才需要传入；
+  Excel 未定义独立的「落地知识库」接口，故不臆造必填变体）
+- 元信息采用基类 + 派生：`SourceMetadata`（SDK 版，无 docId）/
+  `RegisteredMetadata`（SERVICE 版，docId 必填），保证 SDK 序列化不出现 docId
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ikc_sdk.core.enums import OwnerType, SourceType
+
+
+class StorageTarget(BaseModel):
+    """源文件基础元信息（落地知识库场景必选）"""
+    klgId: Optional[str] = Field(None, description="知识ID")
+    kbId: Optional[str] = Field(None, description="知识库ID")
+    ownershipType: Optional[OwnerType] = Field(
+        None, description="归属类型: PERSONAL/TEAM/ENTERPRISE"
+    )
+    ownershipId: Optional[str] = Field(None, description="归属ID，与 ownershipType 搭配使用")
+
+
+class ObjectStorage(BaseModel):
+    """对象存储内容"""
+    storageProvider: Optional[str] = Field(None, description="存储供应商")
+    bucket: str = Field(..., description="租户空间")
+    objectKey: str = Field(..., description="文件/目录/压缩包对象标识，如 OSS 对象路径")
+
+
+class SourceMetadata(BaseModel):
+    """源文件扩展元信息（SDK 版）
+
+    不含 docId 字段（Excel SDK 元信息表）；支持额外扩展字段。
+    """
+    model_config = ConfigDict(extra="allow")
+
+    docTitle: Optional[str] = Field(None, description="文档标题")
+
+
+class RegisteredMetadata(SourceMetadata):
+    """已登记文档扩展元信息（SERVICE 版）
+
+    在 SDK 版元信息基础上增加必填 docId（知识管理库模块生成）。
+    """
+    docId: str = Field(..., description="文档 ID，由知识管理库模块生成（SERVICE 版必填）")
+
+
+# ──────────────────────────────────────────────
+# SDK 版：来源自声明（面向 API 调用方）
+# ──────────────────────────────────────────────
+class DeclaredSource(BaseModel):
+    """来源自声明（SDK 版，面向 API 调用方）
+
+    与 SERVICE 版的强制性区别：
+    - type 为必填项，显式声明来源类型
+    - url / objectStorage / uploadToken 三选一（validator 强制）
+    - metadata 不含 docId 字段
+    - storageTarget 可选（落地知识库场景传入）
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    type: SourceType = Field(
+        ..., description="文件来源类型: URL/OBJECT_STORAGE/UPLOAD_TOKEN"
+    )
+    url: Optional[str] = Field(None, description="远程文件下载地址")
+    objectStorage: Optional[ObjectStorage] = Field(None, description="对象存储内容")
+    uploadToken: Optional[str] = Field(
+        None, description="文件上传凭证或临时对象标识"
+    )
+    storageTarget: Optional[StorageTarget] = Field(
+        None, description="源文件基础元信息，落地知识库场景必选"
+    )
+    metadata: Optional[SourceMetadata] = Field(
+        None, description="源文件扩展元信息（SDK 版：无 docId）"
+    )
+
+    @model_validator(mode="after")
+    def _check_source_exclusive(self) -> "DeclaredSource":
+        supplied = {
+            SourceType.URL: self.url,
+            SourceType.OBJECT_STORAGE: self.objectStorage,
+            SourceType.UPLOAD_TOKEN: self.uploadToken,
+        }
+        present = [kind for kind, value in supplied.items() if value is not None]
+        if len(present) != 1:
+            raise ValueError("url / objectStorage / uploadToken 必须三选一")
+        if present[0] is not self.type:
+            raise ValueError(
+                f"source.type={self.type.value} 与来源字段 {present[0].value} 不匹配"
+            )
+        if self.metadata is not None and self.metadata.model_dump().get("docId") is not None:
+            raise ValueError("SDK 版 source.metadata 不含 docId 字段")
+        return self
+
+
+# ──────────────────────────────────────────────
+# SERVICE 版：已登记文档（API 之后调用后端 service）
+# ──────────────────────────────────────────────
+class RegisteredSource(BaseModel):
+    """已登记文档来源（SERVICE 版，API 之后调用后端 service）
+
+    与 SDK 版的强制性区别：
+    - 不含 type / objectStorage / uploadToken 字段（以已登记 docId 定位）
+    - metadata.docId 为必填项（知识管理库模块生成）
+    - storageTarget 可选（落地知识库场景传入）
+    """
+    model_config = ConfigDict(extra="forbid")
+
+    url: Optional[str] = Field(None, description="远程文件下载地址")
+    storageTarget: Optional[StorageTarget] = Field(
+        None, description="源文件基础元信息，落地知识库场景必选"
+    )
+    metadata: RegisteredMetadata = Field(
+        ..., description="已登记文档扩展元信息（SERVICE 版：docId 必填）"
+    )

ikc_sdk/core/models/task.py

@@ -0,0 +1,60 @@
+"""任务与结果相关模型"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from ikc_sdk.core.enums import (
+    ExecutionMode,
+    FinalTaskStatus,
+    OutputFormat,
+    ProcessingStage,
+    SubTaskStatus,
+    TaskStatus,
+)
+
+
+class ResultArtifact(BaseModel):
+    """解析结果产物"""
+    type: OutputFormat = Field(..., description="下载文件类型")
+    downloadUrl: str = Field(..., description="下载文件地址")
+    expiresAt: str = Field(..., description="下载文件有效时间")
+
+
+class DocumentIngestionTask(BaseModel):
+    """文档摄入任务结果"""
+    docId: str = Field(..., description="文档 ID")
+    taskStatus: FinalTaskStatus = Field(
+        ..., description="任务状态: PENDING/SUCCEEDED/FAILED/CANCELLED"
+    )
+    executeMode: ExecutionMode = Field(..., description="执行方式: sync/async")
+    startedAt: str = Field(..., description="任务开始时间")
+    completedAt: str = Field(..., description="任务完成时间")
+    durationMs: int = Field(..., description="任务执行时间（毫秒）")
+    expiresAt: str = Field(..., description="任务结果过期时间")
+    artifacts: Optional[list[ResultArtifact]] = Field(None, description="结果产物列表")
+
+
+class SubTask(BaseModel):
+    """子任务详细信息"""
+    sequence: int = Field(..., description="子任务顺序")
+    stage: ProcessingStage = Field(..., description="子任务阶段名称")
+    startedAt: str = Field(..., description="子任务开始时间")
+    completedAt: str = Field(..., description="子任务结束时间")
+    durationMs: int = Field(..., description="子任务耗时（毫秒）")
+    subTaskId: str = Field(..., description="celery 子任务 ID")
+    status: SubTaskStatus = Field(..., description="子任务状态")
+    message: Optional[str] = Field(None, description="子任务描述")
+
+
+class ProcessingTask(BaseModel):
+    """解析任务结果摘要"""
+    taskId: str = Field(..., description="主任务 ID")
+    taskStatus: TaskStatus = Field(..., description="任务状态")
+    currentStage: ProcessingStage = Field(..., description="当前处理阶段")
+    startedAt: str = Field(..., description="主任务开始时间")
+    completedAt: str = Field(..., description="主任务完成时间")
+    expiresAt: Optional[str] = Field(None, description="主任务过期时间，为空时表示永不过期")
+    durationMs: int = Field(..., description="主任务执行时间（毫秒）")
+    subTasks: list[SubTask] = Field(..., description="任务详细信息")

ikc_sdk_lib-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,41 @@
+ikc_sdk/__init__.py,sha256=JUKEDLvHIa3cnoh3Dm7wqcVAwLyMvOc2BO1OWy1bOL8,538
+ikc_sdk/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+ikc_sdk/core/__init__.py,sha256=QO7hbQS08ks1VlpbBcH9H1_AhPG944By6bO2QvWs5fg,3390
+ikc_sdk/core/enums.py,sha256=2k6GSK4BQMKNvwIxvGfLfpluDubdcfBFZ1EIs8OR3yI,4991
+ikc_sdk/core/api/__init__.py,sha256=JaIRoGb4FzfqSa9kPFxKxyYBYTd41ZHPIwbxNPsPVA8,675
+ikc_sdk/core/api/document/__init__.py,sha256=qojc-cGRPA178WgT_pEU1IM-waWR5EKLEgR5hYEFzGM,482
+ikc_sdk/core/api/document/get.py,sha256=4VCo4yVES3YgFXsFigmut5oRQgWmtGv1EFImiOwywuA,211
+ikc_sdk/core/api/document/ingest.py,sha256=qmfE3bpvF9cNPZ3nOCgq8jjchrwwehlmDVuoECm0PMo,233
+ikc_sdk/core/api/document/ingest_and_parse.py,sha256=76DoHQhGonBE2CuhAlmsFGLnHSTesHvAiZDVuy6G8B0,274
+ikc_sdk/core/api/document/parse.py,sha256=mNqGDt7elHK_zeVF5BEXty8n1Io_FnjDpZWj8iT-Bj4,297
+ikc_sdk/core/api/document/upload.py,sha256=3lq64ISdbOOxUdckm3oDbjP1EkdtwD6wAGgN1lU4drw,269
+ikc_sdk/core/api/document/parse_result/__init__.py,sha256=0XkVjCYAv5gJJaNJPiMZF2aiZYf-QMEsYvycP07Ygxw,266
+ikc_sdk/core/api/document/parse_result/download.py,sha256=rCZuGpMS5559P3ybXPIAI72JMvNy3ZK6ypcAu0unrIs,312
+ikc_sdk/core/api/document/parse_result/issue_ticket.py,sha256=QOzN2paKEYk3zyZZWlU-QbI0yIgKKx_U11L1yTT31kU,300
+ikc_sdk/core/api/document/parse_result/query.py,sha256=yKphCPaNf8dA-iEan89tAJ64ybylKex78KxATHXnmPs,292
+ikc_sdk/core/api/knowledge_base/__init__.py,sha256=hcp09ru_JEmLtMS068HrXry60Y_Nd9ngPcd3kMikRm8,281
+ikc_sdk/core/api/knowledge_base/create.py,sha256=lnsx44pUuad5_tjS5jwoPGCZfVQe4-RwVIIwCI_8TOU,169
+ikc_sdk/core/api/knowledge_base/get.py,sha256=P6PJkD79yrCGr-cjPCyNxr4qOl-xJFiCF8ux6-mFYn4,182
+ikc_sdk/core/api/knowledge_base/query.py,sha256=Kky15mAXoDtMF9a9FLcEG3VQPfTF6kCA83p_j2TbkVU,180
+ikc_sdk/core/api/knowledge_base/update.py,sha256=A0x7b0vMoeFXl3S1CTz36sHWLajJ-uQskcRVExOAPW8,175
+ikc_sdk/core/api/parse/__init__.py,sha256=fbBizrAy8_Ce3ritWVI7Eb37bGy9eY_wHgJ9Yye0rEM,987
+ikc_sdk/core/api/parse/direct.py,sha256=nDRgtIsLnYBwkwqhq4KfTH7ZM_GoqfIaInbc2vFdvOM,4056
+ikc_sdk/core/api/parse/download.py,sha256=v3w2cQK4pLgkDGIkVRfGiQDFIXwtybkDlEGTQE4IKRI,762
+ikc_sdk/core/api/parse/query.py,sha256=4uY_1CyweCbzyfsZDj7FWjGqbZ6qcndnqZmSmOthl6s,734
+ikc_sdk/core/api/search/__init__.py,sha256=1ABA225-MqoZ4K1Ww-my-IdIiWjv6RYpVjhj3Pv-efE,298
+ikc_sdk/core/api/search/deep.py,sha256=xOgrRIVdeRCHzYNLe6lMtUUlsJ95qJo7HHm6dk1mxL8,310
+ikc_sdk/core/api/search/query.py,sha256=89EGAdj9wDOG-GMY5d3yyUnsDlLxdqgEIZy7q3RXZfI,267
+ikc_sdk/core/api/search/universal.py,sha256=BHhi_yR8blZebeM-9EDoiG984kW2PZA32-zy8rhXVP0,306
+ikc_sdk/core/models/__init__.py,sha256=Bzwy91L7MgsDkfCyK-cG8jUUQc2sbiKfHIE5Crkf4lk,1068
+ikc_sdk/core/models/chunking.py,sha256=VScXd5Uvg0mQa_4VrKp8tHkVrVlaykKT7TCBNWvqleI,1536
+ikc_sdk/core/models/envelope.py,sha256=Pa7pTXZIULUBeJcxNuEaka1BF_SkE1zOmdx9If9l9P4,1290
+ikc_sdk/core/models/model.py,sha256=bqjxj46hSTTwCeQ2nbB5nNHl_6UbE7PSyUEZqF-Wx3o,2557
+ikc_sdk/core/models/output.py,sha256=UmV4edsX9Q98SbStmma2vFIk--QlzlHYIwENlNKVQgY,711
+ikc_sdk/core/models/parsing.py,sha256=mv2C-gTmGcIZbxDnQrX4pBymCdodsnci4lSlm1qqutE,1594
+ikc_sdk/core/models/prompt.py,sha256=vApujTKY7nSHkGvJJmdZQLcVCCnhdZTsPzFq8L_7a6Q,677
+ikc_sdk/core/models/source.py,sha256=uE1HMjLak-Xr10diuzPJNg3mQy7EPrDdl3H7MSxNgwI,5742
+ikc_sdk/core/models/task.py,sha256=P0fbsDPnHMzAPoxsHBXLen_Ta_lzTKwsisBiApXawvw,2584
+ikc_sdk_lib-0.1.0.dist-info/METADATA,sha256=S6iYdE1aidQJJWC6BVIi98gj6peTGU1AmNSF9DAkPQA,5516
+ikc_sdk_lib-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ikc_sdk_lib-0.1.0.dist-info/top_level.txt,sha256=B5nUSNuuxW9QNHpRw3Cuct0f6DyPna92oPngo1mJEhs,8
+ikc_sdk_lib-0.1.0.dist-info/RECORD,,

ikc_sdk_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ikc_sdk_lib-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ikc_sdk