We have reached the final part of our foundational refactor.

By the end of Part 4.6, the main Genome Toolkit flow already works:

FASTA
  ↓
SequenceRecord
  ↓
DNA
  ↓
algorithm(Sequence)
  ↓
structured result
    ├── metadata
    ├── inputs
    ├── parameters
    └── output

We now have a modern uv project, validated biological models, plain-text and FASTA loading, generic k-mer algorithms, and structured scientific results.

That is a big improvement over the small script we started with.

But before we leave the refactoring work behind and return to adding more bioinformatics, there is one important question left:

What happens when something goes wrong, and how do we make sure the behavior we already built keeps working as Genome Toolkit grows?

That is what Part 4.7 is about.

We are going to add a small set of meaningful Genome Toolkit errors, introduce automated tests with pytest, use those tests to discover a few real edge cases, fix only what the tests show us needs fixing, replace our old README with a practical final version, and then run one last verification of the project.

Our path looks like this:

working architecture
        ↓
clear error types
        ↓
automated tests
        ↓
tests expose hidden problems
        ↓
small focused fixes
        ↓
rerun tests
        ↓
README + documentation
        ↓
final verification
        ↓
PART 4 REFACTOR COMPLETE

The architecture is already doing its job. In this part, we are adding the reliability around it: clear errors, automated checks, and one final verification before we return to bioinformatics.

Before We Start: Two Useful Background Videos

We only need a small part of Python exception handling and pytest for this article, but both topics are important enough that they are worth understanding properly.

If exceptions or automated testing are completely new to you, I strongly recommend making a short detour before continuing. Spend some time learning what exceptions are, what tests do, how a simple test is written, and why developers run those tests again and again while software changes.

These two videos are a good starting point.

Python exceptions

Corey Schafer — Python Tutorial: Using Try/Except Blocks for Error Handling

https://youtu.be/NIWwJbo-9_8

pytest

Anthony Explains — getting started with pytest (beginner – intermediate)

https://youtu.be/mzlH8lp4ISA

You do not need to become a testing expert before continuing with us.

We will explain every pytest feature we actually use. The reason for the detour is simply that testing is a normal part of building serious software, and it becomes especially important for scientific software. If somebody uses our toolkit for an experiment, we want them to know that the code was not only written and manually tried a few times, but that important behavior is also checked automatically.

Tests will not prove that every scientific result is biologically correct. We will come back to that distinction later. What they give us is a repeatable way to check the software behavior we have deliberately defined.

What Are We Changing?

Part 4.7 adds one small module to the package:

src/genome_toolkit/exceptions.py

and one new top-level directory:

tests/

We will also update:

src/genome_toolkit/load/text.py
src/genome_toolkit/load/fasta.py
src/genome_toolkit/algorithms/kmer.py
README.md
pyproject.toml
uv.lock

Our biological models, structured-result design, and the experiment workflow from Part 4.6 stay in place.

There is one useful design idea to keep in mind.

Genome Toolkit should understand failures that belong to Genome Toolkit itself. For example:

this FASTA file is malformed
this biological record does not exist
this algorithm parameter does not make sense

A future user interface can decide how to present those failures.

That future interface could be:

a Python script
a web application
an API
an AI agent
another scientific tool

Genome Toolkit should simply report the scientific or data-processing problem clearly. We do not need to put web-server logic, AI-agent logic, or user-interface behavior inside the scientific package.

1. Add Clear Genome Toolkit Exception Types

Before we write the tests, let us make one small improvement to the errors Genome Toolkit can report.

Python already gives us useful built-in exceptions such as:

FileNotFoundError
PermissionError
ValueError

Pydantic gives us:

ValidationError

We are keeping all of those where they already describe the problem clearly.

The problem is that ValueError can mean many different things. For example:

the caller used a function incorrectly
the FASTA source is malformed
the requested biological record does not exist
an algorithm parameter does not make sense

For a small script, reading the message may be enough.

For a library that may later be used by another Python program, a web API, an MCP tool, or an AI agent, it is useful to distinguish these failures by their Python type as well.

The professional name for what we are adding is custom domain exceptions.

They are normal Python exception classes whose names describe failures that have specific meaning inside Genome Toolkit.

You can also think of them as clearer labels for different kinds of problems:

FormatError
→ the source data has the wrong structure

RecordNotFoundError
→ the source is valid, but the requested record is missing

AlgorithmInputError
→ an algorithm parameter is outside the supported domain

Create:

src/genome_toolkit/exceptions.py    # <-- NEW

with:

"""Genome Toolkit domain exceptions."""


class GenomeToolkitError(Exception):
    """Base exception for Genome Toolkit domain errors."""


class FormatError(GenomeToolkitError):
    """Input data does not follow the expected format."""


class RecordNotFoundError(GenomeToolkitError):
    """Requested biological record was not found."""


class AlgorithmInputError(GenomeToolkitError):
    """Algorithm parameter is outside its supported domain."""

These classes deliberately contain no extra machinery.

GenomeToolkitError gives us one common base class. The three subclasses give callers a more specific category when something goes wrong.

We will use this simple rule:

file does not exist
→ FileNotFoundError

permission denied
→ PermissionError

DNA model validation fails
→ Pydantic ValidationError

caller misuses a Python function
→ ValueError where appropriate

source data has the wrong format
→ FormatError

requested biological record does not exist
→ RecordNotFoundError

algorithm parameter is outside the supported domain
→ AlgorithmInputError

That is enough for the scientific package.

A future API, web application, or AI agent can decide how it wants to present those errors to an end user.

2. Add pytest as a Development Dependency

Now let us add the tool that will run our automated tests.

From the Genome Toolkit project root, run:

uv add --dev pytest

The important part is:

--dev

That tells uv that pytest is a development dependency.

We need pytest while we are building and checking Genome Toolkit, but somebody using the scientific package does not need pytest just to run its algorithms.

After the command, expect these two files to change:

pyproject.toml    # <-- UPDATED
uv.lock           # <-- UPDATED

This also makes the development environment reproducible.

Having pytest installed inside one existing .venv is not enough. Declaring it in the project means another machine can run:

uv sync

and get the testing dependency too.

We can quickly verify that pytest is available:

uv run pytest --version

Now we are ready to write our first automated checks.

3. Start With Two Simple DNA Tests

We will start with the easiest part of Genome Toolkit.

Our DNA model already works, and these tests do not require any implementation changes.

Create:

tests/
└── test_sequence.py    # <-- NEW

3.1 Check That DNA Keeps Its Identifier and Normalizes the Sequence

Start with the import we need:

from genome_toolkit.sequence import DNA

Then add:

def test_dna_preserves_identifier_and_normalizes_sequence() -> None:
    """Check that DNA keeps the identifier we provide
    and converts lowercase sequence symbols to uppercase.
    """
    dna = DNA(
        identifier="example",
        sequence="acgtn",
    )

    assert dna.identifier == "example"
    assert dna.sequence == "ACGTN"

This gives us one small permanent check for two pieces of normal DNA behavior:

identifier
→ preserved

sequence
→ normalized to uppercase

Run:

uv run pytest tests/test_sequence.py -v

The -v means verbose. It tells pytest to show the individual test names.

We should see:

test_dna_preserves_identifier_and_normalizes_sequence PASSED

3.2 Check That Invalid DNA Still Fails

Now we want to check the opposite case.

This test needs pytest and Pydantic’s ValidationError, so this is the point where we add those imports:

import pytest
from pydantic import ValidationError

from genome_toolkit.sequence import DNA

Add:

def test_dna_rejects_invalid_symbols() -> None:
    """Check that DNA refuses sequence symbols outside
    the alphabet supported by our DNA model.
    """
    with pytest.raises(ValidationError):
        DNA(
            identifier="example",
            sequence="ACGTZ",
        )

pytest.raises(ValidationError) means that this failure is the expected behavior.

If ACGTZ suddenly becomes valid DNA in our model, the test should fail.

Run again:

uv run pytest tests/test_sequence.py -v

Both tests should pass.

We now have a working pytest setup and our first automated checks.

4. Update the Loader Error Types Before Testing the Loaders

Before we write tests for text.py and fasta.py, we want those loaders to use the clearer exception types we just created.

The important point is that we are not rewriting the loaders.

We are changing only the places where an existing generic ValueError has a more useful Genome Toolkit meaning.

This lets us finish each source file once and then stay inside the test file while we verify the behavior.

4.1 Update text.py

Open:

src/genome_toolkit/load/text.py

This file now needs FormatError, so add:

from genome_toolkit.exceptions import FormatError

The plain-text loader already checks whether the file contains usable sequence data.

Change this:

if not sequence:
    raise ValueError(
        f"'{path}' does not contain sequence data."
    )

to this:

if not sequence:
    raise FormatError(
        f"'{path}' does not contain sequence data."
    )

The meaning is now more specific:

file exists
but contains no usable sequence
→ FormatError

A missing path still naturally raises:

FileNotFoundError

Python already describes that case correctly, so we do not catch or wrap it.

Because this is a public function, make sure its Raises: documentation matches the new behavior:

Raises:
    FormatError: If the file does not contain usable sequence data.

That completes the Part 4.7 change in text.py.

4.2 Update fasta.py

Now open:

src/genome_toolkit/load/fasta.py

The FASTA loader needs two of our new exception types:

from genome_toolkit.exceptions import (
    FormatError,
    RecordNotFoundError,
)

The rule is:

bad FASTA structure or unusable FASTA data
→ FormatError

valid FASTA, requested record does not exist
→ RecordNotFoundError

caller misused the Python function
→ ValueError

We only need to update the existing failure branches.

_parse_header(): Blank Header

Change:

if not header:
    raise ValueError(
        "A FASTA header must contain a sequence identifier."
    )

to:

if not header:
    raise FormatError(
        "A FASTA header must contain a sequence identifier."
    )

Here header is singular because _parse_header() is checking one FASTA header.

get_headers(): Sequence Before the First Header

Change:

elif not headers:
    raise ValueError(
        f"'{path}' does not begin with a FASTA header."
    )

to:

elif not headers:
    raise FormatError(
        f"'{path}' does not begin with a FASTA header."
    )

get_headers(): No FASTA Records

Change:

if not headers:
    raise ValueError(
        f"'{path}' does not contain FASTA records."
    )

to:

if not headers:
    raise FormatError(
        f"'{path}' does not contain FASTA records."
    )

Here headers is plural because get_headers() owns the list of discovered records.

get_sequence(): Sequence Before Any Header

Change:

if not seen_header:
    raise ValueError(
        f"'{path}' does not begin with a FASTA header."
    )

to:

if not seen_header:
    raise FormatError(
        f"'{path}' does not begin with a FASTA header."
    )

get_sequence(): Requested Record Is Missing

Change the existing missing-record error from ValueError to RecordNotFoundError:

if selected_identifier is None:
    target = (
        identifier
        if identifier is not None
        else f"index {index}"
    )

    raise RecordNotFoundError(
        f"No sequence found matching '{target}' in '{path}'."
    )

The FASTA source itself may be perfectly valid here. The requested record simply is not present.

get_sequence(): Selected Record Has No Sequence

Keep the existing check, but report it as a format problem:

if not sequence:
    raise FormatError(
        f"Sequence '{selected_identifier}' in '{path}' "
        "does not contain sequence data."
    )

We still keep ordinary ValueError for direct Python API misuse:

both identifier and index supplied
neither selector supplied
blank identifier
negative index

Finally, make sure the public Raises: documentation agrees with the implementation:

Raises:
    ValueError: If both selectors or neither selector is provided,
        `identifier` is empty, or `index` is negative.
    FormatError: If the FASTA structure is invalid or the selected
        record contains no sequence data.
    RecordNotFoundError: If the requested identifier or index does
        not exist.

That completes the Part 4.7 changes in fasta.py.

We do not need to return to either loader again.

5. Test the Loaders

Now we can stay inside one file:

tests/test_load.py

We will add the tests one at a time.

The short docstring inside each test explains exactly what behavior we are checking, so we do not need a paragraph of theory around every function.

5.1 Plain-text Loading

Start with:

from pathlib import Path

from genome_toolkit.load import text

Add:

def test_text_loader_reads_wrapped_sequence(
    tmp_path: Path,
) -> None:
    """Check that sequence text spread across multiple lines
    and spaces is joined into one clean sequence.
    """
    path = tmp_path / "sample.txt"

    path.write_text(
        """
         AATT
           TTAA
          AAC
        """,
        encoding="utf-8",
    )

    record = text.get_sequence(path)

    assert record.sequence == "AATTTTAAAAC"

The only new pytest feature here is:

tmp_path

tmp_path is a pytest fixture that gives this test a temporary directory.

We can create realistic little files there without adding disposable test files to the repository.

Run:

uv run pytest tests/test_load.py -v

Expected:

test_text_loader_reads_wrapped_sequence PASSED

5.2 FASTA Header Discovery

We are using fasta for the first time in this file, so update the import:

from genome_toolkit.load import fasta, text

Add:

def test_fasta_discovers_headers(
    tmp_path: Path,
) -> None:
    """Check that get_headers() finds every FASTA record
    and returns each identifier and description in file order.
    """
    path = tmp_path / "sample.fasta"

    path.write_text(
        """
        >first one
        AAAA
        >second two
        CCCC
        """,
        encoding="utf-8",
    )

    headers = fasta.get_headers(path)

    assert headers == [
        ("first", "one"),
        ("second", "two"),
    ]

Run again:

uv run pytest tests/test_load.py -v

Both tests should pass.

5.3 Select a FASTA Record by Identifier

Add:

def test_fasta_selects_record_by_identifier(
    tmp_path: Path,
) -> None:
    """Check that get_sequence() can find the requested FASTA record
    by identifier and return its identifier, description, and sequence.
    """
    path = tmp_path / "sample.fasta"

    path.write_text(
        """
        >first one
        AAAA
        >second two
        CCCC
        """,
        encoding="utf-8",
    )

    record = fasta.get_sequence(
        path,
        identifier="second",
    )

    assert record.identifier == "second"
    assert record.description == "two"
    assert record.sequence == "CCCC"

Run again:

uv run pytest tests/test_load.py -v

Expected: green.

5.4 Select a FASTA Record by Index

Add:

def test_fasta_selects_record_by_index(
    tmp_path: Path,
) -> None:
    """Check that get_sequence() can select a FASTA record
    by its zero-based position in the file.
    """
    path = tmp_path / "sample.fasta"

    path.write_text(
        """
        >first one
        AAAA
        >second two
        CCCC
        """,
        encoding="utf-8",
    )

    record = fasta.get_sequence(
        path,
        index=1,
    )

    assert record.identifier == "second"
    assert record.sequence == "CCCC"

Run again.

Expected: green.

5.5 Test the Loader Error Types

Now this file needs pytest and our two loader exceptions, so add them now:

import pytest

from genome_toolkit.exceptions import (
    FormatError,
    RecordNotFoundError,
)

First, an empty plain-text file:

def test_text_loader_rejects_empty_file(
    tmp_path: Path,
) -> None:
    """Check that an existing text file with no sequence data
    is reported as a Genome Toolkit format problem.
    """
    path = tmp_path / "empty.txt"
    path.write_text("", encoding="utf-8")

    with pytest.raises(FormatError):
        text.get_sequence(path)

Next, malformed FASTA:

def test_fasta_rejects_invalid_format(
    tmp_path: Path,
) -> None:
    """Check that sequence data appearing before the first FASTA header
    is rejected as malformed FASTA input.
    """
    path = tmp_path / "invalid.fasta"

    path.write_text(
        """
        ACGT
        """,
        encoding="utf-8",
    )

    with pytest.raises(FormatError):
        fasta.get_headers(path)

Finally, a valid FASTA file with a missing requested record:

def test_fasta_reports_missing_record(
    tmp_path: Path,
) -> None:
    """Check that valid FASTA raises RecordNotFoundError
    when the requested sequence identifier does not exist.
    """
    path = tmp_path / "sample.fasta"

    path.write_text(
        """
        >first
        AAAA
        """,
        encoding="utf-8",
    )

    with pytest.raises(RecordNotFoundError):
        fasta.get_sequence(
            path,
            identifier="missing",
        )

Run:

uv run pytest tests/test_load.py -v

All loader tests should now be green.

We have checked:

wrapped plain text
→ PASS

FASTA header discovery
→ PASS

FASTA selection by identifier
→ PASS

FASTA selection by index
→ PASS

empty plain text
→ FormatError

malformed FASTA
→ FormatError

missing FASTA record
→ RecordNotFoundError

That finishes the loading layer.

6. Test the K-mer Algorithms

Now let us move to:

tests/test_kmer.py

There is one important difference from the loaders.

The loaders already had explicit failure branches that we could simply give better exception types.

The k-mer algorithms do not yet have equivalent explicit checks for all of the edge cases we want to test.

If we changed kmer.py first, we would hide the useful part where pytest actually exposes the missing behavior.

So we will stay in the test file, add the reasonable tests, run them, and only then return to kmer.py once.

6.1 Make Sure Overlapping Counting Still Works

Start with:

from genome_toolkit.algorithms import count_kmer
from genome_toolkit.sequence import DNA

Add:

def test_count_kmer_counts_overlaps() -> None:
    """Check that count_kmer() includes overlapping matches
    instead of skipping positions after the first match.
    """
    dna = DNA(
        identifier="overlap",
        sequence="AAAAA",
    )

    result = count_kmer(
        dna,
        "AAA",
    )

    assert result.output.count == 3

For:

AAAAA

the k-mer:

AAA

appears three times:

AAA..
.AAA.
..AAA

Run:

uv run pytest tests/test_kmer.py -v

Expected:

test_count_kmer_counts_overlaps PASSED

This is a regression test for behavior that already works.

6.2 Try a Lowercase k-mer

Add:

def test_count_kmer_normalizes_lowercase_kmer() -> None:
    """Check that lowercase input represents the same biological k-mer
    and that the result records the normalized uppercase parameter.
    """
    dna = DNA(
        identifier="example",
        sequence="AAAAA",
    )

    result = count_kmer(
        dna,
        "aaa",
    )

    assert result.output.count == 3
    assert result.parameters.kmer == "AAA"

Do not change the algorithm yet.

6.3 Try an Empty k-mer

This is the first algorithm test that needs pytest and AlgorithmInputError, so add:

import pytest

from genome_toolkit.exceptions import AlgorithmInputError

Then add:

def test_count_kmer_rejects_empty_kmer() -> None:
    """Check that an empty string is rejected because it cannot
    represent a meaningful k-mer for this algorithm.
    """
    dna = DNA(
        identifier="example",
        sequence="ACGT",
    )

    with pytest.raises(AlgorithmInputError):
        count_kmer(
            dna,
            "",
        )

Again, do not change kmer.py yet.

6.4 Check the Normal Most-frequent-k-mer Result

We now use the second algorithm, so update the algorithm import:

from genome_toolkit.algorithms import (
    count_kmer,
    find_most_frequent_kmers,
)

Add:

def test_frequent_kmers_returns_kmers_and_frequency() -> None:
    """Check that the algorithm returns the most frequent k-mer
    together with the number of times it occurs.
    """
    dna = DNA(
        identifier="example",
        sequence="AAATTTAAA",
    )

    result = find_most_frequent_kmers(
        dna,
        k_len=3,
    )

    assert result.output.kmers == ["AAA"]
    assert result.output.frequency == 2

The frequency field already exists from Part 4.6.

This test is only protecting the result we already built.

6.5 Try Invalid k_len Values

For a sequence with length 4, these are useful boundary values:

0
-1
5

Instead of writing three nearly identical test functions, we can use pytest parametrization.

Add:

@pytest.mark.parametrize(
    "k_len",
    [
        0,
        -1,
        5,
    ],
)
def test_frequent_kmers_rejects_invalid_length(
    k_len: int,
) -> None:
    """Check that zero, negative, and too-large k-mer lengths
    are all rejected with the same algorithm input error.
    """
    dna = DNA(
        identifier="example",
        sequence="ACGT",
    )

    with pytest.raises(AlgorithmInputError):
        find_most_frequent_kmers(
            dna,
            k_len,
        )

@pytest.mark.parametrize() tells pytest to run the same test several times with different values.

Conceptually, this one function becomes:

test with k_len = 0
test with k_len = -1
test with k_len = 5

Now run the file:

uv run pytest tests/test_kmer.py -v

The normal behavior stays green, but the new edge cases expose three issue groups:

overlapping count_kmer()
→ PASS

lowercase k-mer
→ FAIL

empty k-mer
→ FAIL

normal find_most_frequent_kmers()
→ PASS

invalid k_len values
→ FAIL

The lowercase case is a real correctness bug.

Our validated sequence is uppercase:

"AAA"

but the algorithm compares it directly with:

"aaa"

so the strings do not match.

The empty k-mer is different. Python can operate on an empty string, but an empty string is not a meaningful k-mer for this algorithm.

The invalid k_len values are another undefined boundary. We should reject them deliberately instead of relying on strange slicing behavior or a later generic Python error.

Now we know exactly what to change.

7. Fix the K-mer Edge Cases

Open:

src/genome_toolkit/algorithms/kmer.py

This is the first time the implementation itself needs AlgorithmInputError, so add:

from genome_toolkit.exceptions import AlgorithmInputError

7.1 Fix count_kmer()

Before the existing calculation, add:

if not kmer:
    raise AlgorithmInputError(
        "'kmer' must not be empty."
    )

kmer = kmer.upper()

The first check rejects an input that has no meaningful k-mer interpretation.

The second line normalizes the parameter once so both the comparison and the structured result use the same uppercase form.

Update the relevant public docstring lines so the behavior is visible to callers:

Args:
    sequence: Validated biological sequence to search.
    kmer: K-mer to count. The value is normalized to uppercase.

Raises:
    AlgorithmInputError: If `kmer` is empty.

A k-mer longer than the sequence can still naturally return:

0

so we do not invent another error for that case.

7.2 Fix find_most_frequent_kmers()

Before the existing frequency calculation, add:

if k_len <= 0:
    raise AlgorithmInputError(
        "'k_len' must be greater than zero."
    )

if k_len > len(sequence):
    raise AlgorithmInputError(
        "'k_len' must not be greater than the sequence length."
    )

These checks define the supported algorithm domain before the calculation starts.

Update its Raises: documentation too:

Raises:
    AlgorithmInputError: If `k_len` is not greater than zero or is
        greater than the sequence length.

We do not add DNA-specific alphabet validation here.

These algorithms accept the shared Sequence model and may later be useful with other biological sequence types.

Now rerun:

uv run pytest tests/test_kmer.py -v

Everything in test_kmer.py should be green.

8. Run the Complete Test Suite

While working on one area, a focused command is convenient:

uv run pytest tests/test_kmer.py -v

Before we finish, run everything:

uv run pytest -v

The complete suite checks:

sequence models
loaders
algorithms
expected errors

This gives us one repeatable command we can run whenever Genome Toolkit changes.

Tests do not prove that an algorithm is scientifically correct.

Scientific correctness may still require known reference results, published methods, benchmarking, comparisons with trusted implementations, and biological validation.

What pytest gives us is a repeatable engineering check that the software still behaves the way we deliberately defined.

9. Run the Same Tests From VS Code

Everything we have done so far works directly from the terminal:

uv run pytest -v

That command remains our simplest universal way to run the complete test suite because it works regardless of which editor we use.

If you use VS Code or VSCodium, we can also connect the editor to the same pytest tests. This gives us a visual list of the tests and lets us run the whole suite, one test file, or one individual test without typing the command each time.

This is still the same pytest setup we have already built. VS Code is only giving us a graphical interface around it.

9.1 Configure Python Tests and Choose pytest

Open the Testing panel from the activity bar on the left.

If testing has not been configured for this workspace yet, VS Code will show:

Configure Python Tests

Click it and choose:

pytest

We already installed pytest with:

uv add --dev pytest

so we are not installing a second testing framework here. We are simply telling VS Code which framework our project already uses.

9.2 Tell VS Code Where Our Tests Live

Next, VS Code asks us to select the directory that contains the tests.

Choose:

tests

That is the directory we created in this article:

tests/
├── test_kmer.py
├── test_load.py
└── test_sequence.py

After we select it, VS Code can discover the pytest tests inside those files.

9.3 Run the Complete Test Suite From the Testing Panel

Once discovery finishes, the Testing panel shows our test files and the individual tests inside them.

We can run the complete suite by clicking the Run Test button at the top level of the project.

In our current project, VS Code discovers all of the tests we created in this article. A green check beside a test means its latest run passed.

This is the graphical equivalent of running:

uv run pytest -v

The terminal command is still useful and remains the command we can rely on in any editor, CI system, or remote environment.

9.4 Run One Test File or One Individual Test

We do not always need to run everything.

From the Testing panel, we can run:

the complete test suite
one test file
one individual test

We can also work directly inside a test file. VS Code shows a small test-status control beside discovered test functions. After a successful run it appears as a green check, and we can use that control to run that individual test again.

For example, while working on:

test_frequent_kmers_returns_kmers_and_frequency()

we can run only that test instead of running all sixteen tests.

This becomes especially useful as the project grows. While changing one algorithm, we can quickly run its focused test, then run the complete suite before we finish.

9.5 Ignore Local VS Code Settings

Configuring Python tests in VS Code creates workspace-specific editor settings inside:

.vscode/

Those settings are useful on our own machine, but they are editor-specific and are not part of Genome Toolkit itself.

Open:

.gitignore

and add .vscode under the local environment section.

Our .gitignore now becomes:

# Python-generated files

__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments

.venv
.vscode

This keeps Python-generated files, the local virtual environment, and our local VS Code workspace settings out of the Git repository.

The two ways of running our tests now look like this:

terminal
→ uv run pytest -v

VS Code / VSCodium
→ Testing panel
→ run all tests, one file, or one test

Both use the same pytest tests in the same tests/ directory.

10. Replace README.md With the Final Project README

We have changed Genome Toolkit quite a lot during Part 4.

The README should now describe the project we actually have without turning into another tutorial.

A new reader mainly needs to know:

what Genome Toolkit is
what it can currently do
how to install uv
how to set up the project
how to run the application
how to run the tests

Open:

README.md

and replace its contents with:

# Genome Toolkit

Genome Toolkit is a small Python bioinformatics toolkit for working with DNA sequences and learning how common bioinformatics algorithms work.

## Current capabilities

- Represent and validate DNA sequences
- Load sequences from plain-text files
- Read FASTA files
- Select FASTA sequences by identifier or index
- Count occurrences of a k-mer
- Find the most frequent k-mers in a DNA sequence

## Requirements

