dnakit 0.1.0.dev0__tar.gz

dnakit-0.1.0.dev0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+本项目遵循语义化版本。`0.1.0.dev0` 是开发预览版，公开接口在首个正式版本前可能调整。
+
+## [0.1.0.dev0] - 2026-08-28
+
+### Added
+
+- 面向普通用户的统一 `dnakit.DNA(...)` 门面：同一个入口接收单条/多条序列、逐条 record mapping、ID、拓扑、metadata、feature 和旧核心对象；下标与切片仍返回 `DNA`。
+- 新增 `dnakit.representations`：可选择 11 种 DNA 基础模型提取固定长度 rep，checkpoint 默认下载到当前目录 `ckpt/` 并复用；新增 `neural_cluster_sequences()` 完成 L2、可选 PCA、seed 固定的 k-means、中心最近代表序列和完整结果审计。
+- 新增 `evaluate_frechet_distance()`：默认复用 DATA-027 的 LucaOne 表征和 L2 归一化，以样本空间等价算法计算两个 DNA 集合的 Fréchet 表征分布距离。
+- 新增 `evaluate_fragment_similarity()` 和 `evaluate_snn()`：分别以 exact k-mer 出现次数余弦相似度和 hashed k-mer 指纹最近邻 Tanimoto 均值实现 MOSES Frag/SNN 的 DNA 适配。
+- `dnakit.datasets.exclude_species()` 和 `exclude_chromosomes()`：按显式 metadata 精确排除一个或多个物种/染色体；缺少目标字段时结构化报错。
+- MkDocs 文档站启用中文站内搜索框、搜索建议和结果关键词高亮。
+- `ValidationConfig(sequence_length=...)`、`dnakit validate --sequence-length` 和工作流 `validate` 步骤现可按标准化后的精确 `symbol_length` 判定序列是否合法。
+- 根目录新增 MIT 许可证文件，版权人标注为 Pengsen Ma，并将许可证纳入发行归档。
+- 新增 `THIRD_PARTY_NOTICES.md`、`DISCLAIMER.md` 及文档站“致谢与引用”合并页，明确外部工具、用户数据、费用和非临床使用边界。
+- 有界 GenBank 子集、GFF3、BED3–6、AGP 2.1、普通 FASTA/严格四行 FASTQ 持久索引、坐标提取、分块迭代和元数据管理。
+- 以显式 `TableSchema` 有界读写 CSV/TSV/JSON/Parquet 的 `read_table()`、`export_table()` 和不可变审计结果。
+- 复杂度/重复描述符，motif/PWM、ORF、限制酶、PAM、CpG island、回文、倒置重复、串联重复、STR 和低复杂度扫描。
+- 分子量、基于公开 nearest-neighbor 吸光参数的未修饰 ssDNA 260 nm 理论消光系数，以及内部复现的 SantaLucia 1998 Tm、盐修正、nearest-neighbor、ΔG/ΔH/ΔS、堆积、完整互补 duplex 和局部 Tm；`duplex_stability()` 可显式使用用户安装的 Primer3 CLI adapter 评价 canonical mismatch/dangling heterodimer。
+- 单/双链光学性质、OD260/A260/摩尔浓度/质量浓度/物质的量/质量换算、显式染料/修饰修正，以及 Ka/Kd、双链比例、理论熔解曲线、末端稳定性、Na⁺+K⁺ 和 DMSO/甲酰胺经验修正。
+- dot-bracket 二级结构与配对概率派生指标、单独许可安装后才执行的显式 NUPACK 4 adapter，以及 PDB 坐标几何、SASA、体积、形状、骨架二面角、近似螺旋参数、NMR ensemble RMSF 和 3DNA/DSSR 解析。
+- RCSB 1BNA、1AC7、139D 本地校验样本、SHA-256 清单、带进度条的结构分析脚本和机器可读结果。
+- 纯外部 CLI 的 `Primer3CLIAdapter`，要求显式 `oligotm`/`ntthal` 路径，支持 Tm、hairpin、self-dimer 和 heterodimer，并记录许可、路径和 provenance；下游统一结果会校验序列、条件和结构选项绑定。
+- MinHash/FracMinHash、motif/限制酶/GC/repeat/coding/固定 16 维热力学/混合/多尺度指纹及训练集拟合的预处理器；结构特征使用显式 adapter 或固定缺失策略。
+- 有界近似匹配、global/local/semi-global 线性/仿射 gap 比对、sketch 相似度、持久索引和 Top-k 最近邻。
+- 环状/IUPAC/近似去重、identity/edit/k-mer/fingerprint 聚类、层次聚类、代表序列、时间划分、多约束启发式划分、leakage 和划分质量评价。
+- `SplitConfig(method="hash")` 顺序无关的稳定哈希划分：使用 SHA-256、seed 和唯一 `record.id`，并保持精确比例配额。
+- validity、ambiguity、quality、complexity、uniqueness、diversity、redundancy、reference-scoped novelty/memorization、分布相似度、synthesis-risk 和规则型 scorecard。
+- 酶切、末端/连接、PCR、引物匹配、可选结构引物属性、严格设计请求及显式路径的 `Primer3CLIDesignAdapter`、Gibson/LCR/Golden Gate/BioBrick 序列级组装、CRISPR 候选、规则优化、密码子优化和突变文库；Primer3 设计候选会反查模板坐标、左右引物序列和产物长度。
+- 线性/环状 feature 图、alignment 图、相似度矩阵、自包含 HTML 报告，以及可选 PNG/TIFF/PDF 600 dpi 导出。
+- 后端 registry、BLAST/MMseqs2/sourmash 被动 metadata/显式版本句柄、要求调用方提供可执行文件的严格 Dashing Jaccard/Top-k adapter、内容寻址 JSON 缓存、线程批处理、稳定 resume、JSON/YAML 多步骤工作流和可审计运行清单。
+- `describe`、`fingerprint`、`search`、`orfs`、`compare`、`report` 和 `workflow` 等统一 CLI 能力，以及兼容开发入口 `python -m dnakit.cli.workflow run`。
+- 本地正确性验证器、带 seed/环境/参数/逐样本记录的 microbenchmark、DNAKit/Biopython 对等任务比较、所选公开 callable 源码行口径、高级 Notebook、完整工作流示例和阶段 4/5 交付报告。
+- TestPyPI 和正式 PyPI 的手动工作流配置；构建审查 job 无发布凭据，只有上传 job 具有 `id-token: write`，二者均带许可证、版本与显式确认门禁，本阶段未触发。
+
+### Changed
+
+- `evolution_generate()` 保留 `mut_frac` 参数名，并新增逐碱基 `insert_frac`、`delete_frac` 概率；插入可用 `insert_min/insert_max` 选择单碱基或随机长度片段，算法审计版本升级为 `dnakit-evoaug-v3`。单次连续片段插入/删除继续由 `indel_generate()` 提供。
+- 文档将 FP-004 Canonical k-mer 并入 FP-003 k-mer 特征的 Canonical 模式，并将 FP-005 统一命名为 k-mer Sketch；公开 Python API 和稳定追踪编号保持兼容。
+- 普通文件读取统一为 `read(..., mode="dna"|"stream")`，验证统一为 `validate()`；无后缀编辑、反向互补和环状操作对 `DNA` 输入同步注释并返回 `DNA`，旧 `read_one/read_set/validate_set/*_record` 入口继续兼容。
+- DNA 基础模型表征和神经网络聚类的默认 checkpoint 从 GROVER 改为 `LucaGroup/LucaOne-gene-step36.8M`；默认缓存目录为 `ckpt/lucaone-gene-step36-8m/`，自定义 checkpoint 代码仍需显式授权。
+- 删除内置 DiProDB 240 个数值；固定 240 字段 schema 保持不变，默认后 60 项为 `None`，用户可加载有权使用的严格 15×16 JSON 表。
+- 删除 `primer3` extra、`primer3-py` 依赖和 Python binding adapter；Primer3 统一改为用户单独安装并提供显式 CLI 路径。
+- `normalize()` 新增 `keep_ambiguous`、`keep_u`和 `keep_other`；默认保留 IUPAC 模糊碱基，审计删除 `U` 和其他非 DNA 字符。
+- 需求追踪矩阵改为逐项按当前源码、测试和本地后端状态核对，不再保留过期 `planned` 声明。
+- 将独立的 identity、query coverage 和 target coverage 功能项合并到 `SIM-008` 序列比对结果，并删除重复编号。
+- 批处理支持有界线程执行、稳定原始索引/派生 seed 和已完成 ID 跳过。
+- 可视化范围收缩为序列、feature、alignment 和相似度矩阵，通用图片导出和 HTML 报告保持不变。
+- 可视化导出扩展为原子多格式输出，并对像素、记录数和内嵌结果字节数设硬上限。
+- README、安装、快速入门、API、FAQ、引用/许可证和文档站导航同步到阶段 4/5 真实状态。
+
+### Validation
+
+- 11 种模型 registry、checkpoint 复用/下载契约、IUPAC/Gap/矩阵边界和 rep → k-means/PCA 由单元测试覆盖；GROVER 使用真实本地 checkpoint 完成 4 条序列的 rep + k-means smoke，其余模型保持条件状态。
+- 人工小序列、IUPAC、空序列、200,000 nt 输入和跨原点环状限制酶位点通过边界验证。
+- 限制酶、分子量终端约定、全局比对、字面搜索和 single/complete/average linkage 与 Biopython 对照通过。
+- Primer3 CLI adapter 以临时受控替身验证命令白名单、Boulder-IO、字段/单位解析、失败、超时和输出上限；不再把旧 Python binding 对照写成当前科学验证。
+- Dashing adapter 的固定命令、矩阵解析、失败/超时/输出/输入突变边界由受控替身覆盖，本地 `v1.0.2-4-g0635` 两序列 exact 文档示例 smoke 通过；尚未做科学差分。
+- Primer3 不属于 Python 依赖且不随 DNAKit 打包；CLI adapter 记录 `GPL-2.0-or-later` 提示，用户仍须按实际安装版本复核。
+- NUPACK adapter 的字段映射、边界和错误处理已用受控替身测试；当前环境没有 NUPACK，因此仍不存在真实 NUPACK 数值差分结论。
+
+### Remaining boundaries
+
+- DNAKit 自身许可证已确定为 MIT；本版本作为开发预览版发布，依赖兼容性仍需持续复核。
+- 尚未部署 GitHub Pages，也未执行论文复现实验。
+- NUPACK、Primer3、DSSR/3DNA 和 Dashing 不随项目安装/下载；DiProDB 数值不再内置；各外部工具/数据的许可、可能费用和真实科学差分仍由使用者按实际版本复核。
+- PyArrow 25.0.1 下的 DNAKit Parquet 写出/`read_table()` 往返已通过；其他引擎/版本交叉矩阵尚未执行。

