Metadata-Version: 2.4
Name: helixr
Version: 0.3.0
Summary: Dependency-free Python API SDK for HelixR Service.
Author-email: Axiora AI <wangweile@axioraai.com>
License: Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# HelixR Python SDK

HelixR Service 的轻量 Python 客户端，无第三方运行时依赖。SDK 面向企业 Agent、
RAG 服务和私有化集成，不暴露 HelixR 算法内部对象。

## 安装

从 PyPI 或企业私有包仓库安装：

```bash
pip install helixr
```

尚未发布包仓库的源码交付环境仍可使用
`pip install ./helix-service/sdk/python`。

`helixr` 是调用 HelixR Service 的公共 API SDK。需要在服务进程内运行核心
算法的私有化或 Embedded 场景，请单独安装 `helixr-algorithms` 并从
`helix_memory` 导入。

## 最小接入

```python
import os

from helixr import HelixRClient, MemorySpaceCreateRequest, SearchRequest

client = HelixRClient(
    api_key=os.environ["HELIXR_API_KEY"],
).for_scope(
    tenant_id="tenant_a",
    project_id="agent_platform",
    dataset_id="production_memory",
)

space = client.create_space(MemorySpaceCreateRequest(
    space_type="personal",
    name="My Long-Term Memory",
    owner_type="principal",
    owner_id="current-user",
))

results = client.search(SearchRequest(
    query="客户上次为什么调整交付计划？",
    space_id=space["space_id"],
    top_k=5,
    enable_bridging=True,
))
```

绑定 `HelixScope` 后，`add`、`add_bulk`、`search`、`evidence`、`feedback`、
`record_eval` 和 `eval_events` 会自动补齐未显式填写的租户、项目和数据集范围。
请求中显式提供的 Scope 始终优先，便于授权后的跨项目管理调用。

Memory Space 的创建、列表、成员角色、策略和按 `space_id` 的 Evidence 查询均可直接
通过 SDK 完成，不需要调用私有 HTTP 方法。

Trace 使用 `trace_id` / `request_id` 构造参数；线上评测使用 `record_eval`、
`eval_events`，黄金集评测使用 `run_golden_eval`。完整接口示例见
`../../docs/SDK_GUIDE_ZH.md`。

显式启用服务端 Trace 内容留存后，可用 `evaluate_shadow_trace(trace_id, payload)`
只读比较候选检索参数与源 Evidence 排名；回归结果自动写入线上评测并可进入人审。
SDK 不会取得源 query 或私有排名快照，服务端仍按 Trace Scope 校验权限。

任务级认知可通过 `reconstruct_working_memory_cognitive_context` 获得
`CognitiveContext`、Evidence Sufficiency、Hypothesis Validation、五态 CognitiveDecision
和原始 `trace_id`。假设证据的来源绑定不等于支持立场；受信任的 Judge 或人工可在后续请求中用
`HypothesisEvidenceAnnotation` 显式提交 supporting/refuting Evidence。只能引用本次
CognitiveContext 可见 Evidence，默认 shadow 不写状态，显式 apply 也只更新 Working Memory，
不会自动晋升 Deep Memory。
Agent Runtime 完成后可显式回传 Outcome：

```python
from helix_service_client import CognitiveDecisionOutcomeRequest

result = client.record_cognitive_decision_outcome(
    cognitive_context["cognitive_decision"]["decision_id"],
    CognitiveDecisionOutcomeRequest(
        trace_id=cognitive_context["trace_id"],
        observed_outcome="succeeded",
        judgment="correct",  # 必须来自外部 Judge 或人工
        idempotency_key="agent-task-42-outcome-v1",
    ),
)
calibration = client.cognitive_decision_calibration()
```

`observed_outcome` 不会被自动解释为 Decision 正误；`judgment` 必须由调用方明确提供。
错误或待审样本可进入人审队列，当前反馈只用于审计和校准，不自动修改 Cognitive Strategy，
也不让 HelixR 接管 Tool、Workflow 或 Action。

客户 Hypothesis Validation Gold Set 可通过
`import_hypothesis_holdout` 幂等进入同一人审队列。Reviewer 先调用
`claim_review`，再用 `adjudicate_hypothesis_holdout` 提交 `gold_status`、
label version 以及显式 supporting/refuting Evidence ID；最后调用
`export_hypothesis_holdout` 导出仍包含 pending case 的脱敏版本。服务端拒绝跨 case
Evidence、错误 stance 契约和过期 revision。该流程只产生评测标签，不写 Working Memory
或 Deep Memory。若私有部署配置了服务端授权源清单，claimed reviewer 还可调用
`preview_hypothesis_holdout_source` 临时读取并校验原文；响应禁止缓存，原文不会进入
Memory、Review snapshot 或 Trace。

