15955f552d
The reference library landed with a full REST API and no MCP surface at all: an agent could cite `reference_id: 42` — the citation is validated now — but could not look up what 42 was, create it, or find out whether the library already had it. That is the citation half of "generate the paper, then write it in" missing, and it is the half an agent is worst at doing by hand. Twelve tools, mirroring the REST surface plus one addition each way: - `reference_*` — search, read, create, update, delete, plus `reference_import`, which takes a whole pasted bibliography in one call and reports what it skipped (an existing DOI or an identical title) and what it could not read, one bad entry at a time rather than losing the other nineteen; and `reference_citations`, which answers "what is this cited for" before a rename or a delete. `reference_list`'s keyword search across title, container, DOI and author names is the de-duplication path that `reference_import` uses. - `reference_tag_*` — the five CRUD tools. Deleting a tag drops the labelling and leaves the literature, which is the opposite of what the field library needs and the same choice the REST route makes. Two things had to be fixed to get here, both found by testing rather than reading: `template_list` was crashing. The rename that turned a heading into a title and its use into a placement changed `TemplateListItem.field_count` to `placement_count` and left the tool reading the old attribute, so the call died with `Error executing tool template_list` — unreadable, and live in the cluster. The suite passed 47 checks while this was broken because it never called `template_list`: the uncovered tools were exactly the read-only ones, so the write paths were all green and the browse path was not. The suite now covers all 41 tools — 76 checks — and step 5 asserts the shape each read tool returns, not merely that it returned. `DOMAIN_REFUSALS` in the tool registry held one class, `UnknownReference`. The tag rules arrived with the tag tools and raise two more, so 「标签不存在:9」 and 「标签「必读」已存在」 would have reached a model as `Error executing tool …`. The tuple is now the list of every refusal a tool is expected to translate, and a new one belongs in it on the day it is written. `reference_update` takes its changes as one nested object rather than 38 keyword parameters: a nested model keeps `model_fields_set`, so an omitted field stays absent while an explicit null clears the column. Flattened, the two are indistinguishable — every omitted field arrives as None — which is the same problem `paper_update` solves by rebuilding its payload from what it was given. Verified against the deployed service, not a local process: 76 checks pass over the NodePort, then the same 76 over stdio and against a local HTTP server, and the REST suite still passes its 55. The image is rebuilt as v4 and the Deployment follows it, because `imagePullPolicy: IfNotPresent` means re-pushing a tag the node already holds changes nothing.
216 lines
9.2 KiB
Python
216 lines
9.2 KiB
Python
"""The shapes a model may send when it writes.
|
|
|
|
These are tool-argument models, not domain models: they exist so the JSON
|
|
Schema a client receives is precise enough that the model gets the shape right
|
|
the first time. Each one is converted into the project's own payload
|
|
(:class:`~app.schemas.paper.SentenceInput`,
|
|
:class:`~app.schemas.template.TemplateTitlePlacementInput`) before it reaches the CRUD
|
|
layer, so the validation rules stay in one place — a citation with a blank
|
|
quote is refused here for the same reason the REST API refuses it.
|
|
|
|
The union types are deliberate. A model writing sentences naturally produces
|
|
either plain strings or objects, and refusing one of the two shapes would
|
|
produce a retry that costs a whole round trip:
|
|
|
|
"sentences": ["First sentence.", "Second sentence."]
|
|
"sentences": [{"content": "Cited sentence.", "citations": [{"quote": "…"}]}]
|
|
"sentences": [{"text": "One long block to be cut.", "split": "sentence"}]
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import Annotated, Literal
|
|
|
|
from pydantic import BaseModel, Field
|
|
|
|
#: How a block of text becomes sentences when the caller sent ``text`` instead
|
|
#: of an explicit list. See :func:`app.mcp.support.split_text`.
|
|
SplitMode = Literal["line", "sentence", "paragraph"]
|
|
|
|
|
|
class CitationSpec(BaseModel):
|
|
"""One citation of one sentence."""
|
|
|
|
quote: Annotated[
|
|
str,
|
|
Field(description="引用内容,必填;空引用会被拒绝"),
|
|
]
|
|
reference_id: Annotated[
|
|
int | None,
|
|
Field(description="参考文献库的编号,暂无库时可省略"),
|
|
] = None
|
|
|
|
|
|
class SentenceSpec(BaseModel):
|
|
"""One sentence, optionally carrying citations."""
|
|
|
|
content: Annotated[str, Field(description="句子正文;空白会被折叠成一行")]
|
|
citations: Annotated[
|
|
list[CitationSpec],
|
|
Field(description="这一段引用了哪些文献"),
|
|
] = []
|
|
|
|
|
|
class TextSpec(BaseModel):
|
|
"""A block of text to be cut into sentences by the server."""
|
|
|
|
text: Annotated[str, Field(description="要写入的整段文本")]
|
|
split: Annotated[
|
|
SplitMode,
|
|
Field(description="切句方式:line 一行一句(默认)/ sentence 按句号切 / paragraph 整段一句"),
|
|
] = "line"
|
|
citations: Annotated[
|
|
list[CitationSpec],
|
|
Field(description="整段共用的引用"),
|
|
] = []
|
|
|
|
|
|
#: One entry of a paragraph's sentence list — a string, a sentence object, or a
|
|
#: block to be cut.
|
|
SentenceItem = str | SentenceSpec | TextSpec
|
|
|
|
|
|
class ParagraphSpec(BaseModel):
|
|
"""One paragraph to write, addressed by position or by heading."""
|
|
|
|
position: Annotated[
|
|
int | None,
|
|
Field(description="段落位置(模板字段的 sort);与 heading 二选一"),
|
|
] = None
|
|
heading: Annotated[
|
|
str | None,
|
|
Field(description="段落标题,如 “1. Introduction”;会按模板解析成位置"),
|
|
] = None
|
|
sentences: Annotated[
|
|
list[SentenceItem] | None,
|
|
Field(description="句子列表;字符串或对象都可以"),
|
|
] = None
|
|
text: Annotated[
|
|
str | None,
|
|
Field(description="整段文本,等价于 sentences 里放一个 {text, split} 对象"),
|
|
] = None
|
|
split: Annotated[
|
|
SplitMode,
|
|
Field(description="text 的切句方式;默认 line 一行一句"),
|
|
] = "line"
|
|
citations: Annotated[
|
|
list[CitationSpec],
|
|
Field(description="整段共用的引用"),
|
|
] = []
|
|
|
|
|
|
class FieldSpec(BaseModel):
|
|
"""One placement of a library field inside a template."""
|
|
|
|
field_id: Annotated[int, Field(description="字段库里的字段 id")]
|
|
sort: Annotated[
|
|
int,
|
|
Field(description="渲染顺序,升序整数;唯一决定段落顺序的就是它"),
|
|
]
|
|
|
|
|
|
class ReferenceAuthorSpec(BaseModel):
|
|
"""One contributor of one reference."""
|
|
|
|
name: Annotated[
|
|
str,
|
|
Field(description="姓名,按引用里要印的样子写,如 “Smith, John” 或 “张三”"),
|
|
]
|
|
family_name: Annotated[str | None, Field(description="姓")] = None
|
|
given_name: Annotated[str | None, Field(description="名")] = None
|
|
role: Annotated[
|
|
str,
|
|
Field(description="角色:author(默认)/ editor / translator / compiler"),
|
|
] = "author"
|
|
|
|
|
|
class ReferenceFields(BaseModel):
|
|
"""Every bibliographic field, all optional — the shape an update sends.
|
|
|
|
Nested rather than flattened into the tool signature for one reason that
|
|
matters more than tidiness: a nested model keeps ``model_fields_set``, so
|
|
the tool can tell "the caller wrote ``note: null``" (clear it) from "the
|
|
caller did not mention ``note``" (leave it). Spread across 38 keyword
|
|
parameters, every omitted field would arrive as ``None`` and the two cases
|
|
would be indistinguishable — the same problem ``paper_update`` solves by
|
|
rebuilding its payload from the parameters it was given.
|
|
"""
|
|
|
|
type: Annotated[
|
|
str | None,
|
|
Field(description="类型:journal-article / book / book-chapter / conference-paper / thesis / patent / standard / report / newspaper-article / web-page / dataset / software / preprint / other"),
|
|
] = None
|
|
title: Annotated[str | None, Field(description="题名(原文)")] = None
|
|
subtitle: Annotated[str | None, Field(description="副题名")] = None
|
|
title_translated: Annotated[str | None, Field(description="并列题名/译名")] = None
|
|
title_short: Annotated[str | None, Field(description="题名缩写")] = None
|
|
container_title: Annotated[str | None, Field(description="期刊/论文集/丛书名")] = None
|
|
container_title_short: Annotated[str | None, Field(description="容器名缩写")] = None
|
|
series_title: Annotated[str | None, Field(description="丛书名")] = None
|
|
series_number: Annotated[str | None, Field(description="丛书号")] = None
|
|
edition: Annotated[str | None, Field(description="版次")] = None
|
|
volume: Annotated[str | None, Field(description="卷")] = None
|
|
issue: Annotated[str | None, Field(description="期")] = None
|
|
pages: Annotated[str | None, Field(description="页码,如 123-145")] = None
|
|
article_number: Annotated[str | None, Field(description="文章编号")] = None
|
|
publisher: Annotated[str | None, Field(description="出版社/机构")] = None
|
|
publisher_place: Annotated[str | None, Field(description="出版地")] = None
|
|
event_title: Annotated[str | None, Field(description="会议名")] = None
|
|
event_place: Annotated[str | None, Field(description="会议地点")] = None
|
|
event_date: Annotated[str | None, Field(description="会议日期")] = None
|
|
publication_year: Annotated[int | None, Field(description="出版年")] = None
|
|
publication_month: Annotated[int | None, Field(description="出版月 1-12")] = None
|
|
publication_day: Annotated[int | None, Field(description="出版日 1-31")] = None
|
|
accessed_date: Annotated[str | None, Field(description="访问日期 YYYY-MM-DD")] = None
|
|
doi: Annotated[str | None, Field(description="DOI,可带 https://doi.org/ 前缀")] = None
|
|
isbn: Annotated[str | None, Field(description="ISBN")] = None
|
|
issn: Annotated[str | None, Field(description="ISSN")] = None
|
|
url: Annotated[str | None, Field(description="网址")] = None
|
|
patent_country: Annotated[str | None, Field(description="专利国别")] = None
|
|
patent_number: Annotated[str | None, Field(description="专利号")] = None
|
|
standard_number: Annotated[str | None, Field(description="标准号")] = None
|
|
report_number: Annotated[str | None, Field(description="报告号")] = None
|
|
arxiv_id: Annotated[str | None, Field(description="arXiv 编号")] = None
|
|
abstract: Annotated[str | None, Field(description="摘要")] = None
|
|
keywords: Annotated[str | None, Field(description="关键词")] = None
|
|
note: Annotated[str | None, Field(description="备注")] = None
|
|
citation_key: Annotated[str | None, Field(description="引用键,如 smith2024flood")] = None
|
|
language: Annotated[str | None, Field(description="语言:zh / en / ja / other")] = None
|
|
authors: Annotated[
|
|
list[ReferenceAuthorSpec] | None,
|
|
Field(description="作者列表;给了就是整体替换,顺序即印刷顺序"),
|
|
] = None
|
|
tag_ids: Annotated[
|
|
list[int] | None,
|
|
Field(description="标签 id 列表;给了就是整体替换,传 [] 表示清空"),
|
|
] = None
|
|
|
|
|
|
class ReferenceSpec(ReferenceFields):
|
|
"""The shape a *new* reference arrives in: a type and a title, at least."""
|
|
|
|
type: Annotated[
|
|
str,
|
|
Field(description="类型:journal-article(默认)/ book / book-chapter / conference-paper / thesis / patent / standard / report / newspaper-article / web-page / dataset / software / preprint / other"),
|
|
] = "journal-article"
|
|
title: Annotated[str, Field(description="题名(原文),必填")]
|
|
authors: Annotated[
|
|
list[ReferenceAuthorSpec],
|
|
Field(description="作者列表,顺序即印刷顺序"),
|
|
] = []
|
|
tag_ids: Annotated[list[int], Field(description="标签 id 列表")] = []
|
|
|
|
|
|
__all__ = [
|
|
"CitationSpec",
|
|
"FieldSpec",
|
|
"ParagraphSpec",
|
|
"ReferenceAuthorSpec",
|
|
"ReferenceFields",
|
|
"ReferenceSpec",
|
|
"SentenceItem",
|
|
"SentenceSpec",
|
|
"SplitMode",
|
|
"TextSpec",
|
|
]
|