The project uses [uv](https://docs.astral.sh/uv/) for Python, dependency, and virtual-environment management.

### Install uv

#### Linux

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

#### macOS

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

#### Windows

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Verify the installation:

```bash
uv --version
```

## Installation

Clone the repository:

```bash
git clone https://github.com/rebelC0der/Genome_Toolkit.git
cd Genome_Toolkit
```

Synchronize the environment:

```bash
uv sync
```

`uv` creates and manages the project's virtual environment automatically.

## Running Genome Toolkit

Run the development application:

```bash
uv run application.py
```

Run the complete tests:

```bash
uv run pytest -v
```

## Repository

Genome Toolkit is developed as an educational bioinformatics project focused on simple, readable implementations of biological data handling and algorithms.

The outer example uses four backticks because the README itself contains normal three-backtick code blocks.

We are not adding an examples/ directory in Part 4.7.

application.py remains our development and experiment playground.

11. Final Project Structure

After this final reliability pass, our project looks like this:

Genome_Toolkit/
├── .gitignore                         # <-- UPDATED
├── README.md                         # <-- UPDATED
├── application.py
├── pyproject.toml                    # <-- UPDATED
├── uv.lock                           # <-- UPDATED
├── samples/
│   ├── sample.txt
│   └── sample.fasta
├── tests/                            # <-- NEW
│   ├── test_kmer.py                  # <-- NEW
│   ├── test_load.py                  # <-- NEW
│   └── test_sequence.py              # <-- NEW
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── exceptions.py             # <-- NEW
        ├── py.typed
        ├── algorithms/
        │   ├── __init__.py
        │   ├── base.py
        │   └── kmer.py               # <-- UPDATED
        ├── load/
        │   ├── __init__.py
        │   ├── fasta.py              # <-- UPDATED
        │   ├── records.py
        │   └── text.py               # <-- UPDATED
        └── sequence/
            ├── __init__.py
            ├── base.py
            └── dna.py

Every new file now has a clear reason to exist:

exceptions.py
→ clear Genome Toolkit-specific failures

tests/
→ repeatable checks around the package

We have not added extra architecture just to make the project look more complicated.

12. Final Verification

We are ready for one last check.

First, synchronize the environment:

uv sync

Then run every test:

uv run pytest -v

Finally, run the application again:

uv run application.py

We can consider the foundational refactor complete when:

package syncs
tests pass
application runs
README explains setup

Why run application.py if we already have tests?

Because they answer slightly different questions.

The tests check specific pieces of behavior automatically.

application.py still gives us a complete real workflow:

FASTA
  ↓
SequenceRecord
  ↓
DNA
  ↓
algorithms
  ↓
structured scientific results

Running both gives us more confidence than relying on only one of them.

Summary

Part 4.7 finishes the reliability and usability work around our Genome Toolkit refactor.

We added four small exception classes:

GenomeToolkitError
FormatError
RecordNotFoundError
AlgorithmInputError

Together they give Genome Toolkit a simple error contract: a predictable way to tell other code what kind of package-level problem happened.

We kept normal Python and Pydantic exceptions where they already made sense.

Then we added pytest and wrote tests for the three main parts of our package:

sequence models
loaders
k-mer algorithms

The interesting part was that testing did not only confirm what already worked.

Our normal cases stayed green:

overlapping count_kmer()
→ PASSED

normal find_most_frequent_kmers()
→ PASSED

But reasonable edge cases found things our manual experiments had missed:

lowercase k-mer
→ FAILED
→ normalize it once

empty k-mer
→ FAILED
→ reject it clearly

invalid k_len
→ FAILED
→ define the valid range

That is exactly the kind of feedback we want from automated tests.

We also connected the same pytest suite to VS Code / VSCodium, added .vscode to .gitignore, replaced the README with a much more useful project landing page, and ran one final project verification.

Genome Toolkit now has:

modern package structure
validated biological objects
FASTA and plain-text loaders
generic k-mer algorithms
structured scientific results
clear Genome Toolkit errors
automated tests
practical setup documentation

The foundation is finished.

New Concepts We Learned

• Exception — The normal Python mechanism for reporting that something went wrong.

• Custom exception — An exception class we create ourselves when a problem has specific meaning inside our own project.

• Domain exception — Another way of saying a custom error that describes a problem from our problem area. For Genome Toolkit, examples include malformed biological data or a missing biological record.

• Error contract — The small, predictable set of exception types our package intentionally uses so other code can understand what kind of failure happened.

• pytest — The testing framework we use to discover and run automated Python tests.

• Development dependency — A package we need while developing or testing Genome Toolkit, but not simply to use its scientific functions.

• Test — Code that runs part of our project and checks whether the result matches what we expect.

• Arrange, Act, Assert — Prepare the input, run the code, and check the result.

• pytest.raises() — A pytest tool for checking that code raises the exception we expect.

• Fixture — Something pytest prepares for a test automatically. We used tmp_path to get a temporary directory for test files.

• Parametrization — Running one test several times with different input values.

• Regression test — A test for something that already works, kept so a future change does not accidentally break that feature.

• Edge case — An unusual but important input near the limits of what a function is expected to handle.

The main lesson is simple:

Tests do not prove that our biology is correct. They give us repeatable checks that our software behaves the way we have defined, and they help us catch accidental changes before those changes reach a real experiment.

What is Next?

Part 4 is complete.

PART 4
FOUNDATIONAL REFACTOR COMPLETE

        ↓

PART 5+
EXPAND THE SCIENCE

That means our focus can now shift back toward bioinformatics.

Instead of repeatedly restructuring the package, we can use the structure we already built to add more science.

A future algorithm can follow a simple rhythm:

BIOLOGICAL QUESTION

What are we trying to learn or calculate?
Why is it biologically useful?

        ↓

RESULT

What information should the algorithm return?

        ↓

IMPLEMENT

Build the algorithm inside Genome Toolkit.

        ↓

TEST

Test normal inputs.
Try important edge cases.
Check expected failures.

        ↓

EXPERIMENT

Run it on representative or real biological data.
Compare parameters and results.

        ↓

REPEAT

That is the workflow we want to carry into Part 5.

When several algorithms eventually form a genuinely useful workflow, we can keep that workflow in a dedicated example. Until then, application.py remains our place for development and experiments.

As Genome Toolkit grows, we may also open it more broadly so other developers or researchers can contribute algorithms and improvements. And later, the toolkit may be used through other interfaces such as an API or an AI agent.

The important thing is that those future tools can now build on a package whose main features and errors are much clearer and much better tested.

The full source code for Genome Toolkit is available here:

https://github.com/rebelC0der/Genome_Toolkit

I hope adding clear errors, learning how automated tests can expose problems we missed manually, and completing the Genome Toolkit foundation was useful for your bioinformatics and programming journey! If you found this article valuable and want to help us continue building rebelScience, please consider supporting our project. You can explore various ways to contribute here:

https://rebelscience.club/cryptocurrency-donations/

Until next time, rebelCoder, signing out.

References

• Corey Schafer — Python Tutorial: Using Try/Except Blocks for Error Handling https://youtu.be/NIWwJbo-9_8

• Anthony Explains — getting started with pytest (beginner – intermediate) https://youtu.be/mzlH8lp4ISA

• pytest documentation https://docs.pytest.org/

• pytest parametrization https://docs.pytest.org/en/stable/how-to/parametrize.html

• uv development dependencies https://docs.astral.sh/uv/concepts/projects/dependencies/

• uv installation https://docs.astral.sh/uv/getting-started/installation/

• VS Code Python testing https://code.visualstudio.com/docs/python/testing

Video version:

In Part 4.5, we completed the basic input side of Genome Toolkit. We can now load a real multi-record FASTA file, select one record, convert the neutral SequenceRecord into a validated DNA model, and pass its sequence into our existing k-mer algorithms.

Our current workflow is:

FASTA
  ↓
SequenceRecord
  ↓
DNA
  ↓
dna.sequence
  ↓
count_kmer()
find_most_frequent_kmers()

The calculations already work.

In Part 4.6, we are not replacing those algorithms or making the mathematics more complicated. We are making the information going into and coming out of them more consistent, reliable, and useful for scientific work.

We will see the complete before-and-after picture in a moment, then build that change one small piece at a time.

What Are We Trying to Achieve?

Before Part 4.6, the two algorithms look conceptually like this:

count_kmer()

plain string
"AATTTTAAAAC"

+

plain string
"AA"

↓

algorithm

↓

integer
4

and:

find_most_frequent_kmers()

plain string
"AATTTTAAAAC"

+

integer
3

↓

algorithm

↓

list[str]
["TTT", "AAA"]

There is nothing wrong with those calculated values.

The problem is that the result itself does not know where it came from.

If we save:

4

or:

["TTT", "AAA"]

we have lost most of the context that made those values meaningful.

After Part 4.6, the flow becomes:

FASTA file
    ↓
SequenceRecord
    ↓
validated DNA
    ↓
algorithm
    ↓
structured scientific result

The algorithm can still give us the simple value:

# Read only the calculated count from the structured result.
count_result.output.count

or:

# Read only the most frequent k-mer list from the structured result.
frequency_result.output.kmers

but the same result object also contains:

metadata
inputs
parameters
output

That is the entire goal of this part.

For Genome Toolkit today, that validated object is our DNA model.

Later, when we add other biological models such as RNA or Protein, generic algorithms that only need sequence behavior will be able to work with those too.

The FASTA file itself does not validate the biology. Our loader reads FASTA structure and returns a neutral SequenceRecord. The biological model then validates the sequence before the algorithm receives it:

FASTA
  ↓
SequenceRecord
  ↓
DNA validation
  ↓
algorithm

So by the time count_kmer() receives our object, we are no longer handing it an arbitrary string with no biological context.

The Result Shape

Before we build the models, let us define one word we will use throughout this part: metadata.

Metadata simply means data that describes other data. Our calculated result might be 4, but metadata gives us additional information that helps explain that result, such as which algorithm produced it, which Genome Toolkit version was used, and when the calculation happened. It does not change the scientific result itself. It gives that result useful context.

In Genome Toolkit, the calculated value belongs under output, while metadata describes the execution that produced it.

We want every successful Genome Toolkit algorithm result to use the same top-level vocabulary:

metadata
inputs
parameters
output

For count_kmer(), that will look like:

{
  "metadata": {
    "toolkit_version": "0.1.0",
    "algorithm": "count_kmer",
    "timestamp": "<UTC timestamp>"
  },
  "inputs": {
    "sequence": {
      "identifier": "original_example",
      "description": "Original Genome Toolkit test sequence",
      "length": 11
    }
  },
  "parameters": {
    "kmer": "AA"
  },
  "output": {
    "count": 4
  }
}

The result is larger than:

4

but now we know what that 4 actually belongs to.

And when we only want the number, we still write:

# Access the simple calculated count when the extra context is not needed.
result.output.count

So we get both:

simple access
+
full scientific context

Why Use Explicit Result Models?

At first, creating several small Pydantic models for one algorithm may look like unnecessary code.

Inside the calculation, we still use ordinary Python values:

int
str
list
dict

We do not create classes for local counters, dictionaries, loops, or intermediate values.

The models appear only at the important algorithm boundary, where they give us:

predictable fields
runtime validation
attribute access
serialization
JSON Schema
stable API / MCP contracts

Some models currently contain only one field. That is intentional. They define stable sections of a scientific result, not internal algorithm state.

So the rule is simple:

inside the calculation
→ plain Python

at important boundaries
→ explicit typed models

Yes, this creates a little more code. But the repetition is visible and predictable, and each class has one small job. We will only introduce more automation if future algorithms show us, with real evidence, that another abstraction would actually make the code easier to maintain.

Why Keep inputs, parameters, and output Separate?

The distinction is practical.

The biological sequence is the object being analyzed:

inputs.sequence

The k-mer is a setting chosen for this calculation:

parameters.kmer

And the count is what the algorithm calculated:

output.count

For example:

same DNA
  +
kmer = "AA"
  ↓
count = 4

and:

same DNA
  +
kmer = "TT"
  ↓
different result

The biological input stayed the same.

The parameter changed.

A future algorithm may have two biological inputs, or completely different parameters, but it can still follow the same top-level result vocabulary.

Why Will the Algorithms Accept Sequence?

Our k-mer functions currently accept:

# Before Part 4.6, the algorithm accepted a plain sequence string.
sequence: str

That made sense when our project was still working with hardcoded strings.

But now our application already has:

# Our application already has a validated DNA object at this point.
dna

which contains:

identifier
description
validated sequence

Before calling the algorithm, we currently throw that context away:

# Old approach: discard the model context and pass only its string sequence.
seq = dna.sequence

and pass only the string.

In Part 4.6, we stop doing that.

The generic k-mer algorithms will accept:

# New approach: accept the shared validated Sequence model directly.
sequence: Sequence

instead.

Our current DNA class inherits from Sequence, so this works directly:

# DNA inherits from Sequence, so the validated object can be passed directly.
count_kmer(dna, kmer)

The k-mer algorithm does not need any DNA-specific rule. It only needs to:

measure the sequence
index it
slice it

Those behaviors already belong to our shared Sequence model.

That gives us a useful rule for future algorithms:

Use the least-specific validated biological type that provides everything the calculation needs.

For generic k-mer calculations:

Sequence

is enough.

For a DNA-specific algorithm such as reverse complement, the appropriate input would still be:

DNA

Files Changed in This Part

Before writing any code, let us look at the exact files we will touch.

We are adding one new file:

src/genome_toolkit/algorithms/base.py        # <-- NEW

and updating three existing files:

src/genome_toolkit/algorithms/kmer.py        # <-- UPDATED
src/genome_toolkit/algorithms/__init__.py    # <-- UPDATED
application.py                               # <-- UPDATED

Nothing else changes.

Our relevant project structure will become:

genome_toolkit/
├── application.py                          # <-- UPDATED
├── pyproject.toml
├── uv.lock
├── samples/
│   ├── sample.txt
│   └── sample.fasta
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── py.typed
        ├── algorithms/
        │   ├── __init__.py                  # <-- UPDATED
        │   ├── base.py                      # <-- NEW
        │   └── kmer.py                      # <-- UPDATED
        ├── load/
        │   ├── __init__.py
        │   ├── fasta.py
        │   ├── records.py
        │   └── text.py
        └── sequence/
            ├── __init__.py
            ├── base.py
            └── dna.py

There are no new dependencies.

Pydantic is already part of Genome Toolkit from Part 4.3, so:

pyproject.toml
uv.lock

stay unchanged.

Our work is focused entirely on the algorithm input and result layer.

1. Create the Shared Result Foundation

We will start with the one new file in this part:

src/genome_toolkit/algorithms/base.py

This file will contain only the result models that our algorithms can share.

We will build it one small class at a time so the inheritance remains easy to follow.

Start with:

"""Shared models for structured algorithm results."""

# Import UTC-aware timestamps for execution metadata.
from datetime import UTC, datetime

# Import the Pydantic tools used by our result models.
from pydantic import BaseModel, ConfigDict, Field

# Record the installed toolkit version in every result.
from genome_toolkit import __version__

# Build compact input metadata from validated Sequence objects.
from genome_toolkit.sequence import Sequence

We already use Pydantic for our biological models, so Part 4.6 does not add a new dependency.

The new standard-library import:

# Import UTC-aware timestamps for result provenance.
from datetime import UTC, datetime

will let us record when a result was created.

We also import:

# Reuse the installed package version in every structured result.
from genome_toolkit import __version__

because the package version is useful provenance. If we return to a saved result later, we want to know which Genome Toolkit version produced it.

1. ResultModel

Add:

# Give every result-related model the same strict configuration.
class ResultModel(BaseModel):
    """Base configuration for algorithm result models."""

    # Reject unexpected fields so the result shape stays predictable.
    model_config = ConfigDict(extra="forbid")

This is the common base for all of our result-related models.

We already met:

# Pydantic ConfigDict controls shared model configuration.
ConfigDict

when building our biological models.

Here:

# Reject unexpected fields so scientific result shapes stay predictable.
extra="forbid"

means Pydantic rejects fields that we did not define.

For example, if a result model expects:

count

but some code accidentally supplies:

counts

the unexpected field is rejected instead of silently changing the shape of our scientific result.

At this point the inheritance is only:

Pydantic BaseModel
        ↓
    ResultModel

2. ToolkitMetadata

Next add:

# Store information about the toolkit execution itself.
class ToolkitMetadata(ResultModel):
    """Toolkit execution information for an algorithm result."""

    # Record the toolkit version that produced the result.
    toolkit_version: str = __version__

    # Record the exact algorithm name.
    algorithm: str

    # Create a fresh UTC timestamp for each new result.
    timestamp: datetime = Field(
        default_factory=lambda: datetime.now(UTC)
    )

This model stores:

toolkit_version
algorithm
timestamp

The version comes from the same package version source we created earlier in the series.

The algorithm name will be supplied when a result is created.

The timestamp is generated automatically.

Our inheritance is now:

ResultModel
└── ToolkitMetadata

Why Use default_factory?

It may be tempting to write:

# This would calculate the timestamp too early, when the class is defined.
timestamp: datetime = datetime.now(UTC)

But that expression would be evaluated when Python creates the class.

We need a fresh timestamp for every result.

So we use:

# Use a factory so every new result receives its own fresh timestamp.
timestamp: datetime = Field(
    default_factory=lambda: datetime.now(UTC)
)

The factory runs each time Pydantic creates a new ToolkitMetadata object:

result 1 → timestamp 1
result 2 → timestamp 2
result 3 → timestamp 3

The small:

# This zero-argument function returns the current UTC time when called.
lambda: datetime.now(UTC)

is simply a function with no arguments that returns the current UTC time.

We use UTC because scientific calculations may run on machines in different time zones.

3. SequenceMetadata

Next add:

# Keep compact information about the analyzed biological sequence.
class SequenceMetadata(ResultModel):
    """Compact information about an analyzed biological sequence."""

    # Preserve the sequence identifier.
    identifier: str

    # Preserve its optional description.
    description: str | None = None

    # Record its length without copying the full sequence.
    length: int

This model stores only:

identifier
description
length

It deliberately does not copy the entire biological sequence.

Real sequences can become very large. Duplicating a complete genome into every saved algorithm result would make even a small calculation produce a huge result.

The real validated Sequence remains the algorithm input.

The result keeps compact information describing what was analyzed.

SequenceMetadata therefore stays a data-only schema. The small sequence_metadata() function will handle the transformation into that schema.

4. sequence_metadata()

SequenceMetadata now has one job:

define the shape of compact sequence metadata

We still need a small reusable way to transform a validated Sequence object into that schema.

Without a helper, every algorithm would have to repeat:

# Manual version: build compact metadata from the validated sequence.
SequenceMetadata(
    identifier=sequence.identifier,
    description=sequence.description,
    length=len(sequence),
)

Instead, add one plain helper function below the model:

# Convert a validated Sequence into our compact result schema.
def sequence_metadata(
    sequence: Sequence,
) -> SequenceMetadata:
    """Build compact metadata from a validated sequence object.

    Args:
        sequence: Validated biological sequence used by an algorithm.

    Returns:
        Compact metadata describing the analyzed sequence.
    """
    # Copy only the small shared fields needed by algorithm results.
    return SequenceMetadata(
        identifier=sequence.identifier,
        description=sequence.description,
        length=len(sequence),
    )

Now our responsibilities stay very clear:

SequenceMetadata
→ defines the data/schema

sequence_metadata()
→ performs the small Sequence → SequenceMetadata transformation

An algorithm can simply write:

# Convert the validated sequence into compact input metadata.
sequence_metadata(sequence)

and keep the repeated metadata plumbing out of the scientific calculation.

5. SequenceInputs

Next add:

# Group one analyzed biological sequence under `inputs.sequence`.
class SequenceInputs(ResultModel):
    """Biological inputs for an algorithm using one sequence."""

    # Store compact sequence metadata rather than the entire sequence.
    sequence: SequenceMetadata

For our current algorithms, the input section becomes:

inputs
└── sequence
    ├── identifier
    ├── description
    └── length

A future algorithm can define another input model if it needs something different.

6. AlgorithmResult

Finally add:

# Give every complete algorithm result the same metadata section.
class AlgorithmResult(ResultModel):
    """Base class for structured Genome Toolkit results."""

    # Record how and when the algorithm result was produced.
    metadata: ToolkitMetadata

Every complete algorithm result will inherit this shared metadata field.

Later:

KmerCountResult
FrequentKmersResult

will inherit from AlgorithmResult.

We deliberately keep AlgorithmResult small. We are not trying to model jobs, workflow engines, users, server responses, storage systems, or complete input sequences.

We only need a reliable base for successful scientific results.

A Simple Mental Model

Before moving on, here is the whole relationship in one place:

ResultModel
    shared Pydantic behavior

ToolkitMetadata
    toolkit version + algorithm + UTC timestamp

SequenceMetadata
    compact information about the analyzed sequence

sequence_metadata()
    Sequence → SequenceMetadata

SequenceInputs
    common input structure for one-sequence algorithms

AlgorithmResult
    shared result foundation

The k-mer-specific result classes we add next will build on that shared foundation.

The important point is that these classes are not adding new scientific calculations. They are giving the inputs and outputs a predictable structure.

base.py Is Finished

That completes the new shared result foundation.

We now have:

ResultModel
ToolkitMetadata
SequenceMetadata
sequence_metadata()
SequenceInputs
AlgorithmResult

Each piece has one small responsibility, and we only had to define the shared structure once.

Now we can move into our existing kmer.py and use that foundation around the real scientific calculations.

Updating kmer.py

Open:

src/genome_toolkit/algorithms/kmer.py

We will update one algorithm at a time.

For each algorithm, we only need to:

1. define its parameters
2. define its output
3. define its full result
4. return that result from the existing calculation

The mathematical loops remain unchanged.

2. Upgrade count_kmer() First

Adding the Result Models

Open:

src/genome_toolkit/algorithms/kmer.py

Its imports now become:

"""K-mer analysis algorithms and structured results."""

# Generic k-mer algorithms need only the shared validated Sequence API.
from genome_toolkit.sequence import Sequence

# Import the shared models and metadata helper used to assemble results.
from .base import (
    AlgorithmResult,
    ResultModel,
    SequenceInputs,
    ToolkitMetadata,
    sequence_metadata,
)

The important new input type is:

# Generic k-mer algorithms now depend on the shared validated Sequence type.
Sequence

We also import:

# Reuse the tiny transformation from Sequence to SequenceMetadata.
sequence_metadata

so each algorithm can build the common input metadata without repeating the same field-copying code.

Then add the three small models used by count_kmer():

# Define the parameter section for count_kmer().
class KmerCountParameters(ResultModel):
    """Parameters passed to `count_kmer()`."""

    # K-mer whose overlapping occurrences we want to count.
    kmer: str


# Define the output section for count_kmer().
class KmerCountOutput(ResultModel):
    """Values computed by `count_kmer()`."""

    # Number of overlapping occurrences found.
    count: int


# Combine metadata, inputs, parameters, and output in one public result.
class KmerCountResult(AlgorithmResult):
    """Structured result returned by `count_kmer()`."""

    # Biological input metadata.
    inputs: SequenceInputs

    # Parameters chosen for this calculation.
    parameters: KmerCountParameters

    # Value calculated by the algorithm.
    output: KmerCountOutput

Their structure is easy to read:

KmerCountResult
├── metadata
├── inputs
├── parameters
│   └── kmer
└── output
    └── count

metadata comes from:

# KmerCountResult inherits the shared metadata field from AlgorithmResult.
AlgorithmResult

The other three sections are defined by the specific result.

Changing the count_kmer() Function Boundary

Before Part 4.6:

# Before Part 4.6: plain string input and primitive integer output.
def count_kmer(
    sequence: str,
    kmer: str,
) -> int:

Now change it to:

# After Part 4.6: validated Sequence input and structured result output.
def count_kmer(
    sequence: Sequence,
    kmer: str,
) -> KmerCountResult:

There are two changes:

input
str → Sequence

output
int → KmerCountResult

The complete function becomes:

# Accept a validated Sequence and return a structured result.
def count_kmer(
    sequence: Sequence,
    kmer: str,
) -> KmerCountResult:
    """Count overlapping occurrences of a k-mer.

    Args:
        sequence: Validated biological sequence to search.
        kmer: K-mer to count, including overlapping occurrences.

    Returns:
        Structured result containing input metadata, parameters, and count.
    """
    # Start the same counter used by our original algorithm.
    kmer_count = 0

    # Visit every valid overlapping starting position.
    for position in range(len(sequence) - (len(kmer) - 1)):
        # Compare the current slice with the requested k-mer.
        if sequence[position : position + len(kmer)] == kmer:
            # Count this matching occurrence.
            kmer_count += 1

    # Package the unchanged count together with its scientific context.
    return KmerCountResult(
        # Record toolkit version, algorithm name, and execution time.
        metadata=ToolkitMetadata(
            algorithm=count_kmer.__name__,
        ),
        # Convert the validated sequence into compact input metadata.
        inputs=SequenceInputs(
            sequence=sequence_metadata(sequence),
        ),
        # Record the k-mer selected for this calculation.
        parameters=KmerCountParameters(
            kmer=kmer,
        ),
        # Store the calculated count.
        output=KmerCountOutput(
            count=kmer_count,
        ),
    )

Look carefully at the calculation:

# Start the existing counter at zero.
kmer_count = 0

# Slide across every valid overlapping k-mer position.
for position in range(len(sequence) - (len(kmer) - 1)):
    # Count each slice matching the requested k-mer.
    if sequence[position : position + len(kmer)] == kmer:
        kmer_count += 1

That is still our existing algorithm.

We did not change:

the loop
the positions
the slice
the comparison
the counter

The difference is what we do after the calculation.

Before:

# Old return: expose only the primitive calculated count.
return kmer_count

Now:

# New return: package that same count with its scientific context.
return KmerCountResult(...)

The computed integer still exists:

# The underlying calculated integer still exists unchanged.
kmer_count

but we place it under:

output.count

alongside the rest of the scientific context.

So despite the extra result models around it, the actual k-mer counting algorithm is still the same few lines of Python. We are standardizing the successful result, not replacing the science.

3. Apply the Same Pattern to find_most_frequent_kmers()

Now we do the same for our second algorithm.

Adding Its Result Models

Add:

# Define the parameter section for find_most_frequent_kmers().
class FrequentKmersParameters(ResultModel):
    """Parameters passed to `find_most_frequent_kmers()`."""

    # Length of the k-mers we want to analyze.
    k_len: int


# Define the output section for the frequent-kmer calculation.
class FrequentKmersOutput(ResultModel):
    """Values computed by `find_most_frequent_kmers()`."""

    # All k-mers tied for the highest observed frequency.
    kmers: list[str]

    # Shared number of occurrences of those k-mers.
    frequency: int


# Combine metadata, inputs, parameters, and output in one public result.
class FrequentKmersResult(AlgorithmResult):
    """Structured result returned by `find_most_frequent_kmers()`."""

    # Biological input metadata.
    inputs: SequenceInputs

    # Parameters chosen for this calculation.
    parameters: FrequentKmersParameters

    # Values calculated by the algorithm.
    output: FrequentKmersOutput

Its shape is:

FrequentKmersResult
├── metadata
├── inputs
├── parameters
│   └── k_len
└── output
    ├── kmers
    └── frequency

There is one useful addition here:

# Preserve the shared highest frequency instead of throwing it away.
frequency: int

Our original algorithm already calculates:

# The existing algorithm already calculates this value internally.
highest_frequency

but previously returned only the list of tied k-mers:

# Previous output exposed only the tied k-mer strings.
["TTT", "AAA"]

That meant we calculated the frequency and then threw it away.

The structured result keeps it.

Changing the Function Boundary

Before:

# Before Part 4.6: plain string input and primitive list output.
def find_most_frequent_kmers(
    sequence: str,
    k_len: int,
) -> list[str]:

Now:

# After Part 4.6: validated Sequence input and structured result output.
def find_most_frequent_kmers(
    sequence: Sequence,
    k_len: int,
) -> FrequentKmersResult:

The complete function is:

# Accept a validated Sequence and return a structured result.
def find_most_frequent_kmers(
    sequence: Sequence,
    k_len: int,
) -> FrequentKmersResult:
    """Find the most frequent k-mers of a requested length.

    Args:
        sequence: Validated biological sequence to analyze.
        k_len: Length of the k-mers to count.

    Returns:
        Structured result containing the most frequent k-mers and their
        shared frequency.
    """
    # Count the occurrences of every observed k-mer.
    kmer_frequencies: dict[str, int] = {}

    # Visit every overlapping k-mer of the requested length.
    for i in range(len(sequence) - k_len + 1):
        # Extract the current k-mer.
        kmer = sequence[i : i + k_len]

        # Increase an existing count or create the first count.
        if kmer in kmer_frequencies:
            kmer_frequencies[kmer] += 1
        else:
            kmer_frequencies[kmer] = 1

    # Find the largest count in the frequency table.
    highest_frequency = max(kmer_frequencies.values())

    # Keep all k-mers tied for that highest frequency.
    frequent_kmers = [
        kmer
        for kmer, frequency in kmer_frequencies.items()
        if frequency == highest_frequency
    ]

    # Package the calculated values together with their scientific context.
    return FrequentKmersResult(
        # Record toolkit version, algorithm name, and execution time.
        metadata=ToolkitMetadata(
            algorithm=find_most_frequent_kmers.__name__,
        ),
        # Convert the validated sequence into compact input metadata.
        inputs=SequenceInputs(
            sequence=sequence_metadata(sequence),
        ),
        # Record the requested k-mer length.
        parameters=FrequentKmersParameters(
            k_len=k_len,
        ),
        # Preserve both the k-mers and their shared frequency.
        output=FrequentKmersOutput(
            kmers=frequent_kmers,
            frequency=highest_frequency,
        ),
    )

Again, the algorithm itself is still familiar.

We still build:

# Existing dictionary that stores the count for each observed k-mer.
kmer_frequencies

We still scan every overlapping k-mer:

# Existing loop: visit every overlapping k-mer of the requested length.
for i in range(len(sequence) - k_len + 1):

We still find:

# The existing algorithm already calculates this value internally.
highest_frequency

And we still keep every k-mer tied at that frequency.

The only difference is that the result now preserves both:

kmers
frequency

together with the input, parameters, and execution metadata.

4. Keep kmer.py Easy to Navigate

After updating both algorithms, the file should remain ordered like this:

KmerCountParameters
KmerCountOutput
KmerCountResult
count_kmer()

FrequentKmersParameters
FrequentKmersOutput
FrequentKmersResult
find_most_frequent_kmers()

This keeps each result structure beside the algorithm that uses it.

We do not need another layer of algorithm classes, result factories, decorators, or orchestration. The shared repetitive pieces live in base.py; the algorithm-specific models and the scientific calculations remain explicit in kmer.py.

If a future algorithm family becomes genuinely large, we can split it then. We do not need speculative subpackages now.

5. Export the Public Result Types

Our public algorithm package currently exposes only the functions.

Update:

src/genome_toolkit/algorithms/__init__.py

to:

"""Bioinformatics algorithms and structured results."""

# Re-export the two public algorithms and their public result types.
from .kmer import (
    FrequentKmersResult,
    KmerCountResult,
    count_kmer,
    find_most_frequent_kmers,
)

# Define the names that form the public algorithms package API.
__all__ = [
    "count_kmer",
    "find_most_frequent_kmers",
    "KmerCountResult",
    "FrequentKmersResult",
]

The normal function API stays simple:

# Import the public k-mer functions through the package API.
from genome_toolkit.algorithms import (
    count_kmer,
    find_most_frequent_kmers,
)

But the two public result classes are now also available:

# Import the public result types when we need them for annotations
# or future external interface declarations.
from genome_toolkit.algorithms import (
    FrequentKmersResult,
    KmerCountResult,
)

That will be useful for type annotations and for future external interfaces that need to declare exactly what an algorithm returns.

We do not export every small nested model such as:

KmerCountParameters
KmerCountOutput
FrequentKmersParameters
FrequentKmersOutput

Those models support the public result structure internally. They do not need to fill the main algorithm namespace.

6. Turn application.py Into a Small Experiment Workflow

We now have all of the pieces we need for a much more useful final application.py.

Instead of loading or rebuilding the same biological sequence for every calculation, we will do the expensive and scientifically important preparation once:

FASTA
  ↓
select one record
  ↓
SequenceRecord
  ↓
validate once
  ↓
DNA

Then we reuse that same validated DNA object across every experiment:

                     ┌→ count_kmer("CCG")
                     ├→ count_kmer("TTCC")
one validated DNA ───┼→ find_most_frequent_kmers(k_len=4)
                     ├→ find_most_frequent_kmers(k_len=5)
                     └→ k_len sweep from 1 to 8

This is an important consequence of the result design we built in this part.

When we pass:

# Reuse the same validated DNA object.
count_kmer(dna, "CCG")

Python passes the existing object to the function. We are not loading the FASTA file again and we are not creating another full DNA sequence for every algorithm run.

The structured result also does not copy the complete biological sequence into its metadata.

Each result keeps only:

identifier
description
length

through SequenceMetadata.

So our experiment can keep one central validated sequence in memory while producing many independent result objects around it:

one full DNA sequence
        ↓
reused by many calculations
        ↓
many compact result records

Each result still has enough provenance to tell us which biological sequence was analyzed, without storing the entire sequence again and again.

That becomes increasingly important when we move from our small sample to sequences containing millions or billions of bases.

Inspect the FASTA File First

Before selecting a sequence, we can inspect the available FASTA records:

# Read only the FASTA headers so we can see which records are available.
fasta_headers = fasta.get_headers(FASTA_SAMPLE)

# Print each zero-based position and parsed header.
for position, header in enumerate(fasta_headers):
    print(f"{position}: {header}")

This lets us choose a real biological record deliberately instead of hardcoding an unknown sequence string.

For our final experiment, we will load:

M57671.1

by identifier.

This is one of the biological sequences in the sample.fasta file we added in Part 4.5. If you want to use exactly the same FASTA data while following this experiment, you can find the latest version in the Genome Toolkit repository:

https://github.com/rebelC0der/Genome_Toolkit/tree/main/samples

The file we use here is:

sample.fasta

Load and Validate the Sequence Once

We then create our central biological object:

# Load one FASTA record by its biological identifier.
fasta_record_1 = fasta.get_sequence(
    FASTA_SAMPLE,
    identifier="M57671.1",
)

# Validate the neutral loader record once as DNA.
dna = DNA.model_validate(
    fasta_record_1,
    from_attributes=True,
)

From this point onward, every experiment reuses:

# One shared validated biological object.
dna

We do not reload the FASTA file for every k-mer calculation.

Run Independent count_kmer() Experiments

We can now run the same algorithm with different parameters:

# Run two independent count experiments against the same DNA object.
count_kmers_run_1 = count_kmer(dna, "CCG")
count_kmers_run_2 = count_kmer(dna, "TTCC")

Each call produces its own structured scientific result.

We can inspect the original sequence directly when we want:

# The full validated sequence still exists once on the DNA object.
print(f"nSequence: {dna.sequence}")

and serialize each experiment independently:

# Serialize each count experiment as its own complete scientific result.
print(
    f"nExperiment #1:n"
    f"{count_kmers_run_1.model_dump_json(indent=2)}"
)
print(
    f"nExperiment #2:n"
    f"{count_kmers_run_2.model_dump_json(indent=2)}"
)

The two results share the same compact sequence context but preserve different algorithm parameters and outputs.

Run Independent Frequent K-mer Experiments

We can do exactly the same with our second algorithm:

# Analyze the same DNA with two different k-mer lengths.
kmer_freq_run_1 = find_most_frequent_kmers(dna, k_len=4)
kmer_freq_run_2 = find_most_frequent_kmers(dna, k_len=5)

Then serialize both runs:

# Print the complete structured results for both frequency experiments.
print(
    f"nExperiment #3:n"
    f"{kmer_freq_run_1.model_dump_json(indent=2)}"
)
print(
    f"nExperiment #4:n"
    f"{kmer_freq_run_2.model_dump_json(indent=2)}"
)

Again, we have not reloaded or revalidated the sequence.

Only the experiment parameter changed.

Sweep Through Several k_len Values

The final experiment shows why clean algorithm boundaries are useful.

Instead of writing eight separate calls, we can sweep through several k-mer lengths:

# Start one compact parameter-sweep experiment.
print("nExperiment #5:")

# Reuse the same DNA object for k-mer lengths from 1 through 8.
for klen in range(1, 9):
    kmers_found = find_most_frequent_kmers(dna, klen)

    # Pull only the values we want for this compact experiment summary.
    print(
        f"k-len: {klen}, "
        f"kmers found: {len(kmers_found.output.kmers)}: "
        f"{kmers_found.output.kmers}"
    )

This is already starting to look less like a single demonstration and more like a lightweight scientific experiment workflow.

One validated input can drive many independent calculations.

The Final application.py

This is the final application checkpoint for Part 4.6:

from pathlib import Path

from genome_toolkit.algorithms import (
    count_kmer,
    find_most_frequent_kmers,
)
from genome_toolkit.load import fasta
from genome_toolkit.sequence import DNA

SAMPLES_DIR = Path(__file__).resolve().parent / "samples"
FASTA_SAMPLE = SAMPLES_DIR / "sample.fasta"

# Insepct the FASTA File headers:
fasta_headers = fasta.get_headers(FASTA_SAMPLE)

for position, header in enumerate(fasta_headers):
    print(f"{position}: {header}")

# Load a sequence from FASTA by identifier
fasta_record_1 = fasta.get_sequence(
    FASTA_SAMPLE,
    identifier="M57671.1",
)

dna = DNA.model_validate(
    fasta_record_1,
    from_attributes=True,
)

count_kmers_run_1 = count_kmer(dna, "CCG")
count_kmers_run_2 = count_kmer(dna, "TTCC")

print(f"\nSequence: {dna.sequence}")

print(f"\nExperiment #1:\n{count_kmers_run_1.model_dump_json(indent=2)}")
print(f"\nExperiment #2:\n{count_kmers_run_2.model_dump_json(indent=2)}")

kmer_freq_run_1 = find_most_frequent_kmers(dna, k_len=4)
kmer_freq_run_2 = find_most_frequent_kmers(dna, k_len=5)

print(f"\nExperiment #3:{kmer_freq_run_1.model_dump_json(indent=2)}")
print(f"\nExperiment #4:{kmer_freq_run_2.model_dump_json(indent=2)}")

print("\nExperiment #5:")

for klen in range(1, 9):
    kmers_found = find_most_frequent_kmers(dna, klen)
    print(f"k-len: {klen}, kmers found: {kmers_found.output.kmers}")

Run:

uv run python application.py

The recorded run shown in this article produces:

0: ('M57671.1', 'Octodon degus insulin mRNA, complete cds')
1: ('ALPHA_GENE_4582', 'one of the alpha proteins')
2: ('BETA_REGULATOR_991', 'a regulatory sequence from the beta cluster')
3: ('GAMMA_OPERON_SEQ3', 'a short sequence from the gamma operon region')
4: ('original_example', 'Original Genome Toolkit test sequence')

Sequence: TGCGTTAGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCCGGCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGG

Experiment #1:
{
  "metadata": {
    "toolkit_version": "0.1.0",
    "algorithm": "count_kmer",
    "timestamp": "2026-09-10T12:55:09.074227Z"
  },
  "inputs": {
    "sequence": {
      "identifier": "M57671.1",
      "description": "Octodon degus insulin mRNA, complete cds",
      "length": 188
    }
  },
  "parameters": {
    "kmer": "CCG"
  },
  "output": {
    "count": 11
  }
}

Experiment #2:
{
  "metadata": {
    "toolkit_version": "0.1.0",
    "algorithm": "count_kmer",
    "timestamp": "2026-09-10T12:55:09.074287Z"
  },
  "inputs": {
    "sequence": {
      "identifier": "M57671.1",
      "description": "Octodon degus insulin mRNA, complete cds",
      "length": 188
    }
  },
  "parameters": {
    "kmer": "TTCC"
  },
  "output": {
    "count": 5
  }
}

Experiment #3:{
  "metadata": {
    "toolkit_version": "0.1.0",
    "algorithm": "find_most_frequent_kmers",
    "timestamp": "2026-09-10T12:55:09.074464Z"
  },
  "inputs": {
    "sequence": {
      "identifier": "M57671.1",
      "description": "Octodon degus insulin mRNA, complete cds",
      "length": 188
    }
  },
  "parameters": {
    "k_len": 4
  },
  "output": {
    "kmers": [
      "CCGG"
    ],
    "frequency": 11
  }
}

Experiment #4:{
  "metadata": {
    "toolkit_version": "0.1.0",
    "algorithm": "find_most_frequent_kmers",
    "timestamp": "2026-09-10T12:55:09.074538Z"
  },
  "inputs": {
    "sequence": {
      "identifier": "M57671.1",
      "description": "Octodon degus insulin mRNA, complete cds",
      "length": 188
    }
  },
  "parameters": {
    "k_len": 5
  },
  "output": {
    "kmers": [
      "CTTGG",
      "TTGGG",
      "TGGGC",
      "GGGCC"
    ],
    "frequency": 6
  }
}

Experiment #5:
k-len: 1, kmers found: 1: ['G']
k-len: 2, kmers found: 1: ['GG']
k-len: 3, kmers found: 1: ['GGC']
k-len: 4, kmers found: 1: ['CCGG']
k-len: 5, kmers found: 4: ['CTTGG', 'TTGGG', 'TGGGC', 'GGGCC']
k-len: 6, kmers found: 3: ['CTTGGG', 'TTGGGC', 'TGGGCC']
k-len: 7, kmers found: 2: ['CTTGGGC', 'TTGGGCC']
k-len: 8, kmers found: 1: ['CTTGGGCC']

This final application brings together everything we built in Part 4.6.

We load and validate the biological sequence once.

We reuse that same DNA object across multiple independent experiments.

Each algorithm run produces its own structured result.

And each result stores compact provenance about the input without duplicating the complete biological sequence.

7. Final Flow

Our Part 4.6 workflow now looks like this:

FASTA file
    ↓
inspect headers
    ↓
select one record by identifier
    ↓
SequenceRecord
    ↓
validate once
    ↓
DNA
    │
    ├── count_kmer("CCG")
    │      ↓
    │   structured result
    │
    ├── count_kmer("TTCC")
    │      ↓
    │   structured result
    │
    ├── find_most_frequent_kmers(k_len=4)
    │      ↓
    │   structured result
    │
    ├── find_most_frequent_kmers(k_len=5)
    │      ↓
    │   structured result
    │
    └── k_len sweep 1..8
           ↓
        structured results

The full biological sequence exists once on the validated DNA object.

Each algorithm call receives that same object and creates only the result data needed for that run.

Inside the result, SequenceMetadata stores:

identifier
description
length

rather than another copy of:

dna.sequence

So our architecture separates two jobs cleanly:

DNA
→ owns the validated biological sequence

algorithm result
→ records compact provenance + parameters + output

That is a much better foundation for running many experiments against the same biological input.

Before and After

The two diagrams below summarize what changed in Part 4.6.

The first shows our original k-mer functions accepting raw strings and returning primitive Python values. The second shows the finished flow, where biological data comes from FASTA, becomes a validated object, passes through the same scientific algorithms, and returns structured scientific results.

Why This Helps Reproducibility and Provenance

We introduced reproducibility and provenance earlier in this series.

Part 4.6 gives those ideas a concrete place in our code.

A primitive result:

4

contains the computed answer but almost no history.

At the same time, a provenance record does not need to duplicate the complete biological input. Our application keeps the validated DNA object once, while each result records only enough compact sequence metadata to identify what was analyzed.

Our structured result tells us:

which toolkit version ran
which algorithm ran
when it ran
which biological sequence was analyzed
which parameters were used
what the algorithm calculated

That does not magically make every experiment reproducible by itself. A full experiment may also need information about data sources, software environments, preprocessing, and other steps.

But this is a strong foundation.

Instead of throwing away useful context at the moment a result is created, Genome Toolkit begins carrying that context forward.

What We Are Not Solving Yet

Part 4.6 is about the successful result path.

We are not going to mix that work with every algorithm edge case.

For example:

empty k-mer
k_len = 0
negative k_len
k_len greater than sequence length

still need deliberate behavior.

Those cases belong in Part 4.7, where we will write tests first and then define the validation and exceptions those tests show we actually need.

Keeping those concerns separate lets us answer two different questions clearly:

Part 4.6
What does a successful scientific result look like?

Part 4.7
What should happen when an input or source is invalid?

Our Final Project Structure

Part 4.6 changes one application file and the algorithm package.

The complete current structure is:

genome_toolkit/
├── .git/
├── .gitignore
├── .venv/
├── README.md
├── application.py                  # <-- UPDATED
├── pyproject.toml
├── uv.lock
├── samples/
│   ├── sample.txt
│   └── sample.fasta
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── py.typed
        ├── algorithms/
        │   ├── __init__.py          # <-- UPDATED
        │   ├── base.py              # <-- NEW
        │   └── kmer.py              # <-- UPDATED
        ├── load/
        │   ├── __init__.py
        │   ├── fasta.py
        │   ├── records.py
        │   └── text.py
        └── sequence/
            ├── __init__.py
            ├── base.py
            └── dna.py

Notice what did not change:

samples/
load/
sequence/
pyproject.toml
uv.lock

We did not add a dependency, redesign the FASTA loader, or change our DNA validation.

Part 4.6 is focused on the algorithm boundary and the scientific result layer.

Summary

In Part 4.6, we changed both sides of our k-mer algorithms.

Before:

raw str
  ↓
algorithm
  ↓
int / list[str]

Now:

validated Sequence
        ↓
same scientific calculation
        ↓
typed structured result

Every result follows the same predictable structure:

metadata
inputs
parameters
output

We created algorithms/base.py for the small result components shared across algorithms, then upgraded both k-mer functions without changing their scientific calculations.

Our final application.py also demonstrates an important scientific usage pattern:

load once
validate once
reuse many times

We load M57671.1 from FASTA once, create one validated DNA object, and reuse that same object across several independent k-mer experiments.

The structured results do not store another full copy of the sequence. They keep only compact sequence metadata:

identifier
description
length

alongside the algorithm metadata, parameters, and calculated output.

That gives us a useful balance:

one central validated biological object
+
many independent compact scientific results

The final parameter sweep also shows why this matters in practice. Once the input and output boundaries are clean, running a series of related experiments becomes simple Python rather than repeated data-loading code.

Most importantly, the k-mer mathematics itself did not change. We improved how biological inputs are reused and how scientific results preserve their context.

New Concepts We Learned

• Structured scientific result — A typed result object that keeps the calculated value together with useful information about the input, parameters, software, and execution.

• Metadata — Data that describes other data. In our results, metadata gives the calculated output extra context, such as the Genome Toolkit version, algorithm name, and execution timestamp.

• Inputs — The biological objects analyzed by an algorithm. For our current k-mer functions, this is compact metadata describing one sequence.

• Parameters — Settings chosen for a particular algorithm run, such as kmer="AA" or k_len=3.

• Output — The values actually computed by the algorithm, such as a count, a list of frequent k-mers, or their shared frequency.

• default_factory — A Pydantic Field option that calls a function whenever a new model instance needs its default value. We use it so every result receives a fresh UTC timestamp.

• UTC timestamp — A time recorded using a shared global time standard instead of a machine’s local time zone.

• Compact sequence metadata — Instead of copying a potentially huge biological sequence into every result, we preserve its identifier, optional description, and length.

• Reusable validated input — We can load and validate one biological sequence once, then pass the same DNA object into many independent algorithm runs without reloading or duplicating the complete sequence for every experiment.

• sequence_metadata() — A small plain helper function that converts a validated Sequence object into compact SequenceMetadata, while keeping the model itself focused only on the result schema.

• Least-specific validated input type — A generic k-mer calculation needs sequence behavior but no DNA-specific rule, so it accepts Sequence. Our DNA model can still be passed because it inherits from Sequence.

• Typed result classes — KmerCountResult and FrequentKmersResult make each algorithm’s successful return structure explicit to Python, editors, external callers, and future interfaces.

• Serialization — Pydantic can convert the same structured Python result into JSON with model_dump_json(), without creating a separate algorithm implementation.

The central idea is simple:

A scientific calculation should not lose its context the moment it returns a value.

What is Next?

Genome Toolkit now has a much clearer successful-computation path:

biological data
      ↓
SequenceRecord
      ↓
validated biological model
      ↓
algorithm
      ↓
typed structured scientific result

The next question is what happens when something goes wrong.

Our loaders and algorithms still have edge cases such as:

invalid source structure
missing records
empty k-mer
invalid k-mer length

In Part 4.7, we will add automated tests and use those tests to define a clear failure contract for Genome Toolkit.

We will add only the validation and custom exceptions that our actual tests show we need.

The full source code for Genome Toolkit is available here:

https://github.com/rebelC0der/Genome_Toolkit

I hope building typed scientific results, reusing one validated DNA sequence across multiple experiments, and preserving compact provenance for every algorithm run was useful for your bioinformatics and programming journey! If you found this article valuable and want to help us continue building rebelScience, please consider supporting our project. You can explore various ways to contribute here:

https://rebelscience.club/cryptocurrency-donations/

Until next time, rebelCoder, signing out.

References

• Pydantic models: https://docs.pydantic.dev/latest/concepts/models/
• Python datetime: https://docs.python.org/3/library/datetime.html

Video version:

In Part 4.4, we built Genome Toolkit’s first loading layer. We moved our original sequence out of application.py, created the neutral SequenceRecord, added text.get_sequence(), loaded a sequence from sample.txt, converted that parsed record into validated DNA, and kept both of our original k-mer algorithms unchanged.

Our current data flow is:

sample.txt
    ↓
text.get_sequence()
    ↓
SequenceRecord
    ↓
DNA
    ↓
dna.sequence
    ↓
existing k-mer algorithms

That means most of the loading architecture is already in place.

In Part 4.5, we do not need another record model or another biological model. We only need to extend the loading layer so Genome Toolkit can understand a much more useful biological sequence format: FASTA.

We will add one new loader module:

load/fasta.py

and extend our existing loading API.

The new input side becomes:

plain text ─┐
            ├→ SequenceRecord → DNA → dna.sequence → algorithms
FASTA ──────┘

Most importantly, we are still not changing DNA or either k-mer algorithm. The algorithms still accept a normal Python string, and our application will continue passing them:

seq = dna.sequence

Part 4.6 is where we will finally upgrade the algorithm boundary itself.

Starting With Our Working Project

We continue from the exact final state of Part 4.4:

genome_toolkit/
├── .git/
├── .gitignore
├── .venv/
├── README.md
├── application.py
├── pyproject.toml
├── uv.lock
├── samples/
│   └── sample.txt
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── py.typed
        ├── algorithms/
        │   ├── __init__.py
        │   └── kmer.py
        ├── sequence/
        │   ├── __init__.py
        │   ├── base.py
        │   └── dna.py
        └── load/
            ├── __init__.py
            ├── records.py
            └── text.py

Our existing loading boundary is already established:

record = text.get_sequence(
    SAMPLES_DIR / "sample.txt"
)

dna = DNA.model_validate(
    record,
    from_attributes=True,
)

And the final bridge into our algorithms is still:

seq = dna.sequence

so the scientific part of application.py remains:

print(f"Sequence: {seq}")
print(f"k-mer: {kmer}")
print(f"Repeats found: {count_kmer(seq, kmer)}")
print(f"Most frequent k-mer: {find_most_frequent_kmers(seq, k_len)}")

Running:

uv run python application.py

still gives us:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

That output is our checkpoint again. We are going to change the source format without changing the biological validation or scientific calculations.

What Is FASTA and Why Is It So Common?

FASTA is one of the most widely used formats for storing and exchanging biological sequences. It has been used in bioinformatics for decades and has effectively become a de facto standard because it is simple, human-readable, easy for software to parse, and supported by a huge range of biological databases and analysis tools.

FASTA can store different biological sequence types, including:

DNA
RNA
protein / amino-acid sequences

The FASTA format itself does not decide what those symbols mean. It gives us a simple record structure: a header followed by sequence data. Our biological models still decide whether the sequence is valid DNA, RNA, protein, or something else.

FASTA is also one of those formats we will keep running into again and again in bioinformatics. If we download a bacterial genome, a viral genome, a chromosome, an assembled contig, a transcript sequence, or a protein sequence from a biological database, FASTA is one of the most common formats we will see.

There is one useful distinction to remember. Reference and assembled sequences are very commonly distributed as FASTA, while raw sequencing reads are commonly distributed as FASTQ, because FASTQ stores a quality score for every sequenced symbol in addition to the sequence itself.

So as Genome Toolkit moves from small examples toward real biological datasets and experiments, being able to read FASTA is not an optional convenience. It gives us access to one of the standard ways biological sequence data is stored and exchanged.

If FASTA is completely new to you, I recommend reading the Wikipedia overview before continuing. It gives a useful introduction to the format, its history, and the basic record structure:

https://en.wikipedia.org/wiki/FASTA_format

If you followed our earlier DNA Toolkit series, FASTA should already look familiar. We used FASTA files there to load biological sequences and work with them further, including extracting protein sequences from the loaded DNA.

This time, however, we are building FASTA support directly into Genome Toolkit itself. We want the loader to do more than simply read one small example file: it should be able to scan FASTA records one line at a time, find the record we need, and avoid keeping unrelated sequences in memory. We will see exactly how that works later in this article when we build get_sequence().

At its simplest, one FASTA record looks like this:

>identifier optional description
SEQUENCE

A single FASTA file can contain many records:

>original_example Original Genome Toolkit sequence
AATTTT
AAAAC

>second_example Another small sequence
ACGT
ACGT

For the first record, we want to extract:

identifier  → original_example
description → Original Genome Toolkit sequence
sequence    → AATTTTAAAAC

Notice that the sequence is wrapped across two lines in the file, but biologically it is still one continuous sequence.

Compared with our plain-text loader, FASTA adds:

headers
identifiers
optional descriptions
wrapped sequence lines
multiple records per file

So even though Part 4.5 changes only a few files, fasta.py itself contains enough new logic to deserve a proper walkthrough.

Our FASTA Scope for Part 4.5

In this part, we are going to add support for the common FASTA structure used by NCBI and many other sequence resources:

>identifier optional description
SEQUENCE

The first whitespace-separated value after > will become the identifier. Everything after it will be preserved as the optional description.

Our new loader will understand this general FASTA structure, but it will not try to decode provider-specific metadata inside the header.

UniProt is one of the major resources for protein sequences and protein annotation. Its FASTA headers can include information such as protein accessions, entry names, organism names, gene names, and other identifiers connected to the protein record.

Ensembl is a major genome annotation resource. It provides reference genomes together with annotated genes, transcripts, proteins, and related genomic information for many species. Its FASTA headers can also include extra identifiers and metadata describing the sequence record.

So although both resources can provide FASTA files, the text inside their headers can carry more information than the simple:

>identifier optional description

structure we need to understand for Genome Toolkit right now.

We do not need to decode all of those provider-specific details yet. For Part 4.5, our goal is simply:

read a FASTA file
discover records
select one record
return SequenceRecord

This simple FASTA loader will be more than enough for Genome Toolkit and many of the real genome-data experiments we are planning next.

At the same time, it is useful to see where this loading layer could grow in the future.

There are two different kinds of extensions we may eventually need:

actual biological file formats
+
provider-specific interpretation of data inside those formats

For example, our loading package could one day grow into something like this:

src/genome_toolkit/
└── load/
    ├── records.py
    │
    ├── fasta.py       # generic FASTA: DNA / RNA / protein sequences
    ├── fastq.py       # sequence + per-base quality scores
    ├── genbank.py     # sequence + rich biological annotations/features
    ├── embl.py        # EMBL sequence records + annotations
    │
    ├── uniprot.py     # interpret UniProt-specific FASTA metadata
    └── ensembl.py     # interpret Ensembl-specific FASTA metadata

The important distinction is:

FASTA / FASTQ / GenBank / EMBL
→ actual biological data formats

UniProt / Ensembl / NCBI
→ data providers that may use those formats
  while adding their own metadata and conventions

So a generic FASTA record might still look like:

record = SequenceRecord(
    identifier="M57671.1",
    description="Octodon degus insulin mRNA, complete cds",
    sequence="AATTTTAAAAC",
)

while a future UniProt-aware loader could extract more protein-specific metadata from a UniProt FASTA header:

protein = Protein(
    identifier="P12345",
    entry_name="ABC_HUMAN",
    organism="Homo sapiens",
    taxonomy_id=9606,
    gene="ABC1",
    sequence="MKTLLVAG...",
)

A future FASTQ loader would solve a different problem because FASTQ stores sequence reads together with per-base quality information:

read = SequenceRead(
    identifier="read_001",
    sequence="ACGTACGT",
    quality="IIIIIIII",
)

And a GenBank loader could preserve rich biological annotations and features together with the sequence:

record = GenBankRecord(
    identifier="M57671.1",
    organism="Octodon degus",
    sequence="AATTTTAAAAC...",
    features=[...],
)

Other biological data, such as:

GFF / GTF annotations
VCF variants

would probably deserve their own focused modules rather than being forced into the same sequence-loader shape.

That is the long-term direction: Genome Toolkit can gradually become a more robust biological data-processing package by adding focused support for the formats and metadata we actually encounter in our work.

But we are not going to build all of that now.

For the experiments coming next, a simple generic FASTA loader is more than enough. We will add new loaders, richer metadata handling, and other format-specific functionality only when a real experiment gives us a reason to need them.

What Are We Adding?

We need one new module:

src/genome_toolkit/load/fasta.py

with three functions:

_parse_header()     shared FASTA header parsing
get_headers()       discover the records in a FASTA file
get_sequence()      stream through the file and return one record

That is the whole FASTA layer for Part 4.5.

The existing boundary from Part 4.4 stays the same:

FASTA
  ↓
SequenceRecord
  ↓
DNA

The FASTA loader reads the file and returns neutral sequence data. Our DNA model still decides whether those symbols are valid DNA.

Creating fasta.py

Inside our existing loading package, create:

src/genome_toolkit/load/fasta.py

Our loading package becomes:

load/
├── __init__.py
├── fasta.py                   # <-- NEW
├── records.py
└── text.py

Start with:

"""Streaming helpers for reading FASTA files."""

from pathlib import Path

from .records import SequenceRecord

Both imports are familiar from Part 4.4. Path gives us a consistent way to work with the FASTA filepath, and SequenceRecord is still the neutral object returned by our loaders.

Parsing One FASTA Header

Both public FASTA functions need to understand a header such as:

>M57671.1 Octodon degus insulin mRNA, complete cds

Add one small helper:

def _parse_header(line: str) -> tuple[str, str | None]:
    """Parse one FASTA header into its identifier and optional description.

    Args:
        line: FASTA header line including the leading `>` marker.

    Returns:
        A tuple containing the sequence identifier and its optional
        description. The description is `None` when the header contains
        only an identifier.

    Raises:
        ValueError: If the header does not contain a sequence identifier.
    """
    # Remove the leading ">" marker and surrounding whitespace.
    header = line[1:].strip()

    # Reject a header with no identifier.
    if not header:
        raise ValueError("A FASTA header must contain a sequence identifier.")

    # Split the identifier from the optional description.
    parts = header.split(maxsplit=1)

    # Extract the identifier and optional description.
    identifier = parts[0]
    description = parts[1] if len(parts) == 2 else None

    # Return both values.
    return identifier, description

The leading underscore in:

_parse_header()

marks it as an internal helper. Our public functions will be get_headers() and get_sequence().

The first line:

header = line[1:].strip()

removes the leading > and surrounding whitespace.

Then:

parts = header.split(maxsplit=1)

splits the header only once.

For:

M57671.1 Octodon degus insulin mRNA, complete cds

we get:

identifier  → M57671.1
description → Octodon degus insulin mRNA, complete cds

Using maxsplit=1 is important because the description can contain many words.

Finally:

return identifier, description

returns both values as:

tuple[str, str | None]

The description is optional, so a header such as:

>M57671.1

simply returns:

("M57671.1", None)

Discovering FASTA Records With get_headers()

Now let us add our first public FASTA function.

Its job is simple:

Scan the file and tell us which FASTA records are available.

Add:

def get_headers(
    filepath: str | Path,
) -> list[tuple[str, str | None]]:
    """Read FASTA headers and return the available records in file order.

    The function scans the FASTA source without storing sequence data.
    Each returned item contains the record identifier and its optional
    description.

    Args:
        filepath: Path to the FASTA file as a string or `Path` object.

    Returns:
        A list of `(identifier, description)` tuples in file order.
        `description` is `None` when a header contains only an identifier.

    Raises:
        ValueError: If the source contains no FASTA records, sequence data
            appears before the first header, or a FASTA header does not
            contain a sequence identifier.
    """
    path = Path(filepath)
    headers: list[tuple[str, str | None]] = []

As in Part 4.4, we normalize the filepath with:

path = Path(filepath)

Then we create an empty list for the parsed headers.

Now scan the file:

