genomix-cli 0.1.0__py3-none-any.whl

genomix/__init__.py

@@ -0,0 +1,3 @@
+"""Genomix CLI — AI-powered DNA sequence and genome analysis."""
+
+__version__ = "0.1.0"

genomix/agent/context_compressor.py

@@ -0,0 +1,31 @@
+"""Context compression: summarize old tool results when context grows."""
+from __future__ import annotations
+from typing import Any
+
+CHARS_PER_TOKEN = 4
+
+
+def estimate_tokens(messages):
+    return sum(len(m.get("content", "") or "") for m in messages)
+
+
+def should_compress(messages, max_tokens):
+    return estimate_tokens(messages) > max_tokens * 0.8
+
+
+def compress_messages(messages, max_tokens):
+    if not should_compress(messages, max_tokens):
+        return messages
+    result = []
+    if messages and messages[0]["role"] == "system":
+        result.append(messages[0])
+        messages = messages[1:]
+    keep_recent = min(6, len(messages))
+    old = messages[:-keep_recent] if keep_recent < len(messages) else []
+    recent = messages[-keep_recent:]
+    for msg in old:
+        if msg.get("role") == "tool" and len(msg.get("content", "") or "") > 500:
+            msg = {**msg, "content": (msg["content"] or "")[:200] + "\n... [truncated]"}
+        result.append(msg)
+    result.extend(recent)
+    return result

genomix/agent/loop.py

@@ -0,0 +1,93 @@
+"""Agent conversation loop with tool calling support."""
+from __future__ import annotations
+import json
+from typing import Any, Callable
+
+from genomix.providers.base import BaseProvider
+from genomix.tools.registry import ToolRegistry
+from genomix.agent.context_compressor import should_compress, compress_messages
+
+
+class AgentLoop:
+    def __init__(
+        self,
+        provider: BaseProvider,
+        tool_registry: ToolRegistry,
+        system_prompt: str = "",
+        max_iterations: int = 30,
+        on_tool_call: Callable[[str, dict], None] | None = None,
+        on_tool_result: Callable[[str, str], None] | None = None,
+        on_thinking: Callable[[str], None] | None = None,
+    ):
+        self.provider = provider
+        self.tool_registry = tool_registry
+        self.system_prompt = system_prompt
+        self.max_iterations = max_iterations
+        self.messages: list[dict[str, Any]] = []
+        # UI callbacks
+        self.on_tool_call = on_tool_call
+        self.on_tool_result = on_tool_result
+        self.on_thinking = on_thinking
+
+    def _build_messages(self) -> list[dict[str, Any]]:
+        msgs = list(self.messages)
+
+        # Compress if context is getting large
+        max_tokens = self.provider.max_context_length()
+        if should_compress(msgs, max_tokens):
+            msgs = compress_messages(msgs, max_tokens)
+
+        if self.system_prompt:
+            return [{"role": "system", "content": self.system_prompt}] + msgs
+        return msgs
+
+    def _force_final_synthesis(self) -> str:
+        """Ask the model for a final answer with tool use disabled."""
+        self.messages.append(
+            {
+                "role": "user",
+                "content": (
+                    "You have enough information. Do not call any more tools. "
+                    "Provide the best final answer now, clearly noting uncertainty where needed."
+                ),
+            }
+        )
+        response = self.provider.chat(self._build_messages(), tools=None)
+        self.messages.append({"role": "assistant", "content": response.content})
+        return response.content or "Max iterations reached without a final response."
+
+    def chat(self, user_message: str) -> str:
+        self.messages.append({"role": "user", "content": user_message})
+        tools = self.tool_registry.list_tools() or None
+
+        for iteration in range(self.max_iterations):
+            all_messages = self._build_messages()
+
+            if self.on_thinking and iteration == 0:
+                self.on_thinking("Thinking...")
+
+            response = self.provider.chat(all_messages, tools=tools)
+
+            if response.tool_calls:
+                self.messages.append({"role": "assistant", "content": response.content or "", "tool_calls": [
+                    {"id": tc.id, "type": "function", "function": {"name": tc.name, "arguments": json.dumps(tc.arguments) if isinstance(tc.arguments, dict) else tc.arguments}}
+                    for tc in response.tool_calls
+                ]})
+                for tc in response.tool_calls:
+                    if self.on_tool_call:
+                        self.on_tool_call(tc.name, tc.arguments)
+                    try:
+                        result = self.tool_registry.dispatch(tc.name, tc.arguments)
+                    except Exception as e:
+                        result = json.dumps({"error": str(e)})
+                    # Truncate large tool results to prevent context explosion
+                    if len(result) > 2000:
+                        result = result[:2000] + "\n... [truncated]"
+                    if self.on_tool_result:
+                        self.on_tool_result(tc.name, result[:200])
+                    self.messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
+            else:
+                self.messages.append({"role": "assistant", "content": response.content})
+                return response.content or ""
+
+        return self._force_final_synthesis()

