Stop hand-coding the Japanese Rokuyo calendar: LLM-generated lunar logic silently breaks

Shirabe Dev — Sat, 06 Jun 2026 01:37:13 +0000

Originally published in Japanese on Qiita. This is the English edition.

TL;DR

Business requirements that touch the Japanese Rokuyo calendar are surging in the LLM era — wedding-date pickers, moving-day scorers, fortune-telling chatbots.
But if you compute Rokuyo yourself, you get a class of bug that silently miscalculates on specific dates.
The root cause is not the Rokuyo formula. It's the step before it: converting the Gregorian date to the Japanese lunar calendar requires astronomical precision.
The fix is to put an AI-agent-oriented Japanese calendar API in front of it (e.g. Shirabe Calendar API). It's 3 lines of curl / fetch / requests.

What is Rokuyo, briefly

Rokuyo (六曜) is a six-day cycle (Taian / Tomobiki / Sensho / Senbu / Butsumetsu / Shakko) still used across Japan to decide auspicious dates — weddings, funerals, ground-breakings, store openings. If you build anything for the Japanese market that recommends or scores dates, you will eventually need it. It looks trivial. It is not.

Who this is for

Full-stack engineers building LLM agents / AI SaaS.
Anyone who once thought "Rokuyo? I can just write that myself."
Anyone who has shipped LLM-generated date logic to production.

The problem: what happens when you ask an AI to "compute Rokuyo"

Ask a coding assistant for "a function that tells me whether a given date is Taian" and you'll usually get something shaped like this:

// The "naive Rokuyo" an LLM tends to propose
function getRokuyo(gregorianDate: Date): string {
  // (1) Convert Gregorian -> lunar (year / month / day)
  const lunar = convertToLunar(gregorianDate);   // <- this is where accidents live

  // (2) Rokuyo = (lunar month + lunar day) mod 6
  const index = (lunar.month + lunar.day) % 6;
  return ["Taian", "Shakko", "Sensho", "Tomobiki", "Senbu", "Butsumetsu"][index];
}

Step (2) is genuinely correct — that mapping is right. The bug is always in (1), convertToLunar.

The usual ways `convertToLunar` is written (all wrong)

Counting days from the last new moon using a 29.5-day period. The synodic month actually varies between 29.27 and 29.84 days. Even using the mean 29.5306, run it for a year and you drift by days.
Embedding some lunar-conversion table found online. Past the table's terminal year it silently drifts, and leap-month handling differs table to table.
Reusing a Chinese-lunar (农历) library like lunar-javascript. Japan's Tenpō calendar and the Chinese calendar differ in the reference timezone for the new moon (UTC+8 vs UTC+9) and in leap-month placement — so a few dates per year diverge.
A 30–50 line formula the LLM wrote. The solar/lunar ecliptic-longitude approximation is sloppy by one digit somewhere, and dates landing on the new-moon day boundary come out one day off.

Why the drift is scary

It never throws. Types pass, no exception, always returns a Rokuyo-looking string.
Tests miss it. It's wrong on only 2–3 pinpoint days, so sampling tests pass.
You find out on the wedding day. The day you advertised as "Taian" turns out to be "Butsumetsu."

This is the silent-failure class — the most common kind of bug in the era of letting an LLM write the code.

Root cause: lunar conversion needs astronomy

The Rokuyo rule (lunar month + lunar day) mod 6 is deterministic and always correct once the lunar date is right. The hard part is the lunar date. Japan's old calendar (Tenpō) requires:

Compute the instant of the new moon (saku) at 135°E, Japan Standard Time.
The day of the new moon is lunar day 1.
A month that contains no major solar term (chūki) is a leap month.
Leap-month placement changes by year (7 times per ~19 years — the Metonic cycle).

Doing this properly means computing solar and lunar ecliptic longitude at astronomical precision (VSOP87 and friends). Use an approximation and, on days where the new moon falls near midnight, you shift by one day — and every subsequent lunar date that year dominoes by one day.

A widely cited reference implementation is QREKI (by Hideaki Takano): hundreds of lines of AWK computing apparent ecliptic longitudes via series expansion. Hand-porting that is, both in volume and in principle, not the kind of task you should hand to an LLM.

The fix: call a Japanese-calendar API

Drop the self-implementation and hand it to an API designed for AI agents — you win on accuracy, maintenance cost, and ease of AI integration. The examples below use Shirabe Calendar API. The free tier is 10,000 calls/month and you can try it without an API key. The fetch / requests examples below still pass X-API-Key — it's optional, used to track usage and raise limits.

Three lines that work

# One date -> Rokuyo, rekichu (auspicious days), kanshi, solar term, all in one response
curl https://shirabe.dev/api/v1/calendar/2026-04-15

The JSON looks like:

{
  "date": "2026-04-15",
  "rokuyo": {
    "name": "大安",
    "reading": "Taian",
    "timeSlots": { "morning": "good", "noon": "good", "afternoon": "good", "evening": "good" }
  },
  "rekichu": [
    { "name": "一粒万倍日", "type": "auspicious" }
  ],
  "context": {
    "wedding": { "judgment": "excellent", "score": 9,
      "note": "Taian x Ichiryu-manbai-bi. An excellent day for a wedding." }
  },
  "summary": "Reiwa 8 (2026)-04-15 (Wed) Taian / Ichiryu-manbai-bi. Excellent for weddings and openings."
}

