OpAstro: Building an Open-Core Astrology Engine Developers Can Actually Use
If you have ever tried to build astrology features into a product, you probably ran into one of these pain points:
- closed tools with no control over logic
- open projects with weak DX
- engines that compute positions but fail to produce usable outputs
- "black box" responses that are hard to trust or debug
That is exactly why we built OpAstro.
OpAstro is an open-source astrology engine for developers, with:
- deterministic calculations
- Swiss Ephemeris-based astronomical foundations
- an installable Python CLI
- a Python-importable library API
- explainable report generation
- fast local API endpoints
At the same time, OpAstro is intentionally open-core:
- the engine and lite meanings are open
- richer premium editorial narrative layers are offered via https://numerologyapi.com
This article walks through the full developer experience with practical examples you can copy into real projects.
Why OpAstro Exists
Most teams do not need "mystical randomness." They need:
- predictable outputs for a given input
- transparent factor mapping
- CLI and API ergonomics that fit modern workflows
- a clean upgrade path from prototype to production
OpAstro is optimized for that exact workflow:
- prototype quickly from terminal
- integrate from Python service code
- expose via HTTP API
- keep behavior deterministic and testable
Install In Under a Minute
python3 -m pip install -U opastro
Smoke test:
opastro --help
opastro doctor
Generate your first report:
opastro horoscope --period daily --sign ARIES --target-date 2026-04-03
CLI Experience: Designed For Actual Operators
OpAstro is not just "one command." It ships with a full developer command surface.
Core command map
opastro
opastro init
opastro profile list
opastro catalog
opastro doctor
opastro horoscope --period daily --sign ARIES --target-date 2026-04-03
opastro birthday --sign TAURUS --target-date 2026-04-03
opastro planet --period monthly --planet mercury --sign TAURUS --target-date 2026-04-03
opastro explain --kind horoscope --period daily --sign ARIES --target-date 2026-04-03 --json
opastro ui --period daily --sign ARIES --target-date 2026-04-03
opastro batch --kind horoscope --period daily --signs ARIES,TAURUS --date-from 2026-04-03 --date-to 2026-04-05 --format markdown --export-dir reports/batch
opastro serve --host 127.0.0.1 --port 8000 --reload
Save profile defaults once
opastro init
Or save directly:
opastro profile save \
--name default \
--sign ARIES \
--format markdown \
--set-active
Now most commands can run with fewer flags.
Deterministic By Design
For identical inputs, OpAstro returns identical outputs. This is critical for:
- reproducible debugging
- QA snapshots
- analytics consistency
- compliance-friendly behavior in production systems
If you need a different model, pass explicit overrides:
opastro horoscope \
--period weekly \
--sign LEO \
--target-date 2026-06-14 \
--zodiac-system sidereal \
--ayanamsa lahiri \
--house-system placidus \
--node-type true
By default, zodiac mode is tropical. Sidereal is available as an explicit override.
Personalized Mode (Birth Data + Coordinates)
You can anchor reports to birth context for richer personalization:
opastro horoscope \
--period weekly \
--target-date 2026-06-14 \
--birth-date 1997-08-14 \
--birth-time 09:30 \
--lat 4.0511 \
--lon 9.7679 \
--timezone Africa/Douala
This enables house-aware framing where applicable.
Python Library Examples
One of OpAstro's strongest features is that it is easy to import directly in backend code.
Example 1: Daily sign report
from datetime import date
from horoscope_engine.config import ServiceConfig
from horoscope_engine.models import HoroscopeRequest, Period
from horoscope_engine.service import HoroscopeService
service = HoroscopeService(ServiceConfig())
response = service.generate(
HoroscopeRequest(
period=Period.DAILY,
sign="ARIES",
target_date=date(2026, 4, 3),
)
)
print(response.report_type.value, response.sign, response.period.value)
for section in response.sections:
print(section.section.value, "->", section.summary)
Example 2: Personalized weekly report
from datetime import date
from horoscope_engine.config import ServiceConfig
from horoscope_engine.models import BirthData, Coordinates, HoroscopeRequest, Period
from horoscope_engine.service import HoroscopeService
service = HoroscopeService(ServiceConfig())
response = service.generate(
HoroscopeRequest(
period=Period.WEEKLY,
target_date=date(2026, 6, 14),
birth=BirthData(
date=date(1997, 8, 14),
time="09:30",
coordinates=Coordinates(latitude=4.0511, longitude=9.7679),
timezone="Africa/Douala",
),
)
)
print("Resolved sign:", response.sign)
print("Rising sign:", response.data.snapshot.rising_sign)
print("House cusps:", response.data.snapshot.house_cusps)
Example 3: Force sidereal in code
from datetime import date
from horoscope_engine.config import ServiceConfig
from horoscope_engine.models import AyanamsaSystem, HoroscopeRequest, Period, ZodiacSystem
from horoscope_engine.service import HoroscopeService
service = HoroscopeService(ServiceConfig())
response = service.generate(
HoroscopeRequest(
period=Period.MONTHLY,
sign="VIRGO",
target_date=date(2026, 7, 1),
zodiac_system=ZodiacSystem.SIDEREAL,
ayanamsa=AyanamsaSystem.LAHIRI,
)
)
print(response.sign, response.data.snapshot.zodiac_system)
Example 4: Planet-focused generation
from datetime import date
from horoscope_engine.config import ServiceConfig
from horoscope_engine.models import Period, PlanetHoroscopeRequest, PlanetName
from horoscope_engine.service import HoroscopeService
service = HoroscopeService(ServiceConfig())
response = service.generate_planet(
PlanetHoroscopeRequest(
period=Period.MONTHLY,
planet=PlanetName.MERCURY,
sign="TAURUS",
target_date=date(2026, 4, 3),
)
)
print(response.report_type.value)
print(response.sections[0].title)
Example 5: JSON payload for app pipelines
from datetime import date
from horoscope_engine.config import ServiceConfig
from horoscope_engine.models import HoroscopeRequest, Period
from horoscope_engine.service import HoroscopeService
service = HoroscopeService(ServiceConfig())
payload = service.generate(
HoroscopeRequest(period=Period.DAILY, sign="LEO", target_date=date(2026, 4, 3))
).model_dump(mode="json")
print(payload["report_type"], payload["period"], payload["sign"])
Explainability Mode
Modern AI/insight products need provenance. OpAstro ships an explain command so developers can inspect why lines appeared.
opastro explain \
--kind horoscope \
--period daily \
--sign ARIES \
--target-date 2026-04-03 \
--json
This makes it easier to:
- debug section composition
- verify factor influence
- build trust-oriented UX where users can inspect rationale
API Mode For Integration
Start API server:
opastro serve --host 127.0.0.1 --port 8000 --reload
Core endpoints:
GET /healthPOST /horoscopePOST /birthday-horoscopePOST /planet-horoscopeGET /metricsPOST /admin/pregenerate
Example request:
curl -X POST http://127.0.0.1:8000/horoscope \
-H "Content-Type: application/json" \
-d '{"period":"daily","sign":"ARIES","target_date":"2026-04-03"}'
Batch Generation For Content Ops
If you run editorial calendars, BI jobs, or pre-generation workflows, batch mode is a major timesaver:
opastro batch \
--kind horoscope \
--period daily \
--signs ARIES,TAURUS,GEMINI \
--date-from 2026-04-03 \
--date-to 2026-04-07 \
--format markdown \
--export-dir reports/batch
Open Core vs Premium: A Clear Product Boundary
Open in OpAstro
- deterministic calculation engine
- CLI + Python library + local API
- lightweight built-in meanings
- extensible report generation flow
Premium via Numerology API
- richer editorial depth
- advanced narrative packs
- higher-touch production reading experiences
This boundary lets developers ship quickly with confidence while preserving a clear premium path.
Explore premium: https://numerologyapi.com
Practical Adoption Playbook
If you are adopting OpAstro in a product team, this rollout sequence works well:
- Start with CLI in local dev for UX prototyping.
- Integrate Python library in backend worker/services.
- Add API mode for downstream app access.
- Enable explain mode in admin/debug UI for trust.
- Use batch mode for precomputed assets.
- Add premium narrative layer where deeper content is needed.
The astrology toolchain space often forces a tradeoff between openness and usable product quality.
OpAstro tries to avoid that tradeoff:
- open enough for developers to build with confidence
- structured enough for real production usage
- extensible enough to support both lite and premium content strategies
If you are building astrology-powered experiences, this is a strong foundation to start from.
Install now:
python3 -m pip install -U opastro
Project:
- GitHub: https://github.com/dakidarts/opastro
- PyPI: https://pypi.org/project/opastro/
- Premium: https://numerologyapi.com