Seqeron

A bioinformatics toolkit for .NET 10 that you can drive in plain English.

Seqeron is a from-scratch genomics library — 250+ algorithms, from GC-content to CRISPR guide design — with a twist: you don't have to write code or pick tools. Describe a biology task in plain language, and a set of AI agent skills chains the real, validated algorithms for you. Every number is computed by the library, never guessed — and carries its own provenance.

Prefer code? The same algorithms are a normal C# API. Prefer your own agent? They're also exposed as MCP tools. One engine, three front doors.

🧪 Beta — research-grade software, not for clinical or diagnostic use. Seqeron is feature-complete with a stabilizing public API on the road to 1.0, and every algorithm unit has been validated internally against primary literature and reference tools. It has not had an external audit or regulatory clearance. Independently verify outputs before you rely on them, and never use them for clinical or diagnostic decisions. Full status & limitations →

Why Seqeron

Bioinformatics is entering the agentic era, but most scientific libraries still stop at functions. Seqeron is built for the next interface: intent. Describe the biological outcome; an LLM can discover, compose, and execute the right algorithms as a grounded workflow — without becoming the calculator or drowning in schemas.

What you gain	Why it matters
🤖 LLM-native and context-smart	21 skills discover and chain 427 strict-schema tools on demand, without loading the whole catalog into context. You state the biology; Seqeron handles tools, order, parameters, units, coordinates, and provenance.
⚙️ Executable answers, not plausible prose	The LLM orchestrates; Seqeron computes. Alignments, variants, trees, structures, scores, and primer properties come from tested code — never model arithmetic.
🧭 One question, an end-to-end workflow	Move from parsing and QC through alignment, assembly, annotation, RNA, oncology, or assay design. More than 250 algorithms share models and conventions instead of behaving like unrelated utilities.
🔁 Conversation today, production code tomorrow	Skills, MCP tools, and C# reach the same implementations. Explore interactively, then embed the pipeline without rewriting the biology.
🔬 Modern rigor, visible limits	Completed units carry literature-traced parameters, tests, and validation evidence. Boundaries are documented, guarded where detectable, and agent workflows expose how each result was produced.
🏠 Local-first and agent-portable	MCP runs locally over stdio, so data need not leave the machine. Use Claude Code, Copilot, Codex, another MCP client, or no LLM at all.
⚡ A modern engine underneath	.NET 10, NativeAOT-ready executables, Ukkonen search, reusable on-disk indexes, structured results, and 22,000+ tests across ten methodologies.

Seqeron is not a genomics library with an AI wrapper. It is a bioinformatics engine for people and agents: broad enough for real workflows, structured enough to automate, transparent enough to audit, and direct enough to use in one prompt.

Quick start

Prerequisites: the .NET 10 SDK and Python 3.8+ (used by the wiki and validation tooling). NativeAOT publishing additionally needs the C++ build tools — see Performance & NativeAOT.

Clone the repo, open it in Claude Code (or GitHub Copilot / VS Code), and just ask:

install and configure

That triggers the seqeron-setup skill, which checks your toolchain (.NET 10 SDK + Python 3), builds all 11 MCP servers into an on-demand cache, and runs a live smoke test. Or do the same directly:

scripts/setup.sh          # build everything + verify the on-demand tool path

scripts/setup.sh is a Bash script — on Windows run it from Git Bash or WSL, or just use the install and configure skill, which works from any shell. Setup is a one-time step per clone and is idempotent — re-run it any time a build looks stale. Then describe a biology task in plain language and let the skills do the rest.

See it work: an rpoB rifampicin-resistance variant triage

You hand the assistant two 753 bp fragments of the Mycobacterium tuberculosis rpoB gene, which encodes the RNA polymerase β subunit — the molecular target of rifampicin. The reference fragment is taken verbatim from NCBI RefSeq: the M. tuberculosis H37Rv genome NC_000962.3, positions 760,854–761,606 (1-based inclusive) — i.e. rpoB (locus Rv0667) codons 350–600. That fully spans the 81 bp rifampicin resistance-determining region (RRDR), codons 426–452, with hundreds of base pairs of flanking sequence on either side. The second record is an in-silico isolate derived from that fragment by introducing a single Ser450Leu (TCG→TTG) substitution, which WHO classifies as "1) Associated with resistance" — its highest-confidence mutation category — and which is the most frequently observed resistance-associated rpoB variant in the WHO 2023 catalogue, 2nd ed. dataset (in the older E. coli numbering, the well-known Ser531Leu). The changed base is at 0-based offset 301 (1-based position 302), leaving 301 bp upstream and 451 bp downstream — ample real genomic context on both sides for primer design, with no synthetic padding.

The two FASTA records — 753 bp each (click to expand / copy-paste)

Source. The nucleotide sequence in the reference record below is the exact subsequence returned by NCBI E-utilities, with no nucleotide edits; only the FASTA header has been rewritten to make the example self-describing. Re-fetch and diff the sequence:

curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=nuccore&id=NC_000962.3&rettype=fasta&retmode=text&seq_start=760854&seq_stop=761606"

>rpoB_350_600_reference   NC_000962.3:760854-761606 (1-based incl.)  M. tuberculosis H37Rv, rpoB codons 350-600
ACCGTTCCGGGCGGCGTCGAGGTGCCGGTGGAAACCGACGACATCGACCACTTCGGCAACCGCCGCCTGC
GTACGGTCGGCGAGCTGATCCAAAACCAGATCCGGGTCGGCATGTCGCGGATGGAGCGGGTGGTCCGGGA
GCGGATGACCACCCAGGACGTGGAGGCGATCACACCGCAGACGTTGATCAACATCCGGCCGGTGGTCGCC
GCGATCAAGGAGTTCTTCGGCACCAGCCAGCTGAGCCAATTCATGGACCAGAACAACCCGCTGTCGGGGT
TGACCCACAAGCGCCGACTGTCGGCGCTGGGGCCCGGCGGTCTGTCACGTGAGCGTGCCGGGCTGGAGGT
CCGCGACGTGCACCCGTCGCACTACGGCCGGATGTGCCCGATCGAAACCCCTGAGGGGCCCAACATCGGT
CTGATCGGCTCGCTGTCGGTGTACGCGCGGGTCAACCCGTTCGGGTTCATCGAAACGCCGTACCGCAAGG
TGGTCGACGGCGTGGTTAGCGACGAGATCGTGTACCTGACCGCCGACGAGGAGGACCGCCACGTGGTGGC
ACAGGCCAATTCGCCGATCGATGCGGACGGTCGCTTCGTCGAGCCGCGCGTGCTGGTCCGCCGCAAGGCG
GGCGAGGTGGAGTACGTGCCCTCGTCTGAGGTGGACTACATGGACGTCTCGCCCCGCCAGATGGTGTCGG
TGGCCACCGCGATGATTCCCTTCCTGGAGCACGACGACGCCAACCGTGCCCTC
>rpoB_350_600_isolate     same fragment carrying the S450L (rpoB c.1349C>T) rifampicin-resistance substitution
ACCGTTCCGGGCGGCGTCGAGGTGCCGGTGGAAACCGACGACATCGACCACTTCGGCAACCGCCGCCTGC
GTACGGTCGGCGAGCTGATCCAAAACCAGATCCGGGTCGGCATGTCGCGGATGGAGCGGGTGGTCCGGGA
GCGGATGACCACCCAGGACGTGGAGGCGATCACACCGCAGACGTTGATCAACATCCGGCCGGTGGTCGCC
GCGATCAAGGAGTTCTTCGGCACCAGCCAGCTGAGCCAATTCATGGACCAGAACAACCCGCTGTCGGGGT
TGACCCACAAGCGCCGACTGTTGGCGCTGGGGCCCGGCGGTCTGTCACGTGAGCGTGCCGGGCTGGAGGT
CCGCGACGTGCACCCGTCGCACTACGGCCGGATGTGCCCGATCGAAACCCCTGAGGGGCCCAACATCGGT
CTGATCGGCTCGCTGTCGGTGTACGCGCGGGTCAACCCGTTCGGGTTCATCGAAACGCCGTACCGCAAGG
TGGTCGACGGCGTGGTTAGCGACGAGATCGTGTACCTGACCGCCGACGAGGAGGACCGCCACGTGGTGGC
ACAGGCCAATTCGCCGATCGATGCGGACGGTCGCTTCGTCGAGCCGCGCGTGCTGGTCCGCCGCAAGGCG
GGCGAGGTGGAGTACGTGCCCTCGTCTGAGGTGGACTACATGGACGTCTCGCCCCGCCAGATGGTGTCGG
TGGCCACCGCGATGATTCCCTTCCTGGAGCACGACGACGCCAACCGTGCCCTC

Then ask — in the kind of plain language the skill layer is built for. You don't spell out coordinate systems, output formats or primer parameters; the assistant picks sensible ones and shows its working:

"Compare these two rpoB fragments — the first is the M. tuberculosis H37Rv reference (NC_000962.3), the second an in-silico isolate — and characterize the isolate's mutation at the DNA and protein levels, using NC_000962.3 and the H37Rv rpoB annotation for coordinates. Check whether it is an established rifampicin-resistance-associated variant, and cite the source.

Then design a suitable PCR amplicon for confirming the mutation by bidirectional Sanger sequencing. Report the selected primers, their main design metrics, the expected product and any specificity limitations.

The second sequence was generated in silico, so don't imply its resistance phenotype was experimentally measured."

Even from that short ask, the assistant routes through a chain of skills and volunteers the full, auditable answer below. Every metric is computed by the library — none is guessed (the g./c./p. notations then map those computed results onto the cited RefSeq annotation):

