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。

安裝

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

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：

paper-score schema score-result

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

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

使用已安裝的 provider plugin：

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

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

Docker Compose

docker compose run --rm paper_scoring schema score-result

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

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

開發與驗證

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。