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

Source: Dev.to

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);   //  Rokuyo, rekichu (auspicious days), kanshi, solar term, all in one response
curl https://shirabe.dev/api/v1/calendar/2026-04-15

Enter fullscreen mode


Exit fullscreen mode

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."
}

Enter fullscreen mode


Exit fullscreen mode

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 ..."

Enter fullscreen mode


Exit fullscreen mode

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"])

Enter fullscreen mode


Exit fullscreen mode

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"

Enter fullscreen mode


Exit fullscreen mode

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

Enter fullscreen mode


Exit fullscreen mode

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.

Links

• Shirabe Calendar API (official)

• OpenAPI 3.1 spec (bilingual descriptions)

• Rokuyo API guide

• Rekichu (auspicious days) API guide

• GitHub repository

Japanese original: 六曜APIを自前実装するな (Qiita)