Step	Skill	Result
1	`bio-qc`	Both records are well-formed, unambiguous DNA (A/C/G/T only), 753 bp, divisible by 3 and in frame; GC 66.80 % (reference) vs 66.67 % (isolate) — the high GC of M. tuberculosis.
2	`bio-alignment`	99.87 % identical (752/753) — a single substitution, no indels: C→T at 0-based `[301,302)` / 1-based position 302 of the fragment. Mapped onto the reference annotation: `NC_000962.3:g.761155C>T` = `rpoB` `c.1349C>T`.
3	`bio-annotation`	Frame-0 translation (first fragment codon = `rpoB` codon 350) `…KRRL·``S``·ALGP…` → `…KRRL·``L``·ALGP…`: fragment residue 100 = `rpoB` codon 450, a missense change, predicted `NP_215181.1:p.(Ser450Leu)` — the catalogued S450L.
4	`bio-moldesign`	With Seqeron v1.0.0 default parameters (length 18–25, Tm 57–63 °C, GC 40–60 %, Wallace/Marmur–Doty Tm), a valid pair with both binding sites clear of the variant — 0-based half-open on the forward-strand fragment, fwd `[179,201)`, rev `[409,431)`: `GACGTTGATCAACATCCGGCCG` and `GAGCCGATCAGACCGATGTTGG` (5′→3′), each 22 nt, both 58.6 °C (ΔTm 0.0 °C), GC 59.1 %, no primer-dimer or hairpins; nearest-neighbour Tm 61.7 / 60.8 °C. 252 bp amplicon; the variant sits at 0-based offset 122 / 1-based position 123 within it — 122 bp and 130 bp from the two ends, clearing the ≥50 bp Sanger read margin.

What this establishes — and deliberately does not. Ser450Leu is graded "Associated with resistance" in the WHO 2023 mutation catalogue (2nd ed., cited above) and experimentally confirmed to cause rifampicin resistance in isogenic mutants, so the assistant reports that established association together with its source — this is not a nameless SNP hedged into vagueness. What it must not do is imply a measured phenotype: the "isolate" is the H37Rv reference with the change introduced in silico, so it has no experimentally measured MIC / drug-susceptibility result — a catalogued genotype predicts the phenotype, it does not by itself confirm it for a given specimen. Two more scoping notes. The primer pair only flanks the codon: it yields template for Sanger/NGS but does not genotype the allele on its own (that is allele-specific/ARMS-PCR, a TaqMan/molecular-beacon probe per allele, or HRM). And the exact pair is reproducible only once the design parameters are pinned: it is deterministic given the target site [301,302) and the library's default parameters above, but a different thermodynamic parameter set (amplicon range, Tm/length bounds, salt/Mg²⁺) would yield a different — equally valid — pair. Local design over one 753 bp template also checks the primers against that template only — full specificity needs a genome-wide check (Primer-BLAST against the whole NC_000962.3 genome and, ideally, an M. tuberculosis complex database), which the assistant flags as a limitation rather than asserting. Provenance travels with every number: reference NC_000962.3 positions 760,854–761,606 (1-based inclusive) = rpoB codons 350–600; the g./c./p. notations are mapped onto that RefSeq annotation (NC_000962.3 / NP_215181.1), while the fragment-relative coordinates are computed from the alignment.

bio-rigor runs throughout — tool-only computation, 0-based coordinates, provenance on every result, and the discipline to say what the data cannot support. More worked end-to-end tasks live in docs/skills/golden/.

Three ways to use it

The same validated algorithm answers whichever door you walk through.

1. Plain-language skills

A thin routing + discipline layer that turns the library into an agent which solves whole biological tasks — not just single tool calls. The Agent Skills live under .claude/skills/ (Claude Code) with a byte-identical mirror under .github/skills/ (Copilot / VS Code).

Why a skill layer at all? With 427 tools, an LLM drowns if you attach every schema. The skills keep tool descriptions out of the model's context and instead teach it to discover the right tool, orchestrate a correct multi-step pipeline, and stay scientifically honest (compute with tools — never guess; respect each algorithm's validated envelope; carry provenance). Every recipe is dual-mode — it works whether you call the MCP tool or the equivalent C# Method ID — so you don't need MCP at all; the algorithms are identical either way.

The 21 skills:

