ziwei-doushu casts charts in the browser and hands the AI endpoints back to you
Open-source Zi Wei Dou Shu (Purple Star Astrology) chart-calculation engine based on Ni Haixia's Tianji system, with a complete charting algorithm, the Four Transformations system, a pattern knowledge base and original classical-text data.
At a glance
- What is it?
- ziwei-doushu is an MIT licensed TypeScript chart casting engine for Zi Wei Dou Shu, built on the Ni Haixia Tianji system, with configurable leap month and late hour rules, a 518,400 chart sample set under CC BY 4.0, and no backend routes for AI interpretation.
- Who is it for?
- ziwei-doushu fits developers who want the casting logic itself, in TypeScript, with the disputed rules left as switches rather than settled in code. It does not fit anyone who wants AI interpretation out of the box.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Renhuai123/ziwei-doushu18,330 ★ · +14,145
| Repository | 2026-09-21 | 2026-11-15 |
|---|---|---|
| Renhuai123/ziwei-doushu | 4.2k | 18.3k |
14,145 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The chart is cast in your browser, the AI parts are stubs
Chart casting, chart display and combined chart casting all run in the browser against the engine in this repository, and none of them needs an API key. The open source version ships no backend routes at all. What is missing is the AI interpretation endpoint /api/interpret and the combined chart AI analysis endpoint /api/heming, and both places say so in the interface rather than failing quietly. Setting an API key does not change that. The sample environment file is explicit that those variables only matter after you implement the routes yourself, which is the situation issue #30 is about. That split makes the repository usable as a self contained chart engine and leaves the parts that cost money per call to whoever deploys it. The sample file also carries a provider setting and a provider key pair for any OpenAI compatible service, plus a public site URL, which became configurable in the 2026-10-03 round.
birthInfo.hour is a branch index, and the filenames repeat the trap
Every sample stores birthInfo.hour as an index from 0 to 11 naming the double hour branch, where 0 is the zi hour and 11 is the hai hour, and not as an hour of the day. The clock range for index 0 is 23 to 1, and the range for index 11 is 21 to 23, with the other ten branches in between. The filename repeats the convention: YYYY-MM-DD-hHH-gender.json, where h11 means the hai hour and not 11 in the morning. Two boundary rules come with it. A birth between 23:00 and 23:59, the late zi hour, is charted as the next day with index 0, while a birth between 00:00 and 00:59, the early zi hour, stays on the same day and also takes index 0. This misreading was not hypothetical. famous.ts held 11 celebrity sample charts and 7 of them carried hour comments that did not match the hour index. The comments were corrected, a regression was added to hold them, and one of the test files now guards the index boundary.
2,520 of the samples carry a date that never happened
The dataset takes days 1 to 30 in every month, which suits the calendar and fails on two February days. 105 date combinations do not exist: February 30, plus February 29 in each non-leap year. Multiplied by 12 hours and 2 genders that is 2,520 samples, or 0.49 percent of the set. The v3 engine did not raise an error on them, it rolled them forward into March 1 and March 2, so those files duplicate the samples for those two days. The filter is spelled out: drop month = 2 with day = 30, and drop month = 2 with day = 29 in a year that is not a leap year. The engine changed on 2026-10-03 and now rejects a non-existent Gregorian date outright, and the v4.0 dataset released on 2026-10-15 contains only real dates. The 2,520 files are still inside the v3 archives, so any record count taken from v3 has to apply that filter first.
Where schools disagree, the engine offers a switch instead of a verdict
Several rules in this system have more than one accepted answer, and the engine keeps each of them configurable rather than settling the argument in code. A leap month can be assigned to the month before, the month after, split by day, or kept in its own month. The late zi hour day change can be switched too. Star brightness runs seven levels, from temple and prosperous down to no and fallen, with three coarse levels kept alongside for display fallback, and the brightness school itself is a switch, because different schools, including different Wenmo versions, disagree about auxiliary stars. The twelve shensha start from the birth year branch in the natal layer and from the annual branch in the annual layer. True solar time correction uses longitude difference plus the equation of time from cities.ts, so a birth far east or west does not drift by a whole double hour, and Chinese daylight saving time between 1986 and 1991 is detected but never deducted automatically; clock-adjust.ts converts a clock reading to standard time as a separate step.
Eight test files cover 768 charts under one npm test
The test script is a single command that chains seventeen files through tsx, among them pan integrity, Chinese daylight saving time, clock adjustment, the lichun solar term boundary, hongluan and tianxi, famous hour consistency, the iztro time index boundary, date existence, gender validation, natal double four transformation in the same palace and leap policy validation. Type checking is a separate tsc pass with noEmit. The same pair runs in GitHub Actions on every push and every pull request through .github/workflows/ci.yml. The date matters here: before the 2026-09-21 round this repository had no tests at all. That round arrived after three months of quiet in pull request 28, touching 26 files with 2736 insertions and 108 deletions, growing algorithm.ts from 181 lines to 641 and adding eight modules totalling 1367 lines. The issue backlog went from 18 down to 4.
The sample set is three volumes, a checksum file and one cat command
The v3 sample release holds 518,400 charts covering 60 years times 12 months times 30 days times 12 hours times 2 genders, 5.5 GB in total. It arrives as three volumes named ziwei-samples-v3-part1.zip.001 at 1.9 GB, part2 at 1.9 GB and part3 at 1.8 GB, alongside SHA256SUMS.txt, and the volumes have to be concatenated before they can be opened:
# macOS / Linux
cat ziwei-samples-v3-part*.zip.* > combined.zip
unzip combined.zip
# Windows (PowerShell)
Get-Content ziwei-samples-v3-part*.zip.* -Encoding Byte -ReadCount 0 | Set-Content combined.zip -Encoding Byte
Expand-Archive combined.zipEach sample carries the chart JSON plus interpretation text on 13 topics, among them an overall chart reading, wealth, career, relationships and health. The charts were generated by the v3 engine together with the statement library as it stood at the time, and the online engine keeps moving, so newer output can differ from what is archived. Every sample fixes longitude at 120 degrees east, with no per city true solar time correction applied, and birth dates run from 1924 to 1983, one full sexagenary cycle. The stated uses are fine tuning a small model on the 518,000 input and output pairs, a retrieval source for chat, an A and B baseline after editing patterns.ts, and research.
Commercial use is allowed, attribution is the only condition
The data licence is CC BY 4.0 while the code is MIT, and the terms are short: commercial products, SaaS and paid apps, model fine tuning whether the model is open or closed, redistribution and derived datasets, academic work, technical blogs and teaching courses are all permitted, with no payment, no application and no prior notice. One requirement survives all of that. Any use has to keep the attribution naming the dataset as the open source Zi Wei Dou Shu sample dataset v3.0 with its 518,400 record count, the source URL and the author name, and the terms say where that line may live: one line on an About page or in a footer, the Training Data field of a model card or dataset card, the references or acknowledgements of a paper, or the README and metadata of a dataset you redistribute. The complete text sits in DATASET-LICENSE at the repository root.
Dependencies fell from 483 to 185 while Next.js moved to 16
The package is private, named ziwei-master and versioned 0.1.0, and its scripts are the Next.js set of dev, build and start, plus the typecheck and test commands. The runtime list includes iztro, lunar-javascript, the Anthropic SDK, Next.js at ^16.4.3, React at 19.2.5, framer-motion, html2canvas, pg, ioredis and two Vercel analytics packages, while the development side is tsx, TypeScript 5, Tailwind 3.4 and PostCSS. pg, ioredis and the Anthropic SDK are still listed even though the open version ships no server routes. The 2026-10-03 round removed two deployment packages nothing used, the vercel CLI and @cloudflare/next-on-pages, taking the dependency count from 483 down to 185, and then moved to Next.js 16 to close a postcss vulnerability, which cleared 51 GitHub security alerts. That round also committed package-lock.json, added an English README, a contribution guide, a code of conduct and issue and pull request templates, and merged an outside contribution that validates the hour index.
Editorial conclusion
ziwei-doushu fits developers who want the casting logic itself, in TypeScript, with the disputed rules left as switches rather than settled in code. It does not fit anyone who wants AI interpretation out of the box. The v3 samples need a date filter before counting records, while the v4.0 dataset released on 2026-10-15 contains only real dates. Before you build on it, read the hour index convention, apply the February date filter to the v3 samples, and decide whether the statement library differences between the archive and the current engine matter for your use.
Frequently asked questions
What does the ziwei-doushu repository actually ship?
A TypeScript chart casting engine under lib/ziwei together with a Next.js 16 demo interface, code licensed MIT. Chart casting, chart display and combined chart casting all run in the browser using the repository engine and need no API key, while the AI interpretation routes are not part of the open source version.
How many samples are in the ziwei-doushu v3 dataset?
518,400 charts covering 60 years times 12 months times 30 days times 12 hours times 2 genders, 5.5 GB split across three compressed volumes plus a SHA256SUMS.txt file. Each sample holds chart JSON and interpretation text on 13 topics, and about 2,520 of them carry a non-existent February date.
Can I use the ziwei-doushu sample data in a commercial product?
Yes. The data licence covers commercial products, SaaS, paid apps, fine tuning open or closed models, redistribution, derived datasets, research, blogs and courses, with no payment, application or prior notice. The single condition is keeping the attribution that names the dataset, its version, the 518,400 count and the source URL.
Why does ziwei-doushu need no API key for chart casting?
Because the open source version has no backend API routes, so casting, chart display and combined chart casting happen in the browser. Only the AI interpretation at /api/interpret and the combined chart AI analysis at /api/heming need endpoints you implement yourself, and configuring an API key alone does not make them work.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/renhuai123-ziwei-doushu)Star history chart for your README
[](https://hysenlabs.com/projects/renhuai123-ziwei-doushu)Was this useful?