FFFF GitHub - nimblemo/astro-hd: A CLI for take human design date summary · GitHub
[go: up one dir, main page]

Skip to content
nimblemoPublic

About

A CLI for take human design date summary

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

18 Commits

Folders and files

Repository files navigation

astro-hd

crates.io downloads docs.rs CI release license

astro-hd is a fast command-line tool that calculates a Human Design chart from a birth date, time and UTC offset. Planetary positions come from the astro-rust library; the report is rendered as a colorized terminal table, JSON or YAML. The ask command answers questions about the chart using a local RAG knowledge base.

Installation

cargo install astro-hd

The binary is installed as astro-hd (usually into ~/.cargo/bin). The default build includes RAG support. For a lean binary without it use:

cargo install astro-hd --no-default-features

Quick Start

astro-hd --date 1986-05-19 --time 12:00 --utc +6

--date is YYYY-MM-DD, --time is HH:MM, --utc is the UTC offset of the birthplace (e.g. +3, -5, +5.5).

Usage

Options

Flag Short Description
--date -d Birth date in YYYY-MM-DD format.
--time -t Birth time in HH:MM format.
--utc -u Timezone offset (e.g., +3, -5, +5.5).
--scenarios Comma-separated display scenarios (see below).
--topic Thematic output set: full, core, career, psyche, genekeys, venus, variables, or a user-defined topic. Conflicts with --scenarios.
--detail Detail level: detailed (default) or compact.
--format -f Output format: table (default), json, yaml.
--lang -l Language: en (default), ru, es.
--save Save output to a file. Without a value, the name is generated as hd_chart_<date>_<time>.txt.
--no-pager Disable interactive paging of long table output.

Birth-related flags (-d, -t, -u, --lang, --scenarios, --topic, --detail) are global and also work with the ask subcommand.

Commands

Command Description
ask Ask a question using the knowledge base and the calculated chart.
kb Manage the RAG document registry (kb add/list/remove/reindex/search/verify/path).
models Install, inspect, stop or remove the models used by ask (models install/status/stop/remove).
config Show or change default output settings.
topics List built-in and user-defined output topics (topics list).

ask options:

Flag Description
QUESTION Natural-language question; defaults to the scenario question.
--query-scenario Query scenario: reading, career, psyche, genekeys, or a custom one.
--index Build or refresh the embedding index, then exit.
--force Ignore the embedding cache when used with --index.
--top-k Number of retrieved fragments (overrides rag.top_k).
--answer-format text (default) or json.

Long table output is shown page by page when the terminal is interactive: Space — next page, Enter — next line, q — quit. Paging is skipped automatically when output is redirected or piped, and can be disabled with --no-pager.

Display Scenarios

The report is assembled from independent blocks (scenarios), always rendered in this canonical order:

Scenario Content
core Date, Type, Profile, Authority, Strategy
incarnation Incarnation Cross with its four gates; --detail detailed adds the cross and gate descriptions
centers Centers with normal/distorted behavior
channels Active channels
planets Combined Design/Personality planet table; --detail detailed adds gate/line descriptions
circuits Circuit scores
variables Motivation, Vision, Environment, Diet
relationships Fears, sexuality and love by gate
business Business keys for active gates
genekeys Gene Keys of active gates: shadow, gift and siddhi, ordered by planet significance
venus Venus Sequence: six spheres and steps 11–23

--detail compact drops the optional descriptions (core, incarnation, channels, planets, genekeys, venus, centers, circuits).

Built-in topics:

Topic Description Scenarios Detail
full All blocks with descriptions (default output) all scenarios detailed
core Identity and bodygraph mechanics core, centers, channels, planets, circuits detailed
career Core plus business gates (work, money) core, centers, channels, planets, circuits, business detailed
psyche Core plus relationships (fear, sexuality, love) and centers core, centers, relationships detailed
genekeys Core plus planets, Gene Keys, channels and circuits core, channels, planets, genekeys, circuits detailed
venus The Gene Keys set plus the Venus Sequence core, channels, planets, genekeys, venus, circuits detailed
variables Core plus variables (motivation, vision, environment, diet) core, variables detailed

JSON and YAML output always contain the full chart; scenarios affect only the table.

RAG queries

astro-hd ask answers questions using a local knowledge base (books, notes, methodology docs) plus the chart calculated by the CLI. Retrieval runs on in-process fastembed embeddings, generation runs on llama.cpp: the CLI downloads a prebuilt llama-server and a background runtime keeps it warm across calls — the first ask starts the server, every later CLI call extends its lease, and once no call arrives within rag.keep_alive_secs (30 minutes by default) the runtime stops the server and exits. Nothing has to be compiled or installed — everything works offline after the first download.

