gside 0.1.1__tar.gz

gside-0.1.1/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

gside-0.1.1/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install mkdocs mkdocs-material mkdocs-static-i18n
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

gside-0.1.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,64 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gside
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Verify version consistency
+      run: |
+        PYPROJECT_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+        TAG_VERSION="${GITHUB_REF_NAME#v}"
+        echo "pyproject.toml: $PYPROJECT_VERSION"
+        echo "git tag: $TAG_VERSION"
+        if [ "$PYPROJECT_VERSION" != "$TAG_VERSION" ]; then
+          echo "ERROR: pyproject.toml ($PYPROJECT_VERSION) != git tag ($TAG_VERSION)"
+          exit 1
+        fi
+        echo "Versions match: $TAG_VERSION"
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.12'
+
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build package
+      run: python -m build
+
+    - name: Check package
+      run: twine check dist/*
+
+    - name: Verify wheel version and bundled marker tier
+      run: |
+        python -c "
+        import zipfile, glob
+        whl = glob.glob('dist/*.whl')[0]
+        with zipfile.ZipFile(whl) as z:
+            names = z.namelist()
+            meta = next(n for n in names if n.endswith('METADATA'))
+            version = [l for l in z.read(meta).decode().splitlines() if l.startswith('Version:')][0].split(': ')[1]
+            assert version == '${GITHUB_REF_NAME#v}', f'wheel version {version} != tag'
+            for asset in ('marker_rules.yaml', 'markers.fasta', 'markers_blastdb.nhr'):
+                assert any(n.endswith(f'gside/data/db/D1_marker/{asset}') for n in names), f'{asset} missing from wheel'
+        print('wheel OK: version', version, '+ bundled marker tier')
+        "
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      # No API token needed when using trusted publishing

gside-0.1.1/.github/workflows/test.yml

@@ -0,0 +1,56 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/
+          ruff format --check src/ tests/
+
+      - name: Type check with pyright
+        run: |
+          pyright src/gside/
+
+      - name: Test with pytest (coverage)
+        run: |
+          pytest -q --cov=src/gside --cov-report=term-missing --cov-fail-under=95
+
+  pixi:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v5
+
+    - uses: prefix-dev/setup-pixi@v0.9.5
+
+    - name: Install pixi environments
+      run: pixi install --all
+
+    - name: Lint and format check
+      run: pixi run -e dev check
+
+    - name: Type check
+      run: pixi run -e dev typecheck
+
+    - name: Run tests
+      run: pixi run -e dev pytest tests/ -q --cov=src/gside --cov-report=term-missing

gside-0.1.1/.gitignore

@@ -0,0 +1,29 @@
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+# Large reference databases (not in git — use `gside db setup`)
+# D2_ani contents are ignored except the manifests/ build recipe.
+data/db/D2_ani/*
+!data/db/D2_ani/manifests/
+data/db/D3_mash/
+data/db/D4_sourmash/
+site/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# Test & lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+
+# OS
+.DS_Store
+Thumbs.db

gside-0.1.1/AGENTS.md

@@ -0,0 +1,264 @@
+# AGENTS.md
+
+Agent guidance for this repository. Read this before writing or editing any code.
+
+---
+
+## Project Overview
+
+- **Language**: Python 3.12 (standalone species-identification CLI, no frontend)
+- **Package manager**: [pixi](https://pixi.sh) — conda tools (blast/skani/mash/mmseqs2) + PyPI editable install via `pixi.toml`
+- **Linter + Formatter**: [ruff](https://docs.astral.sh/ruff/) (config in `pyproject.toml`; run via pip-installed dev extras, no pixi task)
+- **Testing**: pytest (`tests/`; single file `tests/unit/test_cli.py`, needs real `blastn`)
+- **Docs**: MkDocs Material + static-i18n, English default + Chinese secondary (`docs/*.md` + `*.zh.md` pairs)
+
+---
+
+## Environment Setup
+
+```bash
+# Install pixi (if not already installed)
+curl -fsSL https://pixi.sh/install.sh | bash
+
+# Install conda tools + editable package
+pixi install
+pip install -e .
+
+# Optional docs extras (dev environment)
+pip install -e .[dev]
+```
+
+Bioinformatics binaries come from the pixi `default` env; the Python package is
+pip-installed (editable). `pip install -e .[dev]` adds pytest/ruff/mypy/mkdocs.
+
+---
+
+## Build / Run Commands
+
+```bash
+# Species identification (5 modes, default marker)
+pixi run -e dev python -m gside species contigs.fna --mode marker
+pixi run -e dev python -m gside species contigs.fna --mode all
+
+# Database management
+pixi run -e dev python -m gside db status
+pixi run -e dev python -m gside db setup --tier panel   # panel (default) | mash | mini | all
+
+# After pip install -e ., the console script is also available
+gside species contigs.fna --mode panel
+gside --version
+```
+
+Check `pixi.toml` for the canonical task definitions — only `docs` / `docs-build`
+exist as pixi tasks; everything else runs via `python -m` or the `gside` script.
+
+---
+
+## Lint / Format Commands
+
+```bash
+# No pixi tasks exist for lint; use the pip-installed ruff from .[dev]
+python -m ruff check src/ tests/
+python -m ruff format --check src/ tests/
+python -m ruff format src/ tests/
+```
+
+Config: `pyproject.toml` (`target-version = "py312"`, `line-length = 100`).
+**Always run ruff before committing.** Fix all lint errors; do not use `# noqa`
+suppression unless unavoidable, and always add a comment explaining why.
+
+---
+
+## Testing Commands
+
+```bash
+# Run all tests (dev env now ships pytest + pytest-cov)
+pixi run -e dev pytest tests/ -q
+
+# Run with verbose output
+pixi run -e dev pytest tests/ -v
+
+# Unit tests only (pure logic, no binaries/databases — always fast)
+pixi run -e dev pytest tests/unit -q
+
+# Integration tests (need blastn/skani/mash + databases)
+pixi run -e dev pytest tests/integration -q
+
+# With coverage (ratchet: must not drop below the committed floor)
+pixi run -e dev pytest tests/ -q --cov=src/gside --cov-report=term-missing
+```
+
+Layout: `tests/unit/` = pure, hermetic, milliseconds; `tests/integration/` =
+needs real binaries or databases (gated by `skipif`, never mock a binary —
+either run it or skip). `TestSpeciesMarker` needs `blastn` resolvable via
+`GSIDE_PIXI_BIN` or pixi env (discovery order: `src/gside/config.py`).
+CI (`.github/workflows/test.yml`, pip channel): ruff check + format --check,
+`pyright src/gside/` (must stay zero), `pytest -q --cov=src/gside`.
+Binary-needing tests skip gracefully without conda tools; full runs happen
+in the pixi dev env locally.
+Baseline (2026-10-03): 365 tests, total coverage **97%** — all modules 100%
+except: ani 93%, multigene 98%, taxonomic 93% (quarantined), cli 99%,
+db 92%, kma 94%, kmer 99%, read_mapper 99%. Enforced by `[tool.coverage.report] fail_under = 95` in `pyproject.toml`;
+raise it every time coverage climbs.
+
+---
+
+## Test-Driven Development (TDD)
+
+TDD is mandatory for all behavior changes and bug fixes. No exceptions.
+
+### The loop
+
+1. **Red** — write a failing test FIRST that pins the desired behavior
+   (unit test if the logic is pure, integration test if it needs a binary/DB).
+   Run it, watch it fail for the right reason.
+2. **Green** — write the minimal implementation that makes it pass.
+3. **Refactor** — clean up with tests green; re-run the full suite + ruff.
+
+### Rules
+
+- **One behavior per test** — a test name states the behavior
+  (`test_ani_beats_marker`, not `test_arbitrate2`).
+- **New/changed code ships with tests.** A PR without a covering test is
+  incomplete: pure helpers → `tests/unit/`; binary/DB paths →
+  `tests/integration/` with `skipif` guards, never mocked binaries.
+- **Bug fix = regression test first.** Reproduce with a failing test, then fix.
+- **Coverage ratchet.** Canonical command is `pixi run -e dev cov` (explicit
+  `--cov-fail-under`). The `fail_under` value in `pyproject.toml` IS enforced
+  by pytest-cov whenever `--cov` runs without an explicit flag value, so the
+  config and the flags must stay equal. CI checkouts lack the gitignored
+  databases, so the CI ceiling sits ~1pt below local (CI ~96% vs local 97%)
+  — the floor is 95 to hold in BOTH environments; local coverage must still
+  never go below its last high-water mark. Raise the floor in `pyproject.toml`,
+  the `cov` task, the CI workflow, and this file together — `test_floors_agree`
+  fails otherwise. Capture exit codes **without pipes** (`cmd > log; echo $?`),
+  pipes mask them.
+- **Deterministic tests only.** No network, no wall-clock, no absolute paths
+  outside the repo (use `tmp_path` + `monkeypatch`). Real binaries are fine;
+  the network is not.
+- **Fast unit suite.** `tests/unit` must finish in seconds; anything slower
+  belongs in `tests/integration`.
+
+---
+
+## Code Style Guidelines
+
+### Formatting
+- Line length: **100 characters** (see `pyproject.toml`; not the ruff default 88)
+- Indentation: **4 spaces** (never tabs)
+- String quotes: **double quotes** (`"..."`)
+- Keep functions small; JSON payloads are built as plain dicts
+
+### Imports
+- Use **absolute imports** only (`from gside.config import ...`); no relative imports
+- Import order: stdlib → third-party → local (ruff isort-compatible)
+- No wildcard imports (`from module import *`)
+
+### Naming Conventions
+| Construct | Convention | Example |
+|---|---|---|
+| Module/file | `snake_case` | `multigene_identifier.py` |
+| Function | `snake_case` | `identify_multigene()` |
+| Variable | `snake_case` | `db_dir` |
+| Class | `PascalCase` | `MultiGeneResult` |
+| Constant | `UPPER_SNAKE_CASE` | `_MIN_IDENTITY` |
+| Private | leading underscore | `_arbitrate()` |
+
+### Type Annotations
+- **Always annotate** function signatures (parameters + return type)
+- Use built-in generics (`list[str]`, `dict[str, Any]`) over `typing.List` / `typing.Dict`
+- Use `X | Y` union syntax over `Union[X, Y]`
+
+### Error Handling
+- `gside species` **always exits 0** — per-method failures go into
+  `methods.<mode>.error`, never raise through the CLI
+- `gside db setup` returns 1 only when a result message contains `"ERROR"`
+- Never silence exceptions with empty `except` blocks
+- Prefer `pathlib.Path` over `os.path` for filesystem operations
+
+### CLI Patterns
+- Click group style (mirrors gmlst/gapit family): `HELP_SETTINGS` (`-h`/`--help`), bare invocation prints help and exits 2 (`no_args_is_help`), `-v`/`-q` mutually exclusive (UsageError), thin commands registered via `add_command`
+- Every option carries a short flag: species `-m/--mode -f/--format -D/--db-dir -o/--output`; db `-t/--tier -s/--source -f/--format`
+- Agent-friendly outputs: species defaults to JSON on stdout; `-o` writes the payload to a file (stdout stays empty, notice on stderr); `db status|list` accept `--format table|tsv|json`; `db setup` accepts `--format text|json` (json routes progress to stderr); `-V -J` prints version as JSON
+- Subcommands: `species` / `db` group (`status|setup|list`) / `validate` / `--version`; entry `gside.cli:main`
+- `--mode` choices are exactly `marker|panel|mash_refseq|sourmash|all` — do not invent modes
+- `--db-dir` overrides the database root for one invocation
+
+### File & Module Organization
+```
+src/gside/
+├── __init__.py
+├── cli.py                    # Entry point; all-mode runner + _arbitrate()
+├── config.py                 # DATA_DIR / SPECIES_DB_DIR / pixi binary discovery
+├── db.py                     # gside db status/setup/list + downloaders
+├── engine/                   # Algorithm abstraction (mostly unused, see gotchas)
+│   ├── hits.py               #   Unified Hit dataclass
+│   ├── registry.py           #   Backend registry
+│   ├── read_mapper.py        #   ReadMapper facade
+│   └── backends/             #   blast / skani / kmer / minimap2 / kma / mmseqs2
+└── analysis/
+    ├── multigene_identifier.py   # L1 marker rules (blastn, live)
+    ├── ani_identifier.py         # L2 panel/mash (live)
+    ├── sourmash_identifier.py    # L2 sourmash (needs external binary + GTDB db)
+    ├── taxonomic_validator.py    # L3 (gside validate; standard needs CheckM2/GTDB-Tk env)
+    └── species_canon.py          # DORMANT (no importers)
+tests/
+└── unit/
+    └── test_cli.py           # Real-BLAST smoke + arbitration unit tests
+data/
+├── db/
+│   ├── D1_marker/            # mini tier, TRACKED in git: rules + fasta + blastdb
+│   ├── D2_ani/               # panel tier (skani sketch + genomes), gitignored
+│   │                         # except manifests/ (tracked build recipe)
+│   ├── D3_mash/              # mash tier (mash.msh), gitignored
+│   └── D4_sourmash/          # GTDB reps k31 + lineages, via db setup (3.9GB)
+docs/
+├── index.md / index.zh.md    # + architecture|installation|usage|reference/, same pairing
+└── (nav in mkdocs.yml; en default, zh secondary; build with --strict)
+```
+
+- Keep modules focused and small; no circular imports
+- L1 runtime data lives in `data/db/D1_marker/` (tracked); large L2 databases are
+  gitignored and provisioned via `gside db setup`
+
+---
+
+## pyproject.toml Conventions
+
+```toml
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+```
+
+---
+
+## Key Rules for Agents
+
+1. **Run `pixi run -e dev check` after every code change** (ruff check + format check; `fix` to auto-fix)
+2. **Never use `# type: ignore` or `# noqa` without an explanatory comment**
+3. **Never commit secrets** — tunables go into `marker_rules.yaml` / env vars, not code
+4. **Prefer `pathlib.Path` over `os.path`** for all filesystem operations
+5. **All functions must have type annotations** — no untyped signatures
+6. **One responsibility per module** — don't let files grow into god-modules
+7. **Don't add conda deps without updating `pixi.toml`** — use `pixi add <pkg>`; PyPI-only packages belong in `[feature.dev.pypi-dependencies]`, never in `[dependencies]` (conda channels don't carry them, e.g. `mkdocs-static-i18n`)
+8. **Do not rename `species_markers_v2`** — it is the JSON output contract name (`database.name`), not a filename
+9. **Do not wire up `species_canon.py`** — dormant with no importers; touching it is a separate project (`taxonomic_validator.py` is wired via `gside validate` since Cycle 19)
+10. **Docs come in en/zh pairs** — every `docs/**/*.md` change needs the matching `.zh.md` update, and `mkdocs build --strict` must pass
+11. **TDD is non-negotiable** — failing test first, then implementation; every new line covered; coverage never goes down (see TDD section)
+12. **Keep `pyright` at zero and CI green** — `pixi run -e dev typecheck` must report 0 errors (quarantined files are excluded in `pyproject.toml`, not waived); `.github/workflows/test.yml` must pass before merge
+
+## Known Gotchas (read before touching these areas)
+
+- **Binary discovery**: `GSIDE_PIXI_BIN` env → repo `.pixi` → `~/.pixi` → hardcoded hermes-bacmap fallback path → `PATH` (`config.py`). The hardcoded path is machine-specific; prefer `GSIDE_PIXI_BIN` on other machines.
+- **`gside species` never fails loud**: check `methods.<mode>.error` in JSON, not the exit code.
+- **Marker thresholds are global**: `_MIN_IDENTITY=85.0` / `_MIN_COVERAGE=60.0` / `_HIGH_CONF=90.0`; rule-level `min_coverage` in YAML is currently **ignored** by the engine; `priority_over` is dead code.
+- **Panel thresholds**: ANI ≥ 95 + AF ≥ 0.65 → high; 93–95 → medium. Mash identity ≥ 0.97 → high, 0.90–0.97 → medium.
+- **Arbitration is layer-first**: `(layer, confidence)` tuple — any L2 hit beats any L1 hit (`cli.py:_arbitrate`).
+- **`sourmash` needs its GTDB db**: provisioned via pixi (`sourmash>=4.9`) + `gside db setup --tier sourmash` (~3.9GB rs226 reps, renamed in place); `gather` output is read from `-o` file, never `--csv -` (unsupported flag).
+- **DB download verification**: `db.py` pins digests (`MASH_MD5`, `PANEL_SHA256`, `SOURMASH_LINEAGES_SHA256`); empty constants (`SOURMASH_SIG_SHA256`) mean warn-and-skip. Tar extraction uses `filter="data"`. All pinned artifacts live in the GitHub release tag `db-v0.1` (panel) — re-pin `PANEL_SHA256` whenever the release asset is replaced.
+- **`engine/` is wired for the species-ID hot paths**: marker → `BlastBackend`, panel → `SkaniBackend`, mash_refseq → `MashBackend` (analysis layer resolves binaries via `require_bin` and injects them with `binary=`; outputs are byte-equivalent to the former inline subprocess calls). Shared scaffolding lives in `engine/_env.py` (`require_bin`/`run_checked`; backends pass their module-level `which` as `resolver=` to keep test monkeypatch points). Still unconsumed: `KmaBackend`, `Mmseqs2Backend`, `MinimapBackend`, `ReadMapper`, `SequenceMatcher` — `KmaBackend` imports cleanly (`parse_db_header` ported verbatim into `gside/utils.py`) but has no in-repo callers and no provisioned binary.
+- **FASTA header contract**: `>markers~~~<gene>~~~<desc> role=<primary|confirm|typing|virulence>`; parser takes `split("~~~")[1]` — the `markers` prefix itself is never validated.

gside-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Renton
+
+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.

gside-0.1.1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: gside
+Version: 0.1.1
+Summary: Genome Species IDentification Engine — multi-layer species identification CLI (marker genes / ANI / sketch / consensus)
+Author-email: indexofire <indexofire@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <3.13,>=3.12
+Requires-Dist: biopython>=1.83
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
+Requires-Dist: mkdocs-static-i18n>=1.2; extra == 'dev'
+Requires-Dist: mkdocs>=1.6; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gside（Genome Species IDentification Engine）
+
+独立自包含的基因组物种鉴定 CLI：blastn 靶基因组合规则打底，skani / mash / sourmash
+三路比对补充，`all` 模式按层仲裁，最终输出单一 JSON 判定。
+
+## 鉴定模式
+
+| mode | 底层引擎 | 原理 |
+|---|---|---|
+| `marker`（默认） | blastn | 靶基因组合规则（38 条规则，81 条参考序列） |
+| `panel` | skani | ANI 比对精选参考面板（291 基因组） |
+| `mash_refseq` | mash | RefSeq MinHash 距离 |
+| `sourmash` | sourmash | GTDB gather |
+| `all` | 上述全部 | 顺序执行 4 种方法并按层仲裁 |
+
+## 快速开始
+
+```bash
+pixi install && pip install -e .
+
+# 物种鉴定（--mode 可选 marker/panel/mash_refseq/sourmash/all，默认 marker）
+gside species contigs.fna --mode marker
+gside species contigs.fna --mode panel
+gside species contigs.fna --mode mash_refseq
+gside species contigs.fna --mode sourmash
+gside species contigs.fna --mode all
+
+# 数据库管理（panel/mash/sourmash 需先下载对应库）
+gside db status
+gside db setup --tier panel
+
+gside --version
+```
+
+## 判定阈值
+
+- marker：命中需同时满足 identity >= 85% 且 coverage >= 60%（全局阈值，逐 hit 过滤）；
+  规则字段 `min_hits`（默认 1）、`min_identity`（默认 90）；命中基因平均
+  identity >= 90% 判 high，否则 medium。
+- panel：ANI >= 95% 且 aligned_fraction >= 0.65 判 high；93% <= ANI < 95% 且
+  aligned_fraction >= 0.65 判 medium。
+- mash_refseq：identity >= 0.97 判 high；0.90 <= identity < 0.97 判 medium，更低为 low。
+
+## 仲裁（all 模式）
+
+按 marker、panel、mash_refseq、sourmash 顺序执行，随后仲裁：
+
+- panel / mash_refseq / sourmash 为第 2 层，marker 为第 1 层，层高者优先
+- 层优先于置信度，同层内 high 优先
+- 单法失败不终止其余方法，错误写入该方法在 JSON 中的条目
+
+## 数据目录
+
+| 变量 | 默认 | 内容 |
+|---|---|---|
+| `GSIDE_DATA_DIR` | `<repo>/data` | 参考数据根目录（规则、fasta、预建库） |
+| `GSIDE_DB_DIR` | `<data>/db` | 大型数据库（panel / mash sketch 等） |
+| `GSIDE_PIXI_BIN` | 自动发现 | 生信二进制目录（blastn / skani / mash） |
+
+数据分层：
+
+- mini：随仓库分发，含 marker_rules.yaml（38 条规则）、markers.fasta（81 序列）
+  与预建 BLAST 库，开箱即用
+- panel：skani 精选面板 sketch，约 130MB
+- mash：RefSeq MinHash sketch，约 179MB
+
+## 自定义规则
+
+编辑 `data/db/D1_marker/marker_rules.yaml`，字段为 `species` / `genes` /
+`min_hits` / `min_identity` / `exclude_genes`。修改 fasta 后重建 BLAST 库即生效，
+无需改代码：
+
+```bash
+makeblastdb -in markers.fasta -dbtype nucl -out markers_blastdb
+```
+
+## 输出
+
+统一 JSON 输出（stdout）。顶层字段：`analysis_type` / `tool` / `version` /
+`contigs` / `methods` / `verdict`。`methods` 内 panel、mash_refseq、sourmash 为
+`result` 嵌套结构，marker 为扁平结构（无 `result` key）。`gside species` 恒以
+退出码 0 结束，单法错误写入 JSON，不影响其余方法。
+
+## 验证状态
+
+- marker 法 17/17 金标准基因组（含 10 株近缘阴性对照）
+- 3/3 新增物种真实参考株（C. jejuni / C. coli / S. pyogenes）
+- panel 法 17/17（291 基因组精选面板）
+
+## License
+
+MIT