with path.open("r", encoding="utf-8") as file:
    for raw_line in file:
        line = raw_line.strip()

        if not line:
            continue

        if line.startswith(">"):
            headers.append(_parse_header(line))
            continue

        if not headers:
            raise ValueError(
                f"'{path}' is not a valid FASTA source: "
                "sequence data appears before the first header."
            )

The logic is compact.

Blank lines are ignored.

If the line starts with:

>

we parse it and append the resulting:

(identifier, description)

tuple to headers.

If we encounter sequence data before we have seen even one header:

if not headers:

the file does not have the FASTA structure we expect, so we stop with a clear error.

After the scan:

if not headers:
    raise ValueError(f"'{path}' does not contain any FASTA records.")

return headers

An empty file, or a file containing only blank lines, therefore cannot silently return an empty record list.

The complete function is:

def get_headers(
    filepath: str | Path,
) -> list[tuple[str, str | None]]:
    """Read FASTA headers and return the available records in file order.

    The function scans the FASTA source without storing sequence data.
    Each returned item contains the record identifier and its optional
    description.

    Args:
        filepath: Path to the FASTA file as a string or `Path` object.

    Returns:
        A list of `(identifier, description)` tuples in file order.
        `description` is `None` when a header contains only an identifier.

    Raises:
        ValueError: If the source contains no FASTA records, sequence data
            appears before the first header, or a FASTA header does not
            contain a sequence identifier.
    """
    # Convert the supplied filepath into a Path.
    path = Path(filepath)

    # Prepare an empty list for discovered headers.
    headers: list[tuple[str, str | None]] = []

    # Open the FASTA file.
    with path.open("r", encoding="utf-8") as file:
        # Read the file one line at a time.
        for raw_line in file:
            # Remove surrounding whitespace.
            line = raw_line.strip()

            # Skip empty lines.
            if not line:
                continue

            # If this is a header, parse and save it.
            if line.startswith(">"):
                headers.append(_parse_header(line))
                continue

            # Reject sequence data before the first header.
            if not headers:
                raise ValueError(
                    f"'{path}' is not a valid FASTA source: "
                    "sequence data appears before the first header."
                )

    # Reject a file containing no FASTA headers.
    if not headers:
        raise ValueError(f"'{path}' does not contain any FASTA records.")

    # Return all discovered headers.
    return headers

Notice that get_headers() does not store the sequence data. It scans the file and collects only the identifiers and descriptions we need for record discovery.

Selecting One FASTA Record

Now we can build the main loader:

get_sequence()

We want to select one record either by identifier:

fasta.get_sequence(
    "samples/sample.fasta",
    identifier="M57671.1",
)

or by its zero-based position:

fasta.get_sequence(
    "samples/sample.fasta",
    index=0,
)

Both calls will return one SequenceRecord.

Creating the get_sequence() Boundary

Start with:

def get_sequence(
    filepath: str | Path,
    *,
    identifier: str | None = None,
    index: int | None = None,
) -> SequenceRecord:
    """Return one FASTA record by identifier or zero-based index.

    Args:
        filepath: Path to the FASTA file.
        identifier: Identifier of the record to load.
        index: Zero-based position of the record to load.

    Returns:
        The selected FASTA record as a neutral `SequenceRecord`.

    Raises:
        ValueError: If selector arguments are invalid, sequence data appears
            before the first header, the requested record cannot be found, or
            the selected record contains no sequence data.
    """

The * makes identifier and index keyword-only arguments.

That gives us clear calls such as:

identifier="M57671.1"

or:

index=0

instead of relying on positional values whose meaning is harder to see.

Requiring One Selector

We want exactly one of these:

identifier
index

So add:

if (identifier is None) == (index is None):
    raise ValueError("Provide exactly one of 'identifier' or 'index'.")

The rule is:

identifier only → valid
index only      → valid
both            → invalid
neither         → invalid

Then clean and check the supplied value:

if identifier is not None:
    identifier = identifier.strip()

    if not identifier:
        raise ValueError("'identifier' must not be empty.")

if index is not None and index < 0:
    raise ValueError("'index' is zero-based and must be non-negative.")

Our FASTA indexes are zero-based:

first record  → 0
second record → 1
third record  → 2

Preparing the Record Search

Now add the small amount of state we need while moving through the file:

path = Path(filepath)
current_index = 0
seen_header = False
selected_identifier: str | None = None
selected_description: str | None = None
sequence_parts: list[str] = []

current_index tracks the current FASTA record.

We start directly at:

0

because FASTA record indexes are zero-based. That gives us a simple reading order:

check record 0
advance to 1
check record 1
advance to 2
...

seen_header lets us distinguish a real FASTA record from sequence data that appears before the first header, without using a special negative index value.

selected_identifier and selected_description stay empty until we find the requested record.

sequence_parts will store only the wrapped sequence lines belonging to that selected record.

Streaming Through the FASTA File

Now scan the file:

with path.open("r", encoding="utf-8") as file:
    for raw_line in file:
        line = raw_line.strip()

        if not line:
            continue

        if line.startswith(">"):
            if selected_identifier is not None:
                break

            current_identifier, current_description = _parse_header(line)

            matches = (
                current_identifier == identifier
                if identifier is not None
                else current_index == index
            )

            if matches:
                selected_identifier = current_identifier
                selected_description = current_description

            current_index += 1
            continue

Every header starts another FASTA record.

Once:

selected_identifier is not None

the target record has already been found. The next header therefore means that selected sequence is complete, so:

break

stops reading the file.

For each header, we first parse and check the current record using its existing zero-based index. Only after that header has been processed do we advance:

current_index += 1

So the order stays easy to follow:

check record 0 → advance to 1
check record 1 → advance to 2
check record 2 → advance to 3

Matching by Identifier or Index

This part decides whether the current record is the one we want:

matches = (
    current_identifier == identifier
    if identifier is not None
    else current_index == index
)

If the caller supplied an identifier, we compare identifiers.

Otherwise, we compare the zero-based index.

So:

identifier="original_example"

means:

current_identifier == "original_example"

while:

index=4

means:

current_index == 4

If the record matches:

if matches:
    selected_identifier = current_identifier
    selected_description = current_description

we remember its metadata.

Collecting Only the Selected Sequence

For a sequence line:

if not seen_header:
    raise ValueError(
        f"'{path}' is not a valid FASTA source: "
        "sequence data appears before the first header."
    )

if selected_identifier is not None:
    sequence_parts.append("".join(line.split()))

seen_header remains False until the first FASTA header appears, so sequence data before that point is invalid FASTA structure for our loader.

Once the requested record has been selected, its sequence lines are added to:

sequence_parts

For:

AATTTT
AAAAC

we collect:

["AATTTT", "AAAAC"]

Records before the target are scanned, but their sequence lines are not stored.

When the next header appears after the selected record, the loop stops.

Finishing the Record

After the scan, we handle three simple cases.

If we never saw a header:

if not seen_header:
    raise ValueError(f"'{path}' does not contain any FASTA records.")

If the requested identifier or index was never found:

if selected_identifier is None:
    target = identifier if identifier is not None else f"index {index}"

    raise ValueError(
        f"No sequence found matching '{target}' in '{path}'."
    )

Then join the wrapped sequence lines:

sequence = "".join(sequence_parts)

If the selected record contains no sequence:

if not sequence:
    raise ValueError(
        f"Sequence '{selected_identifier}' in '{path}' "
        "does not contain sequence data."
    )

Finally, return our existing neutral record:

return SequenceRecord(
    identifier=selected_identifier,
    description=selected_description,
    sequence=sequence,
)

The FASTA-specific work is finished.

The Complete get_sequence() Function

Here is the complete function we just built:

def get_sequence(
    filepath: str | Path,
    *,
    identifier: str | None = None,
    index: int | None = None,
) -> SequenceRecord:
    """Return one FASTA record by identifier or zero-based index.

    Args:
        filepath: Path to the FASTA file.
        identifier: Identifier of the record to load.
        index: Zero-based position of the record to load.

    Returns:
        The selected FASTA record as a neutral `SequenceRecord`.

    Raises:
        ValueError: If selector arguments are invalid, sequence data appears
            before the first header, the requested record cannot be found, or
            the selected record contains no sequence data.
    """
    # Require exactly one selector: identifier OR index.
    if (identifier is None) == (index is None):
        raise ValueError("Provide exactly one of 'identifier' or 'index'.")

    # Validate the identifier if one was provided.
    if identifier is not None:
        identifier = identifier.strip()

        if not identifier:
            raise ValueError("'identifier' must not be empty.")

    # Validate the zero-based index if one was provided.
    if index is not None and index < 0:
        raise ValueError("'index' is zero-based and must be non-negative.")

    # Convert the supplied filepath into a Path.
    path = Path(filepath)

    # Start with the first FASTA record at index 0.
    current_index = 0

    # Track whether we have seen at least one FASTA header.
    seen_header = False

    # Prepare storage for the selected record.
    selected_identifier: str | None = None
    selected_description: str | None = None
    sequence_parts: list[str] = []

    # Open the FASTA file.
    with path.open("r", encoding="utf-8") as file:
        # Read the file one line at a time.
        for raw_line in file:
            # Remove surrounding whitespace.
            line = raw_line.strip()

            # Skip empty lines.
            if not line:
                continue

            # If this is a FASTA header:
            if line.startswith(">"):
                # Stop if the selected record has already ended.
                if selected_identifier is not None:
                    break

                # Mark that a FASTA header has been seen.
                seen_header = True

                # Parse the current header.
                current_identifier, current_description = _parse_header(line)

                # Check whether this record matches the requested ID or index.
                matches = (
                    current_identifier == identifier
                    if identifier is not None
                    else current_index == index
                )

                # Remember the selected identifier and description.
                if matches:
                    selected_identifier = current_identifier
                    selected_description = current_description

                # Move to the next record number after processing this header.
                current_index += 1

                # Continue to the next line.
                continue

            # Reject sequence data before the first header.
            if not seen_header:
                raise ValueError(
                    f"'{path}' is not a valid FASTA source: "
                    "sequence data appears before the first header."
                )

            # If this is our selected record, save the sequence line.
            if selected_identifier is not None:
                sequence_parts.append("".join(line.split()))

    # Reject a file containing no FASTA records.
    if not seen_header:
        raise ValueError(f"'{path}' does not contain any FASTA records.")

    # Reject the request if the selected record was never found.
    if selected_identifier is None:
        target = identifier if identifier is not None else f"index {index}"

        raise ValueError(
            f"No sequence found matching '{target}' in '{path}'."
        )

    # Join the selected sequence lines.
    sequence = "".join(sequence_parts)

    # Reject a selected record containing no sequence data.
    if not sequence:
        raise ValueError(
            f"Sequence '{selected_identifier}' in '{path}' "
            "does not contain sequence data."
        )

    # Return the selected data as a SequenceRecord.
    return SequenceRecord(
        identifier=selected_identifier,
        description=selected_description,
        sequence=sequence,
    )

What Makes This Streaming?

The key line is:

for raw_line in file:

Python gives us one line at a time instead of loading the entire FASTA file into another large string first.

For get_sequence():

records before target
    scan, do not store their sequence

selected record
    store its sequence lines

next header
    stop reading

records after target
    never read

So memory mainly depends on the selected sequence rather than every sequence in the FASTA file.

We still scan from the beginning until we reach the target. This is not random-access indexing, but it is exactly the behavior we need for our current experiments.

Why Use _parse_header() as a Helper?

Both public functions need to interpret FASTA headers in exactly the same way.

Without a shared helper:

get_headers()     header parsing
get_sequence()    same header parsing again

With _parse_header():

get_headers()  ─┐
                ├→ _parse_header()
get_sequence() ─┘

we keep that format rule in one place.

get_headers() can focus on discovering the available records, while get_sequence() can focus on finding and returning one selected record.

Biological validation is still separate. The FASTA loader understands the file structure; DNA decides whether the selected sequence contains valid DNA symbols.

The Complete fasta.py

Our complete new module is now:

"""Streaming helpers for reading FASTA files."""

from pathlib import Path

from .records import SequenceRecord


def _parse_header(line: str) -> tuple[str, str | None]:
    """Parse one FASTA header into its identifier and optional description.

    Args:
        line: FASTA header line including the leading `>` marker.

    Returns:
        A tuple containing the sequence identifier and its optional
        description. The description is `None` when the header contains
        only an identifier.

    Raises:
        ValueError: If the header does not contain a sequence identifier.
    """
    # Remove the leading ">" marker and surrounding whitespace.
    header = line[1:].strip()

    # Reject a header with no identifier.
    if not header:
        raise ValueError("A FASTA header must contain a sequence identifier.")

    # Split the identifier from the optional description.
    parts = header.split(maxsplit=1)

    # Extract the identifier and optional description.
    identifier = parts[0]
    description = parts[1] if len(parts) == 2 else None

    # Return both values.
    return identifier, description


def get_headers(
    filepath: str | Path,
) -> list[tuple[str, str | None]]:
    """Read FASTA headers and return the available records in file order.

    The function scans the FASTA source without storing sequence data.
    Each returned item contains the record identifier and its optional
    description.

    Args:
        filepath: Path to the FASTA file as a string or `Path` object.

    Returns:
        A list of `(identifier, description)` tuples in file order.
        `description` is `None` when a header contains only an identifier.

    Raises:
        ValueError: If the source contains no FASTA records, sequence data
            appears before the first header, or a FASTA header does not
            contain a sequence identifier.
    """
    # Convert the supplied filepath into a Path.
    path = Path(filepath)

    # Prepare an empty list for discovered headers.
    headers: list[tuple[str, str | None]] = []

    # Open the FASTA file.
    with path.open("r", encoding="utf-8") as file:
        # Read the file one line at a time.
        for raw_line in file:
            # Remove surrounding whitespace.
            line = raw_line.strip()

            # Skip empty lines.
            if not line:
                continue

            # If this is a header, parse and save it.
            if line.startswith(">"):
                headers.append(_parse_header(line))
                continue

            # Reject sequence data before the first header.
            if not headers:
                raise ValueError(
                    f"'{path}' is not a valid FASTA source: "
                    "sequence data appears before the first header."
                )

    # Reject a file containing no FASTA headers.
    if not headers:
        raise ValueError(f"'{path}' does not contain any FASTA records.")

    # Return all discovered headers.
    return headers


def get_sequence(
    filepath: str | Path,
    *,
    identifier: str | None = None,
    index: int | None = None,
) -> SequenceRecord:
    """Return one FASTA record by identifier or zero-based index.

    Args:
        filepath: Path to the FASTA file.
        identifier: Identifier of the record to load.
        index: Zero-based position of the record to load.

    Returns:
        The selected FASTA record as a neutral `SequenceRecord`.

    Raises:
        ValueError: If selector arguments are invalid, sequence data appears
            before the first header, the requested record cannot be found, or
            the selected record contains no sequence data.
    """
    # Require exactly one selector: identifier OR index.
    if (identifier is None) == (index is None):
        raise ValueError("Provide exactly one of 'identifier' or 'index'.")

    # Validate the identifier if one was provided.
    if identifier is not None:
        identifier = identifier.strip()

        if not identifier:
            raise ValueError("'identifier' must not be empty.")

    # Validate the zero-based index if one was provided.
    if index is not None and index < 0:
        raise ValueError("'index' is zero-based and must be non-negative.")

    # Convert the supplied filepath into a Path.
    path = Path(filepath)

    # Start with the first FASTA record at index 0.
    current_index = 0

    # Track whether we have seen at least one FASTA header.
    seen_header = False

    # Prepare storage for the selected record.
    selected_identifier: str | None = None
    selected_description: str | None = None
    sequence_parts: list[str] = []

    # Open the FASTA file.
    with path.open("r", encoding="utf-8") as file:
        # Read the file one line at a time.
        for raw_line in file:
            # Remove surrounding whitespace.
            line = raw_line.strip()

            # Skip empty lines.
            if not line:
                continue

            # If this is a FASTA header:
            if line.startswith(">"):
                # Stop if the selected record has already ended.
                if selected_identifier is not None:
                    break

                # Mark that a FASTA header has been seen.
                seen_header = True

                # Parse the current header.
                current_identifier, current_description = _parse_header(line)

                # Check whether this record matches the requested ID or index.
                matches = (
                    current_identifier == identifier
                    if identifier is not None
                    else current_index == index
                )

                # Remember the selected identifier and description.
                if matches:
                    selected_identifier = current_identifier
                    selected_description = current_description

                # Move to the next record number after processing this header.
                current_index += 1

                # Continue to the next line.
                continue

            # Reject sequence data before the first header.
            if not seen_header:
                raise ValueError(
                    f"'{path}' is not a valid FASTA source: "
                    "sequence data appears before the first header."
                )

            # If this is our selected record, save the sequence line.
            if selected_identifier is not None:
                sequence_parts.append("".join(line.split()))

    # Reject a file containing no FASTA records.
    if not seen_header:
        raise ValueError(f"'{path}' does not contain any FASTA records.")

    # Reject the request if the selected record was never found.
    if selected_identifier is None:
        target = identifier if identifier is not None else f"index {index}"

        raise ValueError(
            f"No sequence found matching '{target}' in '{path}'."
        )

    # Join the selected sequence lines.
    sequence = "".join(sequence_parts)

    # Reject a selected record containing no sequence data.
    if not sequence:
        raise ValueError(
            f"Sequence '{selected_identifier}' in '{path}' "
            "does not contain sequence data."
        )

    # Return the selected data as a SequenceRecord.
    return SequenceRecord(
        identifier=selected_identifier,
        description=selected_description,
        sequence=sequence,
    )

Exporting FASTA Beside Plain Text

We have added the implementation, so now update:

src/genome_toolkit/load/__init__.py

Our current file is:

"""Sequence loaders and neutral records."""

from . import text
from .records import SequenceRecord

__all__ = ["SequenceRecord", "text"]

Add the new source:

"""Sequence loaders and neutral records."""

from . import fasta, text
from .records import SequenceRecord

__all__ = ["SequenceRecord", "fasta", "text"]

Now our public loading API grows naturally:

text.get_sequence(...)
fasta.get_headers(...)
fasta.get_sequence(...)

We do not need names such as:

get_text_sequence()
get_fasta_sequence()
get_fasta_headers()

in one flat namespace. The source module already tells us which format we are working with.

Adding a Repeatable FASTA Sample

For Part 4.5, we will use a multi-record FASTA sample rather than a file created only around our short test sequence.

Create:

samples/sample.fasta

with:

>M57671.1 Octodon degus insulin mRNA, complete cds
TGCGTTAGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCCGGCTTGGGCCCGGCTT
AGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCC

>ALPHA_GENE_4582 one of the alpha proteins
TGCGTTAGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCCGGCTTGGGCCCGGCTT
AGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCCCGGCTTAGGCTAAACCTTGGGCC

>BETA_REGULATOR_991 a regulatory sequence from the beta cluster
CCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCC
GGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGGTTAAGCTTCCGG

>GAMMA_OPERON_SEQ3 a short sequence from the gamma operon region
GATTACAGATTACA

>original_example Original Genome Toolkit test sequence
AATTTT
AAAAC

This gives us a much better FASTA sample for the loader because the file contains several records, different identifiers and descriptions, and sequences of different lengths.

At the end, we keep our original Genome Toolkit test sequence:

AATTTTAAAAC

as its own FASTA record:

>original_example Original Genome Toolkit test sequence
AATTTT
AAAAC

That lets us demonstrate a realistic multi-record FASTA file while still preserving the exact scientific checkpoint we have used throughout the series.

Our samples directory is now:

samples/
├── sample.txt
└── sample.fasta              # <-- NEW

Checking the Available FASTA Records

Before changing our main application, let us verify get_headers() by itself.

Use:

from genome_toolkit.load import fasta


headers = fasta.get_headers("samples/sample.fasta")
print(headers)

Running it should give us:

[
    ('M57671.1', 'Octodon degus insulin mRNA, complete cds'),
    ('ALPHA_GENE_4582', 'one of the alpha proteins'),
    ('BETA_REGULATOR_991', 'a regulatory sequence from the beta cluster'),
    ('GAMMA_OPERON_SEQ3', 'a short sequence from the gamma operon region'),
    ('original_example', 'Original Genome Toolkit test sequence')
]

In a normal terminal, Python will usually print that list on one line. The important part is that Genome Toolkit discovers all five records in file order and keeps each identifier together with its description.

The list position also gives us the zero-based indexes:

index 0 → M57671.1
index 1 → ALPHA_GENE_4582
index 2 → BETA_REGULATOR_991
index 3 → GAMMA_OPERON_SEQ3
index 4 → original_example

For our main application, we will select our existing checkpoint by identifier:

identifier="original_example"

That makes the intention clearer than depending on where the record happens to appear in the file.

Updating Our Existing application.py

Part 4.4 used the plain-text source:

from genome_toolkit.load import text

and:

record = text.get_sequence(
    SAMPLES_DIR / "sample.txt"
)

Part 4.5 changes only that source-specific part.

Replace the import with:

from genome_toolkit.load import fasta

and load our original Genome Toolkit test sequence by identifier:

record = fasta.get_sequence(
    SAMPLES_DIR / "sample.fasta",
    identifier="original_example",
)

Everything after the returned SequenceRecord stays exactly the same.

The complete application.py is:

from pathlib import Path

from genome_toolkit.algorithms import (
    count_kmer,
    find_most_frequent_kmers,
)
from genome_toolkit.load import fasta
from genome_toolkit.sequence import DNA


SAMPLES_DIR = Path(__file__).resolve().parent / "samples"


record = fasta.get_sequence(
    SAMPLES_DIR / "sample.fasta",
    identifier="original_example",
)

dna = DNA.model_validate(
    record,
    from_attributes=True,
)

seq = dna.sequence
kmer = "AA"
k_len = 3


print(f"Sequence: {seq}")
print(f"k-mer: {kmer}")
print(f"Repeats found: {count_kmer(seq, kmer)}")
print(f"Most frequent k-mer: {find_most_frequent_kmers(seq, k_len)}")

Our workflow is now:

sample.fasta
     ↓