Cross-cutting — seqeron-setup (one-command install for a fresh clone) · seqeron-discovery (find the right tool among 427 without loading schemas) · bio-rigor (tool-only computation, provenance, envelope STOP rules) · seqeron-dev (the C# API path: namespaces, LimitationPolicy, TryCreate) · seqeron-python-client (wrap any tool in a small Python script).
Domains — bio-qc · bio-alignment · bio-assembly · bio-annotation · bio-moldesign · bio-phylo-popgen · bio-metagenomics · bio-chromosome · seqeron-rna-structure · seqeron-protein-features · seqeron-transcriptome · seqeron-epigenetics · seqeron-comparative-genomics · seqeron-oncology · seqeron-mirna · seqeron-structural-variants.

An auto-generated catalog plus a CI guardrail keep the skills in sync with the tools (no drift). Plan of record: docs/skills/STRATEGY.md.

2. The C# library

using Seqeron.Genomics;

var dna = new DnaSequence("AAAGAATTCAAA");

Console.WriteLine($"Length:  {dna.Length}");
Console.WriteLine($"GC%:     {dna.GcContent():F2}");
Console.WriteLine($"RevComp: {dna.ReverseComplement()}");

// Fast motif lookup via suffix tree
bool hasEcoRI = dna.SuffixTree.Contains("GAATTC");
Console.WriteLine($"EcoRI site: {hasEcoRI}");

Prefer to validate input instead of throwing? Every sequence type has a TryCreate:

// 'N' is not one of A/C/G/T, so this input is rejected.
// TryCreate is annotated [NotNullWhen(true)], so seq is non-null in the success branch.
if (DnaSequence.TryCreate("ACGTNN", out var seq))
    Console.WriteLine($"GC%: {seq.GcContent():F2}");
else
    Console.WriteLine("Invalid DNA sequence");

3. MCP integration

MCP lets any LLM call Seqeron tools with strict schemas and reproducible outputs — LLM-native bioinformatics. Because each call is a real algorithm, the results are deterministic and every step is auditable.

Start here: What is MCP · What you get · How to connect · How to use · Why servers are split · Connect to Codex/IDE

Worked example — cloning-insert QC (GC% + restriction sites, every step traced)

Task: given an insert in FASTA, report GC% and whether it contains EcoRI (GAATTC) or BamHI (GGATCC) sites (0-based positions) — a standard cloning QC step.

Prompt:

Use tools only; no manual parsing or calculations. I have a cloning insert in FASTA below.
Read the sequence with tools, then report GC% (2 decimals) and any EcoRI (GAATTC) / BamHI
(GGATCC) sites as 0-based positions, as a Markdown table (id, length, gc_percent, EcoRI_sites,
BamHI_sites). Sites as JSON arrays. Output only the table.

>seq1
GCGCGAATTCATGGATCCATAT

Result:

| id   | length | gc_percent | EcoRI_sites | BamHI_sites |
|------|-------:|-----------:|-------------|-------------|
| seq1 |     22 |      45.45 | [4]         | [12]        |

Tools used, in order: fasta_parse → gc_content (45.45, 10/22) → suffix_tree_find_all GAATTC → [4] → suffix_tree_find_all GGATCC → [12].

Worked example — PCR primer QC (validity + GC% + Tm + ΔTm)

Task: validate two primers, compute GC% and Tm, and report the Tm difference — a routine pre-screen before PCR.

Prompt:

Use tools only. These are PCR primers in FASTA. Read them with tools, confirm each is valid DNA,
report GC% (2 decimals) and Tm in °C (1 decimal) as a Markdown table (id, length, gc_percent,
tm_c), then a line: tm_diff_c = |Tm_FWD - Tm_REV|.

>FWD
ATGCGATCGATCGATCGTAG
>REV
GCGCGATCGATCGATCGCAA

Result:

| id  | length | gc_percent | tm_c |
|-----|-------:|-----------:|-----:|
| FWD |     20 |      50.00 | 51.8 |
| REV |     20 |      60.00 | 55.9 |

tm_diff_c = 4.1

Tools used, in order: fasta_parse → dna_validate ×2 → gc_content ×2 → melting_temperature ×2.

How a task flows — the same validated algorithm answers whether you go through MCP or the C# API:

flowchart LR
    U["Plain-language<br/>biology task"] --> SK["Skill routing<br/>(discover + orchestrate)"]
    SK -.->|"guards every step"| RIG["bio-rigor<br/>tool-only · 0-based<br/>envelope STOP rules"]
    SK -->|"picks Method IDs"| P{"Two equivalent<br/>entry points"}
    P -->|"strict schema"| MCP["MCP tool call"]
    P -->|"in-process"| API["C# Method ID"]
    MCP --> ALG["Validated algorithm<br/>LimitationPolicy-guarded"]
    API --> ALG
    ALG --> OUT["Result + provenance<br/>reproducible · cited · not guessed"]

Tool schemas and examples: Core · Sequence · Parsers.

What's inside

Sequence models — DNA / RNA / Protein with validation and the everyday operations (transcribe, translate, reverse-complement, composition, Tm, molecular weight, pI, …).
Parsers & writers — FASTA, FASTQ, GenBank, GFF, VCF, BED, EMBL.
A broad algorithm library — alignment (global / local / semi-global / MSA); k-mer, motif, repeat, and complexity analysis; annotation and variant calling; phylogenetics and population genetics; metagenomics; comparative and structural genomics; transcriptome analysis and translation; RNA secondary structure; epigenetics; oncology; chromosome-level analysis; and molecular tools (primer / probe / CRISPR design, codon optimization, restriction analysis).
A high-performance suffix tree (Ukkonen) for fast substring queries, plus a persistent on-disk variant.
11 MCP servers exposing the toolsets to LLM/agent workflows — one per domain, plus the core suffix-tree server. (Oncology ships as a C# module only — it has no MCP server; reach it through the C# API or the seqeron-oncology skill.)
Evidence-based validation — algorithm parameters and coefficients reproduced from primary literature and reference implementations, tracked per unit under docs/Validation.

Architecture

The library is a strictly layered set of packages — dependencies only ever point up the levels, never sideways within a level or downward (enforced by architecture tests). An arrow A --> B means B depends on A. Every module also references Core + Infrastructure (Levels 0–1); those universal edges are drawn only where they define the layer, to keep the graph readable.

graph TD
    subgraph "Substrate"
        ST[SuffixTree<br/>Ukkonen + persistent]
    end
    subgraph "Level 0"
        INF[Infrastructure]
    end
    subgraph "Level 1"
        CORE[Core]
    end
    subgraph "Level 2"
        IO[IO]
        ALN[Alignment]
        POP[Population]
        REP[Reports]
    end
    subgraph "Level 3"
        ANA[Analysis]
        PHY[Phylogenetics]
    end
    subgraph "Level 4"
        ANN[Annotation]
        META[Metagenomics]
        MOL[MolTools]
        CHR[Chromosome]
        ONC[Oncology]
    end
    subgraph "Meta-package"
        GEN[Seqeron.Genomics<br/>aggregates all modules]
    end

    ST --> CORE
    INF --> CORE
    CORE --> IO
    CORE --> ALN
    CORE --> POP
    CORE --> REP

    ALN --> ANA
    ALN --> PHY

    ANA --> META
    ANA --> MOL
    ANA --> ONC
    ALN --> CHR
    ANA --> CHR
    IO --> ANN
    ALN --> ANN
    ANA --> ANN
    PHY --> ANN

    ANN --> GEN
    META --> GEN
    MOL --> GEN
    CHR --> GEN
    ONC --> GEN
    POP --> GEN
    REP --> GEN

Repository layout

Seqeron.sln
Directory.Build.props        # Solution-wide defaults (net10.0, nullable, warnings-as-errors, deterministic)
Directory.Packages.props     # Central Package Management — every NuGet version pinned in one place
.editorconfig                # Shared formatting / code-style baseline
.github/workflows/dotnet.yml # CI: restore → build (warnings-as-errors) → full test suite
src/
├── SuffixTree/              # Ukkonen suffix tree (+ persistent) and its MCP server
└── Seqeron/
    ├── Algorithms/          # The genomics modules (Core, IO, Alignment, Analysis, Annotation,
    │                        #   Phylogenetics, Population, Metagenomics, MolTools, Chromosome,
    │                        #   Oncology, Reports) + the Seqeron.Genomics meta-package
    └── Mcp/                 # One MCP server per domain (Sequence, Parsers, Alignment, Analysis,
                             #   Annotation, Phylogenetics, Population, Metagenomics, Chromosome, MolTools)
tests/                       # Per-module + per-server test suites (the bulk of the codebase)
apps/                        # Benchmarks, stress/verification harness, genome demo
docs/                        # Algorithms, MCP guide, skills strategy, validation ledger
wiki/                        # LLM-curated navigation layer over the repository documentation

LLM Wiki: repository knowledge for agents

Seqeron includes an LLM Wiki: a compact, linked knowledge layer that helps an agent find the right project fact before loading large parts of the repository. It complements the plain-language skills, C# API, and MCP tools: skills route biology tasks, MCP executes algorithms, and the wiki answers questions about how this repository is designed, validated, connected, and constrained.

The source of truth remains the repository documentation — everything under docs/** plus root Markdown files such as README.md, ALGORITHMS_CHECKLIST_V2.md, and ALGORITHMS_ROADMAP.md. Curated pages under wiki/ summarize and connect those sources; they record the source path and commit rather than replacing or editing the originals. There is intentionally no copied raw/ tree.

How retrieval works

Start at the 13-line wiki/index.md and open only the smallest relevant shard.
Follow concise [[wikilinks]], or use BM25 search when the index is not specific enough.
Read the relevant concept/source page and traverse backlinks or typed graph edges when relationships matter.
Follow sources: / doc_path: to the authoritative repository document before making a high-stakes claim; cite the answer with [[wikilinks]].

At the point of tool selection, seqeron-discovery's find-tool.py also surfaces the wiki concept — or a (!) sharp-edge (wiki/gotchas/) page — bound to each tool, so an agent sees the science and the known traps before it runs anything. New algorithm ingests keep this current automatically: the wiki-ingest-doc skill's gotcha_candidate.py extracts a doc's sharp edges and wires the resulting gotcha back to its concept and tools.

This is retrieval, not a second source of truth. Every derived page carries provenance, source_commit enables deterministic staleness checks, and the compiled graph is disposable — Markdown remains canonical.

Conceptual map

The wiki connects three overlapping concerns: biological meaning, computational methods, and the evidence and limits that make their use trustworthy. The map is intentionally qualitative and stable: it explains the knowledge model without turning individual pages into fixed categories.

Measured context reduction

These figures describe the repository state in the same Git revision as this README. Counts use wiki_stats.py plus docs/**/*.md and root *.md; both surfaces use whitespace-delimited words:

	Without the LLM Wiki	With the LLM Wiki
Discovery surface	1,184 source files · 170,370 lines · 1,339,139 words	13-line index + a relevant shard (largest: 235 lines)
One-page lookup context	Repository-wide search may expose up to 170,370 source lines	Worst-case indexed discovery: 235 lines; then a 105-line average curated page
Explicit knowledge structure	No normalized cross-document graph	569 pages · 5,155 wikilinks · 569 graph nodes · 4,678 edges
Curated knowledge volume	None	59,976 lines · 492,845 words
Provenance freshness	Manual source/history inspection	`source_commit` on every derived page; current stale count: 0

For a representative one-page lookup, index + largest shard + average page is 353 lines versus 170,370 source lines (~483× less discovery context). This is a context-size comparison, not a claim that the wiki replaces reading the source or improves model correctness by a fixed percentage. Reproduce both sides from this revision:

# Baseline (source docs): file count + total lines, then total words
git ls-files '*.md' | grep -E '^(docs/|[^/]+\.md$)' | xargs wc -l | tail -1
git ls-files '*.md' | grep -E '^(docs/|[^/]+\.md$)' | xargs cat | wc -w
# Wiki side: pages, lines, words, links, largest page, index size
python .claude/skills/llm-wiki/scripts/wiki_stats.py wiki

Retrieval quality at fixed context cutoffs

A fixed benchmark pairs 30 representative search intents with one expected concept page and equivalent English and Ukrainian questions. Without the wiki, any local document in that concept's sources: is gold; with the wiki, the concept page itself is gold. Hit@K means that a gold result appears within the first K BM25 results; it measures retrieval, not the factual correctness of a generated answer.

Each cell shows Without → With the LLM Wiki (absolute gain); all rows use the same 30 intents.

Query form	Hit@1	Hit@3	Hit@10
English (direct)	50.0% → 63.3% (+13.3 pp)	90.0% → 93.3% (+3.3 pp)	93.3% → 100.0% (+6.7 pp)
Українська (direct)	30.0% → 46.7% (+16.7 pp)	46.7% → 66.7% (+20.0 pp)	70.0% → 76.7% (+6.7 pp)
Українська → English normalization	56.7% → 66.7% (+10.0 pp)	90.0% → 96.7% (+6.7 pp)	96.7% → 100.0% (+3.3 pp)

The baseline indexes the contents and paths of docs/**/*.md and root *.md; the wiki surface indexes concept titles and bodies. Both use the same tokenizer and BM25 implementation. Direct queries are passed unchanged. The normalized row uses the fixed, manually reviewed English retrieval query stored beside each Ukrainian question; it measures BM25 after the prescribed normalization, not the reliability of an LLM translator. Reproduce the table from the versioned query set:

python .claude/skills/llm-wiki/scripts/wiki_search_benchmark.py wiki

Example questions

Ask naturally when the llm-wiki skill is available:

/wiki:query Which primer-design path uses full thermodynamic dimer Tm instead of the fast structural screen? Cite the relevant wiki pages.

/wiki:query How does k-mer search depend on canonical k-mer counting, and which validation report supports that relationship?

/wiki:query What are the validated limits of Seqeron's oncology algorithms, and where is each limitation enforced?

Or query the local indexes directly:

# Ranked discovery without collapsing distinct derived concepts
python .claude/skills/llm-wiki/scripts/wiki_search.py \
  "primer dimer thermodynamics" --wiki wiki --top 5 \
  --dedup-provenance --prefer-type concept

# Every page that links to a concept
python .claude/skills/llm-wiki/scripts/wiki_search.py \
  --wiki wiki --backlinks primer-design

# Typed facts and their exact source pages
python .claude/skills/llm-wiki/scripts/wiki_graph_query.py \
  wiki facts --about concept:k-mer-counting

Keep it trustworthy

# One-time: enable the repository's pre-commit wiki guard
git config core.hooksPath .githooks

# Structural/link/index-limit health, provenance freshness, and typed-edge integrity
python .claude/skills/llm-wiki/scripts/wiki_lint.py wiki
python .claude/skills/llm-wiki/scripts/wiki_stale.py wiki
python .claude/skills/llm-wiki/scripts/wiki_graph_lint.py wiki

# Link-extraction and wiki-tool business rules, with the blocking coverage threshold
python -m pip install coverage pyyaml  # one-time Python tooling dependencies
python -m coverage run --rcfile=.claude/skills/llm-wiki/.coveragerc -m unittest discover -s .claude/skills/llm-wiki/tests
python -m coverage report --rcfile=.claude/skills/llm-wiki/.coveragerc

# Rebuild the disposable graph after Markdown graph metadata changes
python .claude/skills/llm-wiki/scripts/wiki_graph_extract.py wiki

When a source changes, run /wiki:ingest <repo-relative-path> (for example, /wiki:ingest README.md), update only the affected pages and index entry, and append one line to wiki/log.md. Page types, frontmatter, size limits, graph provenance, and the exact staleness rule are defined in wiki/SCHEMA.md.

Build & test

dotnet build          # Release build; warnings are errors on every project
dotnet test           # full suite — 22,000+ cases across every assembly

Shared build settings are centralized so all 47 projects stay consistent:

Central Package Management — every NuGet version declared once; project files carry no Version attributes.
Directory.Build.props — one place for net10.0, nullable, implicit usings, deterministic builds, and TreatWarningsAsErrors (applied to every project).
CI — .github/workflows/dotnet.yml restores, builds (warnings-as-errors), and runs the full suite on every push/PR.

Wall-clock performance / benchmark tests are marked [Explicit] so they never flake the parallel gate; run them on demand:

dotnet test --filter "TestCategory=Performance"     # opt-in timing / complexity guards

Performance & NativeAOT

Performance-critical libraries and all MCP-server executables are configured for aggressive NativeAOT compilation — no JIT/CLR at runtime, native instruction sets for the build CPU, and a much smaller binary.

Libraries (SuffixTree.Core, SuffixTree, SuffixTree.Persistent) opt into IsAotCompatible + IsTrimmable. Executables (every Seqeron.Mcp.*, SuffixTree.Mcp.Core, and the SuffixTree.Console harness) enable full PublishAot:

<PublishAot>true</PublishAot>
<OptimizationPreference>Speed</OptimizationPreference>       <!-- aggressive inlining, loop unrolling -->
<IlcInstructionSet>native</IlcInstructionSet>               <!-- target the build CPU's full ISA (AVX2/AVX-512/BMI2/POPCNT, as available) -->
<IlcFoldIdenticalMethodBodies>true</IlcFoldIdenticalMethodBodies>
<StripSymbols>true</StripSymbols>
<InvariantGlobalization>true</InvariantGlobalization>       <!-- drop ICU (~30 MB); genomics needs no culture -->

Publishing requires the Desktop Development with C++ workload:

dotnet publish -c Release -r win-x64

Benchmark strategy & baseline numbers

The benchmark project uses a two-phase strategy to avoid the common pitfall of BenchmarkDotNet re-compiling AOT for every benchmark method (which causes multi-hour "freezes"): a fast JIT baseline, a single NativeAOT publish, then run the pre-compiled binary with the InProcessNoEmitToolchain (--inprocess) so it benchmarks itself without spawning child processes.

# 1. JIT baseline (~3 min)
dotnet run --project apps/SuffixTree.Benchmarks -c Release -f net10.0 -- \
  --filter "*Build_Short*" "*Build_DNA*" "*Contains*" "*LRS*" --iterationCount 3 --warmupCount 1

# 2. Publish NativeAOT once (~5 min)
dotnet publish apps/SuffixTree.Benchmarks -c Release -r win-x64 -f net10.0 \
  /p:PublishAot=true /p:OptimizationPreference=Speed /p:IlcInstructionSet=native \
  /p:IlcFoldIdenticalMethodBodies=true /p:StripSymbols=true /p:InvariantGlobalization=true

# 3. Run the AOT binary in-process (~3 min)
./apps/SuffixTree.Benchmarks/bin/Release/net10.0/win-x64/publish/SuffixTree.Benchmarks.exe \
  --inprocess --filter "*Build_Short*" "*Build_DNA*" "*Contains*" "*LRS*"

JIT baseline (11th Gen Intel Core i7-1185G7, 4C/8T, AVX-512):

Method	Mean	Allocated
LRS_Short	21.2 ns	32 B
LRS_DNA	23.5 ns	56 B
Contains_Short	43.8 ns	0 B
Contains_DNA	107.4 ns	0 B
Build_Short	18.3 µs	19 KB
Build_DNA (50K)	50.7 ms	8.5 MB

Project status & validation

Seqeron is in beta: feature-complete, with a public API that is stabilizing toward 1.0. Public APIs may still change between releases. Here is exactly where it stands — the good and the caveats.

What has been done (verifiable in this repo):

Extensive automated testing — 22,000+ executed test cases ([Test] methods plus parametrized [TestCase] / combinatorial expansions; dotnet test prints the exact executed count) across 258 algorithm units (the "250+ algorithms" tracked individually for validation), with roughly 3.9× more test code than product code (≈367k test vs ≈94k product lines). The full suite is green on .NET 10, warnings-as-errors, CI-gated.

Ten complementary test methodologies — each catches a different class of defect, and each has a per-algorithm checklist under docs/checklists:

Methodology	What it catches
Property-based (FsCheck)	Invariant violations across thousands of generated inputs, not just hand-picked cases.
Metamorphic	Wrong outputs when the exact answer is unknown, by asserting relations between related inputs (e.g. `revcomp(revcomp(x)) == x`).
Fuzzing	Crashes and unhandled edge cases from malformed, random, or adversarial input.
Mutation (Stryker.NET)	Weak tests — seeds deliberate bugs into the code and fails if the suite doesn't notice.
Snapshot / approval (Verify)	Unintended changes to complex outputs, locked against reviewed baselines.
Algebraic	Broken algebraic laws the operations must obey — identity, inverse, idempotence, commutativity.
Architecture (ArchUnitNET)	Layering / dependency-rule drift in the package graph.
Differential	Divergence from an independent or reference implementation of the same algorithm.
Combinatorial / pairwise	Interaction bugs across large parameter-combination spaces, covered efficiently.
Characterization	Regressions during refactoring, by pinning current behaviour.

A per-unit internal validation campaign — a documented findings register, a published limitations / operating-envelope document, and a runtime LimitationPolicy that guards algorithms used outside their validated scope. One report per unit under docs/Validation/reports; index in docs/Validation.
Literature-traced parameters — algorithm coefficients reproduced from primary literature and reference implementations, tracked per unit.

What has not been done — and why you must still validate before relying on it:

No third-party / external audit, peer review, or regulatory clearance.
No certification for clinical, diagnostic, or decision-making use.
Many algorithms are faithful but simplified or subset realisations of fuller published methods; their honest scope is documented in LIMITATIONS.md.

Before using with real data or in production: independently verify all outputs against established tools for your specific use case, and do not use Seqeron for clinical or diagnostic decision-making without your own qualification and validation.

Disclaimer. The authors and contributors make no warranties regarding correctness, reliability, or fitness for any particular purpose. Use at your own risk; the authors shall not be liable for any damages, losses, or harm arising from the use or misuse of this software. See LICENSE for full terms.

Documentation

For study

Start here: Algorithms index.
Areas: Annotation · K-mer · Pattern Matching · Repeat Analysis · Sequence Composition · MolTools.
Suffix Tree (Ukkonen).

For development

MCP guide: docs/mcp/README.md · traceability: docs/mcp/traceability.md.
Skills strategy & worked tasks: docs/skills/STRATEGY.md · docs/skills/golden.
Validation: docs/Validation · LIMITATIONS.md.
Algorithm test specifications: tests/TestSpecs.
LLM Wiki: knowledge layer, measured impact, queries, and maintenance · schema.

Contributing

External review is exactly what would move this project past its current, self-validated state — so audits, bug reports, and corrections are actively welcomed. If you find an error in any algorithm implementation, please open an issue or submit a pull request. Builds are warnings-as-errors and the full test suite runs on every push/PR, so run dotnet build and dotnet test before you submit.

License

MIT — see LICENSE.

Navigation Menu

Repository files navigation

Seqeron

Contents

Why Seqeron

Quick start

See it work: an rpoB rifampicin-resistance variant triage

Three ways to use it

1. Plain-language skills

2. The C# library

3. MCP integration

What's inside

Architecture

Repository layout

LLM Wiki: repository knowledge for agents

How retrieval works

Conceptual map

Measured context reduction

Retrieval quality at fixed context cutoffs

Example questions

Keep it trustworthy

Build & test

Performance & NativeAOT

Project status & validation

Documentation

Contributing

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude		.claude
.githooks		.githooks
.github		.github
.vscode		.vscode
apps		apps
docs		docs
scripts		scripts
src		src
tests		tests
tools/wiki-ingest		tools/wiki-ingest
wiki		wiki
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
ALGORITHMS_CHECKLIST_V2.md		ALGORITHMS_CHECKLIST_V2.md
ALGORITHMS_ROADMAP.md		ALGORITHMS_ROADMAP.md
CodeCoverage.runsettings		CodeCoverage.runsettings
Directory.Build.props		Directory.Build.props
Directory.Packages.props		Directory.Packages.props
LICENSE		LICENSE
README.md		README.md
Seqeron.sln		Seqeron.sln
WIKI_INGEST_CHECKLIST.md		WIKI_INGEST_CHECKLIST.md
dotnet-tools.json		dotnet-tools.json

Latest commit

History

Folders and files

Repository files navigation

Seqeron

Contents

Why Seqeron

Quick start

See it work: an rpoB rifampicin-resistance variant triage

Three ways to use it

1. Plain-language skills

2. The C# library

3. MCP integration

What's inside

Architecture

Repository layout

LLM Wiki: repository knowledge for agents

How retrieval works

Conceptual map

Measured context reduction

Retrieval quality at fixed context cutoffs

Example questions

Keep it trustworthy

Build & test

Performance & NativeAOT

Project status & validation

Documentation

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages