Kefer Astrology Documentation

Project Overview

Mon, 01 Jan 0001 00:00:00 +0000

Function layer for Kefer Astrology

Quickstart

Get up and running in 3 steps:

# 1. Create and activate virtual environment
python3 -m venv venv
# alternatively use makefile
source ./venv/bin/activate  # Linux/Mac
venv\Scripts\activate  # Windows

# 2. Install dependencies (choose your UI)
pip install -r requirements/base.txt  # for base package
pip install -r requirements/streamlit.txt  # For Streamlit UI (browser)
pip install -r requirements/kivy.txt  # For Kivy UI (desktop)

# Or install by package extras
pip install .  # core computation/storage package
pip install .[api]  # FastAPI backend for Tauri/web frontends
pip install .[streamlit]  # Streamlit UI + chart rendering
pip install .[kivy]  # Kivy desktop UI + chart rendering

# 3. Run the application
python3 -m module --streamlit  # Streamlit UI (browser)
python3 -m module --kivy  # Kivy UI (desktop)
python3 -m module --tui   # Text UI (terminal)
python3 -m module         # Default: TUI

For detailed setup instructions, troubleshooting, and advanced options, see the Installation and Venvs.

Streamlit UI

Mon, 01 Jan 0001 00:00:00 +0000

Streamlit UI

The Streamlit UI provides a web-based interface for creating and visualizing astrological charts.

How to Run

Prerequisites

Install Streamlit and required dependencies:

pip install -r requirements/streamlit.txt

Starting the Application

Run the Streamlit interface:

python -m module --streamlit

Or directly:

streamlit run module/ui_streamlit.py

Features

Interactive chart creation
Real-time position calculations
Aspect visualization
Workspace management
Chart export capabilities

Configuration

The Streamlit UI uses the workspace configuration from workspace.yaml. You can customize settings through the UI’s advanced options panel.

Kivy UI

Mon, 01 Jan 0001 00:00:00 +0000

Kivy UI

The Kivy UI provides a native desktop application for astrological chart visualization with embedded interactive charts.

How to Run

Prerequisites

Install Kivy and required dependencies:

pip install -r requirements/kivy.txt

For embedded interactive Plotly charts, install the WebView widget:

pip install kivy-garden
garden install kivy_garden.webview

Starting the Application

Run the Kivy interface:

python -m module --kivy

Features

Native desktop application
Embedded interactive Plotly charts (with WebView)
JPL engine toggle
Standardized Radix chart renderer
Cross-platform support (Windows, macOS, Linux)

Configuration

Default JPL ephemeris file: source/de421.bsp
Chart files are saved to the workspace directory
If WebView is unavailable, charts open in the default browser

Troubleshooting

Unknown class WebView: Install via garden install kivy_garden.webview
JPL not active: Ensure skyfield is installed and source/de421.bsp exists
Chart opens in browser: WebView widget not installed (this is a fallback behavior)

cli Module

Mon, 01 Jan 0001 00:00:00 +0000

`cli` module

CLI interface for Tauri frontend integration.

This module provides a JSON-based command interface that can be called from the Tauri application via subprocess. All commands read JSON from stdin or command-line arguments and output JSON to stdout.

Usage: python -m module.cli <command> [args_json]

Commands:

compute_chart: Compute positions and aspects for a chart
compute_transit_series: Compute transit series for a time range
get_workspace_settings: Get workspace settings and defaults
list_charts: List all charts in workspace
get_chart: Get chart details by ID
sync_workspace: Synchronize workspace manifest with files on disk
export_parquet: Export stored positions to Parquet files

Storage:

models Module

Mon, 01 Jan 0001 00:00:00 +0000

`models` module

Classes

class `Annotation`

Annotation(title: str, content: str, created: datetime.datetime | None, author: str)

Dataclass fields

title: str
content: str
created: Union
author: str

class `Aspect`

Aspect(type: str, source_id: str, target_id: str, angle: float, orb: float)

Dataclass fields

type: str
source_id: str
target_id: str
angle: float
orb: float