The key fields are context and summary. Instead of a bare "Taian" label, you get a per-purpose judgment (8 categories, each scored 1–10) and a one-line summary. An AI agent can drop that summary straight into its answer to the user.

TypeScript

const res = await fetch(
  "https://shirabe.dev/api/v1/calendar/2026-04-15",
  { headers: { "X-API-Key": process.env.SHIRABE_API_KEY! } }
);
const data = await res.json();
console.log(data.rokuyo.name);   // "大安" (Taian)
console.log(data.summary);       // "Reiwa 8 (2026)-04-15 (Wed) Taian ..."

Python

import os, requests

r = requests.get(
    "https://shirabe.dev/api/v1/calendar/2026-04-15",
    headers={"X-API-Key": os.environ["SHIRABE_API_KEY"]},
    timeout=10,
)
print(r.json()["rokuyo"]["name"])

Range queries and best-day search

You're not limited to a single date.

# All Taian/Tomobiki days in April (up to 93 days)
curl "https://shirabe.dev/api/v1/calendar/range?start=2026-04-01&end=2026-04-30&filter_rokuyo=大安,友引"

# Top 5 best wedding days from April to December, by score
curl "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-04-01&end=2026-12-31&limit=5"

best-days is built so an AI agent can externalize the judgment itself. Pass a date range and a purpose (wedding / moving / business and 8 categories total) and you get a ranked list of top-scoring days with the reasoning (e.g. Taian × Tensha-bi).

Integrating with AI agents

Publish an OpenAPI 3.1 spec and this kind of API can be called in one shot from ChatGPT GPTs Actions, Claude tool use, Gemini function calling, LangChain, or LlamaIndex. Shirabe serves it directly at https://shirabe.dev/openapi.yaml.

ChatGPT GPTs Actions

In the GPT Builder, "Create new action" → paste the OpenAPI URL into Import URL:

https://shirabe.dev/openapi.yaml

Choose API Key auth (header name X-API-Key). That's all it takes for a custom GPT to call Shirabe automatically.

LangChain / LlamaIndex / Dify

Feed the same URL to an OpenAPI loader and it's turned into tools. operationId becomes the function name by design, so no glue code is needed.

Self-implementation vs API

Dimension	Self-implementation / LLM-generated code	Japanese calendar API (Shirabe etc.)
Lunar accuracy	Approximations slip by a day at new-moon boundaries	Astronomical precision
Rekichu coverage	Implementing the ~13 auspicious-day types is a separate big job	13+ types out of the box
Per-purpose judgment	Hard to spec and to build	Provided via `context.wedding.score` etc.
Maintenance	Versioning the saku-calculation library, etc.	Zero on the caller side
AI integration	Write your own tool/function definitions	One OpenAPI URL
Initial cost	Looks like zero — but a single wrong-date liability sits behind it	Free tier, 10,000/month

"Free because I built it myself" is only superficially free. Priced with the business risk of a failure, it usually doesn't pay off in this domain.

Wrap-up

The Rokuyo formula itself is easy. The hard part is the lunar conversion before it, which needs astronomical-precision new-moon computation.
Let an LLM write the self-implementation and you get a silent failure that's off by one day exactly on new-moon-boundary dates.
In domains where you find out you were wrong on the day itself — weddings, funerals, moving, contract dates — avoiding self-implementation is the cheaper choice.
Use a Japanese calendar API built for AI agents (OpenAPI published, free tier) and you're done in 3 lines of fetch.

Sample code is also collected under the examples in https://shirabe.dev/openapi.yaml. The same URL works whether you're calling from ChatGPT GPTs Actions, Claude tool use, or Gemini function calling.

DEV Community: Shirabe Dev

Stop hand-coding the Japanese Rokuyo calendar: LLM-generated lunar logic silently breaks

TL;DR

What is Rokuyo, briefly

Who this is for

The problem: what happens when you ask an AI to "compute Rokuyo"

The usual ways `convertToLunar` is written (all wrong)

Why the drift is scary

Root cause: lunar conversion needs astronomy

The fix: call a Japanese-calendar API

Three lines that work

TypeScript

Python

Range queries and best-day search

Integrating with AI agents

ChatGPT GPTs Actions

LangChain / LlamaIndex / Dify

Self-implementation vs API

Wrap-up

Links

DEV Community: Shirabe Dev

Stop hand-coding the Japanese Rokuyo calendar: LLM-generated lunar logic silently breaks

TL;DR

What is Rokuyo, briefly

Who this is for

The problem: what happens when you ask an AI to "compute Rokuyo"

The usual ways convertToLunar is written (all wrong)

Why the drift is scary

Root cause: lunar conversion needs astronomy

The fix: call a Japanese-calendar API

Three lines that work

TypeScript

Python

Range queries and best-day search

Integrating with AI agents

ChatGPT GPTs Actions

LangChain / LlamaIndex / Dify

Self-implementation vs API

Wrap-up

Links

The usual ways `convertToLunar` is written (all wrong)