genomix/agent/prompt_builder.py

@@ -0,0 +1,68 @@
+"""Assemble the system prompt from project context, skills, and mode."""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from genomix.project.manager import GenomixProject
+
+IDENTITY = """You are Genomix, an AI assistant specialized in DNA sequence and genome analysis.
+You help biologists, bioinformaticians, and researchers analyze genomic data by orchestrating
+bioinformatics tools and querying genomic databases.
+
+You are proactive: suggest next steps, explain results in accessible language, and adapt
+your communication to the user's expertise level. When a user speaks in natural language,
+explain in plain terms. When they use slash commands, be concise and technical.
+
+You have access to tools for: file manipulation, sequence alignment, variant calling,
+annotation, BLAST searches, database queries (NCBI, Ensembl, ClinVar, dbSNP), and more.
+
+IMPORTANT — Tool calling strategy:
+- Be STRATEGIC with tool calls. Do NOT query every database for every item.
+- Maximum 5-6 tool calls per question. After that, synthesize from what you have.
+- Use your own knowledge to supplement — you don't need to verify everything via API.
+
+When analyzing VCF files:
+1. Read the file. Check if INFO has annotations (GENE, EFFECT, CLNSIG).
+2. IF annotated: use them directly, no database queries needed.
+3. IF raw (no annotations, ID is "."):
+   → Use YOUR KNOWLEDGE FIRST to identify genes from coordinates:
+     chr17:43,044,000-43,170,000 = BRCA1
+     chr13:32,315,000-32,400,000 = BRCA2
+     chr7:117,480,000-117,668,000 = CFTR
+     chr11:5,225,000-5,228,000 = HBB
+     chr19:44,905,000-44,910,000 = APOE
+   → Only query databases (1-2 calls MAX) for coordinates you truly don't recognize.
+   → Interpret GT (0/1=het, 1/1=hom), DP (read depth), GQ (quality).
+   → Use your knowledge of well-known pathogenic variants at these positions.
+   → RESPOND after reading the file + at most 2 database calls. Do NOT look up every variant.
+
+Advanced analysis capabilities — DO NOT say you can't do these:
+- ANCESTRY INFERENCE: Many variants have population-specific frequencies. Use your
+  knowledge of ancestry-informative markers (e.g. rs334/HBB sickle cell = high frequency
+  in African/Mediterranean populations, CFTR deltaF508 = Northern European, APOE allele
+  frequencies vary by population). Use ensembl_population_frequencies to get gnomAD/1000G
+  frequency data across AFR/EUR/EAS/SAS/AMR populations. Combine multiple variants to
+  suggest likely ancestry.
+- PHENOTYPE INFERENCE: From pathogenic variants, infer likely phenotypic consequences
+  (disease risk, carrier status for recessive conditions, drug response).
+- PHARMACOGENOMICS: Some variants affect drug metabolism. Flag them if present.
+- CARRIER STATUS: For autosomal recessive diseases (sickle cell, CF), heterozygous
+  carriers (0/1) are typically unaffected but can pass the variant to children."""
+
+PRIVACY_ADDENDUM = """
+PRIVACY MODE IS ACTIVE. You must follow these rules strictly:
+- Never include raw sequence data (nucleotide strings) in your responses or reasoning
+- Never include patient identifiers or sample metadata
+- Only reference aggregated statistics, variant IDs (rsIDs), and gene symbols
+- All tools run locally — only summaries are passed to you"""
+
+
+def build_system_prompt(project, skill_body, privacy_mode):
+    parts = [IDENTITY]
+    if project:
+        parts.append(f"\n## Active Project\n- **Name:** {project.name}\n- **Organism:** {project.organism}\n- **Reference genome:** {project.reference_genome}\n- **Data type:** {project.data_type}\n- **Project root:** {project.root}")
+    if skill_body:
+        parts.append(f"\n## Current Task Instructions\n\n{skill_body}")
+    if privacy_mode:
+        parts.append(PRIVACY_ADDENDUM)
+    return "\n".join(parts)

