hermetic-alpha 0.1.2__tar.gz

hermetic_alpha-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install runtime and test dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python3 -m pytest -q
+
+      - name: Smoke import check
+        run: |
+          python3 - <<'PY'
+          import hermetic_alpha
+          from hermetic_alpha.labels import add_forward_returns
+          from hermetic_alpha.analysis import summarize_event_study
+
+          labels = add_forward_returns([100, 110, 99, 120, 95, 128], [1, 7])
+          result = summarize_event_study(labels, [1, 2], 1)
+          assert result.events == 2
+          assert isinstance(hermetic_alpha.__version__, str)
+          assert hermetic_alpha.__version__.count(".") == 2
+          print("smoke ok")
+          PY

hermetic_alpha-0.1.2/.github/workflows/publish-pypi.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Validate built artifacts
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        if: github.event_name == 'workflow_dispatch' || github.event_name == 'release' || startsWith(github.ref, 'refs/tags/')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

hermetic_alpha-0.1.2/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+
+# Local data and outputs
+data/*
+!data/.gitkeep
+outputs/
+
+# OS/editor
+.DS_Store
+.vscode/
+.idea/

hermetic_alpha-0.1.2/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## [Unreleased]
+
+- Work in progress.
+
+## [0.1.2] - 2026-06-05
+
+### Added
+- Add standard OSS distribution metadata in `pyproject.toml` (project urls, keywords, version bump).
+- Add `CHANGELOG.md`.
+- Add import-time smoke test in CI.
+- Improve README quick start with standard `pip install` flow and non-PYTHONPATH usage.
+
+### Changed
+- Synchronize package version constant (`src/hermetic_alpha/__init__.py`) with project version.
+- Update release tagging to `v0.1.2` for packaging alignment.
+
+## [0.1.1] - 2026-06-04
+
+### Added
+- Real market research workflow docs and scripts.
+- Synthetic and real-market astrology-case examples.
+
+### Changed
+- Improve fallback handling and CSV/JSON export consistency for research scripts.
+
+## [0.1.0] - 2026-06-01
+
+- Initial packaged research engine release.

hermetic_alpha-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to Hermetic Alpha Library
+
+Thank you for considering a contribution.
+
+## Project Principles
+
+- Keep research reproducible.
+- Avoid deterministic financial claims.
+- Report sample size and baseline comparisons.
+- Keep core logic independent from CLI, API, and web UI concerns.
+- Update documentation and troubleshooting notes after meaningful code changes.
+
+## Local Development
+
+Preferred setup with `uv`:
+
+```bash
+uv venv
+uv pip install -e ".[dev]"
+uv run python3 -m pytest -q
+```
+
+Standard `venv` setup:
+
+```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 development extra installs `pytest`, and the repository's
+`pyproject.toml` config points pytest at `src/` and `tests/`.
+
+```bash
+PYTHONPATH=src python3 examples/basic_event_study.py
+```
+
+When the development extra is installed:
+
+```bash
+python3 -m pytest -q
+```
+
+## Documentation
+
+Before opening a pull request, update relevant files in `docs/`, especially `docs/troubleshooting.md` for implementation notes, known limitations, or environment issues.

hermetic_alpha-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermetic Alpha Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermetic_alpha-0.1.2/PKG-INFO

@@ -0,0 +1,230 @@
+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

hermetic_alpha-0.1.2/README.md

@@ -0,0 +1,203 @@
+# 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

hermetic_alpha-0.1.2/docs/README.md

@@ -0,0 +1,32 @@
+# Hermetic Alpha Library Documentation
+
+This documentation describes the design, research logic, statistical methods, and implementation plan for **Hermetic Alpha Library**.
+
+Hermetic Alpha Library is the reusable Python core for astro-financial pattern research. It should remain independent from any CLI, API, notebook, or web dashboard.
+
+## Documentation Map
+
+- [Overview](overview.md)
+- [Architecture](architecture.md)
+- [Research Concepts](concepts.md)
+- [Anti-Overfitting Guide](anti-overfitting.md)
+- [Statistical Methods](statistical-methods.md)
+- [Data Model](data-model.md)
+- [Implementation Roadmap](roadmap.md)
+- [Troubleshooting Notes](troubleshooting.md)
+- [ADR 0001: First Ephemeris Engine](adr/0001-first-ephemeris-engine.md)
+- [Research Workflow + Quick Start](research-workflow.md)
+
+## Core Philosophy
+
+Hermetic Alpha should be built as a transparent research engine, not a black-box prediction system.
+
+The project should help answer questions such as:
+
+- How often did Bitcoin rise after a specific astrological aspect?
+- Is the result better than the baseline market probability?
+- How many historical events support the observation?
+- Is the effect stable across different time periods?
+- Are there similar past chart configurations?
+
+Every result should be reproducible, inspectable, and statistically cautious.