Metadata-Version: 2.4
Name: ima-python-sdk
Version: 0.1.0
Summary: 非官方的 IMA OpenAPI Python SDK，提供知识库和笔记管理功能
Author: elxy
License: MIT
Project-URL: Homepage, https://github.com/elxy/ima-python-sdk
Project-URL: Repository, https://github.com/elxy/ima-python-sdk
Project-URL: Issues, https://github.com/elxy/ima-python-sdk/issues
Keywords: ima,knowledge-base,notes,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ima-python-sdk

非官方的 IMA OpenAPI Python SDK，提供知识库和笔记管理功能。

> 本项目参考 [ima-skills](https://clawhub.ai/iampennyli/ima-skills) 中的 API 文档和脚本实现，与 IMA 官方无关。

## 安装

```bash
pip install ima-python-sdk
```

## 配置

SDK 需要 `client_id` 和 `api_key` 两个凭证，按以下优先级自动发现：

1. **构造参数** — `ImaClient(client_id="...", api_key="...")`
2. **环境变量** — `IMA_OPENAPI_CLIENTID` / `IMA_OPENAPI_APIKEY`
3. **配置文件** — `~/.config/ima/client_id` / `~/.config/ima/api_key`

## CLI 使用

`--kb_id` 可通过环境变量 `IMA_KB_ID` 设置，避免每次手动指定。

```bash
# 知识库
ima-sdk kb addable
ima-sdk kb upload report.pdf --kb_id xxx                   # 上传到根目录
ima-sdk kb upload report.pdf 论文/机器学习 --kb_id xxx      # 上传到指定目录
ima-sdk kb import-url https://example.com --kb_id xxx

# 笔记
ima-sdk note search "会议记录"
ima-sdk note create "# 标题"
ima-sdk note read <doc_id> --raw
```

## SDK 使用

```python
from ima_sdk import ImaClient, KnowledgeBaseManager, NotesManager

client = ImaClient()  # 自动读取环境变量或配置文件
kb = KnowledgeBaseManager(client)
notes = NotesManager(client)

# 知识库操作
kb.upload_file("/path/to/report.pdf", knowledge_base_id="xxx")
kb.import_urls(["https://example.com"], knowledge_base_id="xxx")
results = kb.search_knowledge("关键词", knowledge_base_id="xxx")

# 笔记操作
doc_id = notes.create("# 标题\n\n正文内容")
docs, total, is_end = notes.search("会议记录")
content = notes.get_content(doc_id)
```

## 特性

- **零第三方依赖** — 仅使用 Python 标准库（urllib, hmac, hashlib, dataclasses）
- **凭证自动发现** — 构造参数 > 环境变量 > 配置文件，三级优先
- **自动翻页** — 列表接口支持 `fetch_all=True`
- **完整上传流程** — `upload_file()` 一个方法完成预检、重名检查、创建媒体、COS 上传、添加知识
- **UTF-8 安全** — 笔记写入前自动校验编码

## License

MIT