genomix/agent/session_store.py

@@ -0,0 +1,41 @@
+"""Session history storage with SQLite + FTS5."""
+import json, sqlite3, uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+class SessionStore:
+    def __init__(self, db_path):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _init_db(self):
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute("CREATE TABLE IF NOT EXISTS sessions (id TEXT PRIMARY KEY, title TEXT, messages TEXT, created_at TEXT)")
+            conn.execute("CREATE VIRTUAL TABLE IF NOT EXISTS sessions_fts USING fts5(id, title, content)")
+
+    def save_session(self, messages, title=""):
+        sid = uuid.uuid4().hex[:12]
+        now = datetime.now(timezone.utc).isoformat()
+        content = " ".join(m.get("content", "") or "" for m in messages)
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute("INSERT INTO sessions VALUES (?,?,?,?)", (sid, title, json.dumps(messages), now))
+            conn.execute("INSERT INTO sessions_fts VALUES (?,?,?)", (sid, title, content))
+        return sid
+
+    def load_session(self, session_id):
+        with sqlite3.connect(self.db_path) as conn:
+            row = conn.execute("SELECT messages FROM sessions WHERE id=?", (session_id,)).fetchone()
+        return json.loads(row[0]) if row else []
+
+    def search(self, query):
+        with sqlite3.connect(self.db_path) as conn:
+            rows = conn.execute("SELECT id, title FROM sessions_fts WHERE sessions_fts MATCH ?", (query,)).fetchall()
+        return [{"id": r[0], "title": r[1]} for r in rows]
+
+    def list_sessions(self, limit=20):
+        with sqlite3.connect(self.db_path) as conn:
+            rows = conn.execute("SELECT id, title, created_at FROM sessions ORDER BY created_at DESC LIMIT ?", (limit,)).fetchall()
+        return [{"id": r[0], "title": r[1], "created_at": r[2]} for r in rows]

genomix/builtin_skills/common/file-formats/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: file-formats
+description: Recognize and validate FASTA, FASTQ, BAM, VCF, and GFF files by inspecting their content
+version: 1.0.0
+author: genomix-cli
+license: Apache-2.0
+metadata:
+  genomix:
+    tags: [common, file-formats, fasta, fastq, bam, vcf, gff, detection]
+    tools_used: [read_file, run_command]
+---
+
+# Genomic File Format Recognition
+
+## Detection by Content
+
+Never rely solely on file extensions — always verify content.
+
+### FASTA
+- First non-empty line starts with `>`.
+- Second line is a sequence (A, T, G, C, N, IUPAC ambiguity codes, or amino acid letters).
+- Multi-line sequences are allowed; next record starts with `>`.
+
+```
+>sequence_id optional description
+ATCGATCGATCG
+ATCGATCGATCG
+```
+
+### FASTQ
+- Records are 4 lines: `@header`, sequence, `+` (optionally repeated header), quality string.
+- Quality string length must equal sequence length.
+- Quality characters are ASCII 33–126 (Phred+33 encoding for modern Illumina).
+
+```
+@read_id
+ATCGATCGATCG
++
+FFFFIIIIBBBB
+```
+
+Distinguish FASTQ from FASTA: FASTQ starts with `@`, FASTA with `>`. Note: `@` also appears in quality lines, so always check that records are 4 lines.
+
+### BAM / SAM
+- **SAM**: plain text; starts with `@HD` (header line), `@SQ` (reference sequences), then alignment records (11 mandatory tab-separated fields).
+- **BAM**: binary; magic bytes are `BAM\1` (hex `42 41 4D 01`). Use `samtools view -H` to inspect.
+
+```bash
+samtools view -H sample.bam | head -5
+```
+
+### VCF
+- Starts with `##fileformat=VCFv4.x`.
+- Meta-information lines begin with `##`.
+- Header line begins with `#CHROM`.
+- Data lines: CHROM, POS, ID, REF, ALT, QUAL, FILTER, INFO (+ optional FORMAT and sample columns).
+
+```
+##fileformat=VCFv4.2
+#CHROM  POS     ID          REF  ALT  QUAL  FILTER  INFO
+chr17   41245466 rs28897696  G    A    100   PASS    .
+```
+
+### GFF / GTF
+- GFF3: starts with `##gff-version 3`. 9 tab-separated fields; attributes in `key=value` format.
+- GTF (GFF2): attributes in `key "value"` format (used by GENCODE, Ensembl downloads).
+
+```
+##gff-version 3
+chr1  RefSeq  gene  11874  14409  .  +  .  ID=gene1;Name=DDX11L1
+```
+
+## Format Validation Commands
+
+```bash
+# Check FASTA integrity
+seqkit stats sequences.fasta
+
+# Validate FASTQ (check pairing, quality encoding)
+fastqc --nogroup sample.fastq.gz
+
+# Validate BAM (check for truncation, index)
+samtools quickcheck sample.bam && samtools index sample.bam
+
+# Check VCF (validate against spec)
+bcftools stats sample.vcf.gz | head -30
+```
+
+## Common Pitfalls
+
+- **FASTA with wrapped lines**: parsers must handle variable line widths.
+- **FASTQ quality encoding**: older data may use Phred+64 (Illumina 1.3–1.7); seqkit or FastQC can auto-detect.
+- **Multi-sample VCF**: sample columns appear after FORMAT — always check the header for sample names.
+- **BGZF vs gzip**: BAM and indexed VCF use BGZF (block gzip), which is compatible with regular gzip but supports random access via `.tbi` / `.csi` indexes.

genomix/builtin_skills/common/genome-references/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: genome-references
+description: Choose between GRCh38 and GRCh37, perform coordinate liftover, and select organism-specific references
+version: 1.0.0
+author: genomix-cli
+license: Apache-2.0
+metadata:
+  genomix:
+    tags: [common, references, GRCh38, GRCh37, hg38, hg19, liftover, assembly]
+    tools_used: [run_command, ncbi_search]
+---
+
+# Genome Reference Selection
+
+## GRCh38 vs GRCh37
+
+| Feature | GRCh37 (hg19) | GRCh38 (hg38) |
+|---------|---------------|----------------|
+| Release | 2009 | 2013 (last patch 2022) |
+| Alternate loci | None | 261 ALT sequences |
+| Centromere resolution | Incomplete | Near-complete |
+| Annotation currency | Legacy databases | Active updates (GENCODE, RefSeq) |
+| Clinical databases | ClinVar legacy data | Current default |
+| Chromosome names | chr1–22, chrX, chrY | chr1–22, chrX, chrY (same) |
+
+**Use GRCh38** for all new projects. GRCh37 is only justified when:
+- Reanalyzing legacy data that must remain comparable to a previous GRCh37 run.
+- A clinical database or variant report explicitly uses GRCh37 coordinates.
+- A collaboration partner mandates GRCh37.
+
+Note: UCSC names (hg19/hg38) are interchangeable with Ensembl/NCBI names (GRCh37/GRCh38) for the primary assembly — the sequences are identical.
+
+## Coordinate Liftover
+
+To convert coordinates from GRCh37 to GRCh38 (or reverse), use UCSC liftOver or Picard LiftoverVcf.
+
+### liftOver (BED)
+
+```bash
+# Download chain file
+wget https://hgdownload.soe.ucsc.edu/goldenPath/hg19/liftOver/hg19ToHg38.over.chain.gz
+
+liftOver \
+  input.hg19.bed \
+  hg19ToHg38.over.chain.gz \
+  output.hg38.bed \
+  unmapped.bed
+```
+
+### Picard LiftoverVcf
+
+```bash
+gatk LiftoverVcf \
+  -I sample.hg19.vcf.gz \
+  -O sample.hg38.vcf.gz \
+  --CHAIN hg19ToHg38.over.chain.gz \
+  -R GRCh38.fa \
+  --REJECT rejected.vcf.gz
+```
+
+Always inspect the `unmapped.bed` or `rejected.vcf.gz` — coordinates in regions that were restructured between assemblies cannot be lifted over reliably.
+
+## Common Organism References
+
+| Organism | Assembly | NCBI Accession |
+|----------|----------|----------------|
+| Human | GRCh38.p14 | GCA_000001405.29 |
+| Mouse | GRCm39 | GCA_000001635.9 |
+| Zebrafish | GRCz11 | GCA_000002035.4 |
+| Drosophila | dm6 | GCA_000001215.4 |
+| C. elegans | WBcel235 | GCA_000002985.3 |
+| E. coli K-12 | ASM584v2 | GCA_000005845.2 |
+| SARS-CoV-2 | ASM985889v3 | GCA_009858895.3 |
+| Arabidopsis | TAIR10.1 | GCA_000001735.2 |
+
+## Reference Download
+
+```bash
+# Human GRCh38 from NCBI
+wget https://ftp.ncbi.nlm.nih.gov/genomes/all/GCA/000/001/405/GCA_000001405.15_GRCh38/GCA_000001405.15_GRCh38_assembly_structure/Primary_Assembly/assembled_chromosomes/FASTA/chroms.tar.gz
+
+# Or via Ensembl (soft-masked)
+wget https://ftp.ensembl.org/pub/release-110/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
+```
+
+Ensembl FASTA uses chromosome names without `chr` prefix (e.g., `1`, `X`). UCSC/NCBI FASTAs use `chr1`, `chrX`. Ensure the chromosome naming convention matches your annotation files to avoid silently skipping records.

