Metadata-Version: 2.4
Name: hermetic-alpha
Version: 0.1.2
Summary: Core Python research engine for astro-financial pattern analysis.
Project-URL: Homepage, https://github.com/wauputr4/hermetic-alpha-library
Project-URL: Documentation, https://github.com/wauputr4/hermetic-alpha-library/blob/main/README.md
Project-URL: Repository, https://github.com/wauputr4/hermetic-alpha-library
Project-URL: Issues, https://github.com/wauputr4/hermetic-alpha-library/issues
Project-URL: Changelog, https://github.com/wauputr4/hermetic-alpha-library/blob/main/CHANGELOG.md
Author: Hermetic Alpha Contributors
License: MIT
License-File: LICENSE
Keywords: astro-finance,astrology,event-study,market-research,python-library
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: ephemeris
Requires-Dist: pyswisseph>=2.10; extra == 'ephemeris'
Description-Content-Type: text/markdown

# Hermetic Alpha Library

**Hermetic Alpha Library** is the core research engine for exploring statistical relationships between astrological configurations and financial market behavior.

The library is designed to calculate planetary positions, derive astrological aspects, transform them into quantitative features, and evaluate their relationship with market outcomes such as bullish probability, local tops, local bottoms, and forward returns.

> This project does not claim deterministic prediction. It provides transparent tools for statistical research, event studies, and reproducible backtesting.

Hermetic Alpha is not financial advice and should not be used as a standalone
trading signal. Any observed relationship between astrological features and
market outcomes must be interpreted as exploratory until it is supported by
adequate sample size, baseline comparison, confidence intervals, and validation
on data that was not used to discover the pattern.

See the [anti-overfitting guide](docs/anti-overfitting.md) for the project
rules on responsible probability reporting, leakage prevention, and
cherry-picking control.

## Goals

- Compute planetary positions and astrological aspects for historical timestamps.
- Convert chart configurations into machine-readable features.
- Analyze whether specific aspects correlate with market behavior.
- Support event-study workflows for assets such as Bitcoin.
- Provide reusable Python APIs for CLI, notebooks, and future web applications.

## Initial Scope

The first version focuses on:

- Natal/transit-style chart calculation for timestamps.
- Major aspects: conjunction, opposition, trine, square, sextile.
- Configurable orb ranges.
- Market return labels across multiple horizons.
- Conditional probability analysis.
- Event-study summaries.
- Exportable CSV/JSON results.

## Planned Python Package

```python
from hermetic_alpha.analysis import summarize_event_study
from hermetic_alpha.astro import detect_aspect
from hermetic_alpha.labels import add_forward_returns

closes = [100, 110, 99, 120, 95, 128]
labels = add_forward_returns(closes, horizons=[1, 7, 30])

aspect = detect_aspect(
    body_a="sun",
    longitude_a=10,
    body_b="jupiter",
    longitude_b=12,
    aspect="conjunction",
    max_orb=3,
)

assert aspect is not None
result = summarize_event_study(labels, event_indexes=[0, 1], horizon=1)
print(result)
```

Export library result objects without adding runtime dependencies:

```python
from hermetic_alpha.exports import to_csv, to_json

json_text = to_json(result)
csv_text = to_csv([result])
```

CSV export is intentionally limited to flat rows. Flatten nested research
structures before writing CSV so downstream column names remain explicit.

## Repository Role

This repository contains only the reusable core logic. User-facing tools such as command-line interfaces, APIs, and dashboards should call this library instead of duplicating analysis logic.

## Development Quickstart

### Install package

Jika `hermetic-alpha` sudah dipublish ke PyPI, ini adalah cara paling sederhana:

```bash
python3 -m pip install hermetic-alpha
```

Jika belum dipublish, install dari Git tag/repository GitHub:

```bash
python3 -m pip install "git+https://github.com/wauputr4/hermetic-alpha-library.git@v0.1.2"
```

Atau dari arsip tag GitHub (jika tersedia jaringan ke GitHub):

```bash
python3 -m pip install "https://github.com/wauputr4/hermetic-alpha-library/archive/refs/tags/v0.1.2.tar.gz"
```

Opsional fitur ephemeris nyata:

```bash
python3 -m pip install "git+https://github.com/wauputr4/hermetic-alpha-library.git@v0.1.2#egg=hermetic-alpha[ephemeris]"
```

Untuk kontribusi pengembangan:

```bash
python3 -m pip install -e ".[dev,ephemeris]"
```

Create a local development environment with `uv` when it is available:

```bash
uv venv
uv pip install -e ".[dev]"
uv run python3 -m pytest -q
```

Or use the standard library `venv` plus `pip`:

```bash
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -U pip
python3 -m pip install -e ".[dev]"
python3 -m pytest -q
```

The `pyproject.toml` pytest configuration sets `pythonpath = ["src"]`, so tests
can import the package directly from the source tree even before an editable
install is created.

```bash
python3 examples/basic_event_study.py
```

Fetch normalized BTC daily candles through the first market provider and write
the local JSON cache with the library storage helper:

```bash
python3 examples/provider_to_cache.py data/btc-daily.json --start 2024-01-01 --end 2024-01-31
```

Yahoo Finance is a convenient research input, not an audit-grade market feed.

When the development extra is installed:

```bash
python3 -m pytest -q
```

## Quick Start Penelitian

Langkah cepat untuk jalankan riset dari nol:

1. Buat label market dari close:

```bash
python3 - <<'PY'
from hermetic_alpha.labels import add_forward_returns
returns = add_forward_returns([100, 110, 99, 120, 95, 128], [1, 7, 30])
print(returns)
PY
```

2. Jalankan contoh alur sintetik lengkap (conjunction Sun-Moon vs return 1d):

```bash
python3 examples/synthetic_astronomy_return_case.py
```

3. Jalankan contoh real-market (data harga nyata dari Yahoo Finance):

```bash
python3 examples/real_market_astronomy_return_case.py
```

Untuk mode yang lebih kuat (multi-asset dan walk-forward), jalankan:

```bash
python3 examples/real_market_astronomy_return_case.py \
  --assets BTC-USD,ETH-USD,SOL-USD \
  --start 2025-01-01 \
  --end 2026-01-01 \
  --horizon 1 \
  --aspects conjunction,square \
  --bodies sun,moon \
  --max-orb 1.0 \
  --walk-forward-train-size 200 \
  --walk-forward-test-size 60 \
  --walk-forward-step-size 60
```

4. Baca flow riset + catatan anti-overfitting di:

- [Research workflow docs](docs/research-workflow.md)
- [Anti-overfitting guide](docs/anti-overfitting.md)

## License

MIT