独立候选版本试点使用 `ShadowTrafficClient` 组合两套
`HelixServiceClient`。主实例检索完成后立即返回；确定性采样命中的候选检索和比较在
后台线程执行，候选超时、报错或评测写入失败都不会改变主结果：

```python
from helix_service_client import (
    ShadowTrafficClient,
    ShadowTrafficConfig,
)

candidate = HelixServiceClient(
    "http://helixr-candidate:8100/v1",
    api_key="candidate-read-only-key",
    scope=client.scope,
)
shadow = ShadowTrafficClient(
    client,
    candidate,
    ShadowTrafficConfig(sample_rate=0.01, candidate_name="release-2026-08"),
)
submission = shadow.search(SearchRequest(query="客户上次为何调整计划？"))
results = submission.primary_results

# Agent 主回答不依赖该 Future；进程退出前再等待或调用 shadow.close()。
if submission.comparison is not None:
    submission.comparison.add_done_callback(
        lambda future: print(future.result().outcome)
    )
```

采样率可设为 `0` 立即停用候选流量。线上评测只保留 query SHA-256、Evidence ID
差异和聚合指标，不保留原始问题；候选 Endpoint 自身的访问日志与 Trace 保留策略仍需
单独配置。主 Principal 需要 `memory:read` 和 `eval:write`，候选 Principal 只需
`memory:read`。

本体深记忆接入使用 `register_ontology_type`、`resolve_memory_cell`、
`extract_claims` 和 `confirm_claim`。抽取只返回 Top-N Key 建议；必须由调用方逐 Claim
人工确认后，服务才会写入 Memory Cell 并执行冲突检测。

`candidate_granularity="clause"` 可显式开启保守的复合句拆分；默认仍为
`"sentence"`。确认请求必须沿用同一粒度，每个子 Claim 会保留父句 ID、顺序和精确原文
span。

设置 `ClaimExtractionRequest.extraction_mode="model_assisted"` 可请求服务端语义标注。
模型只能标注已有精确原文候选和本体内 Claim Key，并返回实体、时间及置信度提案；
结果仍为 `committed=false`。模型不可用或输出校验失败时会显式降级到规则模式；
设置 `allow_rule_fallback=False` 可将降级条件作为严格错误处理。

`claim_history` 返回不可覆盖的原始 Claim 历史，`current_claims` 返回经人审、审批和回归
门禁后的当前事实投影，`claim_continuity` 返回同一 Cell / Claim Key 的长期版本链、
当前版本、时间断档和重叠异常。连续性报告只读，不自动改写有效期。冲突裁决通过
`resolve_review` 的
`repair_actions[].claim_adjudication` 提交，不通过 SDK 直接改写 `claim_value`。

跨对象问题可从已知业务对象开始执行受控多 Cell 路由：

```python
from helix_service_client import MultiMemoryCellContextRequest

context = client.assemble_multi_memory_cell_context(
    MultiMemoryCellContextRequest(
        query="北星冷链为什么导致低温酸奶促销延期？",
        tenant_id="tenant_a",
        project_id="agent_platform",
        dataset_id="production_memory",
        seed_memory_cell_ids=["cell:supplier:northstar"],
        max_hops=2,
    )
)
```

响应保留逐跳 Cell、桥接 Evidence ID、分数和原因；服务端会在每一跳重新检查资源范围、
权限、双时间和生命周期。

显式业务关系使用 `register_memory_cell_relation` 注册，必须提供支持证据，可声明方向、
权限和有效期。交付验收可调用 `evaluate_multi_memory_cell_context`，以授权黄金 Cell、
Evidence、Relation 和预期回答状态计算跨 Cell 路径质量；不达门槛时可进入线上评测与
人审队列。

经人审确认的失败样本可通过 `multi_memory_gold_candidates` 查询脱敏候选，再使用
`promote_multi_memory_gold_candidate` 晋升为版本化用例，并由
`run_multi_memory_gold_case` 重放。晋升请求的 query 必须与失败事件保留的 SHA-256
一致；原始 query 不会出现在候选响应中。