genomix/builtin_skills/comparative/blast-analysis/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: blast-analysis
+description: Select the correct BLAST program (blastn/blastp/blastx), set e-value thresholds, and interpret results
+version: 1.0.0
+author: genomix-cli
+license: Apache-2.0
+metadata:
+  genomix:
+    tags: [comparative, blast, blastn, blastp, blastx, similarity, e-value]
+    tools_used: [run_blast, ncbi_search]
+---
+
+# BLAST Analysis
+
+## Program Selection
+
+| Query | Database | Program |
+|-------|----------|---------|
+| Nucleotide | Nucleotide | blastn |
+| Protein | Protein | blastp |
+| Nucleotide (translated) | Protein | blastx |
+| Protein | Nucleotide (translated) | tblastn |
+| Nucleotide (translated) | Nucleotide (translated) | tblastx |
+
+Decision rules:
+- **blastn**: Comparing closely related sequences (same species, >70% identity), primer design, confirming PCR products.
+- **blastp**: Comparing protein sequences across species, finding orthologs, functional domain analysis.
+- **blastx**: Annotating novel nucleotide sequences (EST, genome contig) — finds protein homologs in 6-frame translation.
+- **tblastn**: Finding gene locations in an unannotated genome assembly using a known protein query.
+
+Avoid tblastx for large queries — it is computationally expensive.
+
+## E-value Interpretation
+
+The e-value (expect value) is the number of alignments of equal or better score expected by chance in a database of this size.
+
+| E-value | Interpretation |
+|---------|----------------|
+| < 1e-100 | Nearly identical sequences (>95% identity at full length) |
+| 1e-50 to 1e-100 | Very strong homology, high confidence |
+| 1e-10 to 1e-50 | Significant homology, likely true hit |
+| 1e-3 to 1e-10 | Moderate confidence, check alignment manually |
+| 0.01 to 1 | Weak hit, may be spurious — check length and identity |
+| > 1 | Likely noise, not significant |
+
+Default e-value cutoff is 10. For genomics, use `1e-5` as a starting filter; tighten to `1e-20` for confident functional annotation.
+
+## Key Result Fields
+
+- **% identity**: Fraction of aligned positions with exact match.
+- **query coverage**: Fraction of the query sequence in the alignment. Low coverage (<50%) with high identity often means domain hit rather than full-length homolog.
+- **bit score**: Normalized score independent of database size — use for ranking across runs.
+- **gaps**: High gap content with moderate identity may indicate divergent or frameshifted sequences.
+
+## Local BLAST Command Example
+
+```bash
+# Build local database
+makeblastdb -in proteins.fasta -dbtype prot -out mydb
+
+# Run blastp
+blastp \
+  -query query.fasta \
+  -db mydb \
+  -out results.txt \
+  -evalue 1e-10 \
+  -outfmt "6 qseqid sseqid pident length mismatch gapopen qstart qend sstart send evalue bitscore" \
+  -num_threads 8 \
+  -max_target_seqs 10
+```
+
+Format 6 (tabular) is easiest for downstream filtering. Always specify `-max_target_seqs` to avoid memory issues with large databases.

genomix/builtin_skills/comparative/multiple-alignment/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: multiple-alignment
+description: Perform multiple sequence alignment with MAFFT, choose the right algorithm, and interpret output
+version: 1.0.0
+author: genomix-cli
+license: Apache-2.0
+metadata:
+  genomix:
+    tags: [comparative, mafft, multiple-alignment, msa, phylogenetics]
+    tools_used: [run_command, read_file]
+---
+
+# Multiple Sequence Alignment with MAFFT
+
+## When to Use MAFFT
+
+Use multiple sequence alignment (MSA) when you need to:
+- Compare homologous sequences to identify conserved regions.
+- Prepare input for phylogenetic tree construction.
+- Detect insertions/deletions (indels) across taxa.
+- Find functional motifs conserved across species.
+
+MAFFT is preferred over Clustal Omega for most tasks: it scales to thousands of sequences and handles both protein and nucleotide input.
+
+## Algorithm Selection
+
+| Flag | Algorithm | Use When |
+|------|-----------|----------|
+| `--auto` | Auto-select | Default; let MAFFT decide based on input size |
+| `--localpair --maxiterate 1000` (L-INS-i) | Iterative local alignment | <200 sequences, highly accurate, long gaps expected |
+| `--globalpair --maxiterate 1000` (G-INS-i) | Iterative global alignment | <200 sequences, global homology throughout |
+| `--ep 0 --genafpair --maxiterate 1000` (E-INS-i) | Iterative with multiple conserved domains | <200 sequences, unalignable regions between conserved blocks |
+| `--retree 2 --maxiterate 0` (FFT-NS-2) | Progressive | >1000 sequences, speed is priority |
+
+For phylogenetics: use L-INS-i or G-INS-i on <200 sequences for best accuracy.
+
+## Basic Commands
+
+```bash
+# Protein alignment (auto mode)
+mafft --auto --thread 4 input.fasta > aligned.fasta
+
+# High-accuracy nucleotide alignment (<200 seqs)
+mafft --localpair --maxiterate 1000 --thread 4 input.fasta > aligned.fasta
+
+# Large dataset (>500 seqs)
+mafft --retree 2 --maxiterate 0 --thread 8 input.fasta > aligned.fasta
+```
+
+## Output Interpretation
+
+MAFFT outputs FASTA with gaps represented as `-`. All sequences are padded to the same length.
+
+Key things to check:
+- **Alignment length vs. average sequence length**: A ratio > 3x suggests many large insertions or misaligned sequences — consider removing outliers.
+- **Conserved columns**: Columns with identical residues across all sequences indicate functional/structural constraints.
+- **Gap-rich regions**: Highly gapped columns (>50% gaps) are often unreliable — mask them before phylogenetic analysis using trimAl or Gblocks.
+
+## Downstream Processing
+
+Before building a phylogenetic tree, trim poorly aligned columns:
+
+```bash
+trimal -in aligned.fasta -out trimmed.fasta -automated1
+```
+
+Visualize alignments with AliView or JalView to inspect quality before proceeding.