fasta.get_sequence()
     ↓
SequenceRecord
     ↓
DNA.model_validate(...)
     ↓
validated DNA
     ↓
dna.sequence
     ↓
existing k-mer algorithms

Notice again what did not change:

src/genome_toolkit/sequence/
src/genome_toolkit/algorithms/

We have not changed the algorithm signatures, loops, or return values.

Running the Complete Part 4.5 Application

Run:

uv run python application.py

We should still see:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

The biological input now came from:

samples/sample.fasta

instead of:

samples/sample.txt

but the same validated sequence reached the same algorithms and produced the same result.

That is exactly the kind of continuity we want during this refactor.

Our New Project Structure

At the end of Part 4.5, our project looks like this:

genome_toolkit/
├── .git/
├── .gitignore
├── .venv/
├── README.md
├── application.py              # <-- UPDATED
├── pyproject.toml
├── uv.lock
├── samples/
│   ├── sample.txt
│   └── sample.fasta            # <-- NEW
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── py.typed
        ├── algorithms/
        │   ├── __init__.py
        │   └── kmer.py
        ├── sequence/
        │   ├── __init__.py
        │   ├── base.py
        │   └── dna.py
        └── load/
            ├── __init__.py      # <-- UPDATED
            ├── fasta.py         # <-- NEW
            ├── records.py
            └── text.py

No dependency was added, so:

pyproject.toml
uv.lock

remain unchanged.

The only package implementation files changed in Part 4.5 are:

load/fasta.py        # NEW
load/__init__.py     # UPDATED

plus:

sample.fasta         # NEW
application.py       # UPDATED

That is a small structural change, even though the FASTA parser itself contains several new pieces of logic.

Summary

In Part 4.5, we extended the loading layer we built in Part 4.4 and added our first FASTA loader.

The new fasta.py module gives us three focused functions:

_parse_header()
get_headers()
get_sequence()

Together they let Genome Toolkit:

parse FASTA headers
discover record identifiers and descriptions
select one record by identifier or index
join wrapped sequence lines
read the file incrementally
return SequenceRecord

Both loading paths now reach the same neutral object:

plain text ─┐
            ├→ SequenceRecord
FASTA ──────┘

and the rest of our workflow remains unchanged:

SequenceRecord
      ↓
DNA
      ↓
dna.sequence
      ↓
existing k-mer algorithms

This simple FASTA support is enough for many of the real genome-data experiments we are planning next. As our experiments grow, Genome Toolkit can grow with them by adding new loaders and richer biological-data support only when we actually need them.

New Concepts We Learned

• FASTA — One of the most common formats for storing and exchanging DNA, RNA, and protein sequences.

• FASTA header — A line beginning with > that contains a record identifier and may also contain a description.

• Generic FASTA loader — Our loader understands the common FASTA record structure without trying to decode every provider-specific header convention.

• Private helper function — _parse_header() keeps the shared header parsing rule in one place for both public FASTA functions.

• split(maxsplit=1) — Splits the identifier from the rest of the header while keeping a multi-word description together.

• Tuple return values and unpacking — _parse_header() returns (identifier, description), which we can assign directly to two variables.

• Keyword-only arguments — The * in get_sequence() gives us clear calls such as identifier="..." or index=0.

• Zero-based indexing — The first FASTA record is index 0, the second is index 1, and so on.

• Conditional expression — matches chooses the identifier comparison when an identifier was supplied, otherwise it compares the record index.

• continue and break — continue moves to the next loop iteration, while break stops the scan once the selected FASTA record is complete.

• Streaming record selection — get_sequence() reads the file line by line, ignores sequence data from records we do not need, stores only the selected sequence, and stops at the next header.

The most important architectural idea remains the same:

The loader understands the file format. The biological model decides whether the selected symbols are valid DNA.

What is Next?

Our input side now supports both plain-text and FASTA sequence files:

plain text ─┐
            ├→ SequenceRecord → DNA
FASTA ──────┘

Our two k-mer functions still accept a plain string:

sequence: str

and return simple Python values:

count_kmer()               → int
find_most_frequent_kmers() → list[str]

In Part 4.6, we will improve how those algorithms receive data and how they return scientific results.

The actual k-mer calculations will stay the same.

The full source code for Genome Toolkit is available here:

https://github.com/rebelC0der/Genome_Toolkit

I hope adding our first FASTA loader and learning how to discover and stream biological sequence records through Genome Toolkit was useful for your bioinformatics and programming journey! If you found this article valuable and want to help us continue building rebelScience, please consider supporting our project. You can explore various ways to contribute here:

https://rebelscience.club/cryptocurrency-donations/

Until next time, rebelCoder, signing out.

References

• FASTA format overview: https://en.wikipedia.org/wiki/FASTA_format
• NCBI FASTA format: https://www.ncbi.nlm.nih.gov/genbank/fastaformat/
• UniProt protein information and FASTA conventions: https://www.uniprot.org/help/protein
• Ensembl data downloads and FASTA conventions: https://www.ensembl.org/info/data/ftp/index.html
• Python pathlib: https://docs.python.org/3/library/pathlib.html

Video version of this article:

In Part 4.3, we added our first validated biological models. Genome Toolkit can now create a DNA object, normalize lowercase DNA to uppercase, reject unsupported symbols, and keep useful information such as the sequence identifier and description together with the biological data.

Most importantly, we deliberately left our existing k-mer algorithms unchanged.

They still accept a normal Python string:

sequence: str

and our application passes them the validated sequence through:

seq = dna.sequence

So the end of our current workflow still looks like this:

DNA(...)
    ↓
validated DNA
    ↓
dna.sequence
    ↓
our existing k-mer algorithms

That is exactly where we want to continue from.

Our next limitation is no longer DNA validation. The sequence itself is still written directly inside application.py:

sequence="aattttaaaac",

Real biological data usually comes from somewhere outside our Python source code, so in this part we are going to add the smallest possible loading layer and read one sequence from a plain-text file.

We will add a small neutral SequenceRecord, create a plain-text loader, convert the loaded record into our existing DNA model, and then continue using the same two k-mer algorithms exactly as before.

The new workflow will become:

sample.txt
    ↓
text.get_sequence()
    ↓
SequenceRecord
    ↓
DNA
    ↓
dna.sequence
    ↓
our existing k-mer algorithms

Notice what is not changing:

algorithms/kmer.py

We are not changing the algorithm signatures, the loops, or the return values in Part 4.4. This article is about getting biological data into Genome Toolkit from a file.

Starting With Our Working Project

We continue from the exact final state of Part 4.3.

Our project currently looks like this:

genome_toolkit/
├── .git/
├── .gitignore
├── .venv/
├── README.md
├── application.py
├── pyproject.toml
├── uv.lock
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── py.typed
        ├── algorithms/
        │   ├── __init__.py
        │   └── kmer.py
        └── sequence/
            ├── __init__.py
            ├── base.py
            └── dna.py

Our current application.py creates the DNA directly:

dna = DNA(
    identifier="example_dna",
    description="Part 4.3 demonstration sequence",
    sequence="aattttaaaac",
)

seq = dna.sequence

and the existing algorithms still receive:

count_kmer(seq, kmer)
find_most_frequent_kmers(seq, k_len)

Running the complete Part 4.3 application gives us the same scientific checkpoint we have been preserving throughout the refactor:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

In Part 4.4, we want to keep that result while changing only where the original sequence comes from.

What Are We Going to Add?

We need two small pieces inside a new loading package:

SequenceRecord
text.get_sequence()

SequenceRecord will hold the values that a loader has parsed from an external source.

text.get_sequence() will read one sequence from a plain-text file and return that record.

Then our existing DNA model will decide whether the loaded symbols are actually valid DNA:

plain-text file
      ↓
loader reads the file
      ↓
SequenceRecord
      ↓
DNA validates the biology
      ↓
dna.sequence
      ↓
existing algorithms

This separation is important because reading a file and deciding what the biological symbols mean are two different jobs.

Why Not Return DNA Directly?

Imagine that our text file contains:

ACGTACGT

That could be DNA.

But a plain-text file could just as easily contain:

ACGUACGU

for RNA, or:

MKTLLVAG

for a protein sequence.

The file format itself does not tell us which biological type the symbols are supposed to represent.

If our text loader returned DNA directly:

text loader
    ↓
DNA

the loader would be making two decisions at once:

How do I read this file?
+
What biological type is this sequence?

Instead, we will keep those steps separate:

text file
    ↓
SequenceRecord
    ↓
DNA / future RNA / future Protein

The loader tells us what it parsed. The biological model tells us whether those parsed symbols satisfy the rules for DNA, RNA, protein, or another future sequence type.

This also means we can reuse the same loading code later without teaching the text loader about every biological model Genome Toolkit may eventually support.

Creating the load Package

Inside:

src/genome_toolkit/

create a new folder:

load/

We will build it one file at a time.

The first file we need is:

records.py

So our project temporarily becomes:

src/
└── genome_toolkit/
    ├── algorithms/
    ├── sequence/
    └── load/                   # <-- NEW
        └── records.py          # <-- NEW

Creating a Neutral SequenceRecord

Open:

src/genome_toolkit/load/records.py

and add:

"""Lightweight records returned by sequence loaders."""

from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class SequenceRecord:
    """Parsed sequence data before biological validation."""

    identifier: str
    sequence: str
    description: str | None = None

There are a few new Python ideas here, so let us look at them before moving on.

What Is a Dataclass and Why Are We Using It?

We import:

from dataclasses import dataclass

dataclass comes from Python’s standard library. It is designed for small classes whose main job is to hold data.

When we write:

@dataclass(frozen=True, slots=True)
class SequenceRecord:
    identifier: str
    sequence: str
    description: str | None = None

Python turns those typed fields into a useful data object for us.

Without @dataclass, we would need to write the basic setup ourselves:

class SequenceRecord:
    def __init__(
        self,
        identifier: str,
        sequence: str,
        description: str | None = None,
    ):
        self.identifier = identifier
        self.sequence = sequence
        self.description = description

And that is only the beginning. If we also wanted the same useful object representation, easy comparisons, immutability, and fixed attributes, we would need to write even more code ourselves.

With @dataclass, we get useful behavior automatically:

typed named fields
automatic __init__()
useful __repr__()
optional immutability with frozen=True
compact memory and fixed attributes with slots=True
standard library only

For SequenceRecord, this fits very well because the object has no special behavior to invent. Its job is simply:

Carry parsed sequence data from a loader to a biological model.

It is still just a simple Python object carrying data. @dataclass removes the repetitive plumbing so we can focus on what the record actually contains.

The line:

@dataclass(frozen=True, slots=True)

is also a Python decorator. We already saw decorators such as @field_validator and @classmethod in Part 4.3. Here, the decorator tells Python to process SequenceRecord as a dataclass and apply the two options we supplied.

Check out this very helpful video to learn more about why you should be using Python dataclasses in your propjects:

Why Not Use Another Pydantic Model?

We already use Pydantic for Sequence and DNA, so why not use it here too?

Because SequenceRecord has a much smaller job.

It represents parsed external data before biological validation:

file
  ↓
SequenceRecord
  ↓
DNA validation

We do not need SequenceRecord to decide whether the sequence is DNA, normalize nucleotides, or provide Pydantic validation rules. Our existing biological models already do that.

Compared with a plain dictionary such as:

{
    "id": "sample",
    "seq": "ACGT",
}

our dataclass gives us named fields:

record.identifier
record.sequence
record.description

along with type information, editor autocomplete, and one predictable shape.

What Does frozen=True Do Here?

We used the same idea in our Pydantic model configuration in Part 4.3.

For a dataclass:

frozen=True

means that after we create the record, its fields cannot simply be reassigned.

For example, we do not want loading code to create:

record.sequence = "AAAA"

later by accident.

The record represents what we parsed from the source file, so keeping those parsed values fixed makes the handoff into biological validation easier to reason about.

What Does slots=True Do?

Normally, Python objects can often have new attributes added to them dynamically.

For example, without slots, code could accidentally try to attach something unrelated such as:

record.random_value = 123

slots=True restricts the object to the fields we actually defined:

identifier
sequence
description

It also makes small data objects somewhat more compact in memory. For us, the main practical benefit is that SequenceRecord stays a simple, predictable data container instead of quietly growing arbitrary attributes.

The Three Record Fields

Our record contains:

identifier: str
sequence: str
description: str | None = None

The identifier gives the parsed sequence a name. The sequence contains the symbols read from the source, and description is optional because a simple text file may not provide one.

At this point we have a useful shape for loaded sequence data, but nothing is reading a file yet. Now we can build the loader that creates this record.

Adding the Plain-Text Loader

Create our second file:

src/genome_toolkit/load/text.py

Our loading package now contains:

load/
├── records.py
└── text.py                    # <-- NEW

Add:

"""Loader for plain-text sequence files."""

from pathlib import Path

from .records import SequenceRecord


def get_sequence(filepath: str | Path) -> SequenceRecord:
    """Load one sequence and remove all whitespace.

    Args:
        filepath: Path to a plain-text file containing one sequence.

    Returns:
        A neutral sequence record containing the parsed sequence.

    Raises:
        ValueError: If the file contains no sequence data.
    """
    path = Path(filepath)

    with path.open("r", encoding="utf-8") as file:
        sequence = "".join("".join(line.split()) for line in file)

    if not sequence:
        raise ValueError(f"'{path}' does not contain sequence data.")

    return SequenceRecord(
        identifier=path.stem,
        sequence=sequence,
    )

This is the first actual file loader in Genome Toolkit, so let us go through it from top to bottom.

Working With File Paths Using Path

We begin with:

from pathlib import Path

pathlib is part of Python’s standard library, and Path gives us an object for working with filesystem paths.

Instead of treating a path only as a string such as:

"samples/sample.txt"

we can work with:

Path("samples/sample.txt")

and use useful path operations such as opening the file or getting its filename without the extension.

Our function accepts:

filepath: str | Path

The | means either type is accepted.

So both of these are valid:

text.get_sequence("samples/sample.txt")

and:

text.get_sequence(Path("samples/sample.txt"))

The first line inside the function:

path = Path(filepath)

converts either form into one consistent Path object. From that point onward, the rest of the loader only needs to work with path.

Opening the File

Next we have:

with path.open("r", encoding="utf-8") as file:

The "r" means we are opening the file for reading.

encoding="utf-8" tells Python how the text inside the file should be decoded. UTF-8 is the standard text encoding we will use for our sequence files.

The with statement creates a context manager. In simple terms, Python opens the file for this block and automatically closes it again when the block finishes, even if something goes wrong while we are reading it.

So instead of manually doing:

open file
read file
remember to close file

we get:

with file open
    read what we need
leave block
    file is closed automatically

Removing Whitespace From the Sequence

Inside the file block we use:

sequence = "".join("".join(line.split()) for line in file)

There are several small operations packed into this one line.

For each line:

line.split()

splits the line around whitespace.

For example:

"AATT TTAAn"

becomes pieces similar to:

"AATT"
"TTAA"

Then:

"".join(line.split())

joins those pieces back together without spaces:

AATTTTAA

The expression:

for line in file

processes the file one line at a time, and the outer:

"".join(...)

joins all of those cleaned lines into one final sequence.

So a file containing:

AATTTT
AAAAC

becomes:

AATTTTAAAAC

For this simple plain-text format, whitespace is formatting. It is not part of the biological sequence we want to pass into our model.

Rejecting an Empty Sequence

After reading the file we check:

if not sequence:
    raise ValueError(f"'{path}' does not contain sequence data.")

If the file contains no sequence after whitespace has been removed, there is nothing useful for the loader to return.

Rather than creating an empty record and allowing the problem to travel further into our program, we stop here with a clear error.

We will build a more deliberate error contract later in the series. For now, the ordinary ValueError from our technical plan is enough to communicate that this source did not contain the value our loader expected.

Creating the SequenceRecord

Finally:

return SequenceRecord(
    identifier=path.stem,
    sequence=sequence,
)

creates the neutral record.

The new expression:

path.stem

means the filename without its extension.

For:

samples/sample.txt

the stem is:

sample

so the returned record contains approximately:

identifier  → sample
sequence    → AATTTTAAAAC
description → None

Notice that the loader has still made no DNA decision.

If the text file contained invalid DNA symbols, text.get_sequence() could still return a SequenceRecord. The biological check happens in the next step when we try to turn that record into DNA.

Exposing Our Loading API

Now that the actual text loader exists, create:

src/genome_toolkit/load/__init__.py

Our loading package is now:

load/
├── __init__.py               # <-- NEW
├── records.py
└── text.py

Add:

"""Sequence loaders and neutral records."""

from . import text
from .records import SequenceRecord

__all__ = ["SequenceRecord", "text"]

This gives us a clean public loading API.

Instead of importing the function from its internal module path:

from genome_toolkit.load.text import get_sequence

we can write:

from genome_toolkit.load import text

and then call:

text.get_sequence(...)

Keeping the source name visible will also scale naturally when we add another loader:

text.get_sequence(...)
fasta.get_sequence(...)

That is clearer than creating increasingly long names such as:

get_text_sequence()
get_fasta_sequence()

in one flat namespace.

Adding Our First Sample File

At the repository root, create a new folder:

samples/

Then create:

samples/sample.txt

with:

AATTTT
AAAAC

We are deliberately using the same original Genome Toolkit sequence we have used throughout the series:

AATTTTAAAAC

The only difference is that it is now stored outside our Python code and wrapped across two lines.

This gives us a very useful checkpoint:

hardcoded sequence
        ↓
AATTTTAAAAC

plain-text file
        ↓
AATTTTAAAAC

If the loading layer is working correctly, the scientific calculation at the end of the workflow should still see the same sequence.

Loading Our First SequenceRecord

Now we can connect the new loader to our existing application.

Add:

from pathlib import Path

and:

from genome_toolkit.load import text

Then define the location of our sample files:

SAMPLES_DIR = Path(__file__).resolve().parent / "samples"

There are three useful path operations here:

__file__
    current Python file

.resolve()
    absolute filesystem path

.parent
    directory containing application.py

Then:

/ "samples"

uses Path‘s / operator to build the path to our samples/ directory.

So regardless of where we run the command from, application.py can find the sample directory relative to its own location.

Now load the file:

record = text.get_sequence(
    SAMPLES_DIR / "sample.txt"
)

At this point:

record.identifier

is:

sample

and:

record.sequence

is:

AATTTTAAAAC

But this is still only parsed data. We have not yet asked our biological model whether the sequence is valid DNA.

Converting the Record Into Validated DNA

This is where Part 4.3 connects directly to our new loading layer.

Our SequenceRecord contains:

identifier
description
sequence

and our DNA model expects those same field names.

Before we use any Pydantic shortcut, let us connect them manually so we can see exactly what is happening.

First, Map the Fields Manually

After loading our record:

record = text.get_sequence(
    SAMPLES_DIR / "sample.txt"
)

we can create the DNA object exactly the same way we created DNA in Part 4.3:

dna = DNA(
    identifier=record.identifier,
    description=record.description,
    sequence=record.sequence,
)

There is nothing wrong with this approach.

We are simply taking each value from:

SequenceRecord

and assigning it to the matching field in:

DNA

The mapping is easy to see:

record.identifier   →   DNA.identifier
record.description  →   DNA.description
record.sequence     →   DNA.sequence

Our existing bridge to the algorithms can then remain:

seq = dna.sequence

and the same algorithm calls still work:

count_kmer(seq, kmer)
find_most_frequent_kmers(seq, k_len)

If we run:

uv run python application.py

the important scientific checkpoint is still:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

So we have already completed the important connection:

sample.txt
    ↓
SequenceRecord
    ↓
manual field mapping
    ↓
DNA
    ↓
dna.sequence
    ↓
existing algorithms

Now we can simplify one repetitive part.

Let Pydantic Read the Matching Fields for Us

Notice that both objects intentionally use the same field names:

SequenceRecord       DNA
--------------       ---
identifier       →   identifier
description      →   description
sequence         →   sequence

Writing:

dna = DNA(
    identifier=record.identifier,
    description=record.description,
    sequence=record.sequence,
)

is clear, but we are manually copying three matching fields.

Because DNA is a Pydantic model, it already has:

model_validate()

We can therefore replace the manual mapping with:

dna = DNA.model_validate(
    record,
    from_attributes=True,
)

This does not change our biological validation. It only changes how the values from record are supplied to the DNA model.

What Does model_validate() Do?

model_validate() is a Pydantic method for creating and validating a model from another value.

In our case:

source object   → SequenceRecord
target model    → DNA

The important option is:

from_attributes=True

That tells Pydantic to read matching values from the source object’s attributes.

So instead of us manually writing:

identifier=record.identifier
description=record.description
sequence=record.sequence

Pydantic reads those matching attributes for us.

The flow becomes:

SequenceRecord
      ↓
DNA.model_validate(
    record,
    from_attributes=True,
)
      ↓
read matching attributes
      ↓
run inherited Sequence rules
      ↓
run DNA validator
      ↓
valid → DNA object created
invalid → Pydantic validation error

This is important: model_validate() does not bypass anything we built in Part 4.3.

If the loaded record contains:

AATTTTZAAAC

our DNA validator still sees the Z, rejects it, and no valid DNA object is created.

So our manual version:

dna = DNA(
    identifier=record.identifier,
    description=record.description,
    sequence=record.sequence,
)

and our shorter Pydantic version:

dna = DNA.model_validate(
    record,
    from_attributes=True,
)

both end at the same place:

validated DNA object

The second version simply avoids repeating field-by-field assignments when the two objects were deliberately designed with matching names.

When Should We Use This Conversion?

Automatic attribute conversion is convenient when the source object and target model intentionally share the same core schema.

For our current models, that is exactly what we have.

A few practical rules are useful to remember:

record has extra fields
→ unused source attributes can be ignored

DNA has optional/defaulted fields
→ their defaults can still be used

DNA requires a field the record does not provide
→ validation fails

matching record field contains invalid DNA
→ DNA validation fails

field names do not match
→ map the fields explicitly

So:

model_validate(..., from_attributes=True)