class `AspectContext` (str, Enum)

Contexts where an aspect can be used.

class `AspectDefinition`

AspectDefinition(id: str, glyph: str, angle: float, default_orb: float, i18n: Dict[str, str], color: str | None = None, importance: int | None = None, line_style: str | None = None, line_width: float | None = None, show_label: bool | None = None, valid_contexts: List[module.models.AspectContext] | None = None)

services Module

Mon, 01 Jan 0001 00:00:00 +0000

`services` module

Functions

`build_chart_instance`

build_chart_instance(name: str, dt_str: str, loc_text: str, mode: module.models.ChartMode, ws: Optional[module.models.Workspace] = None, ephemeris_path: Optional[str] = None) -> module.models.ChartInstance

Build a ChartInstance using workspace defaults when provided.

Resolves engine and house system from ws if available.
Uses utils.prepare_horoscope to produce a fully-typed ChartInstance.

`build_radix_figure_for_chart`

build_radix_figure_for_chart(chart: module.models.ChartInstance, engine_override: Optional[module.models.EngineType] = None, ephemeris_path_override: Optional[str] = None, ws: Optional[ForwardRef('Workspace')] = None) -> Any

Extract positions from a ChartInstance’s computed_chart and return a Plotly Figure ready to render.

Parameters

chart: ChartInstance to compute positions for
engine_override: Optional engine to use instead of chart’s stored engine

storage Module

Mon, 01 Jan 0001 00:00:00 +0000

`storage` module

DuckDB and Parquet storage helpers for computed astrological data.

This module provides optional storage functionality for Python to write computed positions and aspects directly to DuckDB/Parquet, avoiding large JSON transfers for batch operations like transit series.

Usage: from module.storage import DuckDBStorage

storage = DuckDBStorage('/path/to/workspace/data/workspace.db')
storage.store_positions(chart_id, datetime, positions, engine='jpl')

# Optimized batch computation
storage.compute_and_store_series(
    chart_id='transit_base',
    start_datetime=start_dt,
    end_datetime=end_dt,
    time_step=timedelta(minutes=1),
    location=location,
    engine='jpl',
    requested_objects=['sun', 'moon', ...],
    include_physical=True,
    include_topocentric=True
)

Functions

`get_storage_path`

get_storage_path(workspace_path: str | pathlib.Path) -> pathlib.Path

Get DuckDB storage path for a workspace.

ui_streamlit Module

Mon, 01 Jan 0001 00:00:00 +0000

`ui_streamlit` module

Functions

`main`

main()

`render_toolbar`

render_toolbar()

How the UI is invoked

Entry point: main()

utils Module

Mon, 01 Jan 0001 00:00:00 +0000

`utils` module

Functions

`combine_date_time`

combine_date_time(input_date: datetime.date, input_time: datetime.time) -> datetime.datetime

Combine a date and time into a naive datetime (no timezone).

Parameters

input_date: Date object
input_time: Time object

Returns

Naive datetime combining date and time

`compute_vernal_equinox_offset`

compute_vernal_equinox_offset(year: int, eph, observer, ts) -> float

Compute the vernal equinox offset for tropical astrology adjustment.

Parameters

year: The year to compute the vernal equinox for
eph: Skyfield ephemeris object
observer: Skyfield Topos observer object
ts: Skyfield timescale object

workspace Module

Mon, 01 Jan 0001 00:00:00 +0000

`workspace` module

Functions

`add_chart`

add_chart(ws: module.models.Workspace, chart: module.models.ChartInstance, base_dir: str | pathlib.Path) -> str

Add a chart to a Workspace and write its YAML file.

Parameters

ws: Workspace to add chart to
chart: ChartInstance to add
base_dir: Base directory for workspace files

Returns

Relative path to chart YAML file

Notes

Prevents duplicates by checking existing charts. Removes computed_chart and ephemeral overrides before serialization.

`add_or_update_chart`

add_or_update_chart(ws: module.models.Workspace, chart: module.models.ChartInstance, base_dir: str | pathlib.Path) -> str