genomix/builtin_skills/comparative/phylogenetics/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: phylogenetics
+description: Build phylogenetic trees with FastTree, interpret Newick format, and assess bootstrap support
+version: 1.0.0
+author: genomix-cli
+license: Apache-2.0
+metadata:
+  genomix:
+    tags: [comparative, phylogenetics, fasttree, newick, tree-building]
+    tools_used: [run_command, read_file]
+---
+
+# Phylogenetic Tree Building with FastTree
+
+## When to Use FastTree
+
+FastTree approximates maximum-likelihood (ML) trees using neighbor-joining for an initial topology, then applies NNI (nearest-neighbor interchange) and SPR (subtree pruning/regrafting) moves. It is orders of magnitude faster than RAxML or IQ-TREE for large datasets (>500 sequences).
+
+Use FastTree when:
+- You have >200 sequences and need a result in minutes.
+- You need a quick exploratory tree before committing to a slower, more thorough method.
+
+Use IQ-TREE or RAxML when:
+- Accuracy is paramount (publication-quality tree with model selection).
+- Dataset is <500 sequences and run time is not a constraint.
+
+## Input Requirements
+
+FastTree requires a multiple sequence alignment in FASTA or PHYLIP format. Always trim the alignment first (see multiple-alignment skill).
+
+## Commands
+
+```bash
+# Nucleotide alignment (GTR+CAT model — default for DNA)
+FastTree -gtr -nt trimmed.fasta > tree.nwk
+
+# Protein alignment (WAG model)
+FastTree trimmed.fasta > tree.nwk
+
+# With 1000 bootstrap replicates (slower but adds confidence values)
+FastTree -gtr -nt -boot 1000 trimmed.fasta > tree.nwk
+```
+
+## Newick Format
+
+A Newick tree encodes topology and branch lengths as nested parentheses:
+
+```
+((A:0.1,B:0.2):0.05,(C:0.3,D:0.15):0.08);
+```
+
+- Each leaf is a sequence identifier.
+- Numbers after `:` are branch lengths (substitutions per site).
+- Numbers before `:` at internal nodes are bootstrap values (0–1 for FastTree; 0–100 for RAxML/IQ-TREE).
+- The semicolon terminates the tree.
+
+## Interpreting Bootstrap Support
+
+| Value (0–1 scale) | Interpretation |
+|-------------------|----------------|
+| ≥ 0.95 | Strong support — clade is well-resolved |
+| 0.70–0.94 | Moderate support — likely correct |
+| 0.50–0.69 | Weak support — treat with caution |
+| < 0.50 | Unresolved — do not over-interpret the clade |
+
+## Visualization
+
+Convert and visualize Newick trees with:
+- **FigTree** (GUI, free): color branches by bootstrap, midpoint-root.
+- **iTOL** (web): publication-quality with metadata overlays.
+- **ETE3** (Python): programmatic rendering.
+
+```python
+from ete3 import Tree
+t = Tree("tree.nwk")
+print(t.get_ascii(show_internal=True))
+```
+
+Always root the tree at an outgroup or by midpoint before interpreting topology.