iztro: a charting library whose Qimen capability lives on someone else's server

The package is the charting library, Qimen is not in it

The readme separates two products that share a name.

The npm package is described as a lightweight Purple Star Astrology charting library, and that is what the source tree contains. It takes a birth date in either the solar or the lunar calendar, a birth time and a gender, and returns chart data.

Alongside it, the project advertises four hosted AI models: two for the astrology system and two for a decision-making system, each with a faster, cheaper variant. Those are reached over an HTTP API with a key, or through an agent SDK.

Then the note that settles it. The npm package remains the open source charting library, those AI models are used through the API and the SDK, and the Qimen capability is not a local Qimen charting module.

So the division is clean and worth stating plainly. Chart computation is local and offline. Decision-making interpretation is a hosted service that calls back into the charting tools. Anyone planning an offline product, or one that must not send birth data to a third party, has to design around that line.

A Qimen session charts from the moment of the request

The hosted decision-making models need a time, and the default is the least reproducible choice available.

By default a Qimen session is set up from the request time. If the user's time zone differs, or if you need a result you can reproduce later, you pass an explicit timestamp with a UTC offset in the message.

That single parameter is the difference between an answer you can log and replay and one that quietly depends on when the request arrived. For anything that goes into a record, the second form is the only one that will still mean the same thing next month.

The same session model applies to the astrology models, which take birth date, birth time, gender and the analysis topic instead, and they can remember the birth information and earlier context across a session.

There is also a field for overriding the system prompt, which the example uses to ask for concise Chinese without heavy terminology and a suggested follow-up direction. That is a per-request instruction rather than a model setting, which means the same hosted model behaves differently depending on what you send it.

One question per session, and the dates are candidates

The Qimen side carries a rule about how to ask, and it is stated as a rule rather than a preference.

One thing, one chart. Unrelated matters should be asked separately.

The reason is structural: the chart is derived from the moment of the question, so a session that mixes a question about a partnership with a question about a launch is reading a single arrangement for two unrelated situations.

The output has a matching shape. You get a conclusion, the main basis for it, the obstacles, and a recommended action, and when the question is about timing the answer includes candidate trigger windows on the real calendar.

And then the caveat, which is worth quoting in substance because it is the difference between a tool and a promise: those dates are trigger candidates derived from a global reading, not a guarantee that a given day will succeed.

The readme's own example question shows what a well-formed request looks like. Two rounds of channel partnership talks have already happened, the revenue split and the launch date are still undecided, and the question is whether to push, keep talking or pause, with a request for the nearest action window and the reasoning.

The CDN files have no version in their path

There are two ways to consume the library, and they resolve to differently named files.

The manifest points the package manager fields at the build output, and points the two CDN fields at one unversioned minified file.

"main": "lib/index.js",
"types": "lib/index.d.ts",
"unpkg": "dist/iztro.min.js",
"jsdelivr": "dist/iztro.min.js"

The readme, for a plain HTML page, recommends the opposite: a versioned file name, brought in with a script tag, and it notes that the build also keeps the unversioned name so existing references keep working.

So a page that follows the CDN field gets whatever the registry currently serves at that path, while a page that follows the readme gets a file it can name. For a library whose output feeds a chart that people make decisions from, that difference matters.

The standalone bundle is a separate download too. The release assets include a tarball containing a minified and obfuscated script with its source map, available from version 2.0.4 onward. The obfuscation is why the source map is part of the same archive.

Releases carry two tag styles and push themselves

The recent tags are three in number, and they do not agree with each other.

The two newest carry a version prefix, one from September 3, 2026 and one from August 15. The third, from March 5, 2026, does not.

So anything that parses the tag list has to handle both forms, and a release script that assumes the prefix will miss one version.

The version scripts in the manifest are worth reading too, because they do the git work themselves. Committing a version runs the formatter and then stages the source directory with an add-all flag. After a version step, the post hook pushes the branch and pushes the tags.

That is a release flow that assumes the working tree is disposable at version time, and it also means a fork has to disable those hooks or a release attempt will push to the fork's configured remote.

The publishing path itself is guarded by a pre-publish hook that runs the tests, the linter and the UMD build, and the prepare hook builds on install from source.

The chainable API is built around one recurring question

Reading the feature list tells you what kind of library this is. Most of the entries are predicates of the same shape.

Is this star present in this palace. Is it present in the three palaces related to it. Does either of those carry a given transformation. Is the star at a particular brightness. What is its opposite palace. What does the given stem produce as transformations, and which palace receives them.

The recurring unit is a palace together with the three palaces that relate to it, which in this system is a defined geometric relationship rather than an adjacent one.

The chainable form expresses exactly that, and it is the whole public idiom.

import { astro } from 'iztro';

const astrolabe = astro.bySolar('2000-8-16', 2, '男', true, 'zh-CN');

astrolabe.star('紫微').surroundedPalaces().haveMutagen('忌');

Four arguments identify the subject, and the last is the output language. Then a chain that reads as a sentence: this star, its related palaces, does it carry this transformation.

Everything else in the library is that query with a different subject. A zodiac animal, a constellation, four pillars, data for each of six period lengths, and dynamic stars for the major and annual periods.

Configuration exists because schools disagree

The reason the library has a configuration system and a third-party plugin API is a disagreement inside the tradition, and it arrives in version 2.3.0.

Different schools of the astrology differ slightly on which transformations a stem produces and on star brightness. That is not a bug to be fixed but a difference of opinion to be parameterised, and the project treats it that way.

So the plugin surface is not an extension point for unrelated features. It is the mechanism by which a practitioner selects a school.

Language support is a related compromise, and the readme is candid about it. Simplified and traditional Chinese, English, Japanese, Korean and Vietnamese are supported, input can mix languages from different regions, and output is selectable. The English text is described as mostly a free translation rather than a standard one, with the author noting that this is why the English version may read more easily, and inviting pull requests from people who know the astrology vocabulary.

The repository itself is arranged around that audience. Two continuous integration configurations, one for GitHub Actions and one for GitLab. A custom domain name file and a no-Jekyll marker for the documentation site. Separate readmes for traditional Chinese and English. And a separate jest configuration file rather than test settings inside the package manifest.

Editorial conclusion

Use the iztro package if you want chart data computed locally, with no key and no network call, and if your questions are of the form the library is built around: which stars sit in this palace, which of them carry a transformation, what changes in the next period. Read two boundaries before you rely on it. The Qimen decision-making capability is not in the package at all, it is one of four hosted models reached over HTTP, so a deployment that assumes local Qimen is wrong. And the CDN files are unversioned, so pin a versioned file in your own markup rather than trusting the shared URL to keep pointing at the version you tested. Also know that schools disagree on transformations and star brightness, which is why configuration and plugins exist, and that the English text is a loose translation of the Chinese original.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. SylarLong/iztro on GitHub