dnakit-0.1.0.dev0/CITATION.cff

@@ -0,0 +1,16 @@
+cff-version: 1.2.0
+message: "DNAKit is a development preview. Cite DNAKit plus every algorithm, database, and optional backend used by your workflow."
+title: "DNAKit"
+type: software
+version: "0.1.0.dev0"
+license: "MIT"
+authors:
+  - name: "DNAKit contributors"
+abstract: "A development-stage Python toolkit for deterministic DNA sequence standardization, descriptors, thermodynamics, fingerprints, similarity, dataset curation, evaluation, molecular-biology simulation, and visualization."
+keywords:
+  - DNA
+  - bioinformatics
+  - sequence analysis
+  - thermodynamics
+  - data curation
+  - reproducibility

dnakit-0.1.0.dev0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# 贡献指南
+
+DNAKit 当前处于本地开发阶段，尚未建立公开 GitHub 协作流程。贡献应先保持小范围、可测试并与需求追踪矩阵对应。
+
+## 开发环境
+
+```bash
+conda env create -f environment-dev.yml
+conda activate dnakit-dev
+python -m pip install -e ".[dev,docs]"
+```
+
+环境必须保持 `PYTHONNOUSERSITE=1`，避免用户级包影响验证。
+
+## 修改要求
+
+- 支持 Python 3.10 及以上版本，使用类型注解。
+- 公共行为需要 pytest 测试；边界行为需要明确错误和参数验证。
+- 算法必须标记为 `native`、`adapter`、`reimplementation` 或 `novel`。
+- adapter 必须记录后端名称、版本、参数、许可证提示和缺失后端行为。
+- 随机流程必须记录 seed；外部数据库必须记录版本和校验信息。
+- 不提交 NUPACK、Dashing、数据库快照、构建产物、缓存或其他不可分发工件。
+- 不虚构尚未实现的 API、benchmark 或正确性结论。
+
+## 本地检查
+
+```bash
+ruff check src tests
+ruff format --check src tests
+mypy
+pytest
+pytest --nbmake notebooks/00_skeleton_check.ipynb
+mkdocs build --strict
+python -m build
+twine check dist/*
+```
+
+代码、测试、文档、追踪矩阵和变更记录应在同一次修改中保持一致。
+
+## 提交内容
+
+每项实现应说明：
+
+1. 对应的需求 ID；
+2. 公共 API 和 CLI 行为；
+3. 输入边界、异常和数值容差；
+4. 测试与对照工具；
+5. 算法来源、引用、许可证和 provenance；
+6. 用户可见的变更记录和示例。
+
+## 发布限制
+
+项目采用 MIT 许可证，但当前仍不创建正式发布、不上传 TestPyPI/PyPI、不推送 GitHub，也不部署网站。发布操作必须在项目所有者明确批准后单独执行。