Add a new chart or update an existing one by id or subject name; persist YAML and manifest.

z_visual Module

Mon, 01 Jan 0001 00:00:00 +0000

`z_visual` module

Functions

`build_radix_figure`

build_radix_figure(positions: dict) -> plotly.graph_objs._figure.Figure

Build a standardized polar (radix) chart figure from planet positions in degrees [0,360). positions: mapping of planet name (lowercase or mixed) -> ecliptic longitude in degrees

`display_3d`

display_3d(categories: list, values_degrees: list, labels: list) -> None

Render a simple Matplotlib 3D scatter plot for objects at given angles.

`display_radial`

display_radial(categories: list, values_degrees: list, labels: list) -> None

Quick Matplotlib radial scatter demo for given categories and degrees.

Parameters

categories: labels for angular ticks
values_degrees: list of angles in degrees

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The architecture separates UI, computation, workspace management, and storage so multiple frontends can share the same backend behavior.

Repository Structure (top level)

cache: temporary files for computation
module: all the program logic
scripts: generators for documentation
tests: scenario and functionality testing
venv: python environment with libraries

Core Layers

UI layer: Streamlit, Kivy, or Tauri/Svelte call Python services directly.
Services layer: module.services computes positions/aspects and builds charts.
Workspace layer: module.workspace loads/saves modular YAML workspaces.
Storage layer: module.storage persists positions to DuckDB and Parquet (positions-only).

Data Flow

UI collects inputs and opens a workspace.
Services compute positions (and aspects on demand).
Storage writes positions to DuckDB and/or Parquet.
UI renders charts from computed positions.

Storage Model

Positions-only: aspects are computed on demand.
Dual engines: Kerykeion (fast) and JPL/Skyfield (extended properties).
Radix support: radix_chart_id + is_radix for transit comparisons.
Hybrid storage: DuckDB for active queries, Parquet for time series.

Storage (Backend)

Strategy (Python vs Rust)

Python storage (batch):

Mon, 01 Jan 0001 00:00:00 +0000

CLI Reference

Overview

The Python sidecar provides a JSON-based CLI interface for the Tauri frontend. All commands accept JSON arguments and return JSON results.

Usage

python -m module.cli <command> [args_json]

Or with JSON from stdin:

echo '{"workspace_path": "/path/to/workspace.yaml", "chart_id": "my-chart"}' | python -m module.cli compute_chart

Commands

1. `compute_chart`

Compute positions and aspects for a chart.

Arguments:

{
  "workspace_path": "/path/to/workspace.yaml",
  "chart_id": "chart-id",
  "include_physical": false,      // Optional: Include extended physical properties (JPL only)
  "include_topocentric": false   // Optional: Include altitude/azimuth (JPL with location)
}

Response:

Mon, 01 Jan 0001 00:00:00 +0000

Enum Overview

This document lists all enumerations defined in module.models.

Enum	Description	Members
`AspectContext`	Contexts where an aspect can be used.	CHART, TRANSIT, DIRECTION
`Ayanamsa`	Ayanamsa enumeration	LAHIRI, RAMAN, KRISHNAMURTI, FAGAN_BRADLEY, DE_LUCE, USER_DEFINED
`ChartMode`	ChartMode enumeration	NATAL, EVENT, HORARY, COMPOSITE
`Element`	The four classical elements.	FIRE, EARTH, AIR, WATER
`EngineType`	Engine enumeration	SWISSEPH, JYOTISH, JPL, CUSTOM
`HouseSystem`	House enumeration	PLACIDUS, WHOLE_SIGN, CAMPANUS, KOCH, EQUAL, REGIOMONTANUS, VEHL, PORPHYRY, ALCABITIUS
`LayoutStyle`	Layout enumeration	SINGLE, TIMELINE_OVERLAY, DUAL_WHEEL, COMPARISON
`ObjectType`	Type of observable object in the chart.	PLANET, ASTEROID, ANGLE, HOUSE_CUSP, CALCULATED_POINT, LUNAR_NODE, PART
`RelationType`	Relation enumeration	TRANSIT, SYNASTRY, PROGRESSION, COMPOSITE
`TimeSystem`	Time representation systems.	GREGORIAN, JULIAN_DAY, JULIAN_CALENDAR, UNIX_TIMESTAMP, ORDINAL_DATE, ISO_WEEK_DATE, COMPACT_DATE
`ViewModuleType`	ViewModule enumeration	WHEEL, TIMELINE, GRID, TABLE, TEXT
`ZodiacType`	Zodiac enumeration	TROPICAL, SIDEREAL

Mon, 01 Jan 0001 00:00:00 +0000

Ephemeris files

Default file: de440s.bsp

The default JPL ephemeris was upgraded from de421.bsp to de440s.bsp.

default_ephemeris_path() in module/utils.py resolves the file in this order:

source/de440s.bsp   # preferred
source/de421.bsp    # legacy fallback

The old de421.bsp remains in source/ as a fallback for environments that have not yet received de440s.bsp. Once de440s.bsp is present, it is used automatically — no configuration change needed.

What de440s actually provides

de440s.bsp contains the same set of queryable bodies as de421.bsp:

Mon, 01 Jan 0001 00:00:00 +0000

FastAPI + React + Tauri Integration

Overview

This guide describes the recommended way to use the Python package in a desktop application built from:

React (or Svelte) frontend
FastAPI backend
Tauri packaging

The key idea is to treat the Python package as a reusable computation library, and to keep UI-specific modules optional.

Recommended runtime flow:

Tauri shell
  -> React frontend
  -> HTTP calls to FastAPI on localhost
  -> FastAPI calls module.services / module.workspace / module.storage

Do not build the Tauri app around module/ui_streamlit.py or module/ui_kivy.py. Those files are alternative Python frontends, not the ideal integration surface for Tauri.

Mon, 01 Jan 0001 00:00:00 +0000

Installation and Venvs

This project uses multiple virtual environments so the core backend stays lean while UI wrappers remain optional.

Recommended venvs

venv (base): core backend only
venv-streamlit: Streamlit UI
venv-kivy: Kivy UI
venv-docs: documentation export (imports UI modules)

Makefile targets

Use the Makefile to create isolated environments with pinned dependencies:

make venv (creates venv with requirements/base.txt)
make venv-streamlit (creates venv-streamlit with requirements/streamlit.txt)
make venv-kivy (creates venv-kivy with requirements/kivy.txt)
make venv-docs (creates venv-docs with .[docs] extras)

Notes

A single venv cannot switch environments without uninstalling packages.
Separate venvs avoid heavy or conflicting UI dependencies.

Environment preparation

Create virtual environment:

python3 -m venv venv

Activate virtual environment:

Windows: venv\Scripts\activate
Linux: source ./venv/bin/activate

Install libraries:

Using precompiled lockfiles (recommended):
- Base only: pip install -r requirements/base.txt
- Streamlit UI: pip install -r requirements/streamlit.txt
- Kivy UI: pip install -r requirements/kivy.txt
- Dev all‑in: pip install -r requirements/dev.txt (or top‑level requirements.txt if present)
To (re)compile lockfiles with pip‑tools:
- Base: pip-compile requirements/base.in -o requirements/base.txt
- Streamlit: pip-compile requirements/streamlit.in -o requirements/streamlit.txt
- Kivy: pip-compile requirements/kivy.in -o requirements/kivy.txt
- Dev all‑in: create requirements/dev.in that includes -r requirements/streamlit.in and -r requirements/kivy.in, then: pip-compile requirements/dev.in -o requirements/dev.txt

Run the application:

Default: python3 -m module (runs TUI)
Streamlit UI: python3 -m module --streamlit
Kivy UI: python3 -m module --kivy
TUI explicitly: python3 -m module --tui

Run tests:

See docs/TESTING_GUIDE.md for detailed instructions
Quick start: python3 -m unittest discover tests -v
Or use Makefile: make run_tests

Project structure (core modules):

services.py — chart creation/selection and compute orchestration
utils.py — utilities for date and location parsing
workspace.py — workspace, chart and settings management
z_visual.py — visualization

Dependency management

Dependency definitions live in requirements/ as .in files:
- requirements/base.in contains core runtime deps.
- requirements/streamlit.in and requirements/kivy.in should start with -r base.in.
Reproducible installs use compiled lockfiles in requirements/*.txt.
Dev/all‑in: keep requirements/dev.txt under requirements/. Optionally provide a root requirements.txt that contains -r requirements/dev.txt.

Environment strategy (one venv vs multiple)

A single venv cannot “switch” environments without uninstalling packages; once installed, they persist.
Recommended: use separate venvs per UI target (base, streamlit, kivy, docs) to avoid heavy or conflicting deps.
If you still want one venv, install the base first, then add extras:
- pip install -e . (core only)
- pip install -e ".[streamlit]" or pip install -e ".[kivy]"
- pip install -e ".[docs]" (includes UI deps so make docs can import UI modules)

Sync pyproject from requirements

pyproject.toml is derived from requirements/*.in (not from the compiled .txt lockfiles).

Mon, 01 Jan 0001 00:00:00 +0000

Testing Guide

Overview

This guide covers testing strategies for the Kefer Astrology sidecar module, including CLI handlers, storage functionality, and core computation services.

Test Structure

tests/
├── __init__.py
├── test_cli.py              # CLI command handlers
├── test_storage.py          # DuckDB storage (NEW)
├── test_workspace_flow.py   # Workspace operations
├── test_dates_places.py    # Date/location parsing
├── test_locations.py        # Location handling
├── test_starfisher.py      # Starfisher integration
├── test_polar.py           # Polar coordinates
└── test_docs.py            # Documentation generation

Running Tests

All Tests

python -m unittest discover tests

Specific Test Suite

python -m unittest tests.test_cli
python -m unittest tests.test_storage
python -m unittest tests.test_workspace_flow

With Coverage

pip install coverage
coverage run -m unittest discover tests
coverage report
coverage html  # Generate HTML report in htmlcov/

Test Coverage Status

✅ Covered

CLI handlers (test_cli.py)

Kefer Astrology Documentation

Project Overview

Function layer for Kefer Astrology

Quickstart

Streamlit UI

Streamlit UI

How to Run

Prerequisites

Starting the Application

Features

Configuration

Kivy UI

Kivy UI

How to Run

Prerequisites

Starting the Application

Features

Configuration

Troubleshooting

cli Module

cli module

models Module

models module

Classes

class Annotation

Dataclass fields

class Aspect

Dataclass fields

class AspectContext (str, Enum)

class AspectDefinition

services Module

services module

Functions

build_chart_instance

build_radix_figure_for_chart

Parameters

storage Module

storage module

Functions

get_storage_path

ui_streamlit Module

ui_streamlit module

Functions

main

render_toolbar

How the UI is invoked

utils Module

utils module

Functions

combine_date_time

Parameters

Returns

compute_vernal_equinox_offset

Parameters

workspace Module

workspace module

Functions

add_chart

Parameters

Returns

Notes

add_or_update_chart

z_visual Module

z_visual module

Functions

build_radix_figure

display_3d

display_radial

Parameters

Overview

Repository Structure (top level)

Core Layers

Data Flow

Storage Model

Storage (Backend)

Strategy (Python vs Rust)

CLI Reference

Overview

Usage

Commands

`cli` module

`models` module

class `Annotation`

class `Aspect`

class `AspectContext` (str, Enum)

class `AspectDefinition`

`services` module

`build_chart_instance`

`build_radix_figure_for_chart`

`storage` module

`get_storage_path`

`ui_streamlit` module

`main`

`render_toolbar`

`utils` module

`combine_date_time`

`compute_vernal_equinox_offset`

`workspace` module

`add_chart`

`add_or_update_chart`

`z_visual` module

`build_radix_figure`

`display_3d`

`display_radial`

1. `compute_chart`