Airalogy类型

airalogy中提供了多种内置类型。Airalogy平台原生支持这些内置类型，以方便用户在定义Airalogy Protocol Model中data fields的类型。这些内置类型通常在Airalogy平台上能够被自动解析，以提供一些额外的功能，例如基于用户的基本信息进行赋值，或自动生成独特的界面交互。

现在这些官方内置类型也被纳入了一套可插拔的类型注册表。也就是说，官方类型仍然保持稳定，但第三方包也可以在不修改 Airalogy 源码的情况下注册新的公共类型。

另见：

• Type Plugins

UserName

from airalogy.types import UserName
from pydantic import BaseModel

class VarModel(BaseModel):
    user_name: UserName

定义为UserName类型的字段，可以在Airalogy平台上自动赋值为当前用户的用户名。

所有Research Node built-in types在生成Model JSON Schema时，均会默认附加一个额外的JSON Schema字段，airalogy_type，用于标识该字段的内置类型。例如，上述案例中的VarModel JSON Schema如下：

{   
    "title": "VarModel",
    "type": "object",
    "properties": {
        "user_name": {
            "title": "User Name",
            "type": "string",
            "airalogy_type": "UserName",
        }
    },
    "required": ["user_name"]
}

Current

CurrentTime

from airalogy.types import CurrentTime
from pydantic import BaseModel

class VarModel(BaseModel):
    current_time: CurrentTime

定义为CurrentTime类型的字段，可以在Airalogy平台上自动赋值为当前时间，时间所属时区为用户浏览器的时区。

CurrentProtocolId

from airalogy.types import CurrentProtocolID
from pydantic import BaseModel

class VarModel(BaseModel):
    current_protocol_id: CurrentProtocolID

定义为CurrentProtocolID类型的字段，可以在Airalogy平台上自动赋值为当前Protocol的Airalogy Protocol ID。

CurrentRecordId

from airalogy.types import CurrentRecordId
from pydantic import BaseModel

class VarModel(BaseModel):
    current_record_id: CurrentRecordId

定义为CurrentRecordId类型的字段，可以在Airalogy平台上自动赋值为当前Record的Airalogy Record ID。

AiralogyMarkdown

from airalogy.types import AiralogyMarkdown
from pydantic import BaseModel

class VarModel(BaseModel):
    content: AiralogyMarkdown

定义为AiralogyMarkdown类型的字段，可以在Airalogy平台上自动生成一个Markdown编辑器，用于编辑Airalogy Markdown文本。注意，这里我们将其命名为AiralogyMarkdown，而非Markdown/Md，是因为Markdown有很多种变体和语法规范，我们这里显式的指定该Markdown采用Airalogy Markdown语法规范，以保证前端渲染的一致性和稳定性。

SnakeStr

from airalogy.types import SnakeStr
from pydantic import BaseModel
class VarModel(BaseModel):
    snake_case_string: SnakeStr

定义为SnakeStr类型的字段，要求字符串必须符合Python的snake_case命名规范。该类型通常用于需要遵循特定命名规范的字符串字段。

VersionStr

from airalogy.types import VersionStr
from pydantic import BaseModel
class VarModel(BaseModel):
    version: VersionStr

定义为VersionStr类型的字段，要求字符串必须符合语义化版本控制（SemVer）规范，即：x.y.z，其中x、y、z均为非负整数。该类型通常用于表示版本号。

ProtocolId

from airalogy.types import ProtocolId
from pydantic import BaseModel
class Model(BaseModel):
    protocol_id: ProtocolId

定义为ProtocolId类型的字段，要求字符串必须符合Airalogy Protocol ID规范。该规范通常用于唯一标识一个Protocol，格式为：

airalogy.id.lab.{lab_id}.project.{project_id}.protocol.{protocol_id}.v.{version}

其中lab_id、project_id、protocol_id符合SnakeStr规范，version符合VersionStr规范。

RecordId

from airalogy.types import RecordId
from pydantic import BaseModel

class VarModel(BaseModel):
    record_id: RecordId

定义为RecordId类型的字段，Airalogy平台会生成一个供用户选择历史Record的下拉框。用户选择后，该字段会被赋值为所选Record的str形式的ID。

FileId

在Airalogy中，允许用户自定义数据字段为FileId相关类型，这些数据字段的记录界面的插槽会自动显示文件上传按钮，用户可以通过点击按钮上传文件。上传的文件会被自动保存到Airalogy的文件系统中，并且会被赋予一个唯一的文件ID (type: str)。用户可以通过该文件ID来访问该文件。

from airalogy.types import (
    # Image file types
    FileIdPNG, FileIdJPG, FileIdSVG, FileIdWEBP, FileIdTIFF,
    # Video file types
    FileIdMP4,
    # Audio file types
    FileIdMP3,
    # Document file types
    FileIdAIMD, FileIdMD, FileIdTXT,
    FileIdCSV, FileIdJSON,
    FileIdDOCX,FileIdXLSX, FileIdPPTX, 
    FileIdPDF,
    FileIdDna # SnapGene软件常用的`.dna`文件类型
)
from pydantic import BaseModel

class VarModel(BaseModel):
    png_file_id: FileIdPNG
    jpg_file_id: FileIdJPG
    svg_file_id: FileIdSVG
    webp_file_id: FileIdWEBP
    tiff_file_id: FileIdTIFF
    mp4_file_id: FileIdMP4
    mp3_file_id: FileIdMP3
    aimd_file_id: FileIdAIMD
    md_file_id: FileIdMD
    txt_file_id: FileIdTXT
    csv_file_id: FileIdCSV
    json_file_id: FileIdJSON
    docx_file_id: FileIdDOCX
    xlsx_file_id: FileIdXLSX
    pptx_file_id: FileIdPPTX
    pdf_file_id: FileIdPDF
    dna_file_id: FileIdDna