dnakit-0.1.0.dev0/DISCLAIMER.md

@@ -0,0 +1,26 @@
+# DNAKit 免责声明 / Disclaimer
+
+## 中文
+
+DNAKit 是研究与教学用途的软件，不是医疗器械，也不用于临床诊断、治疗、患者管理、实验安全决策或其他高风险用途。软件输出可能不完整、不准确或不适用于特定实验；使用者必须独立验证计算、参数、输入数据和实验结论。
+
+DNAKit 按仓库 `LICENSE` 中的 MIT 许可证提供。该许可证已经包含“按原样提供”、无明示或默示担保以及责任限制条款。本文件用于进一步说明使用边界，不替代、缩减或修改 MIT 许可证，也不构成法律、医疗或合规意见。
+
+DNAKit 自身采用 MIT 许可证，允许研究和商业使用。因此，“本项目仅供学术研究”只是当前开发目的说明，不能被解释为对下游使用者施加非商业限制，也不能自动免除作者或使用者的法律责任。
+
+使用者负责：
+
+- 确认其提供的数据、参数表、数据库和外部程序具有适用的访问、使用与再分发权限；
+- 遵守第三方许可证、订阅条款、署名/引用要求、出口管制、隐私、伦理、生物安全及所在司法辖区的法律法规；
+- 在论文、软件或服务中准确披露实际使用的方法、版本、参数、限制和第三方来源；
+- 在依赖结果开展实验、发表、部署或商业活动前完成独立验证和必要的专业审查。
+
+DNAKit 不保证任何第三方资源免费、持续可用、适合商业用途或允许再分发。第三方条款和费用可能变化；请在使用时核对其官方许可证和价格页面。详见 `THIRD_PARTY_NOTICES.md`。
+
+## English
+
+DNAKit is research and educational software. It is not a medical device and is not intended for clinical diagnosis, treatment, patient management, laboratory-safety decisions, or other high-risk uses. Results may be incomplete, inaccurate, or unsuitable for a particular experiment and must be independently validated.
+
+DNAKit is provided under the MIT License in `LICENSE`, including its “AS IS” warranty disclaimer and limitation of liability. This document clarifies scope; it does not replace, narrow, or modify the MIT License and is not legal, medical, or regulatory advice.
+
+Users are responsible for verifying their rights to all supplied data, parameter tables, databases, and external software; complying with applicable third-party terms, citation requirements, privacy, ethics, biosafety, export-control, and other laws; and independently validating results before publication, deployment, experimentation, or commercial use. DNAKit does not warrant that third-party resources are free, continuously available, commercially usable, or redistributable. See `THIRD_PARTY_NOTICES.md`.

