Metadata-Version: 2.4
Name: routed-confidence
Version: 0.1.1
Summary: Field-level confidence evaluator SDK for routed extraction results
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.31.0

# routed-confidence

字段级置信度评估 SDK。

这个包默认只负责一件事：输入一条提取结果，输出每个字段的置信度分数。

如果初始化时显式传入 `collection_dir`，SDK 会额外把评估过的数据同步收集到本地 JSON 文件中。收集功能默认关闭，不传 `collection_dir` 就不会写任何文件。

SDK 不计算检出率、误伤率、日报统计，也不包含 Web、API 服务或自动迭代逻辑。

## 位置

源码目录：

```text
routed_confidence/
```

主要入口：

```text
routed_confidence/evaluator.py
```

内部评分组件：

```text
routed_confidence/internal/confidence_evaluators/
```

默认规则文件：

```text
routed_confidence/rules/meeting_ruler.json
```

## 安装

在当前仓库本地开发安装：

```bash
pip install -e .
```

从本地 wheel 安装：

```bash
python3 -m pip wheel . --no-deps --no-build-isolation -w dist
pip install dist/routed_confidence-0.1.0-py3-none-any.whl
```

如果发布到 PyPI 或私有 PyPI 后：

```bash
pip install routed-confidence
```

Python 导入名使用下划线：

```python
from routed_confidence import ConfidenceEvaluator
```

## 使用

```python
from routed_confidence import ConfidenceEvaluator

record = {
    "extraction_result": {
        "会议召开时间": {
            "value": "2026-05-20 14:00:00",
            "content": "会议召开时间为2026年5月20日14:00",
            "type": "text",
            "title_path": ["一、会议基本情况"],
        }
    },
    "input_text": "会议召开时间为2026年5月20日14:00。",
}

evaluator = ConfidenceEvaluator()
result = evaluator.evaluate(record)
print(result)
```

也可以使用一次性函数：

```python
from routed_confidence import evaluate_confidence

result = evaluate_confidence(record)
```

## 可选数据收集

如果想保存评估过的数据，初始化时传入 `collection_dir`：

```python
from routed_confidence import ConfidenceEvaluator

evaluator = ConfidenceEvaluator(
    collection_dir="./collected_data",
)

result = evaluator.evaluate(
    record,
    uuid="doc-001",
    infotype="股东大会-股东大会召开情况",
)
```

生成文件：

```text
./collected_data/evaluated_records_collected.json
```

收集文件格式：

```json
{
  "collection_info": {
    "description": "routed_confidence SDK collected evaluations",
    "format_version": "1.0"
  },
  "summary": {
    "total_records": 1,
    "updated_at": "2026-05-13T12:00:00"
  },
  "records": {
    "doc-001": {
      "uuid": "doc-001",
      "timestamp": "2026-05-13T12:00:00",
      "infotype": "股东大会-股东大会召开情况",
      "input": {
        "extraction_result": {}
      },
      "output": {
        "field_scores": {},
        "summary": {}
      }
    }
  }
}
```

说明：

- 只有传入 `collection_dir` 才会开启收集。
- `uuid` 用于去重；同一个 `uuid` 重复评估时只保留第一次收集的数据。
- 如果不传 `uuid`，SDK 会尝试从 `record["uuid"]`、`record["met_uuid"]`、`record["id"]` 或 `record["metadata"]` / `record["met_meta"]` 中读取；都没有时会自动生成一个 UUID。
- `infotype` 只作为记录元数据保存，不影响输出文件名。
- 收集失败不会影响评估结果返回。

## 返回格式

```json
{
  "field_scores": {
    "会议召开时间": {
      "source_value": "2026-05-20 14:00:00",
      "total_score": 0.75,
      "dimension_scores": {
        "schema": 1.0,
        "similarity": 0.82,
        "historical": 0.5,
        "relation": 1.0
      },
      "reason": "字段符合规则要求",
      "violations": [],
      "suggestions": []
    }
  },
  "summary": {
    "total_fields": 1,
    "average_score": 0.75
  }
}
```

注意：SDK 不返回 `is_correct`。`is_correct` 属于“标注数据 vs 提取数据”的评测逻辑，不属于置信度 SDK。

## 自定义规则和权重

```python
from routed_confidence import ConfidenceEvaluator

evaluator = ConfidenceEvaluator(
    rules_file="/path/to/meeting_ruler.json",
    weights={
        "schema": 0.1,
        "sim": 0.2,
        "wilson": 0.1,
        "relation": 0.6,
    },
)
```

如果不传 `rules_file`，SDK 会优先寻找当前项目里的 `schema/ruler/meeting_ruler.json`，找不到时使用包内置的默认规则。

## Embedding 相似度配置

`similarity` 维度默认会尝试调用 OpenAI-compatible embedding 接口。

开源包不会内置任何 embedding 服务地址、模型名或 API Key。不显式配置时，SDK 会提示并自动使用本地字符串相似度，评估流程不会中断。

如果显式配置了 embedding，但服务不可用，SDK 也会提示并自动回退到本地字符串相似度。

显式配置：

```python
from routed_confidence import ConfidenceEvaluator

evaluator = ConfidenceEvaluator(
    embedding_api_base_url="http://your-embedding-service:8191",
    embedding_model="qwen3-embedding-0.6b",
    embedding_api_key="your-api-key",  # 如果服务不需要鉴权，可以不传
)
```

也可以用环境变量：

```bash
export ROUTED_CONFIDENCE_EMBEDDING_API_BASE_URL="http://your-embedding-service:8191"
export ROUTED_CONFIDENCE_EMBEDDING_MODEL="qwen3-embedding-0.6b"
export ROUTED_CONFIDENCE_EMBEDDING_API_KEY="your-api-key"
```

## 发布

安装构建工具：

```bash
pip install build twine
```

构建：

```bash
python -m build
```

会生成：

```text
dist/routed_confidence-0.1.0-py3-none-any.whl
dist/routed_confidence-0.1.0.tar.gz
```

上传到 PyPI：

```bash
twine upload dist/*
```

上传到私有 PyPI：

```bash
twine upload --repository-url https://your-private-pypi/simple/ dist/*
```

发布后安装：

```bash
pip install routed-confidence
```

## 当前边界

- 只做单条/字段级置信度评估。
- 可选收集评估过的数据，但默认关闭。
- 不计算检出率。
- 不计算误伤率。
- 不依赖 `methods/api`、`methods/web_conf`、`methods/reflect_rule`。
- 不要求用户导入内部四维组件。