cargo build --release        # RAG is included by default

astro-hd ask -d 1986-05-19 -t 12:00 -u +6 \
  --query-scenario career \
  "How do my channels show up in work and money?"

The first call downloads the embedding model, the Qwen3-4B GGUF checkpoint and the llama.cpp build (all SHA-256 verified), so later runs are offline. All of it is managed by the binary:

astro-hd models install    # download everything `ask` needs
astro-hd models status     # what is installed, how much space it takes, where
astro-hd models stop       # stop the background runtime and its llama.cpp server
astro-hd models remove     # delete the models and llama.cpp builds

astro-hd ask --index, kb reindex and kb search only provision the embedding model, because indexing and retrieval do not call the chat model. Set "auto_pull_models": false in the RAG config to disable automatic downloads; in that case ask fails with a hint to run models install.

For a lean binary without RAG:

cargo build --release --no-default-features

Documents are not copied: kb add registers each file by its absolute path, and the indexer reads it in place. Chunks are embedded once and cached in the platform data directory, so subsequent runs only embed new or changed files.

Query scenarios compose a question with a chart topic:

Scenario Chart blocks
reading core, channels, planets, centers, relationships (compact)
career core, business, channels, planets, centers, circuits
psyche core, centers, relationships
genekeys core, channels, planets, genekeys, circuits
astro-hd ask --index                       # (re)index and exit
astro-hd ask -d 1986-05-19 -t 12:00 -u +6 --query-scenario genekeys
astro-hd ask -d 1986-05-19 -t 12:00 -u +6 --answer-format json "What does the chart say about relationships?"
astro-hd ask -d 1986-05-19 -t 12:00 -u +6 --topic career "..."   # override the chart topic

RAG settings live in config.json:

{
  "rag": {
    "local_embed_model": "multilingual-e5-small",
    "device": "auto",
    "top_k": 6,
    "chunk_chars": 1200,
    "chunk_overlap": 150,
    "max_chart_chars": 16000,
    "num_ctx": 16384,
    "auto_pull_models": true,
    "keep_alive_secs": 1800,
    "query_scenarios": {
      "my_reading": {
        "default_question": "What should I focus on this year?",
        "scenarios": ["core", "centers", "variables"]
      }
    }
  }
}

rag.cache_dir overrides the data folder that holds the registry, the index and converted documents.

Background runtime (keep-alive)

Loading the model takes seconds, so astro-hd keeps llama-server warm across calls instead of starting and stopping it every time. The first call that needs inference starts a small detached process — the same binary running the hidden __runtime command — which owns the server and a lease:

  • every CLI call (not just ask) extends the runtime lease by rag.keep_alive_secs;
  • when no call arrives within that window, the runtime stops the server and exits, removing its state files;
  • plain chart calculations never start the runtime — they only keep a running one alive;
  • ask --index, kb reindex and kb search never start it, because indexing and retrieval use fastembed only.
astro-hd models status     # runtime state, llama.cpp port and backend
astro-hd models stop       # stop the runtime and its server immediately

With a runtime up, models status adds a block like:

Runtime: running (pid 12345, up 42s, idle timeout 1800s, expires in 1758s)
  llama.cpp: not started
Key Default Description
keep_alive_secs 1800 How long the runtime (and its llama.cpp server) stays alive after the last CLI call. 0 disables the runtime and starts a one-shot server per ask.

The server is restarted automatically when a setting that affects it changes (device, num_ctx, or the model file), and a crashed or upgraded runtime is replaced on the next call. If the runtime cannot be started, ask falls back to a one-shot server for that request.

Local models and GPU

Nothing RAG-related is compiled or downloaded at build time: ask installs what it needs on the first run, and the same artifacts can be managed explicitly.

astro-hd models install    # embedding model + GGUF checkpoint + llama.cpp build
astro-hd models status     # what is installed, where, and the runtime state
astro-hd models stop       # stop the background runtime and its server
astro-hd models remove     # delete the models and llama.cpp builds
Component   Details                  State             Size  Path
Embeddings  multilingual-e5-small    installed     464.8 MB  <data>/rag/fastembed
Chat model  qwen3-4b-q4-k-m          installed       2.3 GB  <data>/rag/models/qwen3-4b-q4-k-m
llama.cpp   cuda                     installed     721.8 MB  <data>/rag/llama

Runtime: running (pid 12345, up 42s, idle timeout 1800s, expires in 1758s)
  llama.cpp: port 51234 (cuda)

models remove stops the running runtime first, then deletes the three folders above and prints the freed space. The vector index is kept — it stays valid when the same embedding model is installed again; use kb reindex to rebuild it from scratch.

Artifact Size Purpose
multilingual-e5-small (fastembed/ONNX) ~470 MB embeddings
Qwen3-4B-Q4_K_M.gguf + tokenizer/config ~2.3 GB answers
llama-server (llama.cpp) 15–520 MB inference, depends on the detected GPU
Key Default Description
device auto auto picks a GPU when one is detected, gpu requires one, cpu forces CPU.
local_embed_model multilingual-e5-small Also all-minilm-l6-v2, all-minilm-l6-v2-q, bge-small-en-v1.5.
num_ctx 16384 Context window passed to llama.cpp as --ctx-size.

Pick the device without editing the config:

astro-hd config --set-device auto   # GPU when detected (default)
astro-hd config --set-device gpu    # fail instead of falling back to CPU
astro-hd config --set-device cpu    # always CPU

The CLI detects the GPU and downloads the matching prebuilt llama.cpp build:

Platform GPU build Download
Windows x86_64 CUDA when nvidia-smi is present, else Vulkan 520 MB / 30 MB
Linux x86_64 / arm64 Vulkan (llama.cpp ships no CUDA build for Linux) 30 MB
macOS arm64 / x64 Metal 11 MB
no GPU / other targets CPU 11–17 MB

With device = "auto", a GPU build that fails to start (missing driver, out of memory) falls back to the CPU build instead of aborting the request. The llama.cpp build is started with all layers offloaded to the GPU (-ngl 99); when both an integrated and a discrete GPU are visible, the discrete one is selected (llama-server --list-devices prints the ids). Model files live in <data>/rag/models/, the binaries in <data>/rag/llama/, the embedding cache in <data>/rag/fastembed/; kb path prints the folder.

Knowledge base registry

Documents stay where they are. kb add records the absolute path of each document in registry.json, and the indexer reads it from that path:

astro-hd kb path                         # print the data folder (registry, index, converted)
astro-hd kb add ./books/venus.md         # register and index a file in place
astro-hd kb add ./books                  # register and index every supported file in a folder
astro-hd kb list                         # id, state, size, date and path of each document
astro-hd kb remove venus.md              # remove by id, path or unique suffix
astro-hd kb verify                       # check that files exist and are unchanged
astro-hd kb reindex                      # rebuild the embedding index
astro-hd kb reindex --force              # ignore the cache and re-embed everything
astro-hd kb search "profile 1/3"         # retrieval preview without generation

Registry and index live in the platform data directory (Windows: %APPDATA%\nimblemo\astro-hd\data\rag, Linux: ~/.local/share/astro-hd/rag, macOS: ~/Library/Application Support/com.nimblemo.astro-hd/rag); rag.cache_dir overrides it.

kb list states:

State Meaning
ok The file exists and matches the registration.
stale The file changed on disk; the next index run re-embeds it.
missing The file is gone; it is skipped by the indexer until you kb remove it.

kb add registers the documents and immediately embeds the new or changed chunks (using the configured fastembed model). Long runs report progress: the conversion size and duration, the chunk count per document, and the embedding percentage. kb remove drops the document's cached chunks, so the change takes effect without a full reindex. The next ask picks the registry up automatically; kb reindex rebuilds everything explicitly. kb verify exits with a non-zero status when any document needs attention.

Document conversion (PDF → Markdown)

kb add also accepts documents the index cannot read directly — .pdf, .docx, .doc, .docm, .odt, .rtf, .epub, .html, .htm, .xhtml. They are converted to Markdown with Firecrawl /v2/parse; only the generated .md is registered, and it is stored in the data folder under converted/ (the source file is never modified):

astro-hd config --set-ocr-key fc-...    # stored in config.json
astro-hd kb add ./books/venus.pdf       # → <data>/rag/converted/<id>-venus.md
astro-hd kb add ./books --force         # re-convert every supported file in the folder

The key can also come from the FIRECRAWL_API_KEY environment variable (rag.ocr.api_key_env); a key stored in the config takes precedence. astro-hd config shows whether a key is set (only the last four characters are printed).

kb list shows such documents with a from <original> line. Removing them deletes the generated Markdown as well.

Conversion is layout-aware with OCR fallback for scanned pages, files up to 50 MB per request. Settings live in rag.ocr:

Key Default Description
enabled true Convert non-text documents in kb add; false rejects them.
api_url https://api.firecrawl.dev/v2/parse Parse endpoint (self-hosted instances allowed).
api_key_env FIRECRAWL_API_KEY Environment variable holding the API key.
api_key — Key stored directly in the config; set it with astro-hd config --set-ocr-key <KEY> (takes precedence over the env var).
mode auto PDF strategy: auto (text first, OCR fallback), fast (text only), ocr (force OCR).
max_pages — Parse only the first N pages, to cap cost.
timeout_secs 600 HTTP timeout for one conversion.

Without the rag feature (cargo build --no-default-features) conversion is unavailable and only text files are accepted.

Configuration

Defaults are stored in config.json:

OS Path
Windows %APPDATA%\nimblemo\astro-hd\config\config.json
Linux ~/.config/astro-hd/config.json
macOS ~/Library/Application Support/com.nimblemo.astro-hd/config.json
{
  "language": "en",
  "output": {
    "detail": "detailed",
    "scenarios": ["core", "channels", "planets", "centers"]
  },
  "topics": {
    "my_reading": {
      "detail": "compact",
      "scenarios": ["core", "centers"]
    }
  }
}

An empty scenarios list means all scenarios. User-defined topics take precedence over built-in ones.

astro-hd topics list                         # list topics with descriptions
astro-hd config                              # show current defaults
astro-hd config --list-scenarios             # list scenarios and topics
astro-hd config --set-lang ru                # change default language
astro-hd config --set-scenarios core,centers # set default scenarios
astro-hd config --set-detail compact         # set default detail level
astro-hd config --set-topic career           # apply a topic as default
astro-hd config --set-device auto            # inference device (auto | gpu | cpu)
astro-hd config --set-ocr-key fc-...         # store the Firecrawl key for PDF → Markdown

Priority: CLI flags (--scenarios / --topic / --detail) > config file > built-in defaults.

Examples

Concise table output:

astro-hd -d 1986-05-19 -t 12:00 -u +6 --topic core

Export to JSON:

astro-hd -d 1986-05-19 -t 12:00 -u +6 --format json > chart.json

Save to a file:

astro-hd -d 1986-05-19 -t 12:00 -u +6 --save my_chart.txt

Another language (English is the default):

astro-hd -d 1986-05-19 -t 12:00 -u +6 --lang ru

Selected scenarios:

astro-hd -d 1986-05-19 -t 12:00 -u +6 --scenarios core,channels,centers --detail compact

Topic:

astro-hd -d 1986-05-19 -t 12:00 -u +6 --topic career

Venus Sequence:

astro-hd -d 1986-05-19 -t 12:00 -u +6 --topic venus

Prebuilt binaries

No Rust toolchain required — every release ships ready-to-run binaries for:

Platform Target triple
Linux x86_64 (glibc) x86_64-unknown-linux-gnu
macOS Intel x86_64-apple-darwin
macOS Apple Silicon aarch64-apple-darwin
Windows x86_64 x86_64-pc-windows-msvc

Static musl builds are not published: the embedding model runs on ONNX Runtime, which ships no musl binaries. Use cargo build --no-default-features to get a chart-only static binary from source.

Files are named astro-hd-v<VERSION>-<TARGET> (astro-hd-v<VERSION>-<TARGET>.exe on Windows), and each binary has a .sha256 checksum next to it. Browse them on the releases page.

Release binaries include RAG support. Chart calculation works fully offline; ask downloads the models and the matching llama.cpp build (GPU when one is detected) on first use.

Linux / macOS

VERSION=0.5.0
TARGET=x86_64-unknown-linux-gnu   # see the table above for other platforms
BIN="astro-hd-v${VERSION}-${TARGET}"
BASE="https://github.com/nimblemo/astro-hd/releases/download/v${VERSION}"

curl -fLO "${BASE}/${BIN}"
curl -fLO "${BASE}/${BIN}.sha256"
sha256sum -c "${BIN}.sha256"        # macOS: shasum -a 256 -c "${BIN}.sha256"

chmod +x "${BIN}"
sudo install -m 755 "${BIN}" /usr/local/bin/astro-hd

Windows (PowerShell)

$Version = "0.5.0"
$Bin = "astro-hd-v$Version-x86_64-pc-windows-msvc.exe"
$Base = "https://github.com/nimblemo/astro-hd/releases/download/v$Version"

Invoke-WebRequest "$Base/$Bin" -OutFile $Bin
Invoke-WebRequest "$Base/$Bin.sha256" -OutFile "$Bin.sha256"

$expected = (Get-Content "$Bin.sha256").Split(' ')[0].Trim().ToUpper()
$actual = (Get-FileHash $Bin -Algorithm SHA256).Hash
if ($actual -ne $expected) { throw "Checksum mismatch" }

New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\astro-hd" | Out-Null
Move-Item $Bin "$env:LOCALAPPDATA\astro-hd\astro-hd.exe" -Force
$env:Path += ";$env:LOCALAPPDATA\astro-hd"   # add permanently via System Properties → Environment Variables

From the Git repository

cargo install --git https://github.com/nimblemo/astro-hd --tag v0.5.0

From source

git clone https://github.com/nimblemo/astro-hd.git
cd astro-hd
cargo build --release
# binary: ./target/release/astro-hd

Requirements

  • Rust — only for cargo install / building from source.
  • Nerd Font (optional) — the table uses Nerd Font symbols for zodiac signs and planets. Install e.g. JetBrainsMono Nerd Font and select it in your terminal for the best look.
  • RAG models (optional) — required only for astro-hd ask. The embedding model, the Qwen3-4B GGUF checkpoint and the llama.cpp binary (~2.8 GB in total) are downloaded into the data folder on the first run.
  • Chart calculation is fully offline: gate and center descriptions are embedded in the binary, so no data files or network access are needed.

Project Structure

  • src/main.rs: entry point and command dispatch.
  • src/cli.rs: CLI argument parsing and terminal output formatting.
  • src/calc.rs: core Human Design logic and chart assembly.
  • src/astro_calc.rs: astronomical calculations wrapper.
  • src/scenario.rs: display scenarios, detail levels and topics.
  • src/query.rs: RAG query scenarios composed with chart topics.
  • src/rag.rs: Rig-based retrieval, embedding cache and answer generation (included by default).
  • src/library.rs: document registry (registry.json), kb add/list/remove/verify.
  • src/ocr.rs: PDF/DOCX/EPUB → Markdown conversion via Firecrawl.
  • src/llama.rs: llama.cpp supervision — binary download, server startup and shutdown.
  • src/runtime.rs: background runtime that keeps llama.cpp warm between CLI calls (lease, models status/stop).
  • src/local.rs: model cache — GGUF checkpoint downloads and fastembed embeddings.
  • src/venus.rs: Venus Sequence map (steps 11–23) assembled from existing positions.
  • src/config.rs: user configuration and config path resolution.
  • src/data/: data models and the embedded gates database.
  • data/: gate database and Venus Sequence JSON files bundled into the binary at build time.
  • locales/: translations (en, ru, es).

Development

cargo build            # debug build
cargo test --all-targets
cargo fmt --all --check
cargo clippy --all-targets -- -D warnings

build.rs downloads the gate database into data/ if the files are missing (they are committed to the repository, so a normal build needs no data downloads; Cargo dependencies are fetched as usual).

Build artifacts

target/ grows quickly because every feature set (default, --no-default-features) and the debug profile keep their own artifacts. Dependencies are compiled without debug info ([profile.dev.package."*"] in Cargo.toml), and the rest can be pruned safely:

cargo clean --profile dev      # drop debug artifacts, keep the release build
cargo clean                    # drop everything (~10 GB)
cargo sweep -t 7               # optional: remove artifacts unused for 7 days (cargo install cargo-sweep)

Set CARGO_INCREMENTAL=0 for one-off builds to skip the incremental cache (~5 GB), and avoid running manual builds while rust-analyzer is checking the workspace — they contend for the same lock and can leave half-written artifacts.

Benchmarks and load testing

cargo bench                                  # criterion micro-benchmarks
cargo run --example load_test --release      # throughput, 10 000+ charts

Typical performance results:

  • Calculation speed: ~80–120 µs per chart.
  • Throughput: ~8 000+ charts/sec (multi-threaded).

Releasing

Releases are automated by GitHub Actions:

  1. astro-rust (astronomy library) must be published first: push a v2.1.0 tag to nimblemo/astro-rust — the Publish workflow pushes the crate to crates.io.

  2. In this repository, bump version in Cargo.toml, refresh Cargo.lock (cargo update -p astro-rust), commit, and push a matching tag:

    git tag v0.5.0
    git push origin v0.5.0
  3. The Release workflow then:

    • verifies the tag matches Cargo.toml, runs the test suite;
    • builds ready-to-run binaries for Linux (glibc), macOS (Intel, Apple Silicon) and Windows;
    • publishes the binaries with .sha256 checksums and generated release notes to GitHub Releases;
    • publishes the crate to crates.io.

The crates.io step requires a CARGO_REGISTRY_TOKEN repository secret (an API token from https://crates.io/settings/tokens). If the version is already published, the step is skipped.

License

MIT — see LICENSE.

About

A CLI for take human design date summary

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0