IgnoreStr

以IgnoreStr类型定义的var字段，其在Airalogy平台记录界面可以填写任意字符串，该字符串可以被传入Assigner，但在保存该Airalogy Record时，该字段的值会被忽略，以空字符串代替。

该类型通常应用于管理一些需要被Assigner调用的机密信息，但不希望被保存在Airalogy Record中的场景，如API Key等。

from airalogy.types import IgnoreStr

from pydantic import BaseModel
    api_key: IgnoreStr

编程语言相关代码字符串 (Code Strings)

PyStr, JsStr, TsStr, JsonStr, TomlStr, YamlStr

from airalogy.types import PyStr, JsStr, TsStr, JsonStr, TomlStr, YamlStr
from pydantic import BaseModel

class VarModel(BaseModel):
    python_code: PyStr
    javascript_code: JsStr
    typescript_code: TsStr
    json_str: JsonStr
    toml_str: TomlStr
    yaml_str: YamlStr

定义为PyStr类型的字段，可以在Airalogy平台上自动生成一个Python代码编辑器，用于编辑Python代码。该编辑器会提供语法高亮等功能。该Field的值以str形式存储。

其他编程语言相关字符串类型类似。

ATCG

ATCG 是用于管理DNA序列的内置类型。该类型只允许包含A、T、C、G四个字母的字符串，若包含其他字符会抛出校验错误。

from airalogy.types import ATCG
from pydantic import BaseModel

class VarModel(BaseModel):
    dna_seq: ATCG

定义为 ATCG 类型的字段，只能输入有效的DNA序列。该类型还提供 .complement() 方法用于获取互补链（A<->T, C<->G）：

seq = ATCG("ATCG")
print(seq.complement())  # 输出: TAGC

使用 ATCG 的模型生成的JSON Schema如下：

{
  "title": "VarModel",
  "type": "object",
  "properties": {
    "dna_seq": {
      "title": "Dna Seq",
      "type": "string",
      "airalogy_type": "ATCG",
      "pattern": "^[ATCG]*$"
    }
  },
  "required": ["dna_seq"]
}

DNASequence

DNASequence 是 Airalogy 提供的结构化 DNA 内置类型，用于可编辑的 DNA 序列数据。与只保存原始字符串的 ATCG 不同，DNASequence 会保存：

• 可选的人类可读序列名称
• 标准化后的序列文本
• 拓扑结构（linear / circular）
• 与 GenBank 对齐子集兼容的 annotation 列表

from airalogy.types import DNASequence
from pydantic import BaseModel

class VarModel(BaseModel):
    plasmid: DNASequence

其保存值是如下结构的 JSON 对象：

{
  "format": "airalogy_dna_v1",
  "name": "pUC19",
  "sequence": "ATGCGTNNNATGC",
  "topology": "circular",
  "annotations": [
    {
      "id": "feat_lacz",
      "name": "lacZ CDS",
      "type": "CDS",
      "strand": 1,
      "color": "#2563eb",
      "segments": [
        {
          "start": 121,
          "end": 980,
          "partial_start": false,
          "partial_end": false
        }
      ],
      "qualifiers": [
        { "key": "gene", "value": "lacZ" },
        { "key": "product", "value": "beta-galactosidase" },
        { "key": "note", "value": "Reporter CDS" }
      ]
    }
  ]
}

它不是对 GenBank flatfile 的一比一镜像，而是 Airalogy 内部更适合编辑的 canonical model，同时保留了足够的 GenBank 对齐能力，便于后续导入导出：

• 特征位置使用 segments[] 表达
• 模糊或不完整边界通过 partial_start / partial_end 保存
• GenBank 限定词使用可编辑的 key / value 行保存

当你希望前端直接编辑序列和 annotation 时，使用 DNASequence。如果你只是想上传或引用原始 SnapGene .dna 文件，则使用 FileIdDNA。

DNASequence 是唯一支持的公开类型名。在 AIMD、Python 模型和面向用户的文档中都应统一使用 DNASequence。

中国常用枚举类

airalogy.types.chinese 中内置了若干个在中国业务场景中常用的枚举字段，可用于快速构建人口统计信息相关的数据模型。

from airalogy.types import (
    ChineseEthnicGroup,
    ChineseProvinceLevelRegion,
    ChineseGender,
    ChineseMaritalStatus,
    ChineseEducationLevel,
)
from pydantic import BaseModel


class DemographicModel(BaseModel):
    ethnic_group: ChineseEthnicGroup
    province: ChineseProvinceLevelRegion
    gender: ChineseGender
    marital_status: ChineseMaritalStatus
    education_level: ChineseEducationLevel

ChineseEthnicGroup

使用中国国务院公布的 56 个法定民族（如“汉族”“藏族”“维吾尔族”等）作为可选值。该枚举类型通常用于要求用户明确选择其民族的场景。

ChineseProvinceLevelRegion

涵盖当前 34 个省级行政区（23 个省、5 个自治区、4 个直辖市、2 个特别行政区），枚举值为“北京”“广东”“新疆”“香港”等。适合需要采集常住地或户籍所在省份的字段。

ChineseGender

固定取值为“男”或“女”，可用来快速生成符合中国居民登记习惯的性别选择字段。

ChineseMaritalStatus

包含“未婚”“已婚”“丧偶”“离婚”“再婚”五种状态，可用于婚姻状况调查或表单。

ChineseEducationLevel

覆盖“无学历”“小学”“初中”“高中”“中专”“大专”“本科”“硕士”“博士”九档文化程度，使模型在采集教育背景时保持一致的描述方式。