DEV Community: Uya

Building a Countdown Timer CLI in Python — time, finally, mock, and Testing Exceptions

Uya — Sun, 28 Jun 2026 11:24:34 +0000

Introduction

This is my tenth article as a Java engineer learning TypeScript and Python from scratch.

This is the third project in my Python series. The first was a weight tracker CLI (type hints, pure functions, separating I/O from logic), and the second was a password generator CLI (string, random, any, and a testing strategy for randomness).

This time I built a countdown timer CLI. You pick a number of seconds from a menu, and it counts down one second at a time. Where the previous projects were about "calculating or generating a value," this one centers on time control and exception handling.

What I focused on this time:

Stepping through a process one second at a time with time.sleep()
A reverse loop with range(n, 0, -1) (the countdown)
Overwriting the same line in place with \r (carriage return) plus end="" plus flush=True
Exception design with try / except / finally (catching KeyboardInterrupt and a generic Exception)
Using finally to gather "the message that must appear on success, interruption, or error alike"
Mocking (swapping out) time.sleep in tests to raise exceptions on purpose
Capturing stdout as a string with capsys for verification

As always, I write honestly about where I got stuck, what I thought through, and what I asked AI for.

📝 Where this sits in the series

This is the third article in my Python series. So far the processes always ran to the end, but this time I step into a new theme: how to design and test a process that might stop partway, like a user pressing Ctrl+C mid-run.

My Learning Style (AI Transparency)

💡 Learning companions & how this article is written

I use Claude Pro (design discussions, Q&A, and article drafting) and Cursor Pro (coding support).

Division of roles:

Tech selection, design, implementation, and code verification → me

Article structure, outline, draft prose, and translation → in collaboration with Claude

All content is checked and revised by me before publishing → me

For the code, I set myself these rules: I write the code myself (I never ask AI to write code for me), I use AI for hints, spec clarification, and bug spotting, and I make sure I understand why before moving on. In this article I clearly separate "what I implemented myself" from "what I asked AI for." My line is "the thinking and decisions are mine, the wording is AI-assisted, and I verify the final content myself." This isn't an apology — just stating the facts.

What I Built

A CLI tool where you pick a menu number and count down 60 seconds, 30 seconds, or a custom number of seconds. While counting, the number decreases overwriting the same line.

----------------------------------
Welcome to the countdown timer!
1. Count down 60 seconds
2. Count down 30 seconds
3. Count down custom seconds
4. Exit
----------------------------------
Enter your choice: 3
Enter the number of seconds: 5
1 seconds remaining...Time's up!
Countdown finished.
----------------------------------
Welcome to the countdown timer!
1. Count down 60 seconds
2. Count down 30 seconds
3. Count down custom seconds
4. Exit
----------------------------------
Enter your choice: 4
Exiting the program...

The example only shows 1 seconds remaining..., but that's because 5, 4, 3, 2, 1 are all overwriting the same line (the mechanism is explained later). Press Ctrl+C during the count, and it shows an interruption message and returns to the menu.

📦 Repository: https://github.com/uya0526-design/countdown_timer_py

File Structure and Tech Stack

In the previous project (password generator) I split the logic from the entry point into separate files, so I kept the same approach here. The countdown body goes in timer.py, and the menu and entry point go in main.py.

countdown_timer_py/
├── src/
│   ├── __init__.py
│   ├── main.py          # entry point
│   └── timer.py         # countdown logic
├── tests/
│   ├── __init__.py
│   └── test_timer.py    # unit tests
├── requirements.txt     # dependencies
├── LEARNING_LOG.md      # learning log
└── README.md

Tech stack:

Python 3.12
pytest 9.0.3

I split the countdown logic (timer.py) from the menu I/O (main.py) because I wanted to keep the "separation of concerns" I'd learned in earlier projects. In Java terms, it feels close to separating the class that holds the logic from the startup class that holds main.

What I Implemented Myself

timer.py — A reverse loop and time.sleep to step one second at a time

This is the heart of the countdown. I run range backward and wait one second on each pass with time.sleep(1).

import time

def count_down(seconds: int) -> None:
    '''Count down the specified seconds'''
    try:
        for i in range(seconds, 0, -1):
            print(f"\r{i} seconds remaining...", end="", flush=True)
            time.sleep(1)
        print("Time's up!")
    except KeyboardInterrupt:
        print("Countdown interrupted by user.")
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        print("Countdown finished.")

Three points here.

1. Looping backward with range(seconds, 0, -1)

Passing -1 as the step in range(start, stop, step) makes the loop count down: seconds, seconds-1, ..., 1 (since stop=0 is excluded, it stops at 1). It's a direct replacement for Java's for (int i = seconds; i > 0; i--), so for someone with a Java background it was actually a familiar way to write it.

2. Waiting one second with time.sleep(1)

time.sleep(seconds) pauses the process for that many seconds. That's what creates the feel of "the number drops once per second." It's the counterpart of Java's Thread.sleep(1000) (in milliseconds), but Python takes seconds, which was a small but notable difference.

3. The loop variable i is used for display

In the previous password generator I just needed "the number of repetitions," so I used for _ in range(...) with _. This time I use i (the remaining seconds) for display, so I give it a real name. Being able to consciously choose between i and _ based on "do I use the loop variable or not?" is continuous growth from last time.

timer.py — Overwriting the same line with `\r`

When I first wrote this naively, the countdown stacked up vertically.

5 seconds remaining...
4 seconds remaining...
3 seconds remaining...
...

That doesn't feel like a timer. What I used here is \r (carriage return).

print(f"\r{i} seconds remaining...", end="", flush=True)

The role of each argument:

\r ... returns the cursor to the start of the line, so the next output overwrites the same line
end="" ... stops the newline print adds by default (a newline would break the overwrite)
flush=True ... flushes the output buffer immediately so it reaches the screen without waiting

With these three together, 5, 4, 3, 2, 1 rewrite in place on the same line. I also learned by testing that without flush=True, the display sometimes doesn't update while sleep is paused, and it "stutters."

💡 A common terminal-UI technique

This is a standard terminal-UI trick, and apparently it also applies to progress bars and "processing..." spinners. The look of the display is a real part of UX too — that's the mindset I brought to this spot.

timer.py — Designing a "process that may stop partway" with try / except / finally

The part I thought about most this time was exception design. A countdown is a process where "the user may stop it partway with Ctrl+C," so I want to catch that interruption gracefully instead of crashing with an error. So I used a three-layer structure.

    try:
        for i in range(seconds, 0, -1):
            print(f"\r{i} seconds remaining...", end="", flush=True)
            time.sleep(1)
        print("Time's up!")
    except KeyboardInterrupt:
        print("Countdown interrupted by user.")
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        print("Countdown finished.")

The roles, organized:

Block	Role
`try`	The countdown body. Shows `Time's up!` if it runs to the end
`except KeyboardInterrupt`	Catches a Ctrl+C interruption and shows the interruption message
`except Exception as e`	Catches any other unexpected error and shows a message
`finally`	Always shows the finish message no matter which ending occurs

Here my Java experience paid off directly for the first time in a while. The try / catch / finally structure is almost the same as Java, and the point that finally "always runs regardless of whether an exception occurred" matches too. The differences are that Java's catch (Exception e) becomes except Exception as e in Python, and that you can catch Ctrl+C as a KeyboardInterrupt exception. Signal handling felt like extra work in Java, so being able to treat this as an ordinary exception was fresh.

What I focused on in the design was "what to put in finally." Countdown finished. is a message I want shown on every kind of ending, so I put it in finally. Conversely, the "only on success" Time's up! goes at the end of try, and the "only on interruption" message goes in except. The idea of deciding where to place things by working backward from the requirement "when do I want this shown?" clicked for me this time.

main.py — The menu loop and catching ValueError

The entry point main.py runs the menu with while True and guards the custom-seconds input with try / except.

from timer import count_down

def main() -> None:
    '''Main function'''
    while True:
        print("----------------------------------")
        print("Welcome to the countdown timer!")
        print("1. Count down 60 seconds")
        print("2. Count down 30 seconds")
        print("3. Count down custom seconds")
        print("4. Exit")
        print("----------------------------------")
        choice = input("Enter your choice: ")
        if choice == "1":
            count_down(60)
        elif choice == "2":
            count_down(30)
        elif choice == "3":
            try:
                seconds = int(input("Enter the number of seconds: "))
                count_down(seconds)
            except ValueError:
                print("Invalid input. Please enter a valid number of seconds.")
                continue
        elif choice == "4":
            print("Exiting the program...")
            break
        else:
            print("Invalid choice. Please enter a valid choice.")
            continue

Input that int() can't convert raises ValueError (close to Java's NumberFormatException), so I catch it and continue back to the top of the menu. This try / except ValueError then continue pattern shows up again and again across the Python series, and it has become second nature.

tests/test_timer.py — How to test a "waiting" process and exceptions

The hard parts of testing this time were two: (1) if time.sleep really waits, the test is slow, and (2) how do I raise exceptions (Ctrl+C or an error) on purpose? I solved these with unittest.mock.patch and capsys.

import pytest
from unittest.mock import patch

from src.timer import count_down

def test_count_down(capsys):
    '''The countdown will start for the number of seconds entered'''
    assert count_down(1) is None
    assert "1 seconds remaining...Time's up!\nCountdown finished." in capsys.readouterr().out

def test_keyboard_interrupt(capsys):
    '''KeyboardInterrupt: A message will be returned when an exception occurs'''
    with patch('time.sleep', side_effect=KeyboardInterrupt):
        assert count_down(1) is None
        assert "Countdown interrupted by user." in capsys.readouterr().out

def test_exception(capsys):
    '''Exception: A message will be returned when an exception occurs'''
    with patch('time.sleep', side_effect=Exception):
        assert count_down(1) is None
        assert "An error occurred" in capsys.readouterr().out

Three things I worked out.

1. Capturing stdout with capsys

capsys is a fixture pytest provides, and capsys.readouterr().out lets me grab "the string that print produced." A function that returns None (count_down) can't be verified by its return value alone, so I switched to the mindset of checking correctness by looking at the output.

2. Injecting an exception with patch('time.sleep', side_effect=KeyboardInterrupt)

If I swap out time.sleep with patch and set side_effect to an exception, that exception is raised the moment sleep is called. That let me reproduce "the user pressed Ctrl+C" from the test. It feels close to writing when(...).thenThrow(...) with Mockito in Java.

3. The normal-path count_down(1) actually waits one second

Only the normal-path test leaves sleep un-mocked and really waits one second. One second is within tolerance, so I deliberately ran it as-is here.

📝 A spot I got stuck on

I tripped up once on "where to apply the mock" (detailed below in "Where I Got Stuck"). At first I tried to mock the input, but input isn't called inside count_down, so I was applying it to the wrong place.

What I Asked AI For

Topic	What AI helped with
Code review	Feedback on strengths and improvements after I finished implementing
Intent of `finally`	Confirming that "putting the shared message in `finally`" was the intended design (confirmed it was intentional)
Verifying the display trick	Confirming the role split of `\r` plus `end=""` plus `flush=True`
LEARNING_LOG	Tidying up the learning log

Note: the idea of overwriting a line with \r, and identifying where to apply patch (next section) were things I thought through and debugged myself.

Where I Got Stuck

1. Mocked it, but no exception fires — the patch target was wrong

Situation: When writing the KeyboardInterrupt test, I first thought "if I swap out the input I can raise the exception," and applied patch('builtins.input', ...). But no exception fired at all, and the test didn't behave as intended.

Root cause: Looking closely, input is never called inside the count_down function. The one using input is main.py, and what actually gets called and waits inside count_down is time.sleep. In other words, "where I wanted to inject the exception" and "where I applied the mock" were out of sync.

Fix: I changed the mock target to time.sleep.

# NG: input is not called inside count_down, so nothing happens when applied here
with patch('builtins.input', side_effect=KeyboardInterrupt):
    ...

# OK: apply it to time.sleep, which is actually called inside count_down
with patch('time.sleep', side_effect=KeyboardInterrupt):
    ...

Takeaway: A mock has no effect unless you apply it where the call actually happens. You decide the target by looking not at "what I want to swap out" but at "what the function under test actually calls." I got stuck on "is the path correct?" with __init__.py import resolution last time, and a mock is the same in that "is it pointing at the right target?" is the crux.

2. `"An error occurred: Exception"` makes the assertion fail — the empty-message trap

Situation: In the generic Exception test, I first wrote the assertion expecting the output "An error occurred: Exception", and it failed.

Root cause: The production code embeds the exception with print(f"An error occurred: {e}"). Here side_effect=Exception throws an Exception() with no arguments, so the str(e) going into {e} becomes an empty string. The actual output is therefore "An error occurred: " (nothing after the colon), which doesn't match "An error occurred: Exception".

Fix: I relaxed the assertion to only "does it contain the first part?"

# NG: expected the exception message (after the colon) to match too
assert "An error occurred: Exception" in capsys.readouterr().out

# OK: verify only the first part that always appears
assert "An error occurred" in capsys.readouterr().out

Takeaway: I only noticed that str(Exception()) becomes an empty string by reading the error log. The lesson is that narrowing a test assertion to "the minimal fact that always holds" makes it harder to break and clearer in intent. Following last time's "crush probabilistic failures with a large enough number of trials," my sense for "how to keep tests stable" is slowly growing.

What I Learned

Python syntax and standard library

Topic	Key takeaway
`time.sleep(s)`	Pauses the process for the given seconds (counterpart of Java's `Thread.sleep(ms)`, in seconds)
`range(n, 0, -1)`	A reverse loop with `step=-1`; useful for a countdown
`\r`	Returns the cursor to the start of the line and overwrites it
`print(..., end="", flush=True)`	Suppresses the newline and reflects output immediately
`try / except / finally`	Same structure as Java; `finally` always runs regardless of the ending
`KeyboardInterrupt`	You can catch Ctrl+C as an exception

Testing knowledge

Topic	Key takeaway
`capsys`	Captures `print` output as a string for verification
`patch('time.sleep', side_effect=Exc)`	Swaps a function to raise an exception on purpose
Mock target	Has no effect unless applied to "what the test target actually calls"
Relaxing assertions	Narrowing to a minimal fact that always holds keeps tests robust

Design and debugging thinking

What to put in finally is decided by working backward from "what message do I want on every ending?"
The look of the display (overwriting with \r) is something to treat as part of UX design.
When an error appears, read the difference between "the actual output" and "the expected output." The pattern "if the patch target is wrong, no exception fires" has become a familiar way to isolate causes.

Reflection

As before, I built this by writing the code myself and having AI review it, and I completed implementation, debugging, and testing on my own. As my third Python project, three things stood out.

I stepped into designing a "process that stops partway" for the first time: So far the processes always ran to completion, but this time I designed a way to gracefully catch an interruption via Ctrl+C — an ending that is neither the normal path nor an error — with try / except / finally. It was a nice bonus that my knowledge of Java's finally carried straight over.

A lesson from the mock target: I learned the mock principle "decide the target by what the target actually calls, not by what you want to swap out" by actually getting stuck. As with last time's import resolution, I re-confirmed from a different angle how important it is to "point at the right path / target."

A small win in display control: The moment the number rewrote in place with \r was a quiet but real sense of "now it feels like a timer." Going one step beyond "it just works" to caring about how it looks feels continuous with my front-end learning too.

Wrapping Up

This was my record of building a countdown timer CLI in Python, centered on time, finally, and mock — my third article in the Python series.

Continuous progress from last time:

Learned to write a "process that advances over time" with time.sleep and range(n, 0, -1)
Picked up display control that overwrites the same line with \r plus end="" plus flush=True
Cleanly designed a "process that stops partway" with try / except / finally (Java knowledge paid off)
Wrote tests that swap out time.sleep with patch to raise exceptions on purpose
Learned the principle "apply a mock where the call happens" from actually getting stuck

Next, I'll finally move into persistence to a file (a diary app). I'll graduate from the "data disappears when you exit" simplification I've kept up to now in the next stage.

The full learning log is in the repository:

countdown_timer_py / LEARNING_LOG.md

This article is part of my public learning journey using AI tools (Claude Pro / Cursor Pro). The thinking and all code are mine; I collaborate with AI on the writing (structure, drafting, translation) and verify every line before publishing.

Building a Password Generator CLI in Python — string, random, any, and Testing Randomness

Uya — Sat, 20 Jun 2026 11:24:56 +0000

Introduction

This is my ninth article as a Java engineer learning TypeScript and Python from scratch.

Last time I moved into the Python series, and the first project was a weight tracker CLI. Centered on type hints, pure functions, and pytest, it confirmed that "separate logic from I/O" still works in Python.

For the second Python project, this time it's a password generator CLI. You specify the length and whether to include digits and symbols, and it generates a random password. Where the last one was about "separating calculation logic," this one centers on string manipulation and randomness.

What I focused on this time:

Building a character pool by concatenating string constants (ascii_letters, digits)
Picking one character at a time with random.choice()
any() to check whether an iterable contains an element that meets a condition (close to Java's anyMatch)
Extracting validation logic into independent functions (reused from both main and tests)
A testing strategy for randomness (how to avoid probabilistic failures)
Package recognition with __init__.py, and resolving pytest's imports

As always, I write honestly about where I got stuck, what I thought through, and what I asked AI for.

📝 Where this sits in the series

This is the second article in my Python series. It's also a chance to check whether the habits I learned last time — "separation of concerns" and "write tests" — hold up with a subject that involves randomness.

My Learning Style (AI Transparency)

💡 Learning companions & how this article is written

I use Claude Pro (design discussions, Q&A, and article drafting) and Cursor Pro (coding support).

Division of roles:

Tech selection, design, implementation, and code verification → me

Article structure, outline, draft prose, and translation → in collaboration with Claude

All content is checked and revised by me before publishing → me

What I Built

Enter a menu number, and the CLI generates a password or lists generated ones. You can interactively specify the length and whether to include digits and special characters, and generated passwords are kept as history during the session.

---------------------------------
1. Generate a password
2. List generated passwords
3. Exit
---------------------------------
Enter your choice: 1
Enter the length of the password:
20
Should I include digits? (y/n):
y
Should I include special characters? (y/n):
y
Generated password: BRBK3%n%D2Tm1y4-DG1[
Password generated successfully.
---------------------------------
1. Generate a password
2. List generated passwords
3. Exit
---------------------------------
Enter your choice: 2
1. BRBK3%n%D2Tm1y4-DG1[
---------------------------------
Enter your choice: 3
Exiting the program...

Data is held in memory and resets when you exit (a deliberate simplification for local learning). I'm saving persistence for a later stage.

📦 Repository: https://github.com/uya0526-design/password_generator_py

File Structure and Tech Stack

Last time it was a single file (main.py), but this time I split the logic (password.py) from the entry point (main.py).

password_generator_py/
├── src/
│   ├── __init__.py
│   ├── main.py          # entry point
│   └── password.py      # password generation logic
├── tests/
│   ├── __init__.py
│   └── test_password.py # unit tests
├── requirements.txt     # dependencies
├── LEARNING_LOG.md      # learning log
└── README.md

Tech stack:

Python 3.12
pytest 9.0.3

I split the logic (password.py) from the I/O (main.py) at the file level because I wanted to take last time's "separation of concerns" one step further. In Java terms, it feels close to separating a Service class that holds the logic from the class that holds the main entry point.

What I Implemented Myself

password.py — Building a character pool and picking randomly

This is the heart of password generation. Starting from string.ascii_letters, I concatenate digits and symbols as strings depending on the flags, then pick one character at a time from that pool.

import random
import string

special_chars = "!@#$%^&*()_+-=[]{}|;:,.<>?"
generated_passwords = []

def generate_password(length: int, use_digits: bool, use_special_chars: bool) -> str:
    """A password is generated based on the result selected from the menu"""
    password = ""
    random_string = string.ascii_letters
    if use_digits:
        random_string = random_string + string.digits
    if use_special_chars:
        random_string = random_string + special_chars
    for _ in range(length):
        password += random.choice(random_string)
    generated_passwords.append(password)
    return password

Three points here.

1. The string module's character constants

string.ascii_letters (upper- and lowercase letters) and string.digits (0 to 9) are provided as strings out of the box. Where in Java I'd loop to build them or write out the constants by hand, here the standard library just hands them over. I concatenate only the character types whose flags are set, with +, to build the "pool of allowed characters."

2. for _ in range(length) without a loop variable

This is a case of "I just want to repeat length times and don't use the loop variable's value." In Python, the convention is to put _. The same situation as a Java for (int i = 0; i < length; i++) where i is unused, but here I can make "unused" explicit with _, which felt fresh.

3. Picking one element with random.choice()

random.choice(seq) returns one random element from a sequence. What I used to write as list.get(random.nextInt(list.size())) in Java fits into a single function.

password.py — Extracting validation logic into independent functions

I prepared functions to confirm "does the generated password really contain the specified character types?", made independent of the main logic.

def get_digits(password: str) -> bool:
    """Check if the password contains digits"""
    return any(char.isdigit() for char in password)

def get_special_chars(password: str) -> bool:
    """Check if the password contains special characters"""
    return any(char in special_chars for char in password)

This is where I used any() for the first time. any() returns True if the iterable contains at least one True. So any(char.isdigit() for char in password) expresses "is there at least one digit in the password?" in a single line.

In Java's Stream it's close to password.chars().anyMatch(Character::isDigit): the classic "loop and return true partway through" becomes a declarative one-liner, which felt great.

And the important part is that I extracted these validation functions as independent functions. Last time I learned to split calculation logic into pure functions; this time, by splitting the validation logic, I could reuse the same functions from both the main process (the warning display) and the test code. That pays off in the next section's tests.

password.py — Listing, and the start argument of enumerate

For listing the history, I improved on the enumerate I'd used last time.

def list_generated_passwords() -> None:
    """List the generated passwords"""
    if not generated_passwords:
        print("No passwords have been generated yet.")
        return
    for i, password in enumerate(generated_passwords, 1):
        print(f"{i}. {password}")

Last time I wrote index + 1 to make the display start at 1, but this time I learned you can pass a start number as the second argument, like enumerate(generated_passwords, 1). A small improvement, but a spot where I felt "I wrote this a little more cleanly than last time."

For the empty check I also wrote if not generated_passwords: instead of len(...) == 0. In Python an empty list evaluates as false, so this reads more naturally — something I was taught.

main.py — The menu loop and input validation

The entry point main.py runs the menu with while True and guards numeric input with try / except.

choice = input("Enter your choice: ")
if choice == "1":
    print("Enter the length of the password: ")
    try:
        length = int(input())
    except ValueError:
        print("Invalid input. Please enter a valid number.")
        continue

The try / except ValueError I learned in the weight tracker CLI carried straight over. Input that int() can't convert raises ValueError (close to Java's NumberFormatException), so I catch it and continue back to the top of the menu.

main.py — Showing the warning just once with remind_flag

Something I tweaked this time is the warning for "when the specified character type didn't happen to be included." Since we pick with random, at around 20 characters it's possible to draw no digits at all. So after generating, I check the contents with the validation functions and warn if something is missing.

remind_flag = False
if include_digits and not get_digits(password):
    print("Digits are not included in the password.")
    remind_flag = True
if include_special_chars and not get_special_chars(password):
    print("Special characters are not included in the password.")
    remind_flag = True
if remind_flag:
    print("If you mind, please generate a password again.")

I keep a single remind_flag so that "if either digits or symbols are missing, show 'generate again if you mind' just once at the end." I'm reusing the get_digits / get_special_chars I extracted earlier right here.

📝 A note for next time

In LEARNING_LOG I noted that "instead of a flag variable, you could collect the warning messages into a list and show them all at the end." remind_flag was enough this time, but if warnings grow, the list approach would be easier to extend.

tests/test_password.py — How to test randomness

The part that took the most thought this time was testing. A function that uses random produces different results every run, so a naive test becomes one that "happens to pass / happens to fail."

from src.password import get_digits, get_special_chars, generate_password

def test_get_digits():
    assert get_digits("password123") == True
    assert get_digits("password") == False

def test_generate_password():
    assert isinstance(generate_password(10, True, True), str)
    assert len(generate_password(10, True, True)) == 10

def test_generate_password_with_digits():
    """Check for randomness by checking 1000 length passwords"""
    password = generate_password(1000, True, False)
    assert get_digits(password) == True

What I worked out is test_generate_password_with_digits. Even when I specify "include digits," a short password might by chance contain no digits at all. That makes the test unstable.

So I decided to generate a length-1000 password and verify that. With 1000 characters, the probability of drawing zero from the digit pool is effectively near zero. Reaching the idea "if you can't remove randomness, crush the probabilistic failure with a large enough number of trials" on my own was the win this time.

For the verification, I could reuse the get_digits I'd extracted earlier. Because I'd split the validation logic, the production code and the test could share the same check. The isinstance(..., str) test to confirm the return type also added one more tool to my belt, following last time's pytest.raises.

What I Asked AI For

Topic	What AI helped with
Breaking down the steps	Suggesting the order: password.py first, then main.py, then test_password.py
The `string` module	Telling me about character constants like `ascii_lowercase`, `ascii_uppercase`, `digits`, `punctuation`
Random selection options	Hinting at the difference between `random.choices()` and `random.choice()` (I chose `choice()` myself)
Type hints	Suggesting I add type hints to function signatures
Package structure	The role of `__init__.py` and how pytest resolves imports
README	Tidying it up in both Japanese and English

Note: the idea to test randomness with a long string was mine, and I decided the validation-function split myself.

Where I Got Stuck

1. AttributeError: 'str' object has no attribute 'get_digits'

Situation: When calling the validation, I wrote password.get_digits(password) and got an error.

Root cause: get_digits is a module-level function defined in password.py, but I was calling it as if it were a method of password (a string variable). A string has no method called get_digits, hence AttributeError.

Fix: I changed it to a plain function call, get_digits(password).

# NG: trying to call a method on the string password
password.get_digits(password)

# OK: pass password to the module's function
get_digits(password)

Takeaway: "a.b() (method call)" and "b(a) (pass to a function)" are different things. In Java basically everything is a class method, so I realized my hands aren't yet used to the Python sense of being able to put functions at the module top level. It also helped that reading the error message spelled out the cause clearly.

2. ModuleNotFoundError — pytest can't find the module

Situation: When I ran pytest, the test file's import raised ModuleNotFoundError.

Root cause and trial-and-error:

First from password import ... gave No module named 'password'
Changing to from src.password import ... then gave No module named 'src'

Neither src/ nor tests/ was recognized by Python as a package; they were "just folders."

Fix: I placed src/__init__.py and tests/__init__.py (both empty files) so the folders are recognized as packages, which resolved it. I'd solved a similar problem with tests/__init__.py in the weight tracker CLI, so the instinct "when imports don't resolve, first suspect package recognition" was starting to kick in.

Takeaway: Folder structure is part of "the spec for making things run." The way the presence of __init__.py changes import resolution felt a little like the correspondence between Java's package declarations and directory structure.

What I Learned

Python knowledge

Topic	Key takeaway
`string` module	Character constants like `ascii_letters`, `digits`, `punctuation` can be concatenated as strings
`random.choice(seq)`	Picks one random element from a sequence (close to Java's `list.get(random.nextInt(...))`)
`any()`	Returns `True` if at least one element of an iterable meets a condition (close to Java Stream's `anyMatch`)
`for _ in range(n)`	Use `_` to make "unused" explicit when you don't need the loop variable
`enumerate(seq, 1)`	The second argument sets the start number (more natural than `index + 1`)
Empty check	An empty list is false; `if not list:` expresses "if empty"
`__init__.py`	Makes a folder recognized as a Python package

Testing knowledge

Topic	Key takeaway
Testing randomness	Make the number of trials (characters) large enough to crush probabilistic failures
`isinstance(value, type)`	Useful for tests that confirm the return type
Sharing validation functions	The production code and the test can reuse the same check function

Design thinking

Splitting validation logic into a separate function lets both the main logic (the warning display) and the test code reuse it. This became an applied version of separation of concerns, following last time's "splitting calculation logic."
Instead of a flag variable (remind_flag), you could collect the warning messages into a list and show them all at the end (an option for next time if I extend this).

Reflection

I built this the same way as before: write the code myself and have AI review it. As my second Python project, three things stood out.

Separation of concerns went one level deeper: Last time it was "extract calculation logic as a pure function"; this time I went as far as "extract validation logic and share it between production and tests." The feeling of the same principle widening its range of application was a satisfying sense of continuous growth.

I learned how to deal with randomness and testing: "How do you verify a process whose result changes every time?" was a worry that the deterministic processes so far never had. Reaching the idea "make the number of trials large to crush probabilistic failures" on my own was the biggest gain this time.

The pleasure of writing declaratively with any(): A process that loops and return trues partway through becomes a single any(...) line. The same "from procedural to declarative" feeling I had when learning Java's Stream came back in Python.

The ex-Java habit (confusing a method call with a function call) did surface, but I corrected it along with the reason, from the error message.

Wrapping Up

This was my record of building a password generator CLI in Python, centered on string, random, and any — my second article in the Python series.

Continuous progress from last time:

Picked up the basics of building strings with string and random.choice()
Learned to write "is at least one condition met?" declaratively with any()
Practiced a design that extracts validation logic and shares it between production code and tests
Tested randomness with the idea of "crushing probabilistic failures by making the number of trials large"
Resolved package recognition with __init__.py on my own, drawing on last time's experience

Next, I want to move into persistence — saving generated passwords to a file so they can be listed across sessions — and gradually graduate from this project's "data disappears when you exit" simplification.

The full learning log is in the repository:

password_generator_py / LEARNING_LOG.md

Not 'Did You Use AI' but 'Are You the One Driving' — Reflections on Building a Real Product Through AI Collaboration

Uya — Thu, 18 Jun 2026 12:49:36 +0000

📝 Originally published in Japanese on Zenn. This is the English version.
Canonical: https://zenn.dev/uya0526_design/articles/satellite4_ai-collaboration

📚 This is satellite article #4 (the finale) in my "Read-Aloud Speed Meter dev log" series. For the whole picture, see the main article.

Where This Sits

The read-aloud speed meter was the first project where I adopted "AI-collaborative development" as an explicit mode. Until then, my learning style was "I write all the code myself; AI is a reviewer." With a contest deadline looming, I stepped one notch further.

This article isn't a technical deep dive — it's a reflection on the development style itself. Three things:

The reframe from "did you use AI" to "are you the one driving"
The stumbles I actually hit in AI collaboration, and the patterns I pulled out of them
Why rejecting an AI suggestion was the single most important thing

💡 This is a record of an ex-Java SE engineer learning TypeScript and Python in public. It's less a technical article and more a reflective, prose-y piece on the development process.

I Switched Styles

My learning articles have always run on a rule: I write the code myself; I use AI for hints, spec clarification, and bug spotting. Typing every word myself had learning value.

This time there was a contest deadline, and a huge amount to cover. So I switched into a collaborative mode: AI demonstrates boilerplate (recording, fetch, API Route skeletons), and I handle the conceptual core and the design decisions.

The awkward part was how to disclose that in the article. I'd publicly stated my AI use for code before, but this time I collaborated with AI on the article's outline, structure, draft prose, and even translation. In a contest with money (a prize) on the line, blurring that didn't feel honest.

At first I framed it as "using AI is no different from accepting an IDE's autocomplete." But that was inaccurate.

Autocomplete ≈ word/line-level completion
This time ≈ delegating outline, structure, drafting, and translation → closer to co-building the article with an editor

Since the degree of involvement was far greater than autocomplete, blurring it as "I used AI a little" was wrong. I reconsidered: writing concretely what I delegated to AI and what I did myself is both more honest and more self-protective.

The Reframe: Not "Did You Use AI" but "Are You the One Driving"

The most useful lens for thinking about disclosure was this.

The question isn't "did you use AI" — it's "are you the one driving."

This comes from Zenn's community guidelines emphasizing "a place where people drive the dissemination of information," and listing two conditions for "the person is driving":

The author verifies the content before publishing
The author embeds their own experience and insight into the content

Against this standard, disclosure isn't a "confession" — it's "presenting evidence that I meet the bar." This project:

made its own decisions on tech selection (consolidating on Next.js), the evaluation-algorithm design, and the architecture (BFF)
verified the code's behavior with Vitest, starting with calculateMetrics
holds first-hand information like audio-format compatibility, the divide-by-zero guard, and the hunt for threshold bases

In that sense, I'm on the side that meets the "driving" conditions. So disclosure isn't scary — it's actually a presentation of strengths.

I summarized the axis of disclosure like this:

The thinking is mine, the wording is AI-assisted, and I verify all of it.

Area	Owner
Tech selection, evaluation-algorithm design, architecture decisions, code verification	Author
Article outline, structure, draft prose, translation	In collaboration with AI (Claude)
Reviewing and revising all content before publishing	Author

I decided the tone too: no apologetic register — state the facts plainly. Writing apologetically signals "the author thinks AI use is a problem," which invites the very criticism I want to avoid. Laying out facts calmly conveys "this is just a normal professional workflow."

A Collection of Stumbles — Where Collaboration Got Stuck

AI collaboration is fast, but it isn't unconditionally correct. Here are representative cases I hit, isolated, and fixed myself. The technical details are in satellite #1 (AmiVoice) and satellite #2 (Haiku).

① I got AmiVoice's auth method wrong

I assumed REST API auth meant an Authorization header. AmiVoice's synchronous HTTP puts the API key in the multipart u field. I read the official manual myself, hit it with curl, and finally corrected it.

→ Lesson: For external APIs, take a two-stage check — official spec + actual testing (curl) — not just AI's explanation.

② The mapper returned empty (`result` vs `results`)

In the mapper that reshapes raw JSON, the first version referenced result.tokens (singular) and got nothing. The correct path was results[0].tokens (a plural array).

→ Lesson: This was preventable if I'd looked at the raw JSON with curl first. See the real data with your own eyes before implementing.

③ I rejected `0` as falsy

In an input check I wrote if (!value), which rejected a stagnation rate of 0 (which is actually a good result). Since 0 is falsy, an existence check needs ?? "" or === undefined.

→ Lesson: "no value" and "value is 0" are different things. This was the same as distinguishing Java's Optional/null check from an empty/0 check.

④ The prompt cache wasn't working

I thought I'd cheapened a static prompt with caching, but it didn't reach Claude Haiku's 4,096-token minimum, so it wasn't working at all. I only noticed by looking at usage.

→ Lesson: "The official feature exists" and "it helps in my use case" are different. Check the preconditions too.

⑤ Haiku mentioned punctuation that wasn't in the input

Even for short reads with no punctuation, Haiku tacked on "take a breath at the punctuation." Fixing the prompt still doesn't prevent it 100%.

→ Lesson: Written in the prompt ≠ obeyed. Instruction and verification are separate; check against real data whether it was obeyed.

The Thread Through the Stumbles: "A Passing Test ≠ Behaving as Intended"

Lined up, most of the stumbles had the same structure:

The mapper "worked," but referenced the wrong place (②)
The validation "passed," but wasn't meant to reject 0 (③)
The cache was "configured," but wasn't working (④)
The prompt was "written," but wasn't obeyed (⑤)

These are all gaps between "what I thought I did" and "what's actually true." The lesson I'd grasped in an earlier project — "a passing test ≠ behaving as intended" — applied directly in AI collaboration too.

In AI collaboration, because code comes out fast and plausible-looking, this "thought vs. actual" gap gets harder to see. Which is exactly why the value of keeping your verification in code and real data went up, I feel. The more something is AI-generated, the more you confirm it yourself.

The Most Important Thing Was the "Rejection"

What stuck with me most in AI collaboration wasn't what AI wrote — it was rejecting an AI suggestion.

When I used the openings of The Tale of the Heike and Hōjōki as read-aloud scripts, AI's review explained the two works' attributions backwards (mixing up author and work). I verified against the literature, judged my implementation correct, and rejected AI's correction.

A small event, but it was a moment of demonstrating "the person is driving" through action. Don't swallow AI's suggestions whole; verify domain knowledge against primary sources. That accumulation underpins the trustworthiness of both the code and the article. When I write "I verified AI's suggestions" in the contest disclosure, this isn't abstract — it's a concrete episode I can tell.

A "Pattern" for Collaboration Took Shape

Across several projects, my own pattern for collaboration came into view.

Role	Owner
Lay out option tables for direction / demo boilerplate / review	AI
Choose / decide the design / implement / verify / judge scope	Me

AI is good at "lining up options," "producing a first draft," and "pointing out rough spots"; I take on "choosing," "deciding," and "confirming." Concepts by my own hand, boilerplate to AI — but always demanding an explanation and understanding it before taking it in. This split was the realistic solution that let me balance the deadline with learning.

☕ Java comparison: It's close to designing a detailed interface yourself and delegating part of the implementation. The design is mine, the initial implementation is AI's — which is exactly why I read the delegated parts myself, rewrite them if needed, and keep the final responsibility.

Wrapping Up

A reflection on building a real product through AI collaboration. Three points:

The question is not "did you use AI" but "are you the one driving." Disclosure isn't a confession — it's presenting evidence of being the one driving.
Most stumbles are gaps between "what I thought I did" and "what's actual." "A passing test ≠ behaving as intended" was the thread through AI collaboration too.
The most important thing was, more than what AI wrote, rejecting an AI suggestion. Verify domain knowledge against primary sources.

Working with AI makes development faster. But the faster it goes, the more "thought-I-did" creeps in. So don't let go of the driving. Keep the thinking and the verification with yourself, and collaborate on the wording and the boilerplate — that, for me right now, is "AI-collaborative development where the person is driving."

That completes the series. You can trace the app's whole picture, each implementation, and the basis for the metrics from here:

This article is a record of development and writing done with AI assistants (Claude / Cursor). The design, tech-selection, and verification decisions were made by the author. I collaborated with AI on the article's outline, structure, and draft prose, and reviewed and revised every line before publishing.

I Went Looking for the Basis of 'N Characters Per Minute Is Fast' — There Wasn't One. Setting Read-Aloud Thresholds Honestly

Uya — Thu, 18 Jun 2026 12:47:41 +0000

📝 Originally published in Japanese on Zenn. This is the English version.
Canonical: https://zenn.dev/uya0526_design/articles/satellite3_metrics-rationale

📚 This is satellite article #3 in my "Read-Aloud Speed Meter dev log" series. For the whole picture, see the main article.

Where This Sits

The read-aloud speed meter converts speaking speed into an evaluation label like "slightly fast," and stagnation rate into one like "few." Those labels ultimately become the foundation for Claude Haiku's feedback.

So — on what basis did I draw the thresholds (the dividing lines)? This article digs into that "basis."

The short answer from my research:

I couldn't find a paper that defines an academic threshold for "N characters/min = fast/slow."

This is a record of how I drew the lines honestly once I'd learned there was no firm basis. More than the metric numbers themselves, I believe being transparent about why I chose those numbers is what makes an evaluation app trustworthy.

💡 I'm an ex-Java engineer learning TypeScript in public. This one is mostly about design decisions.

Why Obsess Over the "Basis"?

An evaluation app passes judgment on the user: "your reading is slightly fast." Once you're passing judgment, if you can't explain "why we can say that," it's just guesswork.

This app in particular passes the labels straight to Claude Haiku to generate coaching. If the foundational label has an unclear basis, the feedback built on top of it is a castle on sand. So I decided to nail down the basis for the thresholds first.

Two things to research:

The judgment basis for speaking speed (characters/min)
The judgment basis for stagnation rate (the proportion of silence)

As it turned out, these two had completely different kinds of basis.

Speed Thresholds: No Academic Threshold → Draw From General Rules of Thumb

What I found

For speaking speed, I first looked for academic backing. Here's what I found:

Speaking speed has traditionally been measured against mora count, but prior research from the listener's perspective is itself scarce.
Japanese is considered a "fast language" with many syllables per second, yet there's research suggesting that, correlated with information density, the overall information-transfer rate is similar across languages.

But none of this serves as a basis for judging whether an individual's reading is fast or slow. I couldn't find an academic threshold that says "N characters/min is fast."

The basis I adopted: the announcer standard

So I adopted a rule-of-thumb basis. The premise: the speed expected of an announcer is 300 characters/min.

The NHK announcer standard is "300 chars/min." It's shared knowledge across program staff and serves as a guide for writing scripts.
The trend has been getting faster recently — said to be around 380 chars/min at NHK and 400 at commercial broadcasters.
In settings that demand fast delivery, like sports play-by-play, over 400 chars/min is common.

Announcers are in the realm of language professionals. So if an ordinary reader reaches this speed, I positioned that as already on the "slightly fast" side.

Thresholds (adopted version)

Speed label	Chars/min
Slow	– 149
Slightly slow	150 – 199
Standard	200 – 299
Slightly fast	300 – 350
Fast	351 –

This is where an app-specific design decision comes in. General tables usually put "the NHK standard, ~300 = standard," but this app intentionally shifts that, placing the professional standard of 300 as the start of "slightly fast" for an ordinary person.

The reason is that this app's users are ordinary readers. If I put the professional level at "standard," almost everyone gets a "slow" verdict, and the coaching pushes in a discouraging direction. "If an ordinary person reaches the professional level, that's already on the fast side" is a more natural framing for an encouragement tool.

☕ Mapping into code: These thresholds live as constants in thresholds.ts. The explanation of the numbers' basis (300 = pro standard, etc.) isn't in code comments but in this article and the LEARNING_LOG. In Java terms, it's the same as "extract config values into constants + keep the intent in the design docs."

Writing about it honestly in the article and UI

What I was careful about when presenting the thresholds was not creating the misunderstanding that "Claude is judging on strict academic grounds."

Since there's no academic threshold, write honestly that I adopted a rule-of-thumb basis (announcer standard, 300 chars/min).
Spell out the intent of the custom placement — putting the pro standard of 300 as the ordinary person's "slightly fast" start.
Note that, more rigorously, chars/min is a simplified metric and mora/min is the usual measure.

Rather than dressing it up as "strict science," I figured showing the process — "I drew the lines this way, on this basis" — earns more trust for an evaluation app.

Stagnation-Rate Thresholds: There Isn't Even a "Ruler"

Even less basis than speed

For stagnation rate (the proportion of silence across the whole utterance), the conclusion was even tougher than for speed:

The basis for a numeric threshold of "stagnation under X% is good" is even harder to find than for speed. It's a domain where the "numeric ruler" itself, the kind speed has, simply doesn't exist.

It's also thorny as a general principle. A speaker not taking pauses is not itself regarded as evidence of fluent speech. In fact, research holds that pauses serve important functions:

Speech rate (including pauses) and articulation rate (the speaking portion only) are distinct concepts, and the one including pauses correlates more strongly with auditory impression.
Pauses don't just mark word/phrase/sentence boundaries — they serve the important function of giving the listener a chance to digest information.

In other words, "fewer pauses = better" doesn't simply hold.

Accepting it as an "in-house metric"

Here I made a design decision. For stagnation rate, I decided to claim no academic or general backing and accept it frankly as an in-house heuristic for this app.

Stagnation label	Stagnation rate (% after `labelMetrics`)
Few	– 0.9%
Somewhat few	1.0 – 5.9%
Normal	6.0 – 9.9%
Somewhat many	10.0 – 19.9%
Many	20.0% –

The basis for putting "0% on the good side" is cultural context

Let me get ahead of the question a reader will naturally have: "Why put 0% (speaking without breaks) on the good side?"

The basis isn't academic — it's the cultural context of Japanese. Japanese has an expression, "tate-ita ni mizu" (literally "water down a standing board" — speaking fluently and without interruption), reflecting a disposition to see uninterrupted, flowing speech as "fluent." I drew the line leaning toward that connotation.

That said, this isn't "the correct answer." As noted above, there's research finding that "pauses serve a function of letting the listener digest information," so 0% isn't always good. I judged this to be a domain that isn't academically settled and where people's perceptions differ, and — within a deadline-bound Phase 1 — I didn't chase it deeper; as the designer I adopted the connotation on the "tate-ita ni mizu" side.

⚠️ This metric's limits: As it stands, the stagnation rate does not distinguish Japan's meaningful pauses (ma). A 0.5-second stop that lands appropriately at a punctuation point and a 0.5-second stumble where the reader got stuck are both counted as the same "silence" stagnation. It really ought to be looked at qualitatively, paired with "appropriateness of the pause's position," and this is a research item not yet listed in the README's Phase 2. The app's footer makes this limit explicit too.

The Two Metrics Had Different Kinds of Basis

To summarize, even for the same "evaluation-metric threshold," how I grounded them was completely different:

Metric	Academic threshold	Basis adopted	How I handle it in the article
Speed	None	Rule of thumb (announcer 300 chars/min)	Present an industry-custom value as basis; spell out the custom placement
Stagnation rate	None (no ruler at all)	App-specific heuristic + cultural context	Claim no academic backing; honestly label it an in-house metric

This is the point I most want to land in this article. When you can't find a basis, don't force a "this is scientific" facade. Disclosing the process — "there's no academic threshold, so I drew from a rule of thumb," "I accepted this as an in-house metric" — is, I think, actually stronger for an evaluation app.

What I Decided Myself / What I Asked AI For

Area	Detail
My decisions	The final thresholds, the custom placement of the announcer standard, the call to treat stagnation as an in-house metric, adopting the "tate-ita ni mizu" context, stating the MVP limits
Asked AI for	Presenting tentative boundary tables, helping survey related research and industry-custom values
Verified myself	Checking sources, the final judgment on the validity of the basis (not taking AI's research at face value)

The threshold numbers and their basis were all decided by me. AI helped with the survey and tentative drafts, but "which basis to adopt and how to place it" is the designer's judgment.

Wrapping Up

This was a summary of "on what basis" I drew the read-aloud evaluation thresholds. Three takeaways:

There was no academic threshold for speed, so I grounded it in a rule of thumb (announcer 300 chars/min) and custom-placed the pro standard as the ordinary person's "slightly fast" start.
Stagnation rate has no ruler at all, so I accepted it as an app-specific heuristic; the basis for putting 0% on the good side rests on the cultural context of "tate-ita ni mizu."
When there's no basis, don't dress it up as scientific — disclose the process. That, I believe, is what makes an evaluation app honest.

An evaluation tool's value isn't decided by the precision of the numbers alone. It's whether you can be transparent with the user about how you justified those numbers. I recorded even the dead ends of the basis hunt because that was the thing I most wanted to convey.

The detailed development log is in the repository's LEARNING_LOG.

📦 https://github.com/uya0526-design/reading-speed-meter

Main references

Sources I consulted while organizing the basis for this article.

Ayumi Marushima, "A Study on the Cognition of Speech Rate," Studies in Linguistics online inaugural issue (2008) [in Japanese]
Ayumi Marushima, "A Study on the Tempo of Spoken Language," Studies in Linguistics online no. 2 (2009) [in Japanese]
Ayumi Marushima, "An Experimental-Phonetics Study of Speech Rate from the Speaker's and Listener's Perspectives," doctoral dissertation, University of Tsukuba (2015) [in Japanese]
Reporting and shared industry knowledge on NHK / commercial-broadcaster announcer speech rates (Diamond Online, etc.)

💡 As this article argues, I believe an academic "speed threshold" does not exist. The above aren't sources for the thresholds themselves, but background knowledge for "how to think about speech rate and pauses." I've checked each against the original.

Next time is the finale — I look back at the "AI-collaborative development" that underpinned all these design decisions → satellite #4, "Reflections on AI-collaborative development & a collection of stumbles" (https://dev.to/uya0526design/not-did-you-use-ai-but-are-you-the-one-driving-reflections-on-building-a-real-product-through-464m).

This article is part of my public learning journey using AI tools (Claude / Cursor). The thresholds and the judgment of their basis are mine. I collaborate with AI on the article's structure, outline, and draft prose, and I review and revise every line before publishing.

Don't Let Claude Haiku Do the Math — A Two-Stage Read-Aloud Coach Design, and the Prompt Swamp

Uya — Thu, 18 Jun 2026 12:45:29 +0000

📝 Originally published in Japanese on Zenn. This is the English version.
Canonical: https://zenn.dev/uya0526_design/articles/satellite2_haiku-coaching

📚 This is satellite article #2 in my "Read-Aloud Speed Meter dev log" series. For the whole picture, see the main article; for the AmiVoice integration, see satellite #1.

Where This Sits

This article covers the part of the read-aloud speed meter that hands the measured numbers to Claude Haiku to generate coaching as "one compliment + one improvement."

Many articles that use generative AI just dump it on the model: "here's the recognized text, evaluate it nicely." This article is the opposite. Don't let the LLM do the math. All computation and rule-based decisions are settled in code, and Haiku only does the wording. I'll go through how I designed this "two-stage" split, and which swamps I sank into during implementation.

Four things:

Why "code does the math, Haiku only does the wording" (the role-split design)
The finalized prompt, and the messages / system / cache_control implementation
First-hand findings: the prompt cache that didn't work
The moment real data slapped me with "written in the prompt ≠ obeyed"

💡 I'm an ex-Java engineer learning TypeScript in public, so I drop in Java comparisons.

Why Not Let Haiku Do the "Math"?

Up front: Haiku is more than enough for feedback generation — in fact, you can shape the task into something Haiku is good at. The key is the role split.

I settle all the metric computation (speaking speed, stagnation rate, threshold decisions) entirely in code. So by the time it reaches Haiku, it's already settled facts like this (below is from running labelMetrics on a real measurement — reading the Heike sample during development; stagnationRate is a number for percentage display):

{
  "pureSpeakingSpeed": 322,
  "pureSpeakingSpeedEvaluation": "slightly fast",
  "stagnationRate": 0,
  "stagnationRateEvaluation": "few"
}

Haiku's only job is to translate these numbers and labels into warm, concrete words. That's exactly what small models are best at — wording, summarizing, tone — and it demands no numeric precision.

Conversely, I clearly decided what not to let Haiku do:

Precise numeric computation (deriving speed or scores) → done in code
Multi-step threshold branching (judging "is 322 chars/min fast?") → code interprets it as "slightly fast" before passing it on

☕ Java comparison: This is exactly the separation of the Service layer (computation = code) from the presentation layer (wording = Haiku). Just as you don't write business logic in a template engine, I draw the line at "don't make the LLM write the decisions."

This split has a practical benefit beyond cost: pushing threshold decisions into code makes the output stable. Asking Haiku to judge "is this fast?" every time wavers with its mood, but passing it the label "slightly fast" leaves only the wording free to vary.

The Finalized Prompt

Here's the system prompt (a static coach persona). After running it against real data several times, it settled into this shape. (Translated here for readability; the production version is in Japanese.)

You are a kind, specific coach who reviews Japanese read-aloud practice.

# Premises (strict)
- The JSON you receive is already-computed, already-evaluated fact.
- Do not recompute numbers. Do not invent new metrics. Do not fill in
  facts that aren't in the JSON by guessing.
- Speak only on the basis of what's written in the JSON.
- Do not mention punctuation (samples can be short and may contain none).

# Output format (strict)
- Polite register. Warm, calm tone.
- No emoji, symbols, line breaks, headings, or preamble. Output exactly two sentences.

# Output format (best-effort)
- About 100 Japanese characters total.

# Output content
Sentence 1: Pick the single best point and praise it concretely.
Sentence 2: Give exactly one improvement, as a concrete action to try next.

# How to pick the improvement (top-down; only the first that matches)
1. "stagnationRateEvaluation" is "somewhat many" or worse → how to use pauses (ma)
2. "pureSpeakingSpeedEvaluation" is "slightly slow"/"slow" → ease the tempo forward
3. "pureSpeakingSpeedEvaluation" is "slightly fast"/"fast" → consciously take a breath and read slower
4. None apply → pick the one most-improvable point and frame it positively as the next goal

Three notes on the intent:

I prioritize the improvements and emit only the first match. I also added a fourth branch (a fallback) so the model isn't forced to hunt for flaws when everything is good.
Without explicitly saying "exactly two sentences," it tacks on preamble or bullet points. I lock the purity of the output via the prompt.
"About 100 chars" is a best-effort goal. I explain why below, but it's because LLMs can't count Japanese characters precisely.

API Implementation: `system` / `messages` / `cache_control`

I call it via messages.create from the Claude Messages API (@anthropic-ai/sdk).

const result = await client.messages.create({
  model: process.env.ANTHROPIC_MODEL!, // e.g. claude-haiku-4-5
  max_tokens: 256,
  system: [
    {
      type: "text",
      text: FEEDBACK_PROMPT,
      cache_control: { type: "ephemeral" }, // goes inside the system block
    },
  ],
  messages: [
    { role: "user", content: JSON.stringify(feedbackFacts) }, // settled facts only
  ],
});

What the structure means:

system = Claude's persona and ground rules (outside the conversation). The static coach persona lives here.
messages role: "user" = the actual conversational input (the evaluation JSON that changes each time).
role is either "user" (your input) or "assistant" (Claude's reply). This is a single round-trip, so one user entry is enough.

☕ Java comparison: A fixed system prompt plus a variable user payload is like passing request/response pairs as an array. For multi-turn conversations, you stack the history in order.

How to think about `max_tokens`

I initially set 1024, copied from an official example, but this output (two sentences) measured at about 88 tokens. max_tokens is "the maximum you may generate," not "the amount you must generate," so a generous value does almost no harm — generation stops naturally when the output ends. As a safety valve against unintended long output, I tightened it to 256 as in the code above.

☕ Java comparison: It feels close to StringBuilder's initialCapacity. Reserving large doesn't cost anything if you don't use it.

Swamp ① — The Prompt Cache "Didn't Work"

Here's where the first-hand, verify-it-yourself finding begins.

Since the static system prompt is identical every time, I figured I could make it cheaper with prompt caching. I added cache_control: { type: "ephemeral" }, did the break-even math (cache writes cost 1.25× the first time, reads are ~90% off afterward, so "it pays off after two uses"), and concluded "I should use this."

But it wasn't actually working.

The reason is a minimum-token wall. Claude Haiku 4.5's minimum cacheable size is 4,096 tokens. My system prompt was a few hundred tokens — below the threshold. Even with cache_control written, nothing was being cached.

You can check via the response usage:

console.log(result.usage);
// cache_creation_input_tokens: 0
// cache_read_input_tokens: 0   ← if both are 0, nothing was cached

Both were 0. I was so absorbed in the break-even math that the underlying minimum-token condition was my blind spot.

Writing cache_control does no operational harm (it's simply ignored). But writing "I optimized it with caching" in this app would be false. I decided the most honest — and most useful to the reader — thing was to keep it as a verification process: I thought it would help, checked, found it didn't meet the conditions, and it didn't help.

💡 Lesson: "The official feature exists" and "it helps in my use case" are different problems. If you don't check the preconditions — like a minimum token count — you can end up thinking you optimized while doing nothing.

Swamp ② — "Written in the Prompt ≠ Obeyed"

The other swamp. Reading with real data, this happened:

Read a short ~10-second sample → the recognized text contains no punctuation
Yet Haiku tacked on a concrete tip that wasn't in the input: "take a breath at the punctuation"

The cause was that the finalized prompt's rules had punctuation-dependent wording like "settle at the punctuation." As a fix, I:

Added one line to the premises: "do not mention punctuation"
Changed rule 3 from "settle at the punctuation" → "consciously take a breath and read slower" (punctuation-independent wording)

But there's no guarantee this is obeyed 100%. LLMs can probabilistically break even a "do not ~" prohibition.

In fact, the same run had another wobble. The input was stagnation "somewhat many" + speed "slow," which by the rules should prioritize rule 1 (how to use pauses). But the output leaned toward rule 2 (tempo forward). This surfaced the limit of a design that writes the priority decision into the prompt and lets Haiku choose.

What kicked in here is the same shape as a past lesson: "a passing test ≠ behaving as intended." It's not about whether you instructed it, but whether you verify against real data that it was obeyed. "Written in the prompt" does not equal "obeyed."

☕ Java comparison: It's the same as writing "returns within 100 characters" in a method's Javadoc but still validating on the caller side. Writing a spec and the spec being upheld are separate things. Whether it was upheld is checked on the caller side (in code).

If you want stability, "settle it in code and pass it in"

To make the output fully stable, you can decide which improvement to emit in code and pass it as a single field like { "improvementFocus": "how to use pauses" }. Then Haiku can focus only on wording, and the priority wobble disappears.

Approach	Detail	Trade-off
A (used this time)	Write the priority in the prompt, let Haiku choose	Looks smart, but wobbles
B	Settle the improvement focus in code, pass as one field	Stable output, but rigid

Due to the deadline I left it on approach A this time (watching it after the prompt fix), but I have a clear sense that if the wobble stands out in production, leaning to B is the sure bet. This too was a design-decision point: "looking smart vs. being stable."

How to Handle the Character Limit (Phase 1)

Having Haiku itself count "within 100 chars" isn't trustworthy. LLMs can't count Japanese characters precisely and routinely return over the limit. In Phase 1:

Keep the prompt's "about 100 chars" as a best-effort goal
Hold the actual ceiling with max_tokens: 256
Code-side validation (like truncating on overflow) is not implemented in Phase 1 (a future option)

As with swamp ②, the state here is "the prompt is the spec; the strict guarantee isn't in code yet."

What I Implemented Myself / What I Asked AI For

Area	Detail
My decisions / implementation	The role split (compute = code / wording = Haiku), the finalized prompt text, the improvement priority order, the `max_tokens` value, the cache verification, isolating and fixing the punctuation issue, the A/B trade-off judgment
Asked AI for	The `messages.create` skeleton, how to write the `system` array + `cache_control`, an example of how to check `usage`
Fixed on AI's pointer	Putting `cache_control` inside the block rather than on a string `system`, a sensible `max_tokens` value, observing the punctuation wobble

The prompt text, the role split, and the verification decisions are all mine. I ran it against real data, sank into the swamps, and isolated and fixed them myself.

Wrapping Up

This was my design for generating read-aloud coaching feedback with Claude Haiku. Three takeaways:

A two-stage design — code does the math, Haiku only does the wording. Keep the LLM on its best skill, translation, and settle the decisions in code.
Prompt caching didn't work in this app (it doesn't reach Haiku's 4,096-token minimum). If you don't check the preconditions, "optimizing" becomes "pretending to."
Written in the prompt ≠ obeyed. Verify the punctuation and priority wobbles against real data, and if you need stability, push the decisions into code.

The thread running through it all is one point: instruction and verification are separate. A prompt is a spec, not a guarantee — on that premise, keeping your verification in code and real data is, I believe, the honest stance when using generative AI in a real product.

The detailed development log is in the repository's LEARNING_LOG_Phase1_Step4.md.

📦 https://github.com/uya0526-design/reading-speed-meter

Next time I dig into the rationale behind the metrics — on what basis I set the speed and stagnation-rate thresholds → satellite #3, "The rationale behind the metrics" (https://dev.to/uya0526design/i-went-looking-for-the-basis-of-n-characters-per-minute-is-fast-there-wasnt-one-setting-4967).

This article is part of my public learning journey using AI tools (Claude / Cursor). The design, prompt, and verification decisions are mine, and the output is checked against real data. I collaborate with AI on the article's structure, outline, and draft prose, and I review and revise every line before publishing.

Calling AmiVoice's Synchronous HTTP API Through a Next.js BFF — Auth, multipart Order, and the WebM Trap

Uya — Thu, 18 Jun 2026 12:42:49 +0000

📝 Originally published in Japanese on Zenn. This is the English version.
Canonical: https://zenn.dev/uya0526_design/articles/satellite1_amivoice-bff

📚 This is satellite article #1 in my "Read-Aloud Speed Meter dev log" series. For the whole picture, see the main article.

Where This Sits

In the read-aloud speed meter app, this article covers the part that sends browser-recorded audio to the AmiVoice API to get back recognized text plus timestamps. The theme is calling an external API without exposing your API key to the browser — in other words, implementing a BFF (Backend for Frontend).

The main article only touched the highlights, so here I go down to a level you can reproduce yourself. Specifically, four things:

Why you must not call AmiVoice directly from the browser (why a BFF is needed)
AmiVoice's synchronous HTTP auth, parameters, and multipart order
Why the browser's MediaRecorder output (WebM/Opus) passes through as-is
Reshaping the raw JSON with a pure-function mapper and testing it with fixtures

💡 I'm an ex-Java engineer learning TypeScript in public, so I drop in comparisons to Java here and there.

Why a BFF Is Needed

Using the AmiVoice API requires an API key. And that key must never appear in browser-side code. Frontend JavaScript is fully inspectable by the user, so writing the key there leaks it instantly.

So I insert a relay that holds the key.

[Browser] ──audio Blob──▶ [Next.js API Route (BFF / holds key)] ──▶ [AmiVoice API]
 record / display   audio field      reshape into u / d / a        speech → text

The browser only calls my own API Route (/api/recognize), and that Route attaches the key server-side and forwards to AmiVoice. The key is just read from process.env and never ends up in the bundle shipped to the browser.

☕ Java comparison: This is the same as a Spring @RestController reading an external API key from application.yml (env vars) and relaying without showing it to the client. Think "a thin Servlet that hides the secret and relays an external API." In Next.js, the export async function POST in app/api/recognize/route.ts corresponds to @PostMapping.

AmiVoice Synchronous HTTP API Spec

I used the synchronous HTTP interface, implementing against the official manual and double-checking with curl. The key points:

Item	Detail
Endpoint	`POST https://acp-api.amivoice.com/v1/nolog/recognize` (no-log version)
Auth	Put the API key in the multipart `u` part (not an `Authorization` header)
Engine	Engine name in `d` (e.g. `-a-general` = general conversational)
Audio	Binary in `a`. Must be the final multipart part
Response	`text` at the top; per-word `starttime`/`endtime` in `results[].tokens[]`
Error check	`code` empty string `""` = success; `code !== ""` = failure

I hit three traps here. Let me share them in order.

Trap ① — Auth is the `u` field, not a header

When I think "REST API auth," I think Authorization: Bearer .... AmiVoice's synchronous HTTP is different: the API key goes in a multipart field called u. My first version put it in a header, got a 401-style failure, and I stalled here.

Trap ② — The audio `a` goes last

The multipart parts need to be in the order u → d → a (audio), with the audio as the final part. Adding another field after it caused the audio to be ignored. The order you append to FormData carries meaning directly.

Trap ③ — WebM/Opus passes through as-is (`c` can be omitted)

The browser's MediaRecorder usually outputs audio/webm;codecs=opus. I braced for "I'll probably need to convert the format before handing it to AmiVoice," but WebM + Opus carries a header in the container, so the audio-format parameter c can be omitted on synchronous HTTP (verified with curl). You can send the recording Blob unconverted.

Implementing the API Route (BFF)

Here's app/api/recognize/route.ts with the traps accounted for.

const AMIVOICE_ENDPOINT = "https://acp-api.amivoice.com/v1/nolog/recognize";
const AMIVOICE_ENGINE = "-a-general"; // general conversational

export async function POST(req: Request) {
  // 1. Receive the audio Blob from the browser under the "audio" field
  const inForm = await req.formData();
  const audio = inForm.get("audio") as Blob;

  // 2. Reshape into u / d / a order for AmiVoice
  const outForm = new FormData();
  outForm.append("u", process.env.AMIVOICE_API_KEY ?? ""); // auth (not a header)
  outForm.append("d", AMIVOICE_ENGINE);                    // engine
  outForm.append("a", audio, "recording.webm");            // audio (always last)

  // 3. Forward to synchronous HTTP and return the raw JSON as-is
  const res = await fetch(AMIVOICE_ENDPOINT, { method: "POST", body: outForm });
  const body = await res.text();
  return new NextResponse(body, {
    status: res.status,
    headers: { "Content-Type": res.headers.get("Content-Type") ?? "application/json" },
  });
}

(Simplified. In the real code, a missing AMIVOICE_API_KEY returns 500 and never sends an empty key to AmiVoice.)

The key idea is "two stages of FormData." Browser → my Route receives under the audio field; Route → AmiVoice reassembles into u/d/a.

☕ Java comparison: It's the same shape as reshaping an inbound DTO into the multipart form for an outbound external API. "The shape you receive and the shape you send are different things" maps directly onto the FormData reshape.

I designed this Route to return AmiVoice's raw JSON almost untouched. Rather than putting formatting in the Route, I leave it to the next mapper (a pure function), separating responsibilities.

Look at the raw JSON with curl first

Before implementing, hitting the endpoint with curl to see the shape of the raw response turned out to be the fastest route in the end.

curl -X POST https://acp-api.amivoice.com/v1/nolog/recognize \
  -F u="$AMIVOICE_API_KEY" \
  -F d="-a-general" \
  -F a=@recording.webm

I pass the API key from an environment variable ($AMIVOICE_API_KEY) so I never hardcode a raw key in command history or code. "Keep the key out of the code" applies from the curl-verification stage onward.

The returned JSON looks roughly like this (excerpted; values are examples):

{
  "results": [
    {
      "tokens": [
        { "written": "一番", "spoken": "いちばん", "starttime": 1080, "endtime": 1480 },
        { "written": "買っ", "spoken": "かっ", "starttime": 1480, "endtime": 1672 },
        { "written": "た", "spoken": "た", "starttime": 1720, "endtime": 1800 }
      ],
      "text": "一番買った"
    }
  ],
  "text": "一番買った",
  "code": ""
}

The Mapper: Raw JSON → App Type (a Pure Function)

I reshape the raw JSON into the AmiVoiceResponse type used inside the app. I make this conversion a pure function with no I/O, sitting as a layer outside the measurement logic (calculateMetrics).

interface AmiVoiceResponse {
  text: string;
  segments: { starttime: number; endtime: number }[];
}

export function mapAmiVoiceResponse(rawResponse: unknown): AmiVoiceResponse {
  if (typeof rawResponse !== "object" || rawResponse === null) {
    throw new Error("Invalid response");
  }
  const { text, results } = rawResponse as {
    text: string;
    results: { tokens: { starttime: number; endtime: number }[] }[];
  };
  const segments = results[0]?.tokens.map((token) => ({
    starttime: token.starttime ?? 0,
    endtime: token.endtime ?? 0,
  })) ?? [];
  return { text, segments };
}

There was one fix here too. My first version referenced raw.result.tokens (singular) and got nothing back; I corrected it to raw.results[0].tokens (a plural array). It's a mistake I could have prevented by looking at the raw JSON with curl first, and it reaffirmed how important it is to "get hold of real data early."

🧭 Design decision: You can build segments "per word" or "per utterance." I went with per word, because the gaps (silence) between words then feed into the stagnation rate, letting me measure fluency more granularly.

Testing With Fixtures

Since the mapper is a pure function, it's straightforward to test with Vitest. The key is to save the real data captured with curl as a fixture.

fixtures/
├── test_01.json   # short response (3 tokens)
└── test_02.json   # based on real curl data (9 tokens)

import { describe, test, expect } from "vitest";
import { mapAmiVoiceResponse } from "./mapAmiVoiceResponse";
import raw01 from "../../fixtures/test_01.json";

describe("mapAmiVoiceResponse", () => {
  test("builds segments from tokens and extracts text", () => {
    const result = mapAmiVoiceResponse(raw01);
    expect(result.segments).toHaveLength(3);
    // Not just "the shape matches" — pin the concrete values
    expect(result.segments[0].starttime).toBe(1080);
    expect(result.segments[0].endtime).toBe(1480);
    expect(result.text).toBe("一番買った");
  });
});

What I was conscious of here is a lesson from a past project: "a passing test ≠ behaving as intended." If you only compare the result of .map() against another .map(), you end up writing the test with the same logic as the mapper, which doesn't verify intent. So by hardcoding concrete values like starttime: 1080 and asserting on them, I locked down "is it really pulling the correct values?"

☕ Java comparison: Fixtures are like JUnit test resources (JSON under src/test/resources); toHaveLength / concrete-value asserts correspond to assertEquals. The idea of "pinning production-like raw JSON into your tests" carried over directly.

What I Implemented Myself / What I Asked AI For

This is AI-collaborative development, so for transparency I write out the split.

Area	Detail
My decisions / implementation	Adopting the BFF structure, the `u`/`d`/`a` order, the raw-JSON-return policy, choosing per-word segments, concrete-value asserts in fixtures, checking the official manual, curl verification
Asked AI for	The POST handler skeleton, `fetch` / `FormData` boilerplate, a first-draft mapper example, examples of how to write the tests
Fixed on AI's pointer	`result` → `results[0]`, `Authorization` header → `u` field, a weak `.map()`-only test → concrete-value asserts

AI provided boilerplate examples, but the rewrites to match the official spec, the verification, and the fixes were all mine.

Wrapping Up

This was my record of calling AmiVoice's synchronous HTTP API through a Next.js BFF. The takeaways:

Keep the API key out of the browser. Use a BFF that relays through Next.js API Routes.
For synchronous HTTP, auth is the u field, the audio a is the final part, and WebM/Opus lets you omit c.
Reshape the raw JSON with a pure-function mapper, and test it with a fixture of real curl data + concrete-value asserts.

Most of my stumbles were ones I could have prevented by looking at the raw response first. When working with an external API, hit it once with curl and look at the raw JSON with your own eyes before implementing — that order turned out to be the fastest.

The detailed development log is in the repository's LEARNING_LOG_Phase1_Step3.md.

📦 https://github.com/uya0526-design/reading-speed-meter

Next time I cover the "two-stage" design that hands the recognized result (settled facts) to Claude Haiku to generate one-line feedback → satellite #2, "Claude Haiku coaching design and the prompt swamp" (https://dev.to/uya0526design/dont-let-claude-haiku-do-the-math-a-two-stage-read-aloud-coach-design-and-the-prompt-swamp-2ihc).

This article is part of my public learning journey using AI tools (Claude / Cursor). The design, tech selection, and implementation decisions are mine, and the code is verified with Vitest. I collaborate with AI on the article's structure, outline, and draft prose, and I review and revise every line before publishing.

Measuring Japanese Read-Aloud Speed with AmiVoice Timestamps — A Coaching App That Doesn't Stop at STT-to-Claude

Uya — Thu, 18 Jun 2026 12:41:47 +0000

📝 Originally published in Japanese on Zenn. This is the English version.
Canonical: https://zenn.dev/uya0526_design/articles/main_article_reading-speed-meter

Introduction — What I Built

I built a web app that lets you read a Japanese passage aloud, measures your speed and fluency, and has an AI coach return a one-line piece of feedback.

🌐 Demo: https://reading-speed-meter.vercel.app/
📦 Repository: https://github.com/uya0526-design/reading-speed-meter

The flow is simple. You read a passage aloud into the mic (up to 10 seconds) while looking at the script — I prepared the opening lines of two Japanese classics, The Tale of the Heike and Hōjōki — and when you press "Measure,":

AmiVoice API recognizes the audio,
the code computes your pure speaking speed (characters/min) and stagnation rate from that result, and
Claude Haiku returns coaching as "one compliment + one improvement."

(Measurement starts on a button press after recording — it never runs automatically.)

This article aims to be a single, self-contained piece covering the whole picture, the design decisions, and the reproduction steps.

💡 Where this sits in my journey

I'm an ex-Java engineer learning TypeScript and Python in public. This was my first project where I deliberately adopted "AI-collaborative development" as a clear mode. Throughout, I'll drop in comparisons to Java — hopefully useful for anyone coming from a similar background.

What You'll Get From This Article

How to design evaluation logic that fully exploits the per-word timestamps AmiVoice returns
How to build a BFF (Backend for Frontend) so API keys never reach the browser
A "two-stage" design where code does the math and Claude Haiku only does the wording
First-hand findings you only learn by verifying — e.g., "I thought I'd optimized it, but it wasn't actually working"

I include concrete endpoints, parameters, and environment variables so you can reproduce it yourself.

My Learning Style (AI Transparency)

💡 Learning companions & how this article is written

I use Claude Pro and Cursor Pro as learning companions. This project had a deadline (the AmiVoice-sponsored contest in Zennfes Spring 2026), so I stepped one notch beyond my usual "I write every line myself" style into AI-collaborative development. I'm stating that plainly rather than blurring it.

The axis of disclosure is not "did I use AI" but "am I the one driving."

Area	Owner
Tech selection, evaluation-algorithm design, architecture decisions, code verification	Me
Boilerplate examples (recording, fetch, API Route skeletons)	AI (Claude / Cursor)
Article structure, outline, draft prose, translation	In collaboration with Claude
Reviewing and revising all content before publishing	Me

In other words: the thinking is mine, the wording is AI-assisted, and I verify all of it. Every design decision, every threshold rationale, and every "where I got stuck" is my own first-hand information. I keep a per-step LEARNING_LOG in the repository separating "what I implemented myself" from "what I asked AI for."

Originality — Why Not Stop at "STT → Claude"?

A lot of articles combining speech-to-text (STT) with generative AI stop at "transcribe the audio, then hand the text straight to Claude." That works, but it throws away the best part of AmiVoice.

AmiVoice isn't just transcription. For each individual word, it returns:

Field	Meaning
`written`	Surface form (kanji + kana)
`spoken`	Reading (kana)
`confidence`	Confidence score (0–1)
`starttime` / `endtime`	Word start/end time (milliseconds)

Using starttime / endtime, you know when, which word, and over how long it was read. So my approach is:

Get depth from the evaluation logic (code), then turn it into something human with Claude Haiku — a two-stage design.

In education and phonetics, read-aloud fluency is traditionally discussed along three axes: accuracy, speed, and expressiveness. This app (Phase 1) implements speed primarily, and adds stagnation rate (the proportion of pauses) as an in-house metric that's the flip side of speed. Pauses are academically treated as part of speech rate, so I position stagnation as a speed-adjacent metric.

Axis	Metric in this app	Phase
Speed	Pure speaking speed (chars/min) / stagnation rate (in-house, speed-adjacent)	Phase 1 ✅
Accuracy	Matching via edit distance	Phase 2 (planned — see README)
Expressiveness (intonation, etc.)	—	Not in scope for Phase 1

"Read-aloud evaluation that leans hard on the time information" turned out to be a rare sweet spot — low cost (just arithmetic) yet genuinely distinctive.

Architecture — Keep API Keys Out of the Browser

Both AmiVoice and Claude require API keys, and those keys must never be exposed to the browser. So I insert a thin relay (BFF / proxy) that holds the keys.

[Browser]
  Show script / record (getUserMedia → MediaRecorder → Blob)
        │  FormData(audio)
        ▼
[Next.js API Routes (BFF / holds keys)]
  /api/recognize  → AmiVoice synchronous HTTP (speech → text)
  /api/feedback   → Claude Messages API (one-line feedback)
        │
        ▼
[Browser]  Show metrics → show AI feedback

The browser never calls the two external APIs directly. Next.js API Routes act as a thin key-holding relay.

☕ Java comparison: This is the same idea as a Spring @RestController reading an external API key from application.yml, never showing it to the client, and relaying the call. Think of it as "a thin Servlet that relays an external API without leaking the secret."

Tech stack:

Layer	Choice
Framework	Next.js 16 (App Router) + API Routes
Language	TypeScript
Recording	MediaRecorder API
Speech recognition	AmiVoice API (synchronous HTTP)
AI feedback	Claude API (Haiku / `@anthropic-ai/sdk`)
Testing	Vitest (28 tests)
Deploy	Vercel

I considered splitting the backend off into Python (FastAPI), but to hit the deadline I consolidated on Next.js: one language, one repository, one deploy.

Evaluation Logic (Code Side)

All computation and threshold decisions are settled in code. This is where the "depth" comes from.

Pure speaking speed and stagnation rate (a pure function)

I keep everything inside a pure function calculateMetrics that holds no I/O, so it's directly testable with Vitest.

// Input: a type reshaped from the AmiVoice response
interface AmiVoiceResponse {
  text: string;
  segments: { starttime: number; endtime: number }[]; // milliseconds
}
interface ReadingMetrics {
  pureSpeakingSpeed: number; // chars/min
  stagnationRate: number;    // 0–1
}

export function calculateMetrics(res: AmiVoiceResponse): ReadingMetrics {
  const { text, segments } = res;
  if (text.length === 0 || segments.length === 0) {
    return { pureSpeakingSpeed: 0, stagnationRate: 0 };
  }
  const totalSpeakingTimeMs = segments.reduce(
    (acc, segment) => acc + (segment.endtime - segment.starttime), 0);
  if (totalSpeakingTimeMs === 0) {
    return { pureSpeakingSpeed: 0, stagnationRate: 0 };
  }
  let pureSpeakingSpeed = Math.round(
    [...text].length / (totalSpeakingTimeMs / 60000));
  const totalElapsedTimeMs =
    segments[segments.length - 1].endtime - segments[0].starttime;
  if (totalElapsedTimeMs === 0) {
    return { pureSpeakingSpeed: 0, stagnationRate: 0 };
  }
  let stagnationRate =
    (totalElapsedTimeMs - totalSpeakingTimeMs) / totalElapsedTimeMs;
  stagnationRate = Math.round(stagnationRate * 1000) / 1000;
  return { pureSpeakingSpeed, stagnationRate };
}

Two design points:

Character count is based on the recognized text, in code points: [...text].length. Basing it on the original script would over-estimate speed when the reader skips ahead, so I avoided that.
Keep the numeric type with Math.round. toFixed returns a string, so I don't use it.

☕ Java comparison: [...text].length is a character count that accounts for surrogate pairs; reduce corresponds to stream().mapToLong().sum(). The division-by-zero guards and boundary tests are exactly the kind of error-path and boundary-value analysis you write all the time in JUnit.

Decide thresholds honestly

Next, labelMetrics converts the numbers into evaluation labels ("slightly fast," etc.). The hard question: how many characters/min counts as "fast"?

Honestly: I couldn't find an academic threshold for "N chars/min = fast/slow." So for speed I leaned on a general rule of thumb — a news announcer's pace ≈ 300 chars/min — and intentionally placed that professional level as the start of "slightly fast" for an ordinary person. For stagnation rate there's no numeric standard at all, so I treat it frankly as an in-house heuristic.

Speed label	Chars/min
Slow	– 149
Slightly slow	150 – 199
Standard	200 – 299
Slightly fast	300 – 350
Fast	351 –

The reasoning behind these lines — the in-house placement, why I treat stagnation as an in-house metric, the cultural context of "fluent as water off a board," and the relation to mora — is something I dig into in a separate satellite article: "The rationale behind the metrics" (https://dev.to/uya0526design/i-went-looking-for-the-basis-of-n-characters-per-minute-is-fast-there-wasnt-one-setting-4967). Here, just hold onto the principle: when there's no basis, don't dress it up as science — disclose the process and draw the line.

⚠️ MVP limits (stated honestly): Right now there's no matching of the script against the recognized text (accuracy is Phase 2 in the README), and the stagnation rate doesn't distinguish Japan's meaningful pauses (ma). The latter is a research item not yet listed even in the README's Phase 2. Both are spelled out in the app's footer.

Exploiting AmiVoice Fully

/api/recognize receives the recording Blob and relays it to AmiVoice's synchronous HTTP API. Here are the spots that trip people up. (Full implementation and a deeper dive are in satellite #1, "Implementing AmiVoice synchronous HTTP" (https://dev.to/uya0526design/calling-amivoices-synchronous-http-api-through-a-nextjs-bff-auth-multipart-order-and-the-webm-21o5).)

const AMIVOICE_ENDPOINT = "https://acp-api.amivoice.com/v1/nolog/recognize";
const AMIVOICE_ENGINE = "-a-general"; // general conversational

export async function POST(req: Request) {
  const inForm = await req.formData();
  const audio = inForm.get("audio") as Blob;

  const outForm = new FormData();
  outForm.append("u", process.env.AMIVOICE_API_KEY ?? ""); // auth
  outForm.append("d", AMIVOICE_ENGINE);                    // engine
  outForm.append("a", audio, "recording.webm");            // audio (must be last)

  const res = await fetch(AMIVOICE_ENDPOINT, { method: "POST", body: outForm });
  const body = await res.text();
  return new NextResponse(body, {
    status: res.status,
    headers: { "Content-Type": res.headers.get("Content-Type") ?? "application/json" },
  });
}

(Simplified. In the real code, a missing AMIVOICE_API_KEY returns 500 and never sends an empty key to AmiVoice.)

Gotchas I confirmed against both the official manual and curl:

Auth is the multipart u field, not an Authorization header. I assumed header auth at first and got stuck here.
The audio a must be the final multipart part. Add another field after it and it gets ignored.
WebM + Opus carries a header in the container, so you can omit the audio-format parameter c on synchronous HTTP (verified with curl). The browser's MediaRecorder output (audio/webm;codecs=opus) went through as-is.

I reshape the raw JSON into AmiVoiceResponse with a pure-function mapper before passing it to calculateMetrics. text is top-level; segments are built from starttime / endtime in results[0].tokens — and yes, I initially referenced result (singular) and had to fix it.

Claude Haiku's "Two-Stage" Design

For feedback generation I'm strict about the split: code does the math, Haiku only does the wording. By the time data reaches Haiku, it's already settled facts — for example, a real measurement during development (reading the Heike sample) ran labelMetrics to "speed = 322 chars/min, label = slightly fast, stagnation = 0%, label = few." Haiku's only job is to translate that into warm words. I keep the small model on what it's best at — wording and tone — and never demand numeric precision from it.

const result = await client.messages.create({
  model: process.env.ANTHROPIC_MODEL!, // e.g. claude-haiku-4-5
  max_tokens: 256,
  system: [
    { type: "text", text: FEEDBACK_PROMPT, cache_control: { type: "ephemeral" } },
  ],
  messages: [
    { role: "user", content: JSON.stringify(feedbackFacts) }, // settled facts only
  ],
});

system = persona and ground rules (a static coach persona)
messages role: "user" = the dynamic data that changes each time (the evaluation JSON)

☕ Java comparison: A fixed system prompt plus a variable user payload is the same idea as separating the Service layer (computation = code) from the presentation layer (wording = Haiku).

The "optimization" that wasn't working

This is my biggest first-hand finding this time. I added cache_control to the static system prompt to make it cheaper via prompt caching. I even did the break-even math and concluded "it pays off after two uses."

It wasn't working at all. Claude Haiku 4.5's minimum cacheable size is 4,096 tokens, and my system prompt was a few hundred. It didn't meet the threshold, so even with cache_control written, nothing was cached. (Confirmed via the response usage: both cache_creation_input_tokens and cache_read_input_tokens were 0.)

Writing "I optimized it with caching" would be false. So I'm keeping it in the article as a verification process: I thought it would help, checked, found it didn't meet the conditions, and it didn't help. Not casually claiming "optimized" is, to me, part of being honest.

"Written in the prompt ≠ obeyed"

One more. A ~10-second read produces recognized text with no punctuation. Yet Haiku tacked on a concrete tip that wasn't in the input: "take a breath at the punctuation." I added a line to the prompt — "don't mention punctuation" — but even that isn't a 100% guarantee.

This is the same shape as a lesson from a past project: "a passing test ≠ behaving as intended." What matters isn't whether you instructed something, but whether you verify against real data that it was obeyed. If you ultimately want fully stable output, you can push the improvement focus into code and pass it as a single field (a Phase 2 option).

The finalized prompt, the full cache-verification details, and how I isolated the punctuation issue are in satellite #2, "Claude Haiku coaching design and the prompt swamp" (https://dev.to/uya0526design/dont-let-claude-haiku-do-the-math-a-two-stage-read-aloud-coach-design-and-the-prompt-swamp-2ihc).

Reproduction Steps

The minimum to run it locally:

git clone https://github.com/uya0526-design/reading-speed-meter
cd reading-speed-meter
npm install

Create .env.local at the project root (never commit it):

AMIVOICE_API_KEY=your_amivoice_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_MODEL=claude-haiku-4-5

npm run dev    # → http://localhost:3000
npm test       # Vitest (28 tests)
npm run build  # production build check

To deploy on Vercel: import from GitHub → confirm the Framework Preset is detected as Next.js → add the three Environment Variables above → Deploy. Crucially, none of the three should have a NEXT_PUBLIC_ prefix (that would expose them to the browser). Recording needs mic permission, so it runs over HTTPS (Vercel's public URL) or localhost.

Design Decisions & Gotchas — Highlights

Topic	What happened / how I decided
AmiVoice auth	Assumed an `Authorization` header → found synchronous HTTP uses the `u` field; fixed
Audio part order	Put `a` (audio) as the last part — anything after it is ignored
WebM/Opus	Header present, so `c` can be omitted; `MediaRecorder` output passes as-is
Prompt cache	Thought it would help, but didn't meet Haiku's 4,096-token minimum — it didn't work
Punctuation leak	Haiku mentioned punctuation that wasn't in the input → fixed the prompt (no full guarantee)
Char-count limit	"Within 100 chars" — LLMs can't count precisely, so I demoted it to a best-effort goal
Classics attribution	AI explained the Heike / Hōjōki openings backwards → I verified against sources and rejected it

That last one symbolizes "the human is the one driving" in AI-collaborative development. Don't take AI's suggestions at face value; verify domain knowledge against primary sources. That accumulation is what makes this article and the implementation trustworthy.

Satellite Articles (Deep Dives)

This article is the overview. Each topic is broken out separately:

👉 This article (overview & MVP design)
Satellite #1 — Implementing AmiVoice synchronous HTTP: BFF, auth, mapper (https://dev.to/uya0526design/calling-amivoices-synchronous-http-api-through-a-nextjs-bff-auth-multipart-order-and-the-webm-21o5)
Satellite #2 — Claude Haiku coaching design and the prompt swamp (https://dev.to/uya0526design/dont-let-claude-haiku-do-the-math-a-two-stage-read-aloud-coach-design-and-the-prompt-swamp-2ihc)
Satellite #3 — The rationale behind the metrics: how I set speed and stagnation (https://dev.to/uya0526design/i-went-looking-for-the-basis-of-n-characters-per-minute-is-fast-there-wasnt-one-setting-4967)
Satellite #4 — Reflections on AI-collaborative development & a collection of stumbles (https://dev.to/uya0526design/not-did-you-use-ai-but-are-you-the-one-driving-reflections-on-building-a-real-product-through-464m)

On to Phase 2

Next, following the Phase 2 plan in the README, I'll tackle accuracy (script matching via edit distance), displaying the recognized text on screen, and tempo stability, history, and UI polish. Adding "meaningful pause (ma)" detection to the stagnation rate, and stabilizing Haiku's output (settling the improvement focus in code), remain research items (neither is listed as an individual Phase 2 task yet).

Wrapping Up

This was my record of building a "read-aloud coaching app" with AmiVoice and generative AI. Three takeaways:

Exploiting AmiVoice's timestamps fully gave the app a depth that a plain "STT → Claude hand-off" doesn't have.
A two-stage design — code does the math, Haiku only does the wording — kept the small model on the job it's best at.
I kept the first-hand findings I only learned by verifying (the cache that didn't work, the prompt that wasn't obeyed, the AI's wrong attribution) honestly intact.

The detailed development log lives in the repository's LEARNING_LOG.

📦 https://github.com/uya0526-design/reading-speed-meter

This article is part of my public learning journey using AI tools (Claude / Cursor). The design, tech selection, and evaluation-algorithm decisions are mine, and the code is verified with Vitest. I collaborate with AI on the article's structure, outline, and draft prose, and I review and revise every line before publishing.

Building a Weight Tracker CLI in Python — Type Hints, Pure Functions, and pytest

Uya — Fri, 12 Jun 2026 12:56:39 +0000

Introduction

This is my eighth article as a Java engineer learning TypeScript and Python from scratch.

My first seven articles were all small TypeScript CLIs. In the previous one, I built an HTTP client in TypeScript that calls a FastAPI (Python) server I wrote myself — that was my first contact with Python (FastAPI), but only as "the thing the client calls."

In other words, Python played a supporting role last time. From here, I start Python properly from "project 1." For this first one I go back to the basics: a weight tracker CLI.

What I focused on this time:

Python basics (# comments, def, snake_case, f-strings)
Type hints (list[float], tuple[float, float, float]) and how they differ from Java Generics
Input validation with try / except ValueError
Extracting the calculation logic as a "pure function" (separation of concerns, testability)
Unit testing with pytest (normal, boundary, and error cases)
The habits an ex-Java engineer slips into — and correcting them

As always, I write honestly about where I got stuck, what I thought through, and what I asked AI for.

📝 Where this sits in the series

This is the first article in my Python series. It's also a chance to check whether the mindset I picked up in the TypeScript series — "think in types," "separate logic from I/O," "write tests" — still works when the language changes.

My Learning Style (AI Transparency)

💡 Learning companions & how this article is written

I use Claude Pro (design discussions and Q&A) and Cursor Pro (coding support) as learning companions. Beyond the code, I also collaborate with AI on writing this article itself. Stating the facts plainly here.

Division of roles:

Tech selection, design, implementation, and code verification → me

Article structure, outline, draft prose, and translation → in collaboration with Claude

All content is checked and revised by me before publishing → me

My guiding principle is "the thinking is mine, the wording is AI-assisted, and I verify all of it." I write the code myself (I never ask AI to write code for me), I use AI for hints, spec clarification, and bug spotting, and I make sure I understand why before moving on — and I apply that same stance to the writing process.

In this article, I continue to clearly separate "what I implemented myself" from "what I asked AI for."

What I Built

Enter a menu number, and the CLI records a weight, lists recorded weights, or computes statistics (average, max, min).

--------------------------------
1. Record weight
2. Display the recorded weights
3. Display the weight calculation result
4. Exit
--------------------------------
Enter your choice: 1
Enter your weight(kg): 70.5
--------------------------------
Enter your choice: 3
Weight calculation result:
Average weight: 70.5
Max weight: 70.5
Min weight: 70.5

Data is held in memory and resets when you exit (a deliberate simplification for local learning). I'm saving persistence for the next stage.

📦 Repository: https://github.com/uya0526-design/weight_tracker_py

File Structure and Tech Stack

The structure is very simple.

weight_tracker_py/
├── tests/
│   ├── __init__.py
│   └── test_main.py     # unit tests
├── main.py              # entry point
└── requirements.txt     # dependencies

Tech stack:

Python 3.12
pytest 9.0.3

The flow from creating a virtual environment (venv) to running tests:

python -m venv venv               # project-local isolated environment
.\venv\Scripts\Activate.ps1       # activate (Windows PowerShell)
pip install pytest                # install the test tool
pip freeze > requirements.txt     # record dependencies
python main.py                    # run the app
pytest                            # run the tests

I understood venv as "per-project isolation," close to a Maven local repository or Node's node_modules.

What I Implemented Myself

main.py — The menu loop and function split

I run the menu with while True + if / elif, dispatching to a function per choice, and break on 4 to exit.

def main() -> None:
    while True:
        choice = display_main_menu()
        if choice == "1":
            record_weight()
        elif choice == "2":
            display_recorded_weights()
        elif choice == "3":
            display_weight_calculation_result()
        elif choice == "4":
            break
        else:
            print("Invalid choice")

if __name__ == "__main__":
    main()

I understood if __name__ == "__main__": as a declaration of "this is the program's entry point," close to Java's public static void main(String[] args). It doesn't run when imported — only when the file is run directly.

Input validation — try / except ValueError

The weight is read as a string, so I check whether it can be converted to a number.

def record_weight() -> None:
    weight = input("Enter your weight(kg): ")
    # Check if the weight is a number
    try:
        weight = float(weight)
    except ValueError:
        print("Invalid weight")
        return
    recorded_weights.append(weight)

At first I tried to judge "is this a number?" with isdigit() and got stuck (more below). Structurally this is almost the same as Java's try-catch: a string that can't be converted by float() raises ValueError (close to Java's NumberFormatException).

Listing — enumerate and an empty-list check

I used enumerate to list items with numbers.

def display_recorded_weights() -> None:
    print("Recorded weights: ")
    if len(recorded_weights) == 0:
        print("No weights recorded")
        return
    for index, weight in enumerate(recorded_weights):
        print(f"{index + 1}. {weight}")

enumerate is a loop that gives you the index and the element at once, letting me write what I used to write as for (int i = 0; i < list.size(); i++) in Java much more cleanly. I wanted the display to start at 1, so I print index + 1.

Statistics — extracting a pure function (my biggest lesson this time)

This was the design highlight of the project. At first I bundled display and calculation into one function, but I extracted just the calculation logic as a "pure function that takes arguments and only returns values."

# display side (reads the global list → hard to test)
def display_weight_calculation_result() -> None:
    print("Weight calculation result: ")
    if len(recorded_weights) == 0:
        print("No weights recorded")
        return
    average_weight, max_weight, min_weight = calculate_weight_calculation_result(recorded_weights)
    print(f"Average weight: {average_weight}")
    print(f"Max weight: {max_weight}")
    print(f"Min weight: {min_weight}")

# calculation side (takes arguments, only returns values → easy to test)
def calculate_weight_calculation_result(weights: list[float]) -> tuple[float, float, float]:
    average_weight = round(sum(weights) / len(weights), 2)
    max_weight = max(weights)
    min_weight = min(weights)
    return average_weight, max_weight, min_weight

Two points here.

1. Don't read the global variable directly — take it as an argument

The display_... side reads the module-level recorded_weights. That depends on the result of input(), which makes it hard to test. The calculate_... side takes weights as an argument, so a test can pass any list it likes. This is separation of concerns — the same idea I kept coming back to in the TypeScript series, and it worked just as well in Python.

2. Return multiple values as a tuple

return average_weight, max_weight, min_weight returns three values at once. The caller can unpack them with a, b, c = .... In Java, "multiple return values" meant a dedicated class or an array, so writing it with plain syntax felt fresh.

The return type hint -> tuple[float, float, float] feels close to Generics like List<Float> in Java. The big difference is that it's not enforced at runtime (returning a value that doesn't match the type isn't an error), so I understood it as information for the reader and the IDE.

tests/test_main.py — normal, boundary, and error cases

Because I'd extracted a pure function, the tests were very straightforward to write.

import pytest
from main import calculate_weight_calculation_result

# normal: multiple items
def test_calculate_weight_calculation_result():
    weights = [70.12345, 75, 80, 85, 90]
    average_weight, max_weight, min_weight = calculate_weight_calculation_result(weights)
    assert average_weight == 80.02
    assert max_weight == 90.0
    assert min_weight == 70.12345

# error: empty list → division by zero
def test_calculate_weight_calculation_result_empty_list():
    with pytest.raises(ZeroDivisionError):
        calculate_weight_calculation_result([])

# boundary: a single item
def test_calculate_weight_calculation_result_one_weight():
    weights = [70.12345]
    average_weight, max_weight, min_weight = calculate_weight_calculation_result(weights)
    assert average_weight == 70.12
    assert max_weight == 70.12345
    assert min_weight == 70.12345

pytest.raises(ZeroDivisionError) corresponds to Java's assertThrows(ArithmeticException.class, ...). It's interesting that "this should throw an exception" can be written as a test too.

What I Asked AI For

Topic	What AI helped with
Spec clarification	Surfacing unclear points: input validation, display format, how to exit, menu design
Comment syntax	Pointing out that Python uses `#`, not `//`
Validation	Pointing out that `isdigit()` can't handle decimals
Conversion handling	Pointing out I was appending the raw string, and that double-converting with `float()` was unnecessary
Design suggestion	Suggesting I pass the global variable as an argument, for testability
Type hints	Pointing out a mismatch between `-> None` and `-> list[float]`
Testing	The `pytest.raises` syntax, and the ideal folder structure
Dependencies	Explaining `requirements.txt` (direct deps only vs. pinning everything)
README	Tidying it up in both Japanese and English

Note: I found and fixed the wrong test expectation (below) myself.

Where I Got Stuck

1. I wrote comments with `//`

Situation: I wrote a comment with // and it wouldn't run.

Root cause: A Java / TypeScript habit. Python comments use #.

Fix: Changed them all to #.

Takeaway: When the language changes, the first differences show up in the tiniest syntax. A small thing, but it reliably reminds me "you're writing a different language now."

2. `isdigit()` can't reject decimals

Situation: I used "70.5".isdigit() for input validation, and a valid weight got rejected.

Root cause: isdigit() returns True only when every character is a digit. A decimal point . makes it False, so a value like 70.5 doesn't pass.

Fix: I dropped the character-type check and switched to trying a float() conversion, catching failures with try / except ValueError.

# NG: a decimal point makes it False → rejects a valid weight
if weight.isdigit():
    ...

# OK: try to convert, reject on failure
try:
    weight = float(weight)
except ValueError:
    print("Invalid weight")
    return

Takeaway: If you want to know "can this be used as a number?", actually trying to convert it is more reliable than inspecting character types. I learned to pick the check that fits the goal.

3. ZeroDivisionError on an empty list

Situation: Computing the average with zero recorded weights crashed the program.

Root cause: In sum(weights) / len(weights), len became 0, causing a division by zero (ZeroDivisionError).

Fix and design decision: I added an early return if len(recorded_weights) == 0 on the display side, returning "No weights recorded" to the user. On the other hand, I deliberately left the calculation function (calculate_...) to raise ZeroDivisionError as-is, and verified that with a test.

Takeaway: "Where to prevent an error" and "where to let an exception through" are separate decisions. I block early near the UI, while letting the pure function raise naturally and pinning that behavior with a test.

4. Can't import main.py from tests/

Situation: from main import ... in tests/test_main.py raised ModuleNotFoundError.

Root cause: tests/ wasn't recognized as a package, so the import couldn't be resolved.

Fix: Adding tests/__init__.py (an empty file) resolved it.

Takeaway: Folder structure is part of "the spec for making things run." Tracking down the cause myself was a small confidence boost.

5. My test expectation was wrong

Situation: A test failed. The assert for average_weight didn't match.

Root cause: It wasn't the implementation — my own expected value was wrong. I'd written the round() result from my head without actually computing it.

Fix: The average of [70.12345, 75, 80, 85, 90] is 400.12345 / 5 = 80.02469, and round(..., 2) makes it 80.02. I recomputed it by hand and corrected the expectation.

Takeaway: "A failing test" doesn't always mean "the implementation is wrong." Catching a wrong expectation is also part of a test's value. Experiencing the real-world cycle in miniature — a test fails, then you separate whether the cause is the implementation or the expectation — was my biggest gain this time.

What I Learned

Python basics (mapped to Java)

Topic	Key takeaway
Comments	Use `#` (`//` is Java / JavaScript)
Function definition	`def name():` (corresponds to Java's `static void`)
Naming	snake_case `record_weight` (vs. Java's camelCase)
Multiple return values	`return a, b, c` returns a tuple (Java needs a dedicated class or array)
String formatting	f-strings (`f"{variable}"`)

Type hints

You can annotate arguments and return values (list[float], tuple[float, float, float])
Feels close to Java Generics (List<Float>)
But it's not enforced at runtime — it's information for readability and IDE support

Exception handling

try / except has the same structure as Java's try-catch
A string that float() can't convert raises ValueError (close to Java's NumberFormatException)

Testability (separation of concerns)

Functions containing input() or print() are hard to test
Extracting the calculation logic as a pure function that takes arguments and returns values makes it testable
This is exactly the "separation of concerns" that matters in real work

Unit testing (pytest)

Topic	Key takeaway
Position	`pytest` corresponds to Java's `JUnit`
Exception tests	`with pytest.raises(...)` corresponds to `assertThrows(...)`
Coverage	Covering normal, boundary, and error cases is the baseline
Value	When a test fails, it can also reveal a wrong expectation

Project structure

Putting __init__.py in tests/ resolves pytest's import
requirements.txt can list "direct deps only" or "pin everything." When reproducibility matters, list everything

Reflection

I built this the same way as before: write the code myself and have AI review it. As my first Python project, three things stood out.

The habit of thinking in types carried straight over: The "think in types first" I repeated in the TypeScript series came naturally with Python's type hints. There's the difference that they're not enforced at runtime, but understanding the goal — "write them for the reader and the IDE" — was a real gain.

Separation of concerns transcends the language: Extracting the calculation logic as a pure function made the tests surprisingly easy to write. "Separate I/O from logic" works the same way in TypeScript and in Python.

The experience of a test failing is itself a lesson: Recomputing and fixing my own expectation taught me that "a test isn't just a tool for doubting the implementation." Separating whether a failure comes from the implementation or the expectation was the most satisfying part.

The ex-Java habits (// comments, isdigit()) did surface, but I corrected them along with the reasons, so I should be able to leave them behind for the next Python project.

Wrapping Up

This was my record of building a weight tracker CLI in Python, centered on type hints, pure functions, and pytest — my first article in the Python series.

Continuous progress from the TypeScript series:

Picked up Python basics while staying aware of the differences from Java (#, def, snake_case, tuple multiple returns)
Wrote type hints while understanding that they're not enforced at runtime
Extracted the calculation logic as a pure function, practicing separation of concerns in Python too
Covered normal, boundary, and error cases with pytest
Found and fixed a wrong test expectation myself, experiencing the same cycle as real work

Next, I want to move into persistence with file saving and JSON, and graduate from this project's "data disappears when you exit" simplification.

The full learning log is in the repository:

weight_tracker_py / LEARNING_LOG.md

Building an HTTP Client CLI for Your Own API with TypeScript — FastAPI, POST, and Error Handling

Uya — Sun, 07 Jun 2026 13:32:28 +0000

Introduction

This is my seventh article as a Java engineer learning TypeScript from scratch.

In my previous article, I built a CLI that calls an external weather API (Open-Meteo) with fetch, and learned about async/await, response type definitions, and error handling with response.ok. But that was "read-only (GET)" against "someone else's API." This time I go a step further: I build the API server myself and then build an HTTP client that calls it.

Backend: a REST API server built with FastAPI (Python)
Client: a TypeScript CLI that calls that API

What I focused on this time:

Implementing GET and POST with fetch (previously GET only)
The Content-Type: application/json header on POST (a 422 error I fixed myself)
How where you place try-catch changes behavior (continue vs. exit)
The difference between return and throw error (close to Java's throws)
Narrowing the unknown type with error instanceof Error
FastAPI basics (Spring-like decorators, BaseModel, HTTPException)

Same as always — I write honestly about where I got stuck, what I thought through, and what I asked AI for.

📝 Scope of this article

This article centers on the TypeScript client. The Python (FastAPI) side is introduced compactly, as "the thing the client calls."

My Learning Style (AI Transparency)

💡 Learning companions

I use Claude Pro (design discussions and Q&A) and Cursor Pro (coding support) as learning companions.

My rules:

I write all the code myself — I never ask AI to write code for me

AI helps with hints, spec clarification, and bug spotting

I make sure I understand why something works before moving on

In this article, I clearly separate "what I implemented myself" from "what I asked AI for."

What I Built

Pick a menu option in the CLI, and it gets a list of items, gets an item by ID, or adds an item — all against my own API server.

Custom API Call CLI tool
================================
1. Get all items
2. Get item by ID
3. Add an item
4. Exit
================================
Choose: 1
[
  { id: 1, name: 'apple', price: 100 },
  { id: 2, name: 'banana', price: 200 },
  { id: 3, name: 'cherry', price: 300 }
]

Data is held in memory on the server, so it resets when the server restarts (a deliberate simplification for local learning).

📦 Repositories

Client (TypeScript): https://github.com/uya0526-design/simple_api_ts
Server (Python / FastAPI): https://github.com/uya0526-design/simple_api_py

System Overview

This project is split across two repositories. The roles are simply "server and client."

[ TypeScript CLI ]  --- HTTP (fetch) --->  [ FastAPI server ]
  simple_api_ts                              simple_api_py
  - GET  /items                              - holds items in memory
  - GET  /items/{id}                         - accepts GET / POST
  - POST /items                              - returns 404 via HTTPException

The endpoint spec:

Method	Path	Description
GET	`/items`	Returns all items
GET	`/items/{id}`	Returns one item (404 if not found)
POST	`/items`	Adds an item (id auto-assigned by the server)

Backend: FastAPI Server (Python)

First I need something to call. This was my first time touching FastAPI, but to an ex-Java engineer's eyes it looked remarkably close to a Spring Boot controller.

Setup

python -m venv venv               # project-local isolated environment
.\venv\Scripts\Activate.ps1       # activate (Windows PowerShell)
pip install fastapi uvicorn       # install packages
pip freeze > requirements.txt     # record dependencies
uvicorn main:app --reload         # start the dev server

I understood venv as "per-project isolation," close to a Maven local repository or Node's node_modules, and uvicorn main:app --reload as the dev server equivalent of TypeScript's ts-node.

Implementing the endpoints

Routes are defined in main.py. The decorator feel is just like Spring.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

# internal / response use (has id)
class Item(BaseModel):
    id: int
    name: str
    price: int

# request-receiving use (no id — auto-assigned by server)
class ItemCreate(BaseModel):
    name: str
    price: int

items = [
    Item(id=1, name="apple", price=100),
    Item(id=2, name="banana", price=200),
    Item(id=3, name="cherry", price=300),
]

@app.get("/items")
def get_items():
    return items

@app.get("/items/{item_id}")
def get_item(item_id: int):
    for item in items:
        if item.id == item_id:
            return item
    raise HTTPException(status_code=404, detail="Item not found")

@app.post("/items")
def create_item(item: ItemCreate):
    new_id = len(items) + 1
    new_item = Item(id=new_id, name=item.name, price=item.price)
    items.append(new_item)
    return new_item

Splitting RequestDTO and ResponseDTO

The main design decision was separating the receiving type (ItemCreate) from the internal/return type (Item).

ItemCreate: only name and price. No id (the client shouldn't send it)
Item: includes id. The server assigns it

Avoiding "id can go in either one" and making each type's responsibility clear — I realized this is the same idea as separating RequestDTO and ResponseDTO in Java.

Java mapping (FastAPI to Spring)

FastAPI / Python	Equivalent Java concept
`@app.get("/items")`	`@GetMapping("/items")`
`@app.post("/items")`	`@PostMapping("/items")`
`{item_id}` path parameter	`@PathVariable`
`BaseModel`	DTO class
`item: ItemCreate` (typed argument)	`@RequestBody`
`HTTPException`	`ResponseStatusException`
`raise`	`throw`
`len(items)`	`.size()`
`uvicorn main:app --reload`	`ts-node`
`/docs` (auto Swagger UI)	manual setup like SpringFox

The biggest surprise was that just visiting /docs auto-generates a Swagger UI — coming from setting that up by hand, that felt like magic.

That's the server done. Now for the main event: the TypeScript client.

Client: TypeScript CLI

types.ts — Mirror the server's types

The client types mirror the server's DTOs. Dropping id from ItemCreate follows the same reasoning.

export interface Item {
  id: number;
  name: string;
  price: number;
}

export interface ItemCreate {
  // no id — the server auto-assigns it
  name: string;
  price: number;
}

📝 An interface closes with }, not };

At first I wrote the end of the interface as };. The correct form is } (watch the difference from a class or a function expression). The trailing ; on properties works with or without it, but by TypeScript convention it's common to include it.

api.ts — GET and POST with fetch

Previously I only did GET; this time I add POST too.

import { Item, ItemCreate } from "./types";

const API_ENDPOINT = "http://localhost:8000";

export async function getItems(): Promise<Item[]> {
  const response = await fetch(`${API_ENDPOINT}/items`);
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  return await response.json();
}

export async function getItemById(id: number): Promise<Item> {
  const response = await fetch(`${API_ENDPOINT}/items/${id}`);
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  return await response.json();
}

export async function createItem(inputItem: ItemCreate): Promise<Item> {
  const response = await fetch(`${API_ENDPOINT}/items`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(inputItem),
  });
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  return await response.json();
}

Two things I improved from AI feedback.

1. Collect the base URL into a constant

At first I hardcoded "http://localhost:8000" in all three functions. I pulled it into a single const API_ENDPOINT to make changes easier.

2. The POST body is fine as JSON.stringify(inputItem)

At first I expanded the fields: JSON.stringify({ name: inputItem.name, price: inputItem.price }). But since inputItem is the ItemCreate type and is guaranteed to hold only name and price, JSON.stringify(inputItem) is enough. The type makes the code shorter — a nice example.

index.ts — Interactive menu and input validation

I wrap readline in a Promise and run a menu loop with while (true) + switch (an application of what I built up in previous projects).

const id = await askQuestion("Enter ID: ");
if (isNaN(parseInt(id))) {
  console.log("Please enter a number");
  continue;
}

The important part here is where to place try-catch (more below). In "get item by ID" (case "2"), the CLI was exiting entirely when the server returned 404, so I added try-catch inside the case to keep the loop going.

case "2": {
  const id = await askQuestion("Enter ID: ");
  if (isNaN(parseInt(id))) {
    console.log("Please enter a number");
    break;
  }
  try {
    const item = await getItemById(parseInt(id));
    console.log(item);
  } catch (error) {
    if (error instanceof Error && error.message.includes("404")) {
      console.log("Item not found");
    } else {
      console.error(error);
      throw error; // delegate unexpected errors to main().catch()
    }
  }
  break;
}

api.test.ts — Mocking fetch (success and failure)

Seven tests total. I reuse jest.spyOn(global, "fetch") from last time. This time, for the failure case, I used mockRejectedValue to reproduce fetch itself failing.

test("throws when the API returns an error", async () => {
  jest.spyOn(global, "fetch").mockRejectedValue(new Error("network error"));
  await expect(getItems()).rejects.toThrow();
});

afterEach(() => {
  jest.restoreAllMocks();
});

For the add (POST) test, I compared the count (length) before and after to confirm exactly one item was added.

 PASS  src/__tests__/api.test.ts

Test Suites: 1 passed, 1 total
Tests:       7 passed, 7 total
Time:        0.248 s

💡 Unit vs. integration tests

Tests that complete with mocks are "unit tests"; tests that need the actual FastAPI server running are "integration tests." Right now they share a single describe block, but as things grow, splitting them into unit/ and integration/ folders makes them easier to manage.

What I Asked AI For

Topic	What AI helped with
Spec clarification	Surfacing missing and unclear requirements
Design suggestion (Python)	Explaining why to split `ItemCreate` and `Item`
Concept explanation (Python)	Explaining `venv`, `pip`, `uvicorn`, `HTTPException` vs Java/TS
404 exit bug	Caught that `case "2"` had no try-catch, so errors reached `main().catch()` and exited
Error message branching	Suggested `error.message.includes("404")` to show "not found"
return vs throw	Suggested re-throwing with `throw error` instead of `return` on unexpected errors
Base URL collection	Suggested pulling the three hardcoded URLs into an `API_ENDPOINT` constant
Body simplification	Suggested simplifying to `JSON.stringify(inputItem)`
interface syntax	Caught the trailing `};` that should be `}`

Note: I found and fixed the 422 error (below) myself.

Where I Got Stuck

1. A 422 error on POST (the Content-Type header)

Situation: When adding an item (POST), the server returned 422 (Unprocessable Entity).

Root cause: My fetch POST didn't set the Content-Type: application/json header. Without it, FastAPI can't interpret the request body as JSON and returns 422.

// ❌ no header — the body can't be read as JSON → 422
await fetch(`${API_ENDPOINT}/items`, {
  method: "POST",
  body: JSON.stringify(inputItem),
});

// ✅ declare the Content-Type
await fetch(`${API_ENDPOINT}/items`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(inputItem),
});

Takeaway: I reached the cause on my own. A server and a client only agree to "exchange JSON" once that's declared via the header. I never thought about this while writing GET-only code.

2. The CLI exits entirely on a 404

Situation: Entering a non-existent ID exited the CLI with no error message at all.

Root cause: The exception thrown by getItemById wasn't caught inside the switch and propagated all the way to main().catch(). Since main().catch() is the last line of defense that ends the program, the loop couldn't resume and the CLI fell over.

// ❌ no catch in the case → the exception reaches main().catch() and exits
case "2": {
  const item = await getItemById(parseInt(id)); // 404 throws → loop breaks → exit
  console.log(item);
  break;
}

I added try-catch inside case "2", showing "Item not found" for 404 and continuing the loop (code shown earlier).

Takeaway: Where you catch a thrown error decides whether the program continues or exits. The same exception leads to a different user experience depending on where you place the catch.

3. The difference between `return` and `throw error`

Situation: On unexpected errors, I first exited main with return. That quietly ended the program normally, and I couldn't tell what had happened.

Root cause and fix: return just ends main normally. Logging with console.error(error) and then re-throwing with throw error lets it reach main().catch() and end with process.exit(1) (abnormal exit).

// normal exit. no error detail remains
return;

// abnormal exit. delegate to main().catch() → process.exit(1)
console.error(error);
throw error;

Takeaway: This felt close to delegating an exception upward with Java's throws. Choosing deliberately between "swallow it" and "throw it up" matters.

What I Learned

async/await and fetch (GET / POST)

POST specifies method, headers, and body. The body is stringified with JSON.stringify(...)
Sending JSON to FastAPI requires Content-Type: application/json (without it, 422)
For both GET and POST, you detect errors yourself with !response.ok and throw

Error handling

Topic	Key Takeaway
try-catch placement	Where you catch decides whether the program continues or exits
`error instanceof Error`	A caught `error` is `unknown`. Narrow the type before using `.message`
`return` vs `throw error`	`return` exits normally. `throw error` delegates to `main().catch()` for an abnormal exit. Close to Java's `throws`

Letting types simplify code

Since the ItemCreate type is guaranteed to hold only name and price, JSON.stringify(inputItem) sends it as-is. No need to expand the fields by hand

FastAPI / Python (first contact)

Topic	Key Takeaway
Decorators	`@app.get` / `@app.post` correspond to Spring's `@GetMapping` / `@PostMapping`
`BaseModel`	Defines request/response data structures. Equivalent to a Java DTO
`HTTPException`	An exception with a status code. Equivalent to `ResponseStatusException`
RequestDTO/ResponseDTO split	`ItemCreate` (no id) and `Item` (with id) separate the responsibilities
`/docs`	Just visiting it auto-generates a Swagger UI

Test design

Tests that complete with mocks are unit tests; those needing a running server are integration tests
A POST test can confirm the add by comparing the count (length) before and after

Reflection

I built this the same way as before: write the code myself and have AI review it. The big difference from last time was that I built the "other side" of the API myself.

Three things stood out:

A server and a client are connected by a "contract": The 422 error came down to declaring "this is JSON" via the Content-Type header before FastAPI would understand it. Building both sides myself made that boundary agreement tangible.

Exceptions are a design choice about "where to catch": The 404-exit incident showed me that try-catch placement directly shapes the user experience. The return vs throw error distinction also clicked, connecting back to my memory of Java's throws.

FastAPI looked like Spring: Decorators, DTOs, exception classes, auto-docs. It was rewarding to feel my past Java experience working as a foundation even in a new language.

Wrapping Up

This was my record of building a self-made FastAPI server and a TypeScript HTTP client CLI that calls it.

Progress since the previous projects:

Implemented not just GET but POST with fetch (Content-Type, body)
Found and fixed the cause of a 422 error myself
Understood that try-catch placement changes behavior, and made a CLI that doesn't fall over on 404
Used return and throw error deliberately
Built the server side with FastAPI too, understanding both ends of the API

Building both ends of an API once gave me both perspectives — "the server as seen from the client" and "the client as seen from the server." Next, I want to build on this setup and move toward more practical data operations and persistence.

Full learning logs are in each repository:

This article is part of my public learning journey using AI tools (Claude Pro / Cursor Pro). All code is written by me — AI is used for design discussions, bug hints, and spec clarification only.

Building a Weather API CLI with TypeScript — async/await, fetch, and Response Types

Uya — Sat, 06 Jun 2026 01:32:45 +0000

Introduction

This is my sixth article as a Java engineer learning TypeScript from scratch.

In my previous article, I built a Quiz CLI and learned about enum, tuple types, and mocking an entire module with jest.mock(). This time, I built a Weather API CLI and focused on:

Calling an external API asynchronously with async/await and fetch
Describing an API response with type definitions (type to model the JSON shape)
HTTP error handling with response.ok
Extracting object key types with keyof typeof
Swapping out fetch with jest.spyOn(global, "fetch")
Verifying structure and type at once with toMatchObject + expect.any()

Same as always — I write honestly about where I got stuck, what I thought through, and what I asked AI for.

My Learning Style (AI Transparency)

💡 Learning companions

I use Claude Pro (design discussions and Q&A) and Cursor Pro (coding support) as learning companions.

My rules:

I write all the code myself — I never ask AI to write code for me

AI helps with hints, spec clarification, and bug spotting

I make sure I understand why something works before moving on

In this article, I clearly separate "what I implemented myself" from "what I asked AI for."

What I Built

A CLI weather tool. Pick a city, or enter a latitude and longitude, and it shows the current weather, temperature, humidity, and wind speed.

Weather API Call CLI
================================================
1. Select a city and run
2. Enter latitude and longitude and run
3. Exit
Choose: 1
1. Sapporo
2. Sendai
3. Tokyo
4. Nagoya
5. Osaka
6. Fukuoka
7. Kagoshima
8. Naha
Choose a city: 3
Tokyo weather: Partly cloudy
Tokyo temperature: 20.4°C
Tokyo humidity: 80%
Tokyo wind speed: 3.1km/h
================================================

Weather data comes from the free Open-Meteo API (no API key required).

📦 Repository: https://github.com/uya0526-design/weather_api

Project Structure

weather_api/
├── src/
│   ├── index.ts             # Entry point / CLI menu
│   ├── api.ts               # API call logic
│   ├── types.ts             # Type definitions
│   └── __tests__/
│       └── api.test.ts      # Unit tests
├── jest.config.js
├── tsconfig.json
└── package.json

Same three-layer structure as the previous projects: types.ts (types) / api.ts (logic) / index.ts (UI). New this time: communicating with an external API is the main event.

Tech Stack

TypeScript
Node.js (readline and fetch)
Jest + ts-jest (unit testing)
Open-Meteo API (weather data)

What I Implemented Myself

types.ts — API Response Types

The heart of the type design this time was how to express an API response as a type.

First, define the "city data"

I defined the list of selectable cities and their latitude, longitude, and timezone.

// List of selectable cities
export const cityList = [
  "Sapporo", "Sendai", "Tokyo", "Nagoya",
  "Osaka", "Fukuoka", "Kagoshima", "Naha",
];

// Latitude / longitude / timezone per city
export const cityCoordinates = {
  "Tokyo": {
    latitude: 35.68123,
    longitude: 139.76712,
    timezone: "Asia/Tokyo",
  },
  // ...
};

The quietly useful tool here is keyof typeof. It lets me pull out just the keys of cityCoordinates (the city names) as a type.

type CityName = keyof typeof cityCoordinates;
// becomes a union type: "Sapporo" | "Sendai" | "Tokyo" | ...

In Java I'd define the cities as an enum. In TypeScript I can reuse the keys of an object that already exists directly as a type — that felt fresh.

Define the API response type

This was the main challenge. I called the API first, checked the actual response JSON, and modeled that shape directly with type.

export type WeatherResponse = {
  latitude: number;
  longitude: number;
  timezone: string;
  timezone_abbreviation: string;
  current_units: {
    temperature_2m: string;
    relative_humidity_2m: string;
    weather_code: string;
    wind_speed_10m: string;
  };
  current: {
    time: string;
    interval: number;
    temperature_2m: number;
    relative_humidity_2m: number;
    weather_code: number;
    wind_speed_10m: number;
  };
};

⚠️ A type that didn't match reality

At first I defined temperature_2m and the other fields inside current as string. Looking at the actual API response, they're numbers, so number is correct — and AI caught this for me (more below). A wrong type definition leads to runtime errors, so I felt firsthand how important it is to check the type against the real response.

Convert weather codes to text

Open-Meteo returns WMO (World Meteorological Organization) weather codes as numbers. I defined a mapping to convert them to readable text.

export const WeatherCode = {
  0: { name: "Clear" },
  1: { name: "Mainly clear" },
  2: { name: "Partly cloudy" },
  3: { name: "Cloudy" },
  45: { name: "Fog" },
  // ...
  95: { name: "Thunderstorm" },
};

📝 I first tried writing this as an enum

I originally went for enum, but I decided on my own that a "code → text" mapping reads more naturally as a const object than as an enum. An enum is "a named set of constants," while an object is "a key-to-value mapping" — the difference in purpose started to feel intuitive.

At this point I had written the keys as the string "0", which didn't line up with the numeric weather_code from the API, so I fixed them to the numeric key 0 (also an AI catch).

api.ts — Async API Calls with fetch

The getWeather function takes a latitude, longitude, and timezone, and calls the API.

export async function getWeather(
  latitude: number,
  longitude: number,
  timezone: string | undefined,
): Promise<WeatherResponse> {
  const params = new URLSearchParams({
    latitude: String(latitude),
    longitude: String(longitude),
    current: "temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m",
  });
  if (timezone) {
    params.append("timezone", timezone);
  }

  const url = `https://api.open-meteo.com/v1/forecast?${params.toString()}`;
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return await response.json();
}

Two key points.

1. Detect HTTP errors with response.ok

fetch does not throw on HTTP errors like 404 or 500 — response.ok just becomes false (this differs from how some Java HTTP clients behave). So I have to check if (!response.ok) myself and throw.

2. Branch when timezone is undefined

In the flow where you enter latitude/longitude directly, there may be no timezone, so I branch to leave it out of the query in that case.

index.ts — Wrapping readline in a Promise

I adopted the async/await wrapping I learned in the previous Quiz project, from the start this time.

function askQuestion(prompt: string): Promise<string> {
  return new Promise((resolve) => {
    rl.question(prompt, (answer) => {
      resolve(answer);
    });
  });
}

This lets me write await askQuestion(...) top-to-bottom inside the while (true) menu loop.

In the latitude/longitude input flow, I added validation with isNaN and a range check.

const lat = Number(await askQuestion("Enter latitude: "));
if (isNaN(lat) || lat < -90 || lat > 90) {
  console.log("Latitude must be a number between -90 and 90");
  continue;
}

The weather code is converted to text by looking it up in WeatherCode.

const code = weather.current.weather_code;
const weatherName = WeatherCode[code as keyof typeof WeatherCode]?.name ?? "Unknown";

And rather than hardcoding the units, I pull them from the API response's current_units (another point improved from an AI catch).

console.log(`${city} temperature: ${weather.current.temperature_2m}${weather.current_units.temperature_2m}`);
console.log(`${city} wind speed: ${weather.current.wind_speed_10m}${weather.current_units.wind_speed_10m}`);

Finally, main().catch() catches any unexpected errors in one place.

api.test.ts — Mocking fetch

The highlight of testing this project was mocking fetch.

Success case: hit the real API and check

test("can fetch the weather for Tokyo", async () => {
  const result = await getWeather(35.68, 139.76, "Asia/Tokyo");
  expect(result).toMatchObject({
    latitude: expect.any(Number),
    longitude: expect.any(Number),
    current: {
      temperature_2m: expect.any(Number),
      weather_code: expect.any(Number),
    },
  });
});

Using toMatchObject + expect.any(Number) verifies not just that a field exists, but that its type matches — all at once. I first wrote this with toBeDefined() only, but that would pass even if the type was off, so I improved it.

Failure case: swap fetch for a mock

I can't conveniently produce a broken API for the error path, so I swap fetch for a mock.

test("throws when the API returns an error", async () => {
  jest.spyOn(global, "fetch").mockResolvedValue({
    ok: false,
    status: 500,
  } as Response);

  await expect(getWeather(35.68, 139.76, "Asia/Tokyo")).rejects.toThrow("API error");
});

afterEach(() => {
  jest.restoreAllMocks();
});

Last time, fs couldn't be patched with jest.spyOn and needed jest.mock(), but global.fetch can be swapped with jest.spyOn(global, "fetch"). The lesson from last time — that which approach works depends on the target's property descriptor (configurable) — carried over directly.

💡 Cleanup belongs in afterEach

I first wrote jest.restoreAllMocks() inside the test body, but if the test fails it never reaches that line and the mock stays in place. I moved it into afterEach so cleanup runs whether the test passes or fails.

Test results:

 PASS  src/__tests__/api.test.ts

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Time:        1.216 s

What I Asked AI For

Topic	What AI helped with
Spec clarification	Identified unclear and missing requirements up front
Type fix	Caught numeric fields inside `current` typed as `string`
Hardcoded units	Suggested reading units from `current_units` instead of fixing them to m/s
Weather code key mismatch	Caught string key "0" not matching the numeric `weather_code`
Unused import removal	Removed `WeatherResponse` that wasn't used in `index.ts`
Test type verification	Improved from `toBeDefined()` to `toMatchObject` + `expect.any()`
Mock cleanup	Suggested moving `restoreAllMocks()` into `afterEach`
Peer dependency check	Showed how to use `npm info` with `peerDependencies` to check a package

Where I Got Stuck

1. I typed numeric response fields as string

Situation: Inside current on WeatherResponse, I defined temperature_2m and others as string.

Root cause: Looking at the actual API response, temperature, humidity, weather code, and wind speed are all numbers. The units (°C, %, etc.) live separately in current_units as strings — I was conflating the two.

// ❌ a number, but defined as string
current: {
  temperature_2m: string;
};

// ✅ numbers are number
current: {
  temperature_2m: number;
};

Takeaway: Check type definitions against the real API response. Deciding "this feels string-ish" leads to a runtime mismatch — an obvious lesson I learned the hard way.

2. I hardcoded the units

Situation: I wrote the wind speed unit as "m/s" directly in the code.

Root cause: Open-Meteo actually returns wind speed in km/h. Hardcoding it would make the display a lie. And since the API returns the units in a current_units field, using that is the right answer.

// ❌ unit fixed in code
console.log(`wind speed: ${weather.current.wind_speed_10m}m/s`);

// ✅ use the unit the API returns
console.log(`wind speed: ${weather.current.wind_speed_10m}${weather.current_units.wind_speed_10m}`);

Takeaway: Don't hardcode units or config values — pulling them from the data source is more resilient to spec changes. I aligned temperature and humidity to the same approach.

3. The weather code keys didn't match because they were strings

Situation: I wrote the WeatherCode keys as the strings "0" and "1".

Root cause: The API's weather_code comes back as a number. When looking it up with WeatherCode[weather_code], the keys need to be defined as numbers or the lookup won't work as intended.

// ❌ string keys
export const WeatherCode = {
  "0": { name: "Clear" },
};

// ✅ numeric keys (match the numeric weather_code from the API)
export const WeatherCode = {
  0: { name: "Clear" },
};

Takeaway: Match "the key type" to "the type you look it up with." Object keys can look similar but are different things as numbers vs. strings — a good reminder.

4. AI's suggestions aren't always correct

This was less a sticking point and more a turning point in how I learn.

During development, AI flagged that "the combination of jest ^30 and ts-jest ^29 may have a version mismatch." Rather than taking it at face value, I checked it myself with npm info.

npm info ts-jest peerDependencies
# result: jest: '^29.0.0 || ^30.0.0'

ts-jest supports both jest 29 and 30, so in reality there was no problem.

Takeaway: AI suggestions are just hints. When I can confirm a fact with a command, I confirm it myself. I want to build the habit of "verify and then decide" rather than "fix it because AI said so."

(Side note: npm install brings each package to its latest version independently, so combined versions can drift. But npm installs them anyway without erroring, which makes it easy to miss — learning that I can check ahead of time by running npm info against a package's peerDependencies was a real gain.)

What I Learned

async/await and fetch

Writing await fetch(url) inside an async function lets you write async code top-to-bottom, sequentially
fetch does not throw on HTTP errors — you check response.ok yourself
response.json() extracts the response body as JSON
Some Java HTTP clients throw depending on the status code, so this needed a mental shift

TypeScript Types

Topic	Key Takeaway
Response type definition	You can model each JSON field with `type`. Choosing `number` vs `string` matters
`keyof typeof`	Extracts an existing object's keys as a type. I auto-generated a union of city names
Numeric vs string keys	Object keys differ as numbers vs strings. Match them to the lookup type

Jest Mocking

Topic	Key Takeaway
`jest.spyOn(global, "fetch")`	Swaps the global `fetch` for a mock
`mockResolvedValue`	Creates a mock that returns a Promise (for mocking async functions)
`rejects.toThrow()`	Verifies that an async operation throws
`toMatchObject` + `expect.any()`	Verifies structure and type at once — stricter than `toBeDefined()`
Cleanup in `afterEach`	Mocks reliably reset even when a test fails. Equivalent to Java's `@AfterEach`

Design

Don't hardcode units and config values — pulling them from the data source is more resilient to spec changes
Remove unused imports (readability and maintainability)
Tests should be written with "what am I verifying" in mind, not just "does it run"
Verify AI's suggestions with commands — don't take them at face value

Reflection

I built this with the same style as before: write the code myself and have AI review it.

Three things stood out:

Check type definitions against the real response: Mixing up string and number was a mistake the actual JSON would have prevented. "Look at the real thing, then write the type" is more reliable than "imagine the type first."

A sense for avoiding hardcoding: Pulling units from the API made me pause the next time I felt the urge to hardcode a value.

Use AI, but confirm it yourself in the end: Verifying the version-mismatch flag with npm info myself was my biggest gain this time. AI is convenient, but I want to keep the initiative on fact-checking.

Wrapping Up

This was my record of building an external API tool (a weather CLI) as a TypeScript beginner.

Progress since the previous projects:

Called an external API asynchronously with async/await and fetch
Modeled the API response structure accurately with type (choosing number/string)
Used keyof typeof to leverage object keys as a type
Mocked fetch with jest.spyOn(global, "fetch")
Built the habit of verifying AI's suggestions myself with npm info

Next up: a simple HTTP client that calls my own API (FastAPI), going deeper on async/await and type definitions.

Full learning log: LEARNING_LOG.md

This article is part of my public learning journey using AI tools (Claude Pro / Cursor Pro). All code is written by me — AI is used for design discussions, bug hints, and spec clarification only.

Self-Host Your GitHub Stats Badge on Vercel — Fixing the 'Broken Image' on Your Profile README

Uya — Thu, 04 Jun 2026 12:42:49 +0000

🌐 This is the English version of an article I originally wrote in Japanese on Zenn. The original is linked as the canonical source.

Introduction

You've probably seen that "GitHub Stats" card (github-readme-stats) on a lot of profile READMEs. Ever pasted it in, only to get a broken image? I have.

I touched on this problem in my previous article, but the fix — self-hosting — has enough steps that I split it into its own post.

💡 The background (why it breaks in the first place) is covered in the previous article. Worth reading alongside this one.
👉 I Built a GitHub Profile README — the 'It Won't Show Up' Traps and Tips to Stand Out

In this article, I'll walk through how to self-host github-readme-stats on your own Vercel account so it renders reliably, along with the points that are easy to trip over.

Why self-hosting is needed

The official instance of github-readme-stats (github-readme-stats.vercel.app) is shared by many users. Because of that, it easily hits the free-tier API limits, and during busy periods the image won't render (it returns 503 SERVICE_UNAVAILABLE / DEPLOYMENT_PAUSED).

This isn't a problem on your side — it's a known issue that happens intermittently due to the shared service. If you self-host, you get your own dedicated instance, so you no longer depend on someone else's quota and it renders reliably.

💡 Assume that badges depending on external services will go down someday. For the important ones, self-hosting is the most reassuring option in the end.

Background terms

Before the steps, here's a quick rundown of the terms that come up.

Term	Description
Vercel	A cloud deploy / hosting platform for frontend apps
Hobby plan	The free plan for personal, non-commercial use. Fine for portfolio purposes
Serverless function	A function that runs only on request instead of a server running constantly. Vercel uses this to generate the image dynamically
Environment variable	A config value passed in safely from outside instead of hard-coded. Here it holds the GitHub API token
Fork	Copying someone else's GitHub repository into your own account

Steps

The overall flow is six steps: register on Vercel → fork the repo → get a token → deploy → check the URL → embed in your README.

1. Create a Vercel account

Go to https://vercel.com/signup
Choose "Continue with GitHub" to link your GitHub account
For the plan, choose "Hobby"
If asked for phone verification, enter it in international format (for Japan, choose +81 and drop the leading 0)

Gotcha: the "The user could not be found" error

Even with a correctly entered phone number, you may get this error. It seems to be a known issue on Vercel's side.

Fix: Submit the form at https://vercel.com/accountrecovery to contact support. Example for the "Additional Details" field:

I tried to sign up via GitHub and was asked to verify my phone number. I entered my mobile number but received the error message "The user could not be found." I have tried re-entering the number multiple times but the issue persists. This is a new account and the phone number has not been used with any other Vercel account.

2. Fork the repository

Go to https://github.com/anuraghazra/github-readme-stats
Click the "Fork" button at the top right
Confirm it's been forked into your own GitHub account

3. Get a GitHub Personal Access Token

This is needed so github-readme-stats can call the GitHub API.

Go to https://github.com/settings/tokens
Click "Generate new token" → "Generate new token (classic)"
Settings:
- Note: anything (e.g. vercel-readme-stats)
- Expiration: No expiration (or any period you like)
- Select scopes: check public_repo (use repo if you also want to count private repositories)
Click "Generate token"
Copy and save the token shown (the string starting with ghp_)

⚠️ Security note: The token is only shown once — once you close this screen it's gone, so be sure to save it. Also, never write the token directly in your code or README; pass it only as a Vercel environment variable in the next step, and don't leak it.

4. Deploy to Vercel

Go to https://vercel.com/new
From the Import Git Repository list, select github-readme-stats and click "Import"
Open the "Environment Variables" section and add the following:

| Key | Value |
| :--- | :--- |
| PAT_1 | The token from step 3 (the string starting with ghp_) |

Leave the other settings at their defaults and click "Deploy"
When the "Congratulations!" screen appears, the deployment is done

5. Check the deploy URL

Back on the dashboard, two kinds of URL are shown. The one you use is the fixed URL, so be careful not to mix them up.

URL	Use
The URL in the Domains field (e.g. `github-readme-stats-xxx-yyy.vercel.app`)	The fixed production URL. Use this one
The long URL in the Deployment field (e.g. `github-readme-stats-aabbccddee-xxx.vercel.app`)	A temporary URL that changes per deploy. Don't use it

To verify, open the following in a browser; if the Stats card appears, you're good.

https://[your Domains URL]/api?username=[your GitHub username]

6. Embed it in your README

Add the following to your profile README.md, using your own Domains URL.

![GitHub Stats](https://[your Domains URL]/api?username=[username]&show_icons=true&hide_border=true&count_private=true)
![Top Languages](https://[your Domains URL]/api/top-langs/?username=[username]&layout=compact&hide_border=true)

Now the Stats card renders from your own dedicated instance, unaffected by the congestion on the official one.

Common customization options

You can tweak the look and what's counted via URL query parameters. Here are the ones I use most.

Option	What it does	Example
`&theme=`	Theme color	`radical`, `dark`, `tokyonight`, `merko`
`&show_icons=true`	Show icons	—
`&hide_border=true`	Hide the border	—
`&count_private=true`	Also count private repositories	—
`&hide=`	Hide specific items	`&hide=issues,contribs`
`&layout=compact`	Compact layout for the language card	for top-langs

Hobby plan limits and caveats

For this use case (just showing it on your own README), traffic is extremely low, so the Hobby plan is plenty. Still, keep these in mind:

Serverless function execution limit: 10 seconds (it could rarely time out if the GitHub API is slow to respond, but in practice it's almost never an issue)
Bandwidth: 100 GB/month (nowhere near reachable for personal use)
No commercial use (ads, paid services, etc. require the Pro plan)

Wrap-up

The broken-image problem with github-readme-stats is usually caused by "the official instance being paused" — not a mistake on your side. Even so, putting something that might go down at any time on the face of your profile is unsettling, so I recommend self-hosting to get your own dedicated instance.

To recap the steps:

Register on Vercel (Hobby plan is enough)
Fork github-readme-stats
Get a GitHub Personal Access Token (public_repo)
Put the token in the PAT_1 environment variable and Deploy
Note the fixed Domains URL
Swap your README's image URL for your own Domains URL

Six steps in total. Once you've done it, it just keeps working reliably.

You can see my card in action on my profile 👉 github.com/uya0526-design

Thanks for reading.

References

I Built a GitHub Profile README — the 'It Won't Show Up' Traps and Tips to Stand Out

Uya — Thu, 04 Jun 2026 12:21:49 +0000

🌐 This is the English version of an article I originally wrote in Japanese on Zenn. The original is linked as the canonical source.

Introduction

I usually write "I built a small CLI tool in TypeScript / Python" style posts. This time it's a bit different: a write-up about building my GitHub profile README.

I'm an engineer who spent 15+ years mostly on legacy Java, and I'm now learning TypeScript and Python on my own, publishing what I learn on Zenn and dev.to. Once I had a decent number of learning projects piling up, I decided it was time to build "the face of my GitHub."

Here's the conclusion up front:

Writing the README itself is not hard. You just line up Markdown and badges.
But I kept getting stuck on "it doesn't show up on my profile."
And there was a second trap: the GitHub Stats badge was broken and wouldn't render.

This post focuses on the points that are surprisingly easy to miss if you only read the official docs, using my own profile as a concrete example.

Here's the finished result 👉 github.com/uya0526-design

💡 I'm writing this for people building a profile README for the first time. If you've written repository READMEs before but never the profile one, this should be about the right level.

What is a profile README, anyway?

GitHub has two kinds of README, and it's easy to confuse them at first. Let me separate them clearly.

Type	Where it lives	Where it shows up	Role
Repository README	`README.md` inside each repo	Top of that repository	Explaining the project and how to use it
Profile README	`README.md` inside a repo named exactly like your username	Top of your profile page (`github.com/username`)	Self-introduction and the "face" of your portfolio

The key point: the profile README differs from the repository README you normally write, both in where it lives and what it's for.

The essentials of making one

The mechanism is simple. You create a repository whose name exactly matches your username, and put a README.md at its root.

Username uya0526-design → repository uya0526-design/uya0526-design
GitHub treats this repo as a "special repository"
Put README.md at the root
Make the repository Public

In theory it should now show up... and this is where I fell into the swamp.

Trap 1: the README doesn't show up

I wrote the README, pushed it, and nothing appeared on my profile. I burned a fair amount of time in this state. Let me share the final cause and a checklist for narrowing it down.

The real cause: I hadn't pressed the "Share to profile" button

This was the actual culprit in my case.

Just creating the special repository does not always auto-publish it to your profile
There's a "Share to profile" button on the repository page, and only after pressing it does the README appear on your profile
The button is subtle, and I completely missed it

✅ Takeaway: When your README won't show up even after you wrote and pushed it, first look for the "Share to profile" button on the repository page. In my case, this one action got me out of the swamp.

Checklist for when it won't show up

That said, this isn't the only possible cause. There are several easy-to-miss points. Checking them top to bottom is efficient.

Does the repository name match your username exactly?
- Watch out for mixing up hyphen - and underscore _
- Match case as well
Is the repository Public? (Private repos won't show up)
Is README.md at the root? (It won't be picked up from a subfolder)
Does the README have content? (An empty file won't show)
Is the README at the root of the default branch?
- The profile README only references the README on the "default branch"
- If you created it locally on master, pushed, and added main afterward, the default branch and the branch holding the README can end up out of sync
- Check under Settings → General → Default branch
Did you press "Share to profile"? ← my actual cause
Propagation delay / cache
- There can be a lag right after pushing. Wait a bit, or hard reload (Ctrl + Shift + R)

Number 5 is an especially easy trap for people who used master by local habit. Maybe a classic "ex-SE" mistake.

A tip for checking: view it while logged out

This one helped in a quiet but real way.

Open github.com/username in incognito / InPrivate mode
When you're logged in, the editing UI takes priority and the appearance can differ, so checking "how others see it" while logged out is the reliable way
When it's correctly reflected, the README appears large, above your Pinned repositories
- In other words, if Pinned is at the very top, the README hasn't been reflected yet

Trap 2: the GitHub Stats badge is broken

You know that "GitHub Stats" card (github-readme-stats) you often see on profile READMEs? When I pasted it in, the image turned into a broken-image icon.

The cause: the official instance was paused

When I opened the image URL directly in a browser, it returned 503 SERVICE_UNAVAILABLE / DEPLOYMENT_PAUSED.

This means the official deployment (on a free Vercel tier) is temporarily paused due to congestion or limits
Since it's a service shared by many users, this is a known issue that happens intermittently
It's not a problem on your side

In other words, my README was fine — the shared service I was riding on happened to be down.

The fix: self-host on your own Vercel

If it's a temporary outage you can just wait, but I wasn't comfortable putting something that might go down again on the "face" of my profile. So I decided to self-host on my own Vercel account. That removes the dependency on someone else's quota.

Here are just the key steps (the official repository README has the details).

Create a Vercel account (the free Hobby plan is enough for personal use)
Fork github-readme-stats to your own account
Get a GitHub Personal Access Token (classic, with the public_repo scope)
Import it into Vercel, set the token as the environment variable PAT_1, and Deploy
Note the fixed Domains URL that gets issued (not the temporary URL that changes per deploy)
Replace the image URL in your README, swapping the official instance for your own Domains URL

After swapping, the embed looks like this (replace the URL part with your own):

![GitHub Stats](https://[your Domains URL]/api?username=[username]&show_icons=true&hide_border=true&count_private=true)
![Top Languages](https://[your Domains URL]/api/top-langs/?username=[username]&layout=compact&hide_border=true)

⚠️ Security note: A Personal Access Token is shown only once — copy it before you close the screen. Never write the token directly in your code or README; pass it only as a Vercel environment variable, and don't leak it.

If you get stuck signing up for Vercel (phone verification error): When signing up via GitHub, phone verification can fail with "The user could not be found" (this seems to be a known Vercel issue). If that happens, use the form at Vercel Account Recovery to explain the situation and contact support.

You can see my self-hosted card working in the "GitHub Stats" section near the bottom of my profile.

📝 This self-hosting procedure turned out to be enough material for its own article. I plan to split out the detailed steps (with screenshots) into a separate post.

💡 Lesson: Assume that badges depending on external services will go down someday. Self-host the important ones, or place them where it isn't fatal if they break.

What to highlight: from a reskilling ex-engineer's view

Beyond just "making a working README," the real question is what you communicate to the reader (recruiters, collaborators, peers). My position is "15+ years of real experience, but modern tech is still ahead of me," so I focused on showing that honestly and attractively.

What I included

In my actual profile, I structured it roughly in this order:

Header (one-line catch + badges): years of experience, key certifications, and what I'm learning, at a glance
About Me: which domains I've worked in and for how long, plus where I am now (reskilling)
How I Learn: less abstract self-PR, more "how I actually move my hands"
Certifications: a table with dates (high credibility, easy to read)
Tech Stack: badges split into "professional experience" and "currently learning"
Featured Projects: link + tech used + what I practiced, as a set
Writing: links to Zenn / dev.to
GitHub Stats: the self-hosted version above

Ways of thinking that work for self-promotion

Four things I paid special attention to:

Concrete > abstract. "Lots of Java experience" is weaker than "15 years of enterprise Java in telecom, logistics, and finance." Specific industry names add credibility.
Separate real experience from what you're learning, honestly. Categorizing accurately without exaggeration actually builds trust. That's why I split my Tech Stack into "Professional experience" and "Currently learning & building."
Show how you learn. In my case I wrote about the process itself: "I don't let AI write my code — I implement first, then have AI review," "I design my own tests," "I don't take AI's suggestions at face value — I verify them with actual commands." Showing the process is itself a statement about your attitude as an engineer.
Stack up "finished and published" wins, however small. A pile of small projects with tests, a README, and a learning log is plain but strong.

A small trick for going bilingual

Assuming some global readers, I wrote mainly in English while folding a Japanese version into a collapsible block. That keeps an English-first layout while still being readable for Japanese speakers.

<details>
<summary>Japanese profile (click to expand)</summary>

(Japanese body goes here)

</details>

📝 GitHub READMEs support some HTML (like collapsible blocks and centered text), but behavior can vary by environment. Always check the actual rendering after publishing.

Wrap-up: a checklist for next time

Finally, a checklist for my future self (and for you, if you read this far).

[ ] Created a repository with the same name as your username (exact match)
[ ] Made it Public
[ ] Put README.md at the root of the default branch
[ ] Pressed the "Share to profile" button
[ ] Opened github.com/username in incognito mode to verify
[ ] Checked that external badges (Stats, etc.) render (self-host if not)
[ ] Wrote "real experience" and "currently learning" separately and accurately
[ ] Made the content convey your learning process and consistency

A profile README isn't something you make once and forget — it's a place to keep showing your growth. I'll keep updating Featured Projects and "Next up" as projects accumulate.

Here's the finished profile 👉 github.com/uya0526-design

Thanks for reading. I hope it helps anyone else stuck in the "it won't show up" swamp.

DEV Community: Uya

Building a Countdown Timer CLI in Python — time, finally, mock, and Testing Exceptions

Introduction

My Learning Style (AI Transparency)

What I Built

File Structure and Tech Stack

What I Implemented Myself

timer.py — A reverse loop and time.sleep to step one second at a time

timer.py — Overwriting the same line with \r

timer.py — Designing a "process that may stop partway" with try / except / finally

main.py — The menu loop and catching ValueError

tests/test_timer.py — How to test a "waiting" process and exceptions

What I Asked AI For

Where I Got Stuck

1. Mocked it, but no exception fires — the patch target was wrong

2. "An error occurred: Exception" makes the assertion fail — the empty-message trap

What I Learned

Python syntax and standard library

Testing knowledge

Design and debugging thinking

Reflection

Wrapping Up

Building a Password Generator CLI in Python — string, random, any, and Testing Randomness

Introduction

My Learning Style (AI Transparency)

What I Built

File Structure and Tech Stack

What I Implemented Myself

password.py — Building a character pool and picking randomly

password.py — Extracting validation logic into independent functions

password.py — Listing, and the start argument of enumerate

main.py — The menu loop and input validation

main.py — Showing the warning just once with remind_flag

tests/test_password.py — How to test randomness

What I Asked AI For

Where I Got Stuck

1. AttributeError: 'str' object has no attribute 'get_digits'

2. ModuleNotFoundError — pytest can't find the module

What I Learned

Python knowledge

Testing knowledge

Design thinking

Reflection

Wrapping Up

Not 'Did You Use AI' but 'Are You the One Driving' — Reflections on Building a Real Product Through AI Collaboration

Where This Sits

I Switched Styles

The Reframe: Not "Did You Use AI" but "Are You the One Driving"

A Collection of Stumbles — Where Collaboration Got Stuck

① I got AmiVoice's auth method wrong

② The mapper returned empty (result vs results)

③ I rejected 0 as falsy

④ The prompt cache wasn't working

⑤ Haiku mentioned punctuation that wasn't in the input

The Thread Through the Stumbles: "A Passing Test ≠ Behaving as Intended"

The Most Important Thing Was the "Rejection"

A "Pattern" for Collaboration Took Shape

Wrapping Up

I Went Looking for the Basis of 'N Characters Per Minute Is Fast' — There Wasn't One. Setting Read-Aloud Thresholds Honestly

Where This Sits

Why Obsess Over the "Basis"?

Speed Thresholds: No Academic Threshold → Draw From General Rules of Thumb

What I found

The basis I adopted: the announcer standard

Thresholds (adopted version)

Writing about it honestly in the article and UI

Stagnation-Rate Thresholds: There Isn't Even a "Ruler"

Even less basis than speed

Accepting it as an "in-house metric"

The basis for putting "0% on the good side" is cultural context

The Two Metrics Had Different Kinds of Basis

What I Decided Myself / What I Asked AI For

Wrapping Up

Main references

Don't Let Claude Haiku Do the Math — A Two-Stage Read-Aloud Coach Design, and the Prompt Swamp

Where This Sits

Why Not Let Haiku Do the "Math"?

The Finalized Prompt

API Implementation: system / messages / cache_control

How to think about max_tokens

timer.py — Overwriting the same line with `\r`

2. `"An error occurred: Exception"` makes the assertion fail — the empty-message trap

② The mapper returned empty (`result` vs `results`)

③ I rejected `0` as falsy

API Implementation: `system` / `messages` / `cache_control`

How to think about `max_tokens`

Trap ① — Auth is the `u` field, not a header

Trap ② — The audio `a` goes last

Trap ③ — WebM/Opus passes through as-is (`c` can be omitted)

1. I wrote comments with `//`

2. `isdigit()` can't reject decimals