dnakit-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pengsen Ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dnakit-0.1.0.dev0/MANIFEST.in

@@ -0,0 +1,21 @@
+include README.md
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+include LICENSE
+include DISCLAIMER.md
+include THIRD_PARTY_NOTICES.md
+include pyproject.toml
+include environment-dev.yml
+recursive-include src *.py py.typed
+recursive-include tests *.py
+recursive-include benchmarks *.py *.md *.json
+recursive-include validation *.py *.md *.json
+recursive-include examples *.json *.fasta *.yml *.md
+recursive-include docs *.md *.json *.csv
+include mkdocs.yml
+recursive-include notebooks *.ipynb
+
+prune dashing_similarity
+prune ckpt
+global-exclude __pycache__ *.py[cod] *.so *.a *.o

dnakit-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: dnakit
+Version: 0.1.0.dev0
+Summary: Deterministic tools for DNA sequence analysis
+Author: DNAKit contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mapengsen/DNAKit
+Project-URL: Documentation, https://github.com/mapengsen/DNAKit/tree/main/docs
+Project-URL: Repository, https://github.com/mapengsen/DNAKit
+Project-URL: Issues, https://github.com/mapengsen/DNAKit/issues
+Project-URL: Changelog, https://github.com/mapengsen/DNAKit/blob/main/CHANGELOG.md
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: DISCLAIMER.md
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: numpy<3,>=1.26; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]<1,>=0.27; extra == "docs"
+Requires-Dist: nbmake<2,>=1.5; extra == "docs"
+Provides-Extra: viz
+Requires-Dist: CairoSVG<3,>=2.7; extra == "viz"
+Requires-Dist: Pillow<13,>=10; extra == "viz"
+Provides-Extra: io
+Requires-Dist: pyarrow<26,>=19; extra == "io"
+Provides-Extra: validation
+Requires-Dist: biopython<2,>=1.85; extra == "validation"
+Provides-Extra: neural
+Requires-Dist: huggingface-hub<2,>=0.28; extra == "neural"
+Requires-Dist: numpy<3,>=1.26; extra == "neural"
+Requires-Dist: scikit-learn<2,>=1.5; extra == "neural"
+Requires-Dist: torch<3,>=2.5; extra == "neural"
+Requires-Dist: transformers<5,>=4.49; extra == "neural"
+Provides-Extra: neural-caduceus
+Requires-Dist: mamba-ssm<3,>=2.2; extra == "neural-caduceus"
+Provides-Extra: neural-enformer
+Requires-Dist: enformer-pytorch<1,>=0.8.11; extra == "neural-enformer"
+Provides-Extra: neural-evo2
+Requires-Dist: evo2<0.6,>=0.5.3; extra == "neural-evo2"
+Dynamic: license-file
+
+<p align="center">
+  <img alt="DNAKit logo" src="https://raw.githubusercontent.com/mapengsen/DNAKit/main/docs/assets/images/DNAKit-icon.png" width="40%">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/dnakit/">
+    <img src="https://img.shields.io/pypi/v/dnakit?include_prereleases&amp;label=PyPI" alt="PyPI version">
+  </a>
+  <a href="https://github.com/mapengsen/DNAKit/actions/workflows/ci.yml">
+    <img src="https://github.com/mapengsen/DNAKit/actions/workflows/ci.yml/badge.svg" alt="CI status">
+  </a>
+  <a href="https://pypi.org/project/dnakit/">
+    <img src="https://img.shields.io/pypi/pyversions/dnakit" alt="Supported Python versions">
+  </a>
+  <a href="https://github.com/mapengsen/DNAKit/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/mapengsen/DNAKit" alt="MIT license">
+  </a>
+</p>
+
+# DNAKit 是什么？
+
+DNAKit 是面向 DNA 序列的可复现 Python 工具包，定位类似“DNA 领域的 RDKit”。它覆盖标准化、文件与注释格式、基础操作、描述符、模式扫描、热力学、指纹、相似度、聚类与数据划分、综合评价、分子生物学模拟和可视化，并可选用 DNA 基础模型提取 rep 后进行 k-means 聚类；不集成启动子活性、表达量、TF 结合强度或 CRISPR 编辑效率等任务型深度学习预测模型。
+
+# 安装与快速入门
+
+安装当前开发预览版：
+
+```bash
+pip install dnakit==0.1.0.dev0
+```
+
+如果需要参与开发，克隆仓库后通过 Conda 创建完整环境：
+
+```bash
+conda env create -f environment-dev.yml
+conda activate dnakit-dev
+```
+
+随后可以阅读 [Python 快速入门指南](https://github.com/mapengsen/DNAKit/blob/main/docs/quickstart.md)。
+
+更详细的依赖、可选后端和安装说明见 [安装文档](https://github.com/mapengsen/DNAKit/blob/main/docs/installation.md)。
+
+# 文档
+
+完整文档位于 [DNAKit 文档首页](https://github.com/mapengsen/DNAKit/blob/main/docs/index.md) 和仓库的 [`docs`](https://github.com/mapengsen/DNAKit/tree/main/docs) 目录。
+
+所有功能模块可在 [功能树总览](https://github.com/mapengsen/DNAKit/blob/main/docs/api/features/function_tree.md) 中查看，常见问题见 [FAQ](https://github.com/mapengsen/DNAKit/blob/main/docs/faq.md)。
+
+# 支持与社区
+
+如果有问题、意见或建议，可以先查看：
+
+- [常见问题](https://github.com/mapengsen/DNAKit/blob/main/docs/faq.md)
+- [贡献指南](https://github.com/mapengsen/DNAKit/blob/main/CONTRIBUTING.md)
+- [GitHub Issues](https://github.com/mapengsen/DNAKit/issues)
+
+如果发现缺陷或希望增加功能，请按照 [贡献指南](https://github.com/mapengsen/DNAKit/blob/main/CONTRIBUTING.md) 中的要求记录问题和复现信息。
+
+DNAKit 当前处于开发预览阶段，公开接口在正式版本发布前可能调整。

dnakit-0.1.0.dev0/README.md

@@ -0,0 +1,59 @@
+<p align="center">
+  <img alt="DNAKit logo" src="https://raw.githubusercontent.com/mapengsen/DNAKit/main/docs/assets/images/DNAKit-icon.png" width="40%">
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/dnakit/">
+    <img src="https://img.shields.io/pypi/v/dnakit?include_prereleases&amp;label=PyPI" alt="PyPI version">
+  </a>
+  <a href="https://github.com/mapengsen/DNAKit/actions/workflows/ci.yml">
+    <img src="https://github.com/mapengsen/DNAKit/actions/workflows/ci.yml/badge.svg" alt="CI status">
+  </a>
+  <a href="https://pypi.org/project/dnakit/">
+    <img src="https://img.shields.io/pypi/pyversions/dnakit" alt="Supported Python versions">
+  </a>
+  <a href="https://github.com/mapengsen/DNAKit/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/mapengsen/DNAKit" alt="MIT license">
+  </a>
+</p>
+
+# DNAKit 是什么？
+
+DNAKit 是面向 DNA 序列的可复现 Python 工具包，定位类似“DNA 领域的 RDKit”。它覆盖标准化、文件与注释格式、基础操作、描述符、模式扫描、热力学、指纹、相似度、聚类与数据划分、综合评价、分子生物学模拟和可视化，并可选用 DNA 基础模型提取 rep 后进行 k-means 聚类；不集成启动子活性、表达量、TF 结合强度或 CRISPR 编辑效率等任务型深度学习预测模型。
+
+# 安装与快速入门
+
+安装当前开发预览版：
+
+```bash
+pip install dnakit==0.1.0.dev0
+```
+
+如果需要参与开发，克隆仓库后通过 Conda 创建完整环境：
+
+```bash
+conda env create -f environment-dev.yml
+conda activate dnakit-dev
+```
+
+随后可以阅读 [Python 快速入门指南](https://github.com/mapengsen/DNAKit/blob/main/docs/quickstart.md)。
+
+更详细的依赖、可选后端和安装说明见 [安装文档](https://github.com/mapengsen/DNAKit/blob/main/docs/installation.md)。
+
+# 文档
+
+完整文档位于 [DNAKit 文档首页](https://github.com/mapengsen/DNAKit/blob/main/docs/index.md) 和仓库的 [`docs`](https://github.com/mapengsen/DNAKit/tree/main/docs) 目录。
+
+所有功能模块可在 [功能树总览](https://github.com/mapengsen/DNAKit/blob/main/docs/api/features/function_tree.md) 中查看，常见问题见 [FAQ](https://github.com/mapengsen/DNAKit/blob/main/docs/faq.md)。
+
+# 支持与社区
+
+如果有问题、意见或建议，可以先查看：
+
+- [常见问题](https://github.com/mapengsen/DNAKit/blob/main/docs/faq.md)
+- [贡献指南](https://github.com/mapengsen/DNAKit/blob/main/CONTRIBUTING.md)
+- [GitHub Issues](https://github.com/mapengsen/DNAKit/issues)
+
+如果发现缺陷或希望增加功能，请按照 [贡献指南](https://github.com/mapengsen/DNAKit/blob/main/CONTRIBUTING.md) 中的要求记录问题和复现信息。
+
+DNAKit 当前处于开发预览阶段，公开接口在正式版本发布前可能调整。

dnakit-0.1.0.dev0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,73 @@
+# DNAKit Third-Party Notices
+
+Last reviewed: 2026-08-23.
+
+This file is an engineering compliance inventory, not legal advice. DNAKit itself is licensed under MIT. A dependency, external executable, database, paper, or user-supplied parameter table keeps its own terms; citing a paper does not by itself grant permission to redistribute its software or data.
+
+## Distribution boundary
+
+The DNAKit wheel and sdist do **not** bundle DiProDB numerical tables, Primer3, NUPACK, DSSR/3DNA, Dashing, BLAST, MMseqs2, sourmash, REBASE, JASPAR, DNA foundation-model checkpoints, NCBI, Ensembl, ENA, ENCODE, UCSC, or their databases. External programs are never downloaded automatically. Public-data adapters access providers only when explicitly called. Where an executable adapter exists, the user must install the tool separately and provide an explicit executable or installation path. A model checkpoint is downloaded to the local `ckpt/` directory only when the user explicitly invokes the representation API; it is not redistributed in DNAKit artifacts.
+
+Python dependencies declared in `pyproject.toml` are resolved as separate distributions by the installer; their source code is not vendored into the DNAKit wheel. This inventory covers direct dependencies. Users and redistributors must also inspect resolved transitive dependencies for their actual environment and versions.
+
+## Direct Python dependencies
+
+| Scope | Component | License identifier or upstream label | DNAKit use |
+| --- | --- | --- | --- |
+| Runtime | PyYAML | MIT | YAML configuration |
+| Runtime | Rich | MIT | terminal rendering and progress |
+| Runtime | Typer | MIT | command-line interface |
+| Runtime, Python <3.11 | tomli | MIT | TOML parsing |
+| `viz` extra | CairoSVG | LGPL-3.0-or-later | optional SVG conversion |
+| `viz` extra | Pillow | MIT-CMU | optional raster export |
+| `io` extra | PyArrow | Apache-2.0 | optional Parquet I/O |
+| `validation` extra | Biopython | Biopython License Agreement | validation only |
+| `neural` extra | Hugging Face Hub, NumPy, scikit-learn, PyTorch, Transformers | Apache-2.0, BSD-family, and Apache-2.0 labels; verify resolved versions | checkpoint retrieval, inference, and k-means |
+| `neural-caduceus` extra | mamba-ssm | Apache-2.0 label; verify resolved version | optional Caduceus runtime |
+| `neural-enformer` extra | enformer-pytorch | MIT label; verify resolved version | optional Enformer runtime |
+| `neural-evo2` extra | evo2 and transitive dependencies | verify the installed version and official repository | optional Evo 2 runtime |
+| `docs` extra | MkDocs | BSD-2-Clause | documentation build |
+| `docs` extra | Material for MkDocs | MIT | documentation theme |
+| `docs` extra | mkdocstrings | ISC | API documentation |
+| `docs` extra | nbmake | Apache-2.0 | notebook test gate |
+| `dev` extra | build | MIT | local package build |
+| `dev` extra | Hypothesis | MPL-2.0 | tests |
+| `dev` extra | mypy | MIT | type checking |
+| `dev` extra | pytest | MIT | tests |
+| `dev` extra | pytest-cov | MIT | coverage |
+| `dev` extra | Ruff | MIT | lint and formatting |
+| `dev` extra | twine | Apache-2.0 | local distribution checks |
+| `dev` extra | types-PyYAML | Apache-2.0 | type stubs |
+
+Exact versions and license texts must be checked in the distributions actually installed. Useful upstream locations include [PyPI](https://pypi.org/), [Biopython licensing](https://biopython.org/DIST/docs/LICENSE), and each project repository.
+
+## User-installed tools and supplied data
+
+| Resource | DNAKit integration and distribution | Terms/cost warning |
+| --- | --- | --- |
+| Primer3 CLI (`primer3_core`, `oligotm`, `ntthal`) | Pure external CLI adapter; explicit paths; no Python binding and no bundled binary | Primer3 source files state GPL-2.0-or-later; verify the installed release and comply with its license. See the [official repository](https://github.com/primer3-org/primer3) and [manual](https://github.com/primer3-org/primer3/blob/main/src/primer3_manual.htm). |
+| NUPACK | User installs separately; DNAKit does not download, bundle, or expose it as a hosted service | Separate NUPACK terms/subscription apply and access may require payment. Academic and commercial terms differ. Check the [official download and licensing page](https://www.nupack.org/download/overview) before use. |
+| DSSR/3DNA | User installs separately; DNAKit only parses explicitly supplied output | Academic and commercial permissions differ; free academic availability is still subject to the issued license. Check the [official DSSR licensing notice](https://home.x3dna.org/highlights/x3dna-dssr-is-funded-and-dssr-basic-academic-is-free). |
+| Dashing | User supplies an explicit executable; no binary/source is included in distributions | GPL-3.0; verify the installed version in the [official repository](https://github.com/dnbaker/dashing). |
+| DiProDB-derived or other dinucleotide tables | DNAKit supplies only a JSON schema and loader. It contains no DiProDB numerical values. | No redistribution permission for the public table has been assumed. The user must obtain or create a table they are entitled to use and cite its actual source. See [DiProDB](https://diprodb.fli-leibniz.de/). |
+| BLAST, MMseqs2, sourmash and external databases | Not installed or bundled; registered capabilities are conditional and version-specific | Verify each program and database license separately. Database access does not imply redistribution rights. |
+| NCBI, Ensembl, ENA, ENCODE and UCSC public services/data | Queried or downloaded only on explicit user calls; source URLs and checksums are recorded; no remote dataset is embedded in distributions | Check provider usage, attribution, privacy, controlled-access and redistribution terms. dbGaP and other controlled data still require formal authorization. |
+| Hugging Face DNA-model checkpoints | Downloaded into `ckpt/` after explicit model selection with a source manifest; weights are not bundled in wheel/sdist | DNABERT-2, NTv2, HyenaDNA, Caduceus, GROVER, LucaOne, GENERator, Enformer, and Evo 2 may have different terms. Review the official links on the [clustering feature page](docs/api/features/10_clustering.md#data-027-neural-clustering). |
+| AlphaGenome | Loaded only after the user accepts access terms, obtains the checkpoint, and installs the official research code | The checkpoint is gated and carries non-commercial model terms. Review the [official repository](https://github.com/google-deepmind/alphagenome_research) and current model page. |
+| JanusDNA | Official Harvard Dataverse file is downloaded with MD5 verification; the user must also supply the official source environment | Review the [official repository](https://github.com/Qihao-Duan/JanusDNA), [Dataverse DOI](https://doi.org/10.7910/DVN/HDT0RN), and applicable code/data terms. |
+
+The DNABERT-2, NTv2, HyenaDNA, Caduceus, LucaOne, and GENERator Transformers
+checkpoints include Python code required by their loaders. DNAKit rejects that execution by
+default. It is enabled only after the user reviews the source and explicitly sets
+`allow_remote_code=True`. This opt-in does not replace a code audit, dependency lock, or
+license review.
+
+Keeping a tool in a separate process or asking the user to install it reduces bundling and automatic-distribution risk, but it is not a legal conclusion that every intended use is permitted. Commercial deployment, hosted services, redistribution, or journal supplementary archives require a new review of the exact artifacts being distributed.
+
+## Scientific attribution
+
+Methods, papers, databases, and websites used as scientific foundations are listed in `docs/acknowledgements.md`. Those citations document provenance; they do not replace software/data licenses. Runtime provenance should record the actual tool/table name, version, source, parameters, and checksum.
+
+## No assurance of zero cost or zero risk
+
+DNAKit does not promise that any optional tool, database, or future version is free of charge. Terms, availability, and fees can change. Before each release, archive, hosted deployment, or commercial use, repeat the dependency and artifact audit and retain copies of the applicable license texts.

dnakit-0.1.0.dev0/benchmarks/README.md

@@ -0,0 +1,18 @@
+# DNAKit 本地性能基准
+
+`benchmark_core.py` 测量原生核心操作的耗时和 Python 分配器峰值内存。报告包含完整参数、随机种子、输入摘要、Python/DNAKit/Rich 版本与平台信息。
+
+结果只适用于当前机器与软件环境，不是跨机器性能声明。`tracemalloc` 不统计所有原生库内存。脚本有输入长度、重复次数、预热次数、案例数和总工作量硬上限，默认拒绝覆盖已有报告。
+
+示例：
+
+```bash
+python -m benchmarks.benchmark_core \
+  --sizes 100,1000,10000 \
+  --repeats 3 \
+  --warmups 1 \
+  --seed 20260813 \
+  --tasks construct,normalize,gc_content,kmer_fingerprint,minhash,subsequence_search \
+  --output benchmarks/results/local_benchmark_report.json
+```
+

dnakit-0.1.0.dev0/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Local, bounded DNAKit benchmark utilities."""