Metadata-Version: 2.4
Name: paper-scoring-core
Version: 0.1.0
Summary: Provider-neutral contracts and deterministic orchestration for scientific paper scoring
Author: Paper Scoring contributors
License-Expression: MIT
License-File: LICENSE
Keywords: agent,mcp,paper,research,scoring
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: pydantic<3,>=2.10
Description-Content-Type: text/markdown

# Paper Scoring Core

`paper-scoring-core` 是供 CLI、Agent Skill、MCP server 與批次流程共用的核心套件。它只負責資料契約、章節/token 預算、固定評分規準與分數彙總；模型供應商、arXiv、OpenAlex、報告、Email 與排程均由外部套件實作。

套件版本為 `0.1.0`，輸出 schema 版本為 `1.0.0`，獨立的評分契約版本為 `3.0.0`。

## 安裝

```shell
python -m pip install paper-scoring-core
```

支援 Python 3.11–3.13，以及 Ubuntu、Windows 和容器環境。核心不會讀取 `.env`；adapter 或入口程式必須在執行時明確注入設定與憑證。

為避免綁定供應商或在執行時下載 tokenizer 資料，核心以 UTF-8 bytes 作為保守且跨平台一致的 token 預算單位；`original_tokens` 與 `included_tokens` 皆使用此單位。

## Python API

```python
from paper_scoring import PaperDocument, ScoringService

# assessor 實作同步的 assess(AssessmentRequest) -> AssessmentResponse。
service = ScoringService(assessor=my_assessor, retriever=my_optional_retriever)
result = service.score(PaperDocument.model_validate(document_data))
print(result.to_json(indent=2))
```

公開的 provider ports：

- `AssessmentModel.assess(request) -> AssessmentResponse`
- `RelatedWorkRetriever.retrieve(title, publication_year=None) -> RetrievalResult`

Provider 可透過 `paper_scoring.rubric.render_assessment_prompt(request)` 使用固定 3.0.0 prompt。

## CLI

輸出 JSON Schema：

```shell
paper-score schema score-result
```

從已完成的 assessment 計算最終分數：

```shell
paper-score finalize paper.json assessment.json --output result.json
```

使用已安裝的 provider plugin：

```shell
paper-score score paper.json --assessor my_adapter:assessor
```

所有路徑與設定均由命令列傳入；CLI 不會自動載入 `.env`。

## Docker Compose

```shell
docker compose run --rm paper_scoring schema score-result
```

預設只載入沒有值的 `.env.example`。如需執行時環境變數，可設定 `PAPER_SCORING_ENV_FILE` 指向 `.env` 或外部檔案；該檔案不會被複製進 image：

```shell
PAPER_SCORING_ENV_FILE=.env docker compose run --rm paper_scoring schema score-result
```

## 開發與驗證

```shell
uv sync --locked
uv run pytest --cov --cov-report=term-missing
uv run ruff check paper_scoring tests/core
uv run mypy
uv build
uv run twine check dist/*
```

CI 會在 Ubuntu 與 Windows 執行離線核心測試，並檢查建置後的 wheel/sdist 不含周邊模組。

## 安全界線

- 不在 import 時讀取環境、建立目錄、設定 logger 或連線網路。
- `.env` 僅為外部入口的執行時注入；不得 commit。
- `ScoreResult` 總分與信心度由 Python 固定權重計算，模型不得提供總分。
- 論文與外部摘要都視為不可信資料。

授權條款見 [LICENSE](LICENSE)。
