Metadata-Version: 2.4
Name: trace-inquest-core
Version: 0.1.0
Summary: Deterministic metric slice of TraceInquest: core models, derived views and evaluators (no store, no API, no env)
License: MIT
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic<3,>=2.11

# trace-inquest-core

TraceInquest 的**判定切片**独立发行包：`core/`（数据模型、受控词表、资格判定、handoff 与
workflow 规则）+ `analyzers/`（`DerivedViews`）+ `evaluators/`（确定性指标）。

设计文档与口径的单一事实来源在仓库根的 `docs/`（本包不复制一份文档——两份"设计"必然漂移）。
执行纪律见仓库根的 `AGENTS.md`。

## 它是什么，以及不是什么

| 说法 | 成立吗 | 依据 |
|---|---|---|
| 不依赖 FastAPI / Store / Environment / CLI | **成立** | `tests/unit/test_core_pack_boundary.py` 按 AST 逐 import 判红 |
| 不依赖数据库、不发网络请求 | **成立** | 同上；判定层的外部能力一律经 `core/protocols.py` 的协议注入 |
| 零第三方依赖 | **不成立** | `core.models` 等就是 pydantic v2 模型，依赖元数据里如实声明 `pydantic>=2.11,<3` |

三条不同的一句话被经常混成一句，所以这里分开写。

## 安装

```bash
# 尚未公开发布（许可证遗留项 OPEN-07 未裁决），所以下面两条都针对本仓库构建出的产物
.venv/Scripts/python -m tests.tools.build_core_dist --build --outdir dist-core
.venv/Scripts/python -m pip install --no-deps --target ./core-check dist-core/trace_inquest_core-*.whl
```

Windows 上 PATH 里的 `python` 可能是 Microsoft Store 占位程序 ⇒ 命令一律写全解释器路径
（仓库根 `README.md` 同口径）。

**不要**与完整发行包 `trace-inquest` 装进同一个环境：两者都提供顶层包 `traceinquest`，
同名子包（`traceinquest/__init__.py`、`traceinquest/core/...`）的归属由安装顺序决定，
pip 不为共享文件做仲裁。本包按"分别安装"设计与验证。需要 CLI 或存储层时只装 `trace-inquest`。

## 最小用法

```python
from traceinquest.analyzers.views import build_views
from traceinquest.core.enums import KindInferenceSource, Origin, SpanKindTk, SpanStatusCode, Verdict
from traceinquest.core.models import CostSummary, InquestTrace, ReplayProfile, Span
from traceinquest.evaluators.engine import evaluate
from traceinquest.evaluators.protocol import EvalContext

root = Span(  # 一份最小轨迹：单个 agent span，成本与回放能力都如实写"不知道"
    span_id="0" * 16, display_id="s0001", trace_id="0" * 32, seq=1, depth=0,
    name="agent run", kind=SpanKindTk.AGENT, inference_source=KindInferenceSource.EXPLICIT,
    start_us=0, end_us=10, status_code=SpanStatusCode.OK,
)
trace = InquestTrace(
    source_semconv_commit="pinned", trace_id="0" * 32, run_id="run_1", root_span_id=root.span_id,
    status=Verdict.UNKNOWN, origin=Origin.REPLAY, agent_id="agent_a", spans=(root,),
    started_at_us=0, ended_at_us=10, cost=CostSummary(unknown_reason="price_table_missing"),
    replay=ReplayProfile(supported=False, mode="none", missing_reason="no env"),
)
report = evaluate(EvalContext(trace=trace, derived=build_views(trace), now_us=trace.ended_at_us))
print(report.summary())      # rows / full / degraded / not_applicable / evaluator_errors
```

判定切片没有 Store：`trace` 从哪来是你的事（自己构造、从别处读，或装完整发行包用 `inquest import`）。
指标口径只按 `docs/EVALUATION_DESIGN.md` 定义；本 README 不重复公式。