is not magic conversion between any two Python objects. It is a convenient way to replace the manual mapping we just wrote when the source and target intentionally use matching attributes.

Updating Our Existing application.py

Now we can update the complete application.

In Part 4.3, we added several extra print() calls to demonstrate what our new DNA model could do: length, indexing, slicing, iteration, and JSON serialization. Those examples were useful while we were learning the model, but we do not need to keep all of them in every later version of application.py.

From this point onward, we will return to a cleaner application that focuses on the current data flow and our original scientific checkpoint.

Before Part 4.4:

hardcoded string
      ↓
DNA
      ↓
dna.sequence
      ↓
algorithms

Now:

sample.txt
      ↓
SequenceRecord
      ↓
DNA
      ↓
dna.sequence
      ↓
algorithms

Our algorithm boundary remains unchanged.

Update application.py to:

from pathlib import Path

from genome_toolkit.algorithms import (
    count_kmer,
    find_most_frequent_kmers,
)
from genome_toolkit.load import text
from genome_toolkit.sequence import DNA


SAMPLES_DIR = Path(__file__).resolve().parent / "samples"


record = text.get_sequence(
    SAMPLES_DIR / "sample.txt"
)

dna = DNA.model_validate(
    record,
    from_attributes=True,
)

seq = dna.sequence
kmer = "AA"
k_len = 3


print(f"Sequence: {seq}")
print(f"k-mer: {kmer}")
print(f"Repeats found: {count_kmer(seq, kmer)}")
print(f"Most frequent k-mer: {find_most_frequent_kmers(seq, k_len)}")

Compare the last two calls with Part 4.3:

count_kmer(seq, kmer)
find_most_frequent_kmers(seq, k_len)

They are exactly the same.

And:

seq = dna.sequence

is still exactly the same bridge we established in Part 4.3.

That means we have added external file loading without touching:

src/genome_toolkit/algorithms/kmer.py

at all.

Running the Complete Part 4.4 Application

Run:

uv run python application.py

We should now see:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

Our loader still derives the identifier sample from sample.txt, and the validated DNA object still contains that information internally. We simply no longer print every model feature in the main application because those behaviors were already demonstrated in Part 4.3.

The important scientific data is still:

AATTTTAAAAC

and our original calculations still return:

Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

So our complete path is now:

sample.txt
    ↓
text.get_sequence()
    ↓
SequenceRecord
    ↓
DNA.model_validate(...)
    ↓
validated DNA
    ↓
dna.sequence
    ↓
existing k-mer algorithms

We added an external source without changing the biological model and without changing either algorithm.

Our New Project Structure

At the end of Part 4.4, our project looks like this:

genome_toolkit/
├── .git/
├── .gitignore
├── .venv/
├── README.md
├── application.py              # <-- UPDATED
├── pyproject.toml
├── uv.lock
├── samples/                    # <-- NEW
│   └── sample.txt              # <-- NEW
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── py.typed
        ├── algorithms/
        │   ├── __init__.py
        │   └── kmer.py
        ├── sequence/
        │   ├── __init__.py
        │   ├── base.py
        │   └── dna.py
        └── load/               # <-- NEW
            ├── __init__.py     # <-- NEW
            ├── records.py      # <-- NEW
            └── text.py         # <-- NEW

Notice what stayed untouched:

algorithms/
sequence/
pyproject.toml
uv.lock

We did not add another dependency, and we did not redesign the model or algorithm layers.

The new pieces are only the files needed to bring a simple external sequence into the workflow.

Why This Small Loading Layer Matters

At first, reading one text file may not look like a large feature.

But it gives Genome Toolkit an important new separation:

where data comes from
        ↓
what data was parsed
        ↓
what biological type it represents
        ↓
what scientific calculation we run

Those steps can now evolve independently.

A future FASTA loader can produce the same SequenceRecord. A database or API loader could eventually do the same. Our DNA model can validate those records without learning how each source works, and our k-mer algorithms can continue focusing only on their calculations.

For Part 4.4, however, we keep that architecture deliberately small. We support one plain-text file containing one sequence, and nothing more.

Summary

In Part 4.4, we moved the original Genome Toolkit sequence out of application.py and into our first external sample file.

We created a new load/ package, introduced the neutral SequenceRecord dataclass, and built text.get_sequence() to read a plain-text sequence file, remove whitespace, reject an empty source, and return the parsed sequence together with an identifier.

We then used Pydantic’s DNA.model_validate(..., from_attributes=True) to turn that neutral record into the same validated DNA model we built in Part 4.3.

Most importantly, we did not modify our two k-mer algorithms. They still accept strings, and application.py still passes them:

dna.sequence

through our existing:

seq = dna.sequence

bridge.

Our workflow has therefore grown from:

hardcoded string
      ↓
DNA
      ↓
algorithm

to:

plain-text file
      ↓
SequenceRecord
      ↓
DNA
      ↓
dna.sequence
      ↓
algorithm

while the original k-mer calculations remain unchanged.

New Concepts We Learned

• SequenceRecord — A small neutral object that carries sequence data parsed from an external source before we decide which biological model should validate it.

• dataclass — A Python standard-library tool for creating classes whose main purpose is to hold data. We use it for SequenceRecord so we get named fields, type information, and a predictable object shape without adding another validation framework.

• frozen=True in a dataclass — Prevents the parsed record fields from being reassigned after the object is created. This helps the record continue to represent the data we actually loaded from the source.

• slots=True — Restricts the dataclass to the fields we explicitly defined and prevents arbitrary new attributes from being attached later. It also makes small data objects more compact.

• Path and pathlib — Python’s standard way to work with filesystem paths as objects. We use Path to open files, combine path components, resolve locations, and derive the sample identifier from the filename.

• str | Path — A type annotation meaning that our loader accepts either a normal path string or a Path object.

• Context manager (with) — The with statement manages the lifetime of the open file for us. Python opens the file for the block and closes it automatically when the block ends.

• UTF-8 — The text encoding we explicitly use when reading our sequence files so Python knows how to decode the file contents.

• Path.stem — Gives us the filename without its extension. sample.txt therefore gives our simple loaded record the identifier sample.

• model_validate(..., from_attributes=True) — Lets Pydantic create and validate our DNA model by reading matching attributes from SequenceRecord. The conversion still runs all of the Sequence and DNA validation rules from Part 4.3.

The most important new idea is that parsing external data and validating biology are separate steps. The loader tells us what it read; DNA decides whether those symbols are valid DNA.

What is Next?

Our plain-text loader now gives Genome Toolkit a real external data source, but the format is deliberately minimal.

A plain-text file does not contain the record structure commonly used by real biological sequence collections. FASTA files can contain:

identifiers
descriptions
wrapped sequence lines
multiple biological records

So in Part 4.5, we will extend only the loading layer and add our first minimal streaming FASTA loader.

The workflow will become:

plain text ─┐
            ├→ SequenceRecord → DNA → dna.sequence → algorithms
FASTA ──────┘

And just like Part 4.4, Part 4.5 will leave our existing DNA model and k-mer algorithms unchanged.

The full source code for Genome Toolkit is available here:

https://github.com/rebelC0der/Genome_Toolkit

I hope adding our first plain-text sequence loader and connecting external sequence data to our validated DNA model was useful for your bioinformatics and programming journey! If you found this article valuable and want to help us continue building rebelScience, please consider supporting our project. You can explore various ways to contribute here:

https://rebelscience.club/cryptocurrency-donations/

Until next time, rebelCoder, signing out.

References

• Python dataclasses: https://docs.python.org/3/library/dataclasses.html
• Python pathlib: https://docs.python.org/3/library/pathlib.html
• Pydantic model validation: https://docs.pydantic.dev/latest/concepts/models/

Video version of this article:

In Part 4.1, we looked at where Genome Toolkit is going and why it makes sense to turn our small educational project into a proper scientific Python package. Now we are finally going to start doing it.

The important thing is that our scientific calculations already work. We have two k-mer algorithms, we know what input they receive, and we know exactly what output our current application produces. So before we change anything, we are going to use that working application as our reference point.

Starting With the Working Project

We are continuing inside the same Genome Toolkit Git repository:

genome_toolkit/
├── .git/
├── .gitignore
├── application.py
├── genome_toolkit.py
├── Pipfile
└── Pipfile.lock

The .git/ directory is important because it contains the history of our project. We are improving the same Genome Toolkit we have already been building, so we keep that history and continue working in the same repository.

Before touching the structure, let us run the original application one more time:

python application.py

Or, if you are using the Code Runner extension in Visual Studio Code, you can run it with:

Ctrl + Alt + N

We should get:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

This output is our working checkpoint. We already know these calculations are correct for the example we have been using throughout the series, so after we reorganize the project, we will run the application again and compare the result with this exact output.

That gives us a very simple goal for this article:

old project structure
        ↓
modern Python package
        ↓
same scientific calculations

We are changing how Genome Toolkit is organized, not what our k-mer algorithms calculate.

What Are We Going to Improve?

Right now, Genome Toolkit is still a very small Python project. We have our environment managed with Pipenv, our scientific code lives in one genome_toolkit.py file, and we create a genomeToolkit object before calling our algorithms.

That worked perfectly for the first few parts of the series, but now we want to give Genome Toolkit a cleaner structure that will be easier to grow.

By the end of this article, we will have:

uv
        ↓
a modern Python project

src/genome_toolkit/
        ↓
our installable Genome Toolkit package

algorithms/
        ↓
our k-mer functions

We are not going to learn all of Python packaging at once. We will change one small thing at a time, explain why it helps, and keep checking that our original scientific calculations still work.

The first thing we are going to modernize is how we manage the Python project itself.

Moving From Pipenv to uv

When we started Genome Toolkit, we used Pipenv to create a Python environment and manage our project dependencies. That is why our repository currently contains:

Pipfile
Pipfile.lock

For the modern version of Genome Toolkit, we are going to use uv.

uv is a modern Python project and package manager. It can create projects, manage Python environments, install dependencies, generate lock files, build packages, and run Python commands for us.

If uv is new to you, Corey Schafer has an excellent detailed tutorial on it. We are going to use only the parts we need for Genome Toolkit, but if you want a deeper introduction to the tool, I highly recommend watching his video:

Python Tutorial: UV – A Faster, All-in-One Package Manager to Replace Pip and Venv

In practical terms, many of the jobs for which we previously used several Python tools can now be handled through one tool:

project setup
environment
dependencies
lock file
package build
running commands
        ↓
       uv

For Genome Toolkit, this gives us a clean modern starting point without adding unnecessary tools.

Installing uv

Before we start using uv, we first need to install it.

On macOS and Linux, run:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

That installs uv on our system so we can use commands such as:

uv init
uv sync
uv run

If you already have uv installed, you can skip this step.

Removing the Old Environment Files

We begin by removing the old Pipenv declarations:

rm Pipfile Pipfile.lock

We are not deleting our Python code. application.py and genome_toolkit.py stay in place while we create the new package around them.

Our existing .gitignore also needs a small update.

Because this project already has its existing:

.git/

Git repository, uv does not generate a new .gitignore for us. So instead of deleting the file, open the existing .gitignore and replace its contents with:

# Python-generated files

__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments

.venv

This keeps temporary Python files, build files, and our local virtual environment out of the Git repository.

We keep .git/ exactly where it is because it contains the existing history of Genome Toolkit. At this point, the scientific code has not changed at all; we have only removed the old Pipenv configuration and updated the files that control our development environment.

Initializing Genome Toolkit as a Library

Now we can initialize the existing directory as a uv library:

uv init --lib --name genome-toolkit

There are two useful parts in this command. --name genome-toolkit gives the project its package distribution name, while --lib tells uv that Genome Toolkit is a library: reusable Python code that other programs can import and use.

That distinction is useful for our project:

library
provides reusable scientific functions and objects

application
uses those functions and decides what to show the user

Genome Toolkit itself is becoming the reusable library. Our existing application.py stays at the top level as a simple development and demonstration program that uses that library.

After running the command, uv creates the modern project files and a src/ package structure for us. The exact small details generated by uv can change between versions, so the important thing is to understand the structure rather than memorize every generated line.

We should now see the beginning of a package layout similar to:

genome_toolkit/
├── .git/
├── .gitignore
├── application.py
├── genome_toolkit.py
├── pyproject.toml
├── README.md
└── src/
    └── genome_toolkit/
        ├── __init__.py
        └── py.typed

This is our first major improvement. We still have our original files at the repository root, but now we also have the place where our real installable genome_toolkit package will live:

src/genome_toolkit/

What Is the src/ Layout?

The new src/ directory may look like an unnecessary extra folder at first. Why not simply put the package directly in the repository root?

The basic idea is separation:

repository files
        ↓
src/
        ↓
installable Python package

The repository contains things such as README.md, configuration files, tests, sample data, and our development application. The actual Python package that another project imports lives under src/.

This gives us a clearer distinction between:

the project repository
and
the installed genome_toolkit package

Later, when we write:

import genome_toolkit

we want Python to use the installed package under src/, not accidentally find some unrelated file at the repository root.

We will see one very practical example of why that matters later in this article when we remove the old genome_toolkit.py file.

The New pyproject.toml

One of the most important files created by uv is:

pyproject.toml

This is the main configuration file for a modern Python project. Our old setup used Pipfile for environment and dependency information, while pyproject.toml gives us one standard place for the package information that Python tools need.

For Genome Toolkit, we keep the structure generated by uv and set the project information we actually own:

[project]
name = "genome-toolkit"
version = "0.1.0"
description = "A small, typed bioinformatics toolkit for validated sequences and structured analyses."
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

Let us go through this from top to bottom.

name = "genome-toolkit"

This is the package distribution name.

version = "0.1.0"

Genome Toolkit is still at the beginning of its development, so we keep our current 0.1.0 version.

description = "A small, typed bioinformatics toolkit for validated sequences and structured analyses."

This gives package tools a short description of what the project is.

readme = "README.md"

This tells packaging tools which file contains the longer project description.

Then we have:

requires-python = ">=3.12"

This tells users and package tools which Python versions Genome Toolkit supports. Notice that this does not say that every developer must use one exact Python 3.12 installation; it says that the package requires Python 3.12 or newer.

Finally:

dependencies = []

At this point Genome Toolkit has no external runtime dependencies, so the list is empty. That will change soon, but we do not add dependencies before we actually need them.

Removing the Local Python Version Pin

Depending on the current uv template, project initialization may also create:

.python-version

That file can pin a local checkout to one particular development Python version.

For Genome Toolkit, the compatibility rule we care about is already declared in pyproject.toml:

requires-python = ">=3.12"

So if .python-version was generated, we remove it:

rm .python-version

This keeps the package rule simple: Python 3.12 or newer.

How Does Genome Toolkit Become an Installable Package?

When we ran:

uv init --lib --name genome-toolkit

uv also added the small piece of configuration Python needs to turn our source code into an installable package.

You will see it inside pyproject.toml under:

[build-system]

We do not need to change it.

For Genome Toolkit, our setup is very simple:

Python code
      ↓
uv
      ↓
installable genome_toolkit package

We are not compiling C or C++ code, creating special extensions, or doing anything unusual. Genome Toolkit is just a normal Python package, so the setup that uv generated for us already does the job.

This is all we need to understand for now. Later, if our package ever needs a more complicated build process, we can learn about that when we actually need it.

Moving Our Algorithms Into the Package

Now our package structure is ready, but both of our scientific algorithms are still sitting in the old root-level file:

genome_toolkit.py

There is no reason to recreate them one at a time. They already belong together, so we can simply move the existing file into our new package.

Inside:

src/genome_toolkit/

create a new folder called:

algorithms

Then move:

genome_toolkit.py

into that folder and rename it to:

kmer.py

Finally, create an empty:

__init__.py

inside the new algorithms/ folder.

We should now have:

src/
└── genome_toolkit/
    └── algorithms/
        ├── __init__.py
        └── kmer.py

That already makes the purpose of the file much clearer:

genome_toolkit
      ↓
algorithms
      ↓
kmer.py
      ↓
our k-mer algorithms

Both of our existing algorithms have now moved into the new package together. We have not changed how they work yet; we have simply given them a better home.

Simplifying kmer.py

Our old file wrapped both algorithms inside the genomeToolkit class.

Originally, the two methods begin like this:

def count_kmer(self, sequence, kmer):

and:

def find_most_frequent_kmers(self, sequence, k_len):

For Part 4.2, we are making only one small structural change to them: they become plain functions instead of class methods.

We will also add type hints to the function signatures:

def count_kmer(sequence: str, kmer: str) -> int:

and:

def find_most_frequent_kmers(
    sequence: str,
    k_len: int,
) -> list[str]:

That means:

remove self
    +
add type hints

The actual algorithms stay exactly the same.

Update kmer.py to:

"""K-mer analysis algorithms."""


def count_kmer(sequence: str, kmer: str) -> int:
    """
    Counts the number of times a specific k-mer appears in a given sequence,
    including overlapping k-mers.

    Parameters:
        sequence (str): The DNA sequence to search in.
        kmer (str): The specific k-mer to search for in the sequence.

    Returns:
        int: The number of times the k-mer appears in the sequence.
    """
    kmer_count = 0

    for position in range(len(sequence) - (len(kmer) - 1)):
        if sequence[position : position + len(kmer)] == kmer:
            kmer_count += 1

    return kmer_count


def find_most_frequent_kmers(
    sequence: str,
    k_len: int,
) -> list[str]:
    """
    Finds the most frequent k-mers of a given length in a DNA string.

    Parameters:
        sequence (str): The DNA string to search.
        k_len (int): The length of the k-mers to search for.

    Returns:
        list: A list of the most frequent k-mers in the DNA string.
    """
    kmer_frequencies = {}

    for i in range(len(sequence) - k_len + 1):
        kmer = sequence[i : i + k_len]
        if kmer in kmer_frequencies:
            kmer_frequencies[kmer] += 1
        else:
            kmer_frequencies[kmer] = 1

    highest_frequency = max(kmer_frequencies.values())

    return [
        kmer
        for kmer, frequency in kmer_frequencies.items()
        if frequency == highest_frequency
    ]

Notice what did not change:

kmer_count = 0
kmer_frequencies = {}
the loops
the comparisons
the counting logic
the return logic

We are not improving or modernizing the algorithms themselves in this part. We are moving the same calculations into a proper package and changing the way we call them.

Exposing Our Algorithm API

We now have:

algorithms/
├── __init__.py
└── kmer.py

We could import directly from the kmer.py module:

from genome_toolkit.algorithms.kmer import count_kmer

That works, but we can give users a cleaner public entry point through:

src/genome_toolkit/algorithms/__init__.py

Add:

"""Bioinformatics algorithms."""

from .kmer import count_kmer, find_most_frequent_kmers

__all__ = ["count_kmer", "find_most_frequent_kmers"]

Now both algorithms can be imported from:

from genome_toolkit.algorithms import (
    count_kmer,
    find_most_frequent_kmers,
)

This is the public algorithm interface we want to expose.

The line:

from .kmer import count_kmer, find_most_frequent_kmers

re-exports the two functions from kmer.py through the algorithms package.

Then:

__all__ = ["count_kmer", "find_most_frequent_kmers"]

makes our intention explicit: these are the names this package is deliberately exposing as its public API.

For now, we only expose the two algorithms we actually have.

That is enough to reconnect our application immediately and check whether the refactor still produces the exact same result.

Updating application.py

Our algorithms are now inside the new package, so the next step is to update application.py to use them.

We only need to change the import, remove the old gt object, and update the two places where we call our algorithms:

from genome_toolkit.algorithms import (  # CHANGE TO
    count_kmer,
    find_most_frequent_kmers,
)


# gt = genomeToolkit()  # REMOVE

seq = "AATTTTAAAAC"
kmer = "AA"
k_len = 3

print(f"Sequence: {seq}")
print(f"k-mer: {kmer}")
print(f"Repeats found: {count_kmer(seq, kmer)}")  # UPDATED
print(
    "Most frequent k-mer:",
    find_most_frequent_kmers(seq, k_len),  # UPDATED
)

That is it.

We no longer import the old genomeToolkit class or create a gt object. Instead, we import our two functions directly from the new algorithms package and call them directly.

Everything else stays exactly the same.

Now we are ready to synchronize the new package and test it.

Synchronizing and Testing the New Project

Now we want to test our changes immediately.

Because Genome Toolkit is now an installable package under src/, we first synchronize the project environment, run this command from the project root:

uv sync

The first time we run uv sync, uv creates our local virtual environment:

.venv/

It also creates:

uv.lock

uv.lock records the exact package versions used by the project so the same environment can be recreated consistently later.

uv sync then installs our current Genome Toolkit package into the new .venv according to pyproject.toml.

The first time this environment is created, VS Code or VSCodium may show a message like:

We noticed a new environment has been created.
Do you want to select it for the workspace folder?

Just select Yes.

If the message does not appear, or the editor is still using another Python installation, check the Python interpreter shown in the bottom-right corner of VS Code/VSCodium and select our new project environment. It should point to the .venv created inside the Genome Toolkit project, usually shown as something similar to:

('.venv': venv)

After this step, both the editor and our project environment know where:

genome_toolkit

actually lives, so our new import can work normally.

If you use uv run, uv can also synchronize the environment automatically before running the command. We are running uv sync explicitly here because it gives us a clear checkpoint and also prepares the .venv environment for editors and Code Runner.

Now for the important part.

Run:

uv run python application.py

We should see:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

The scientific output is exactly the same as before.

That is the result we wanted. We changed the environment manager, package structure, imports, and the way our algorithms are exposed, and we also replaced a stateless class with plain functions.

But count_kmer() still returns:

4

and find_most_frequent_kmers() still returns:

['TTT', 'AAA']

Perfect. This is the checkpoint we wanted: we moved the algorithms, simplified how we call them, reconnected application.py, and the scientific result is still exactly the same.

Now that the important path works again, we can take care of two small package details before we finish.

Keeping One Package Version

Now that our application works again, let us clean up one small package detail. The uv template also created:

src/genome_toolkit/__init__.py

This is the top-level package initializer.

