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 只是再导出，字段与码值一律不在此定义。

快速开始

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 优先级最高）， 优先级 调用级 > 客户端级 > 服务端；凭据只上行、不回显。

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 时跨进程/重启可见）。

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。