"""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="句子正文;空白会被折叠成一行")] line_break_before: Annotated[ bool, Field( description=( "这一句前面另起一行(默认 false)。正文被句子拼成一段,所以公式、" "分条列举、作者行这类不是散文的行要在这里开口;break 会顶掉句间的空格," "不会多印一个空格。display 公式($$…$$ 或 \\[…\\])本来就独占一行,不必设这个" ) ), ] = False 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" line_break_before: Annotated[ bool, Field( description=( "这一整块从新的一行开始(默认 false);只作用于切出来的第一句," "因为切出来的其余几句是接着它的,不是各自另起一行" ) ), ] = False 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", ]