We already declared our package version in pyproject.toml:

version = "0.1.0"

We could write the same version again inside Python:

__version__ = "0.1.0"

but then we would have two places to keep synchronized. Instead, we keep one source of truth, so replace the generated src/genome_toolkit/__init__.py with:

"""Genome Toolkit package."""

from importlib.metadata import version

__version__ = version("genome-toolkit")

__all__ = ["__version__"]

The new import:

from importlib.metadata import version

comes from Python’s standard library. It lets our package read the version stored in the installed package metadata.

Then:

__version__ = version("genome-toolkit")

means Python can still tell us the Genome Toolkit version, but the actual version number remains declared in one place:

pyproject.toml
        ↓
installed package metadata
        ↓
genome_toolkit.__version__

That is easier to maintain than copying "0.1.0" into multiple files.

This may look like a small packaging detail now, but the version number will become much more important once we start using Genome Toolkit for real biological experiments.

Imagine that later we analyze a real genome and save the result. If Genome Toolkit changes over time, we will want to know exactly which version of the toolkit produced that result:

Genome Toolkit 0.1.0
        ↓
biological data
        ↓
scientific analysis
        ↓
saved result

That version becomes part of the scientific context of the experiment. If we return to the same data months later, or somebody else wants to repeat our analysis, knowing which Genome Toolkit version was used helps us reproduce the same computational setup.

This connects directly to two ideas we introduced in Part 4.1: reproducibility and provenance. We will come back to both in much more detail in the upcoming articles, when Genome Toolkit starts returning structured scientific results and we begin recording where those results came from.

For now, the important thing is simple: Genome Toolkit should have one reliable version number, and every part of the package should read that same version.

What Is py.typed? In Simple Terms

There is one more small file that uv created for us:

src/genome_toolkit/py.typed

The file is empty, and we leave it empty.

So what does it actually do?

In simple terms, py.typed is just a small marker file. It tells Python development tools:

Genome Toolkit includes type hints in its code, so you can use them.

For example, we now have functions like:

def count_kmer(sequence: str, kmer: str) -> int:

The type hints tell us that:

sequence → string
kmer     → string
result   → integer

And:

def find_most_frequent_kmers(
    sequence: str,
    k_len: int,
) -> list[str]:

tells us that the function expects a string and an integer, and returns a list of strings.

The py.typed file simply tells compatible editors and type-checking tools that these type hints are intentionally part of Genome Toolkit.

Without py.typed, another project may import Genome Toolkit and still run perfectly, but some type-checking tools may not automatically treat our package’s type hints as part of its public interface.

With py.typed, we are explicitly telling those tools:

Genome Toolkit includes type information.
Please use it.

So if another developer passes the wrong kind of value to one of our functions, their editor or type checker has a better chance of warning them before the code even runs.

We do not need to write anything inside py.typed. We just keep the empty file in the package.

A Quick README.md Update

Before we finish the main part of Part 4.2, let us make one small but useful update to:

README.md

uv created this file when we initialized the project, and now we can add a few simple instructions so anyone who finds Genome Toolkit on GitHub knows how to run it after cloning the repository.

Add:

```markdown
## Running Genome Toolkit

After cloning the repository, synchronize the project environment:

```bash
uv sync
```

Then run Genome Toolkit:

```bash
uv run application.py
```

That is enough for now.

Anyone cloning the project can immediately see the two steps they need:

clone repository
      ↓
uv sync
      ↓
uv run application.py

As Genome Toolkit grows, we can keep expanding the README with installation instructions, examples, supported biological data, and other useful project information. For now, we only add what a new user actually needs to run the project.

Before We Finish Part 4.2

And that is it for the main part of Part 4.2. Genome Toolkit is now running as a modern Python package, our two original k-mer algorithms are still producing the same results, and we have a much better foundation for everything we are going to build next.

Before we close this part, however, I want to introduce two optional Pro Tips that will help us a lot as Genome Toolkit grows. They are not required for the project, so you can skip them completely if you want, but they are also useful habits that can serve you well in your own Python projects.

The first is for those of us who use the Code Runner extension. Because our project now uses uv and its own .venv, Code Runner may need a small configuration change so it runs our code inside the correct environment.

The second is about Ruff, a modern Python linter and formatter. It can automatically keep our code clean and consistently formatted as the project grows.

If you want to keep the setup minimal, feel free to skip both. If you want a smoother development workflow going forward, I recommend following them.

Pro Tip #1: Code Runner With uv

If you have been following rebelScience for a while, you may already use the Code Runner extension in VS Code or VSCodium to run Python files quickly without typing a terminal command every time.

The default shortcuts are:

Linux / Windows: Ctrl + Alt + N
macOS:           Cmd + Option + N

After moving Genome Toolkit to uv, there is one small thing we need to check.

uv created our local Python environment inside:

.venv/

But Code Runner may still try to use the global Python installation on your computer. If that happens, it may not be able to find our new installed genome_toolkit package.

Fortunately, this is a simple one-time fix. We just need to tell Code Runner to use the Python interpreter already selected by VS Code or VSCodium.

1. Open the Command Palette:

Ctrl + Shift + P

or on macOS:

Cmd + Shift + P

2. Search for Open User Settings and select the option with (JSON) in its name.
3. Find the existing:

"code-runner.executorMap"

section.

4. Update only the Python entry to:

"code-runner.executorMap": {
    "python": "$pythonPath -u $fullFileName"
}

Leave your other language entries unchanged and save the file.

Code Runner will now use the Python interpreter selected by the editor, which for our project should be the one inside .venv/.

That means our quick:

Ctrl + Alt + N

shortcut can keep working exactly as before, but now it runs Genome Toolkit inside our new uv environment.

Pro Tip #2: Automatic Formatting With Ruff

Here is another small setup improvement that can save us a lot of repetitive work as Genome Toolkit grows.

When we work on the same project across many files and many sessions, formatting can slowly become inconsistent. Spacing changes, imports move around, and a tiny code change can create a much larger Git diff than it really needs to.

For Python, we are going to use Ruff.

Ruff is a modern Python linter and formatter built by Astral, the same team behind uv. A linter helps spot common code problems, while a formatter automatically keeps our Python code laid out consistently.

And as always, Corey Schafer has an excellent detailed walkthrough if you want to understand Ruff beyond the small setup we need here:

Python Tutorial: Ruff – A Fast Linter & Formatter to Replace Multiple Tools and Improve Code Quality

If you use VS Code or VSCodium, the easiest setup is through the official Ruff extension published by Astral Software.

Open the Extensions panel:

Ctrl + Shift + X

or on macOS:

Cmd + Shift + X

Search for Ruff and install or enable the official extension.

Then open your User Settings JSON and add or verify:

{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    },
    "ruff.nativeServer": "on"
}

The most important setting for our everyday workflow is:

"editor.formatOnSave": true

Now every time we save a Python file, Ruff can automatically keep the formatting clean and consistent for us.

Ruff is a development tool, not something Genome Toolkit needs in order to run. We therefore do not add it to the package’s normal runtime dependencies just to format our source code.

Our New Project Structure

After synchronizing the project, the repository should now be approximately:

genome_toolkit/
├── .git/
├── .gitignore
├── .venv/
├── README.md
├── application.py
├── pyproject.toml
├── uv.lock
└── src/
    └── genome_toolkit/
        ├── __init__.py
        ├── py.typed
        └── algorithms/
            ├── __init__.py
            └── kmer.py

This is still a very small project, which is good.

We now have a proper place for the scientific package:

src/genome_toolkit/

and a dedicated place for our current algorithms:

src/genome_toolkit/algorithms/

As we continue through Parts 4.x, we can add the next pieces only when we actually need them.

What Changed and What Stayed the Same?

Quite a lot changed structurally in this article.

We moved from:

Pipenv
        ↓
uv

We moved from:

loose genome_toolkit.py
        ↓
installable src/genome_toolkit package

And we moved from:

stateless genomeToolkit object
        ↓
plain algorithm functions

Our application also imports the scientific functions from the package rather than constructing an object first.

But the important scientific parts did not change:

same input strings
same k-mer calculations
same int/list return values
same scientific results

That distinction is exactly what we wanted to see when we introduced refactoring in Part 4.1. We can improve the way our software is organized while keeping the scientific behavior we already understand.

Summary

In Part 4.2, we took our original working Genome Toolkit and turned it into a modern installable Python package. We moved from Pipenv to uv, created the src/ package structure, moved our existing k-mer algorithms into their new home, simplified the old class methods into plain typed functions, and updated application.py to use them.

Most importantly, the scientific calculations did not change. We reorganized the project, synchronized the new environment, and then confirmed that Genome Toolkit still produces exactly the same k-mer results as before. We now have a much cleaner foundation that will be easier to expand, test, share, and eventually use in real biological experiments.

New Concepts We Learned

• uv — Our new Python project and package manager. It creates and manages the virtual environment, installs dependencies, generates the lock file, runs our project, and helps build the package. It replaces several separate project-management tasks with one modern tool.
• pyproject.toml — The main project configuration file. It tells Python tools what Genome Toolkit is, which Python version and dependencies it needs, its package version and description, and how the project should be built. It solves the problem of keeping the important project and package configuration in one standard place.
• README.md — Human-facing project documentation. It explains what the project does and, in our case, now includes the basic commands needed to run Genome Toolkit after cloning the repository. It helps other people, and future us, understand and use the project without first reading through the source code.
• uv.lock — Records the exact dependency versions selected by uv. For example, if pyproject.toml later allows a range of Pydantic versions, uv.lock records the exact version actually chosen for our project. This helps different machines recreate the same environment instead of silently installing slightly different versions.
• .venv/ — Genome Toolkit’s private Python environment. It contains the Python environment and installed packages used by this project, keeping them isolated from other Python projects on the same computer. This prevents one project’s dependencies from easily interfering with another.
• src/ — Contains the actual installable source code, such as src/genome_toolkit/. It separates the Python package itself from project files such as README.md, pyproject.toml, and application.py, and helps us work with Genome Toolkit the same way another installed project would.
• __init__.py — Used inside package directories such as genome_toolkit/ and algorithms/. In our project, it helps define the package structure and can expose a cleaner public API. For example, instead of importing count_kmer from genome_toolkit.algorithms.kmer, we can expose it through genome_toolkit.algorithms and use the shorter import.
• __all__ — Makes the names we intentionally expose from a module or package explicit. In algorithms/__init__.py, it tells readers and development tools that count_kmer and find_most_frequent_kmers are part of the public algorithm API we want people to use.
• py.typed — Usually an empty marker file saying that the installed package officially provides Python type annotations. It helps external tools such as Pyright, mypy, and IDEs understand that they can use Genome Toolkit’s type hints when checking code that imports our package.
• Type hints — Extra information in function signatures that describes the kinds of values a function expects and returns. For example, sequence: str tells us that count_kmer() expects a string, while -> int tells us that it returns an integer. They make our code easier to understand and allow editors and type-checking tools to catch some mistakes earlier.
• Plain functions instead of class methods — Our original k-mer algorithms lived inside the genomeToolkit class even though they did not need to store any object state. Moving them to plain functions makes them simpler to call and keeps the scientific code focused on the calculation itself, while preserving the exact same algorithm behavior.
• Package versioning — Genome Toolkit now keeps one authoritative version in pyproject.toml and reads that version from the installed package metadata. Later, when we run experiments on real biological data, recording which Genome Toolkit version produced a result will become important for reproducibility and provenance.

The most important thing we learned is that modernizing the structure of a scientific project does not mean rewriting the science. Our algorithms still perform the same calculations, but they now live inside a project that is much easier to install, understand, maintain, and grow.

What is Next?

Genome Toolkit is now a real modern Python package.

But our algorithms still accept this:

sequence: str

And a Python string can contain almost anything:

AATTTTAAAAC
HELLO
12345
???

Python does not know which one is a biological sequence.

So in Part 4.3, we are going to solve the next problem:

If an algorithm is supposed to work on biological sequences, should any random string be allowed to reach it?

We will introduce our first validated biological sequence models and start teaching Genome Toolkit what DNA actually looks like.

The full source code for this part of Genome Toolkit is available here:

https://github.com/rebelC0der/Genome_Toolkit/commits/main

I hope this next step in building Genome Toolkit was useful for your bioinformatics and programming journey! If you found this article valuable and want to help us continue building rebelScience, please consider supporting our project. You can explore various ways to contribute here.

Until next time, rebelCoder, signing out.

Video version of this article is available here: https://youtu.be/fPLjrExTQTM

If you have been following rebelScience and our Genome Toolkit series for a while, you know that it has been quite a while since our last video. A few years, actually. And a lot has changed across software engineering, bioinformatics, and scientific research.

In Parts 1, 2, and 3, we built our first useful bioinformatics algorithms using a very small Python project:

genome_toolkit/
├── .git/
├── .gitignore
├── application.py
├── genome_toolkit.py
├── Pipfile
└── Pipfile.lock

That project already works. application.py creates our genomeToolkit object, runs the two k-mer algorithms we have built so far, and gives us:

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

This was exactly the right structure for learning our first algorithms. We could keep everything close together, focus on the biology and Python, and immediately see what our code produced.

We are absolutely going to continue building Genome Toolkit. We want to add more biological sequence types, load real biological data from files and databases, add more bioinformatics algorithms, and eventually use those tools together in larger experiments.

Before we add all of that, however, we are going to improve the structure underneath the project and turn Genome Toolkit into a small scientific Python package.

That process is called refactoring. Refactoring means reorganizing and improving the structure of existing software without changing what its core functionality is supposed to do.

And by doing this now, relatively early in the project, we are going to get something pretty amazing almost for free. While we are turning Genome Toolkit into a cleaner, more professional scientific Python package, we are also gradually making it AI-ready.

We will see exactly what that means as we progress through Parts 4.x. For now, the important idea is simple: the same clean, tested Genome Toolkit that we use ourselves will also become much easier for APIs, MCP tools, and AI agents to use later, without having to rebuild our scientific logic every time.

We will keep using the same working Genome Toolkit while we improve it step by step. application.py will remain our familiar test: after each major change, we can run it again and make sure our original calculations still work.

A Note for the Biologists

The next few parts will contain more software engineering than Parts 1 through 3, but our biological goal is not changing. We are still building Genome Toolkit so we can work with biological sequences, run useful algorithms, and eventually combine those tools into real experiments.

The workflow will stay familiar:

biological data
      ↓
Genome Toolkit
      ↓
scientific result

We are simply going to make the code underneath that workflow cleaner, easier to test, and easier to expand.

You do not need to become a Python packaging expert to use Genome Toolkit. If your main interest is biology, you can treat these parts as the engineering foundation underneath the experiments we will build later.

What Refactoring Means for Genome Toolkit

Right now, our project is very simple:

application.py
      ↓
genome_toolkit.py
      ↓
two working algorithms

As Genome Toolkit grows, we want something closer to:

application.py
      ↓
genome_toolkit package
      ↓
biological sequences
(DNA, RNA, proteins, etc.)
      ↓
data loaders
(FASTA, NCBI, other formats and sources)
      ↓
algorithms
(k-mer analysis, future sequence algorithms, etc.)
      ↓
scientific results
(results together with useful context)

The important point is that the scientific purpose stays the same. We are not changing count_kmer() just because we are reorganizing the project, and we are not changing find_most_frequent_kmers() just because the files around it move.

We will improve the project structure first. Later, when we add automated tests, we can look at real edge cases and deliberately decide whether any algorithm behavior needs to change.

Why Build a Scientific Python Package?

Our current two-file project works, but it was designed for a much smaller job. As Genome Toolkit grows, we will need to handle more than just two algorithms.

For example, we are going to need code for things such as:

• representing and checking biological sequences;
• loading sequence data from plain-text and FASTA files;
• running different families of bioinformatics algorithms;
• returning scientific results with useful context;
• testing that calculations and error cases behave correctly.

If all of that grows inside one file, the project quickly becomes difficult to understand and change. A package lets us separate those jobs into smaller parts that each have a clear purpose.

For example:

genome_toolkit/
├── sequence/
├── load/
└── algorithms/

sequence/ can contain code for biological sequences such as DNA. load/ can contain code for reading biological data from files. algorithms/ can contain the scientific calculations themselves.

This also makes Genome Toolkit much easier to reuse. Instead of treating it as a couple of Python files that belong to one project folder, we will be able to install it and use it like a normal Python library:

import genome_toolkit

That means the same tested scientific code can later be used from another Python script, a Jupyter notebook, a larger research project, a web application, or another tool.

For us, this is also a useful step from an educational project toward a real portfolio project. We are not only showing that we can write individual bioinformatics algorithms. We are showing that we can organize those algorithms into scientific software that other people can install, test, reuse, and expand.

Our goal with this refactoring is to move from the following type of simple script output:

[Genome Toolkit Initiated]

Sequence: AATTTTAAAAC
k-mer: AA
Repeats found: 4
Most frequent k-mer: ['TTT', 'AAA']

To a scientific results like these:

{
  "metadata": {
    "toolkit_version": "0.1.0",
    "algorithm": "count_kmer",
    "timestamp": "2026-08-24T09:30:53.399181Z"
  },
  "inputs": {
    "sequence": {
      "identifier": "M57671.1",
      "description": "Octodon degus insulin mRNA, complete cds",
      "length": 126
    }
  },
  "parameters": {
    "kmer": "CCTT"
  },
  "output": {
    "count": 5
  }
}

{
  "metadata": {
    "toolkit_version": "0.1.0",
    "algorithm": "find_most_frequent_kmers",
    "timestamp": "2026-08-24T09:30:53.400405Z"
  },
  "inputs": {
    "sequence": {
      "identifier": "M57671.1",
      "description": "Octodon degus insulin mRNA, complete cds",
      "length": 126
    }
  },
  "parameters": {
    "k_len": 5
  },
  "output": {
    "kmers": [
      "CTTGG",
      "TTGGG",
      "TGGGC",
      "GGGCC"
    ],
    "frequency": 6
  }
}

Preparing Genome Toolkit for APIs, MCP, and AI Agents

There is another reason this structure is becoming increasingly useful.

Today, scientific software does not have to be used only by someone manually writing Python code. The same package can later be connected to a web interface, an API, or an AI agent.

An API, or Application Programming Interface, gives one program a structured way to use another program. MCP, or Model Context Protocol, gives AI systems a standardized way to connect to external tools.

We will explain both properly when they become relevant. For now, the important idea is simply that Genome Toolkit can become the tested scientific tool underneath those systems.

Imagine asking an AI agent:

Find 100 genomes of this bacterium, run our k-mer analyses on them, compare the results, and prepare a summary.

Without dedicated scientific tools, the AI has to figure out much of that workflow by itself. It may search for genome sequences from different places, choose how to download them, write analysis code while it is working, pick libraries, and decide how to organize the calculations.

That flexibility can be useful, but it creates a problem for science. Modern language models are non-deterministic, which means they can make different choices across separate runs. If the AI is also writing the algorithms and deciding where the data comes from every time, reproducing exactly the same experiment becomes much harder.

Now imagine that the AI can use Genome Toolkit instead.

AI agent
    ↓
Genome Toolkit tools
    ↓
tested scientific calculations
    ↓
structured results

The AI can still help organize the work, choose which tools to call, compare many results, and prepare a report. But the actual k-mer calculation can come from the same count_kmer() function that we already wrote, understand, and test.

The same idea applies to loading biological data. Instead of inventing a new FASTA parser every time, the AI can use our loader. Instead of returning a number with no context, Genome Toolkit can later return a structured result that tells us which sequence, parameters, algorithm, and software version produced it.

This is where reproducibility and provenance become important. Reproducibility means that we should be able to repeat the same scientific calculation using the same data, algorithm, parameters, and software version. Provenance means keeping enough information to understand where a result came from.

We are not going to build all of that in this article. We will introduce each piece when we actually need it and can immediately see what problem it solves.

For now, the high-level idea is enough:

Python script / notebook / web app / AI agent
                    ↓
              Genome Toolkit
                    ↓
          tested scientific code
                    ↓
             scientific result

Genome Toolkit itself will stay focused on the science. Web servers, APIs, MCP connections, authentication, databases, and AI-agent logic can live outside the package and use Genome Toolkit as the scientific core underneath them.

What We Will Build Next

Over the next few parts, we will gradually turn the same working project into a modern scientific Python package.

At a high level, we will:

• modernize the project with uv and a proper Python package structure;
• add validated biological sequence objects such as DNA;
• load biological data from plain-text and FASTA files;
• return more useful scientific results;
• add automated tests and clearer error behavior.

We do not need to understand all of those pieces yet. We will introduce them one at a time, when we actually build and use them.

The important thing to remember is where we are going:

biological data
      ↓
Genome Toolkit
      ↓
tested algorithms
      ↓
scientific results

Everything else we add is there to make that workflow easier to use, easier to trust, and easier to expand.

Summary

Our original Genome Toolkit project was exactly what we needed for learning our first algorithms. Now we want to grow it into a scientific Python package that can handle biological sequences, external data, more algorithms, better results, and automated testing without becoming difficult to maintain.

The scientific goal stays the same. We are still building a practical bioinformatics toolkit, and our existing k-mer algorithms remain the starting point.

The new package structure will also make Genome Toolkit much easier to reuse from other Python projects, notebooks, future web applications, APIs, MCP tools, and AI agents. Most importantly, it gives us a cleaner foundation for building scientific workflows that are easier to test, understand, and reproduce.

What is Next?

In Genome Toolkit Part 4.2, we will finally start changing the project.

We will begin by running our current application.py one more time and confirming the familiar output. Then we will modernize the same project with uv, create a proper Python package structure, move our existing k-mer algorithms into it, and run application.py again.

That gives us a very simple first goal: change how Genome Toolkit is organized while keeping the scientific calculations working.

From there, we will continue one useful step at a time.

I hope this introduction to building our scientific Python package was useful for your bioinformatics and programming journey! If you found this article valuable and want to help us continue building rebelScience, please consider supporting our project. You can explore various ways to contribute here.

Until next time, rebelCoder, signing out.

A video version of this article: