Metadata-Version: 2.5
Name: ikc-flash-sdk
Version: 0.4.2
Summary: ikc-flash-knowledge 记忆引擎官方客户端 SDK（同步 + 异步；零重依赖）
License: Apache-2.0
Keywords: agent,flash-knowledge,ikc,memory,sdk
Requires-Python: >=3.12
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: ikc-sdk-lib==0.15.0
Requires-Dist: pydantic<3.0,>=2.7
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ikc-flash-sdk

`ikc-flash-knowledge` 记忆引擎的官方客户端（同步 + 异步）。服务端包内已同源 include 本 SDK
（`ikc_flash_sdk`）；本目录的 `pyproject.toml` 用于**独立分发**（`scripts/publish_sdk.sh`）。

> 线缆模型与错误码的单一来源是 `ikc-sdk-lib` 的 `ikc_sdk.flash`（v0.14.0）：本 SDK 的
> `models` / `codes` 只是再导出，字段与码值一律不在此定义。

## 快速开始

```python
from ikc_flash_sdk import IkCFlashClient

with IkCFlashClient("http://127.0.0.1:19400", token="dev-token") as client:
    scope = {"agentId": "demo-agent", "threadId": "t-1"}

    # 摄入（缺省异步：返回 jobId，用 .memory.job 轮询）
    accepted = client.memory.observe(scope=scope, events=[{"role": "user", "content": "我叫老王，做知识管理"}])

    # 召回（token 预算打包，直接塞进提示词）
    recall = client.memory.recall(scope=scope, query="用户是谁", tokenBudget=800)
    print(recall["packedContext"])
```

异步用法：`async with AsyncIkCFlashClient(...) as client:`，方法同名同参。

**用自己的模型做加工**：`model=` 逐字段覆盖服务端 `model:` 配置（网关侧 `modelInfo` 优先级最高），
优先级 **调用级 > 客户端级 > 服务端**；凭据只上行、不回显。

```python
from ikc_flash_sdk import IkCFlashClient, ModelRef

with IkCFlashClient("http://127.0.0.1:19400", token="dev-token",
                    model=ModelRef(name="qwen3-32b", baseUrl="https://llm.customer.example/v1",
                                   apiKey="sk-…")) as client:
    data = client.memory.consolidate(scope={"agentId": "demo-agent"}, async_=False)
    print(data["result"]["modelUsed"])   # {'provider': ..., 'name': 'qwen3-32b', 'source': 'request'}
```

**作业台账**：`jobs()` 读服务端作业列表（创建时间倒序 + 游标分页；`store_backend=pg` 时跨进程/重启可见）。

```python
page = client.memory.jobs(scope_key='demo-agent|t-1', task='consolidate', statuses=['success'], limit=20)
for job in page["items"]:
    print(job["jobId"], job["status"])
```

## 约定

- **只发调用方传入的字段**：SDK 不把缺省值 pin 上线缆（服务端缺省可变，客户端不固化）。
- **错误码类型化**：`IkCFlashRevisionConflictError` / `IkCFlashRecallParamsError` 等可按类型捕获，
  也可用 `err_code` 统一判断；均继承 `ikc_sdk` 的 `IkcSdkError`。
- **安全字段不进 SDK**：不提供 `tenantId` / 向量等入口（由实例侧身份与检索面注入）。

更多见 `docs/SDK开发手册.md`。
