{"id":15029564,"url":"https://github.com/sylarlong/iztro","last_synced_at":"2026-08-27T19:33:03.393Z","repository":{"id":184240843,"uuid":"671405519","full_name":"SylarLong/iztro","owner":"SylarLong","description":"⭐This is a lightweight kit for generating astrolabes for Zi Wei Dou Shu (The Purple Star Astrology), an ancient Chinese astrology. It allows you to obtain your horoscope and personality analysis. 支持多语言轻量级获取紫微斗数排盘信息的javascript开源库。","archived":false,"fork":false,"pushed_at":"2026-08-15T03:31:17.000Z","size":28360,"stargazers_count":4060,"open_issues_count":9,"forks_count":660,"subscribers_count":33,"default_branch":"main","last_synced_at":"2026-08-15T03:48:30.061Z","etag":null,"topics":["astrolabe","astrology","chinese-astrology","horoscope","javascript","natal-chart","npm","typescript","ziweidoushu"],"latest_commit_sha":null,"homepage":"https://iztro.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SylarLong.png","metadata":{"files":{"readme":"README-en_US.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null,"disclosure":null}},"created_at":"2023-07-27T08:41:40.000Z","updated_at":"2026-08-15T03:31:01.000Z","dependencies_parsed_at":"2023-08-29T04:54:59.069Z","dependency_job_id":"89b33189-557f-4785-9113-d5dad44b8ac4","html_url":"https://github.com/SylarLong/iztro","commit_stats":null,"previous_names":["sylarlong/astro","sylarlong/iztro"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/SylarLong/iztro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SylarLong%2Fiztro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SylarLong%2Fiztro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SylarLong%2Fiztro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SylarLong%2Fiztro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SylarLong","download_url":"https://codeload.github.com/SylarLong/iztro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SylarLong%2Fiztro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36946639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-27T02:00:07.166Z","response_time":96,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astrolabe","astrology","chinese-astrology","horoscope","javascript","natal-chart","npm","typescript","ziweidoushu"],"created_at":"2024-09-24T20:11:03.113Z","updated_at":"2026-08-27T19:33:03.375Z","avatar_url":"https://github.com/SylarLong.png","language":"TypeScript","funding_links":["https://img.shields.io/badge/PaypalMe-8A2BE2?logo=paypal\u0026link=https%3A%2F%2Fwww.paypal.com%2Fsylarlong"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n![banner2](https://github.com/SylarLong/iztro/assets/6510425/e8457a88-e52e-435e-8f93-e3f375486d70)\n\n# A lightweight astrolabe generator of The Purple Star Astrology (Zi Wei Dou Shu)\n\n[简体中文](./README.md) 🔸 [繁體中文](./README-zh_TW.md) 🔸 English\n\n[![Join our Discord](https://img.shields.io/badge/JOIN%20OUR%20DISCORD-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white)](https://discord.gg/xvmu6gww6B)\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n  [![NPM Version](https://img.shields.io/npm/v/iztro?logo=npm\u0026logoColor=%23959DA5)](https://www.npmjs.com/package/iztro)\n  [![NPM Minified Size](https://img.shields.io/bundlephobia/min/iztro?logo=npm\u0026logoColor=%23959DA5)](https://www.npmjs.com/package/iztro)\n  [![NPM Downloads](https://img.shields.io/npm/dt/iztro.svg?logo=npm\u0026logoColor=%23959DA5)](https://www.npmjs.com/package/iztro)\n  [![jsDelivr Hits](https://data.jsdelivr.com/v1/package/npm/iztro/badge)](https://www.jsdelivr.com/package/npm/iztro)\n\n  [![GitHub Code Size in Bytes](https://img.shields.io/github/languages/code-size/SylarLong/iztro?logo=github\u0026logoColor=%23959DA5)](https://github.com/SylarLong/iztro)\n  [![Codecov Coverage](https://img.shields.io/codecov/c/github/SylarLong/iztro?logo=codecov\u0026logoColor=%23959DA5)](https://github.com/SylarLong/iztro/actions/workflows/Codecov.yaml)\n  [![Codecov Status](https://github.com/SylarLong/iztro/actions/workflows/Codecov.yaml/badge.svg)](https://github.com/SylarLong/iztro/actions/workflows/Codecov.yaml)\n\n  [![Maintainability](https://qlty.sh/gh/SylarLong/projects/iztro/maintainability.svg)](https://qlty.sh/gh/SylarLong/projects/iztro)\n  [![Package Quality](https://packagequality.com/shield/iztro.svg?logo=github)](https://packagequality.com/#?package=iztro)\n\n  [![License](https://img.shields.io/github/license/sylarlong/iztro?logo=github)](https://www.npmjs.com/package/iztro)\n  [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FSylarLong%2Fiztro.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2FSylarLong%2Fiztro?ref=badge_shield)\n\n\u003c/div\u003e\n\n## iztro AI · Ziwei and Qimen models\n\nBeyond the open-source charting library, `iztro` provides two hosted specialist AI models. They call the server-side astrology tools automatically and are available through the Chat API or Iztro Agents SDK, so you do not have to maintain chart prompts or ask a general model to guess chart facts.\n\n| Model | Best for | Required input |\n| --- | --- | --- |\n| **`iztro-ziwei-v3`** | Natal personality, life pattern, compatibility, and longer-range decade, annual, monthly, or daily trends | Birth date, birth time, gender, and the topic to analyze |\n| **`iztro-qimen-v3`** | The decision, development, obstacles, and timing of one current matter, such as a partnership, negotiation, interview, launch, trip, or specific relationship step | The situation, one clear question, and the question time; **no birth details** |\n\n### `iztro-ziwei-v3`: charts and longer-term trends\n\n- Calls the `iztro` charting tools automatically and reads only the natal and timing layers needed for the question.\n- Uses Ziwei-specific prompting and reasoning, and can retain birth details and prior context in a session.\n\n### `iztro-qimen-v3`: one matter, one chart, with optional timing\n\n- Analyzes **one concrete matter** from the question time and returns a conclusion, supporting evidence, obstacles, and practical guidance.\n- When the user asks **when**, or timing is essential, returns candidate trigger windows on the real calendar.\n- Keep unrelated matters in separate requests. Yingqi dates are triggers to interpret with the whole chart, not guarantees that an outcome must occur on a particular day.\n\nA strong Qimen request is: “We have discussed a distribution partnership twice, but the revenue split and launch date are still open. Should I push now, continue negotiating, or pause? If it can move forward, give me the nearest action windows and evidence.”\n\n\u003e [!NOTE]\n\u003e The `iztro` NPM package remains an open-source **Zi Wei Dou Shu charting library**. `iztro-qimen-v3` is a hosted AI model accessed through the API or Agents SDK; it is not a local Qimen module in this package.\n\nBoth models are available through these integration paths:\n\n### 1. iztro Chat API — call our HTTP API\n\nFor conversational Ziwei or Qimen analysis, use the iztro Chat API. It requires an API key; see the [developer documentation](https://api-doc.iztro.com) and compare both options in the [Models guide](https://api-doc.iztro.com/sdk/qimen).\n\nThe examples below assume the console key is stored in the server-side `ZIWEI_API_KEY` environment variable. Never put it in browser code.\n\nThe recommended integration is the Multi-turn Conversation API: create a conversation first, then send user messages to that conversation so the API can preserve context for you.\n\n```shell\ncurl https://chat-api.iztro.com/v2/platform/sessions \\\n  -H \"Authorization: Bearer $ZIWEI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"external_user_id\": \"user_123\",\n    \"model\": \"iztro-ziwei-v3\",\n    \"system_prompt_override\": \"Answer in concise English markdown and suggest possible follow-up questions.\"\n  }'\n\ncurl https://chat-api.iztro.com/v2/platform/sessions/{session_id}/messages \\\n  -H \"Authorization: Bearer $ZIWEI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"message\": \"Analyze my 2026 career trend. My birthday is 1995-02-23, birth hour is 17, gender is female.\",\n    \"title\": \"2026 Career Reading\",\n    \"language\": \"en\",\n    \"enable_iztro_call\": true\n  }'\n```\n\nSelect `iztro-qimen-v3` when creating a Qimen session. The service uses the request time by default; pass an ISO 8601 `current_datetime` with a UTC offset when the user's timezone differs or the chart must be reproducible:\n\n```shell\ncurl https://chat-api.iztro.com/v2/platform/sessions \\\n  -H \"Authorization: Bearer $ZIWEI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"external_user_id\": \"user_123\",\n    \"model\": \"iztro-qimen-v3\"\n  }'\n\ncurl https://chat-api.iztro.com/v2/platform/sessions/{session_id}/messages \\\n  -H \"Authorization: Bearer $ZIWEI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"message\": \"We have discussed a distribution partnership twice, but the revenue split and launch date are still open. Should I push now, keep negotiating, or pause? If it can move forward, give me the nearest action windows.\",\n    \"current_datetime\": \"2026-07-20T14:30:00+08:00\",\n    \"language\": \"en\",\n    \"enable_iztro_call\": true\n  }'\n```\n\nSee [`examples/chat-api`](./examples/chat-api) for JavaScript and Python examples. A full-stack streaming chatbot with edit and resend support is available in [`examples/fullstack-demo`](./examples/fullstack-demo).\n\n### 2. iztro Agents SDK — build your own agent\n\nBuild your own agent on `iztro-ziwei-v3` or `iztro-qimen-v3` with your own tools, MCP servers, and human-in-the-loop. It is a thin layer over the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), available for both Python and TypeScript:\n\n- **Python** — `pip install openai-iztro-agents` · [github.com/SylarLong/openai-iztro-agents-python](https://github.com/SylarLong/openai-iztro-agents-python)\n- **TypeScript / JavaScript** — `npm install openai-iztro-agents` · [github.com/SylarLong/openai-iztro-agents-js](https://github.com/SylarLong/openai-iztro-agents-js)\n\nBoth SDKs include Ziwei and Qimen factories. Python uses `iztro_ziwei_agent(...)` / `iztro_qimen_agent(...)`; TypeScript uses `iztroZiweiAgent({...})` / `iztroQimenAgent({...})`. See the [Models guide](https://api-doc.iztro.com/sdk/qimen) for the public calculation names returned by the API.\n\n### Full-stack demos\n\n| Integration | Complete example | Included capabilities |\n| --- | --- | --- |\n| iztro Chat API | [`examples/fullstack-demo`](./examples/fullstack-demo) | Node/Python backends, streaming, message editing, regeneration, and a server-only API key |\n| Python Agents SDK | [ChatSession full-stack demo](https://github.com/SylarLong/openai-iztro-agents-python/tree/main/examples/fullstack-demo) | Session list, create/delete/rename, app-level edit branches and forks, chart-call history, and Markdown rendering |\n| TypeScript / JavaScript Agents SDK | [ChatSession full-stack demo](https://github.com/SylarLong/openai-iztro-agents-js/tree/master/examples/fullstack-demo) | The same session workbench and streaming experience as the Python demo |\n\n\u003cimg src=\"./examples/fullstack-demo/assets/chat-session-workbench.png\" alt=\"iztro Agents SDK ChatSession full-stack demo\" width=\"1200\" /\u003e\n\n## Introduction\n\nIt's used to obtain the data of `The Purple Star Astrology (Zi Wei Dou Shu)`.\n\n- Input\n\n  - birthday（support solar date and lunar date）\n  - birth time\n  - gender\n\n- Feature list\n\n  - get `12 palaces` data of Zi Wei Dou Shu.\n  - get Chinese `zodiac`\n  - get `sign`\n  - get birth time by Chinese date\n  - get `horoscope`(`decadal`, `turnly`, `yearly`, `monthly`, `daily`, `timely`)\n  - get horoscope `stars` (`dacadal` and `yearly`)\n  - check if one `palace` includes specific `stars`\n  - check if `surrounded palaces` of specific `palace` include specific `stars`\n  - check if `surrounded palaces` of specific `palace` include specific `mutagen`\n  - check if spedific star is `mutaged`\n  - check if `surrounded palaces` of specific `star` include specific `mutagen`\n  - check star `brightness`\n  - get `mutagen` by `heavenly stem`\n  - get `palace` by `star`\n  - get `surrounded palaces` by `palace`\n  - get `surrounded palaces` by `star`\n  - get `opposite` palace by `star`\n\n- Other\n\n  - Multilingual input/output\n\n    you can mix multiple languages when passing parameters and specify output language. we support Simplified Chinese, Traditional Chinese, English, Japanese, Korean and Vietnamese. however, English translation is not stardand. so I just translate them by meaning. if you're good at English and well known about Zi Wei Dou Shu, welcome to PR. any language is welcome.\n\n  - Chain invoking\n\n    if you want to check if the `surrounded palaces` of  `emperor` is `focused`, you can do it like this:\n\n    ```ts\n    import { astro } from 'iztro';\n\n    const astrolabe = astro.bySolar('2000-8-16', 2, 'male', true, 'en-US');\n\n    astrolabe.star('emperor').surroundedPalaces().haveMutagen('focused');\n    ```\n\n  - Configuration and plugins\n\n     There are many `Zi wei Dou Shu` genres, and the mutagens and star brightness of different genres will be slightly different. In order to meet the needs of different genres and function expansion, iztro has added global configuration and third-party plug-in functions in version `v2.3.0`. For details, see [Configuration Document](https://ziwei.pro/posts/config-n-plugin.html)\n\n## Quick Links\n\n- [Document](https://docs.iztro.com)\n- [Discussions](https://github.com/SylarLong/iztro/discussions)\n- [Issues](https://github.com/SylarLong/iztro/issues)\n- [Demo](https://ziwei.pub)\n\n## Online Demo\n\nTo instantly access iztro's astrolabe with no development required, go directly to https://ziwei.pub for online demo.\n\n## Installation\n\nYou can choose any package manager to install `iztro`.\n\n```shell\n# npm\nnpm install iztro -S\n\n# yarn\nyarn add iztro\n\n# pnpm\npnpm install iztro -S\n```\n\n## Simple Example\n\nThis is a very simple example to show how to use `iztro` to get the astrolabe data. please visit [develop document](https://docs.iztro.com) for details.\n\n- ES6 Module\n\n  ```ts\n  import { astro } from 'iztro';\n\n  // get astrolabe data by solar date\n  const astrolabe = astro.bySolar('2000-8-16', 2, 'male', true, 'en-US');\n\n  // get astrolabe data by lunar date\n  const astrolabe = astro.byLunar('2000-7-17', 2, 'male', false, true, 'en-US');\n  ```\n\n- CommonJS\n\n  ```ts\n  var iztro = require('iztro');\n\n  // get astrolabe data by solar date\n  var astrolabe = iztro.astro.bySolar('2000-8-16', 2, 'male', true, 'en-US');\n\n  // get astrolabe data by lunar date\n  var astrolabe = iztro.astro.byLunar('2000-7-17', 2, 'male', false, true, 'en-US');\n  ```\n\n## Contributing\n\nIf you're interested in `iztro` and wish to join us,it's very welcome. You can contribute by:\n\n- create an issue [here](https://github.com/SylarLong/iztro/issues/new?assignees=SylarLong\u0026labels=%E5%8A%9F%E8%83%BD%EF%BD%9Cfeature\u0026projects=\u0026template=new-feature.md\u0026title=%7B%E6%A0%87%E9%A2%98%7D%EF%BD%9C%7Btitle%7D) if you have any good ideas or suggestions.\n- report a bug [here](https://github.com/SylarLong/iztro/issues/new?assignees=SylarLong\u0026labels=%E6%BC%8F%E6%B4%9E%EF%BD%9Cbug\u0026projects=\u0026template=bug-report.md\u0026title=%7Bversion%7D%3A%7Bfunction%7D-) if you found any bugs.\n- you can also `fork` this code to your repository and create PRs for your changes.\n- also, you can contribute the `localization` files. please refer to [locales](https://github.com/SylarLong/iztro/tree/main/src/i18n/locales) and create the localization files for your lanuage.\n- additionally, buy me a coffee is another great way to support me [![Static Badge](https://img.shields.io/badge/PaypalMe-8A2BE2?logo=paypal\u0026link=https%3A%2F%2Fwww.paypal.com%2Fsylarlong)](https://PayPal.Me/sylarlong)\n\n\u003e [!NOTE]\n\u003e Please read the [Contributing Guide](https://github.com/SylarLong/iztro/blob/main/CONTRIBUTING.md) before starting.\n\n## Summary\n\nYou can generate an astrolabe by using the returned data. Of course it's just an example. You can focus on astrolabe design or data analyzation. This program solves the most tedious work for you, so that you can put more energy on the things you need to pay attention to.\n\n![](docs/assets/astrolabe@2x.5039cc7c-en_US.png)\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?repos=sylarlong%2Fiztro\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=sylarlong/iztro\u0026type=date\u0026theme=dark\u0026legend=top-left\u0026sealed_token=uTaBgMSSccISPgduGiG1mzXHRjyQcwvMHCqQnEspLy_iZECAVyai-XU2WDj1znko5NJPavNbiKTttvEBeE85324vgxCna8hxKGwZUTENSNvnJ0Qv47uwqg\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=sylarlong/iztro\u0026type=date\u0026legend=top-left\u0026sealed_token=uTaBgMSSccISPgduGiG1mzXHRjyQcwvMHCqQnEspLy_iZECAVyai-XU2WDj1znko5NJPavNbiKTttvEBeE85324vgxCna8hxKGwZUTENSNvnJ0Qv47uwqg\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=sylarlong/iztro\u0026type=date\u0026legend=top-left\u0026sealed_token=uTaBgMSSccISPgduGiG1mzXHRjyQcwvMHCqQnEspLy_iZECAVyai-XU2WDj1znko5NJPavNbiKTttvEBeE85324vgxCna8hxKGwZUTENSNvnJ0Qv47uwqg\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\n[MIT License](https://github.com/SylarLong/iztro/blob/main/LICENSE)\n\nCopyright \u0026copy; 2023 All Contributors.\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FSylarLong%2Fiztro.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FSylarLong%2Fiztro?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsylarlong%2Fiztro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsylarlong%2Fiztro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsylarlong%2Fiztro/lists"}