Metadata-Version: 2.4
Name: licos-dev-sdk
Version: 0.7.4
Summary: LICOS Dev SDK - file generation and model capability clients
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: docxtpl>=0.16
Requires-Dist: graphviz>=0.20
Requires-Dist: jinja2>=3.1
Requires-Dist: licos-platform-sdk>=0.9.9
Requires-Dist: matplotlib>=3.9
Requires-Dist: mistune>=3.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pillow>=10.0
Requires-Dist: pypdf>=5.0
Requires-Dist: python-barcode>=0.15
Requires-Dist: python-docx>=1.1
Requires-Dist: python-pptx>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: qrcode[pil]>=8.0
Requires-Dist: skia-pathops>=0.9.2
Requires-Dist: uharfbuzz>=0.50.0
Requires-Dist: weasyprint>=62.0
Requires-Dist: xlsxwriter>=3.2
Description-Content-Type: text/markdown

# licos-dev-sdk

完整能力索引、接入流程与同版本 API：[SDK 文档](src/licos_dev_sdk/docs/index.md)。安装包内文档位于 licos_dev_sdk/docs/index.md。

服务端模型和文件工具 SDK。

## 模型思考内容

`create_chat_openai(preserve_reasoning=True)` 保留 Chat 返回的 `reasoning_content` / `reasoning`，以及 Responses 的思考摘要、`response.reasoning_text.delta` 和结束快照中的思考文本，支持同步、异步与流式调用。新增的原始思考增量统一放入消息的 `additional_kwargs.reasoning_content`，不混入回答正文；原有 Responses 内容块保持兼容。此参数只负责协议解析，编程智能体是否向页面转发仍由 Runtime 的 `harness.thinking.forward_to_frontend` 控制。

## Word 只读兼容（0.7.2 起）

`read_docx` 和 Word 图片提取从包关系定位主文档，兼容 Transitional／Strict OOXML 的正文、表格及媒体关系。适配只发生在内存读取视图中，源文件不会改写。该兼容层不用于文档编辑，不能据此假设 Strict 文档可无损编辑。

`read_docx(..., table_cell_format="text")` 可返回保留合并位置的 `cells:string[]`，原有结构位于 `cell_details`；默认仍返回结构化单元格。官方 Word 读取工具复用此接口，避免重复解析文件。

## 提取文档图片（0.7.1 起）

```python
from licos_dev_sdk import extract_document_images

report = extract_document_images("report.docx", output_dir="extracted", offset=1, limit=20)
for image in report["images"]:
    print(image["path"], image["media_type"], image["locations"])
```

支持 PDF、DOCX、PPTX 的嵌入图片，按内容去重并保留引用位置。PDF/PPTX 可传 `pages=[1, 3]`；DOCX 使用部件和段落位置，不提供物理页码。分页字段为 `total_items/has_more/next_offset`，只写出本次选择的图片。外链图片通过 `warnings` 明确返回，不主动下载。该接口不做 OCR、页面渲染或图表截图；旧版 DOC 需先转换成 DOCX。

## 通用模型服务

0.7.0 起提供 `ModelServiceClient`，全局查询和调用时序、表格等模型。参数、身份及异步调用说明见 [model-services.md](src/licos_dev_sdk/docs/model-services.md)。外部模型授权由平台配置和使用。

## 身份选择（0.6.0 起）

`LICOS_CURRENT_USER_ID` 表示容器启动时配置的执行用户。SDK 不用它推断当前网页登录者，也不读取进程级 `LICOS_USER_TOKEN` 作为模型请求凭证。项目身份指运行时配置的项目所有者身份，按接口选择：

| 接口 | 默认身份 | 以网页登录用户执行 |
| --- | --- | --- |
| 模型目录、模型详情、端点解析 | 项目身份 | 显式传 `user_token` |
| LLM、视觉、图片生成、视频生成、语音识别客户端 | 项目身份 | 每次用户请求创建客户端并传 `user_token` |
| `check_credit_availability` | 项目身份 | 显式传 `user_token` |
| 可观测性 | 项目身份 | 保持项目身份 |
| 文档、表格、图片排版等本地文件工具 | 无需用户 Token | 无需用户 Token |

需要以网页登录用户执行时，从本次认证会话取得不含 `Bearer ` 前缀的 Token，并让积分检查和模型调用使用同一用户身份：

```python
from licos_dev_sdk import LLMClient, check_credit_availability

# token 来自本次请求的认证会话。
availability = check_credit_availability(user_token=token, resource_code='LLM_INVOKE')
result = LLMClient(user_token=token).invoke('你好')
```

用户标识、名称和企业信息来自平台认证结果。项目所有者、工作空间等资源归属字段单独保留；模型实际计费上下文以平台模型详情接口签发的签名为准。

以网页登录用户执行的业务入口缺少 Token 时应返回登录错误，不能省略参数后使用项目身份。不要把请求 Token 或用户 ID 写入 `os.environ`，不要跨用户共享带身份的客户端。显式传入的 Token 为空或失效时直接报错，由调用方更新登录凭证后创建新客户端，不换取容器用户或项目所有者的 Token。

独立 `licos-dev` CLI 的模型和积分命令默认使用 `LICOS_CURRENT_USER_ID`，可用 `--identity project` 选择项目身份；HTTP 服务通过 CLI 代表登录用户执行时使用 `--token-stdin`。SDK 默认身份与 CLI 默认身份不同，调用时按上述接口规则显式选择。

## 编程项目登录身份

- 有内置登录时使用内置登录会话；没有内置登录时使用当前 LICOS 网页登录。内置登录未登录或过期时不能切换成平台用户。
- Node 服务端使用 `createProjectAuth({ mode: 'builtin', resolveBuiltinToken })` 或 `createProjectAuth({ mode: 'platform' })`，每次请求调用 `await projectAuth.userToken(request)`。内置解析器必须读取已有认证会话并返回用户已授权的 LICOS 凭证。
- 无内置登录的浏览器用户接口使用 `@kmlckj/licos-platform-sdk/browser` 的 `createProjectUserFetch`：平台登录桥领取一次性票据，项目后端兑换 Token。不要直接读取跨域平台 localStorage，不在 URL 中传 Token，不修改全局 fetch。项目级 API 保持原有请求方法。
- Python 使用 `ProjectAuth`；Agent/Workflow 通过 `config/licos-auth.json` 配置模式，内置登录设置 `resolver: "模块:函数"`，业务代码使用 `ctx.identity.user_token`。
- 当前用户、企业知识库、本体用户操作显式传 `userToken`/`user_token`。模型、积分和普通知识库按业务选择用户或项目身份。数据库、对象存储和可观测性继续使用项目身份。
- 沿用现有 OAuth 授权范围与接口权限。凭证无权访问目标接口时返回现有鉴权错误，不扩大权限或换用其他身份。
- 修改已有项目时先接它的现有登录机制，不能用新模板的默认平台模式覆盖。真实 Token 只存在于运行时请求/会话，不写入源代码、共享环境变量或 Agent 提示词。
