DEV Community

Cover image for OpAstro: Building an Open-Core Astrology Engine Developers Can Actually Use
Dakidarts profile image Etuge Anselm
Etuge Anselm for Dakidarts

Posted on

OpAstro: Building an Open-Core Astrology Engine Developers Can Actually Use

#opastro #dakidarts #horoscope #python

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:

This article walks through the full developer experience with practical examples you can copy into real projects.

Why OpAstro Exists

OpAstro CLI

Most teams do not need "mystical randomness." They need:

  1. predictable outputs for a given input
  2. transparent factor mapping
  3. CLI and API ergonomics that fit modern workflows
  4. 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
Enter fullscreen mode Exit fullscreen mode

Smoke test:

opastro --help
opastro doctor
Enter fullscreen mode Exit fullscreen mode

Generate your first report:

opastro horoscope --period daily --sign ARIES --target-date 2026-04-03
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Save profile defaults once 

opastro init
Enter fullscreen mode Exit fullscreen mode

Or save directly:

opastro profile save \
  --name default \
  --sign ARIES \
  --format markdown \
  --set-active
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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"])
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Core endpoints:

  • GET /health
  • POST /horoscope
  • POST /birthday-horoscope
  • POST /planet-horoscope
  • GET /metrics
  • POST /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"}'
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Start with CLI in local dev for UX prototyping.
  2. Integrate Python library in backend worker/services.
  3. Add API mode for downstream app access.
  4. Enable explain mode in admin/debug UI for trust.
  5. Use batch mode for precomputed assets.
  6. 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
Enter fullscreen mode Exit fullscreen mode

Project:

Top comments (0)