DEV Community: GetBirthChart organization

Separating Deterministic Calculations from AI Interpretation

Luis Pham — Fri, 21 Aug 2026 06:24:18 +0000

One rule in GetBirthChart has become more important as I’ve added more AI features:

The AI does not get to invent the chart.

It can explain the chart.

It can compare things in the chart.

It can synthesize several placements into a larger pattern.

But the underlying facts come from code.

The easiest architecture is also the one I didn't want

You could build an astrology AI product like this:

User:
"I was born on Nov 3, 1992 at 2:35 PM in Hanoi."

        ↓

LLM:
"Calculate the birth chart and explain it."

Very little infrastructure.

Very impressive demo.

The problem is that one model is now responsible for two completely different jobs.

First:

Where was Saturn?
What was the Ascendant?
Which house contained Venus?
Is Mars retrograde?

Then:

What might those things mean together?

The first group has deterministic answers under a given calculation methodology.

The second group is interpretation.

I don't want them mixed.

The architecture is deliberately less magical

GetBirthChart works more like this:

birth input
    ↓
Python calculation engine
    ↓
canonical chart facts
    ↓
evidence/context selection
    ↓
LLM
    ↓
interpretation

The Python engine uses Swiss Ephemeris and produces structured chart data.

The model receives that data.

So instead of asking the LLM:

Which sign is the Moon in?

I can give it something like:

{
  "body": "moon",
  "sign": "aquarius",
  "degreeInSign": 21.29,
  "house": 12
}

The language model has a much more appropriate job now:

Explain this placement in the context of the other available chart evidence.

This gives the system a source of truth

Imagine the engine returns:

Moon: Aquarius

and the generated interpretation starts talking about:

your Scorpio Moon

That’s a contradiction I can detect.

Without a deterministic chart model, there isn’t a clean authority to compare the output against.

The LLM becomes the calculator, database and writer at the same time.

That makes QA much harder.

Missing data is even more important

Unknown birth time is a good example.

If birth time is unknown, the engine intentionally omits time-dependent fields.

The model might receive:

{
  "birthTimeKnown": false,
  "angles": {},
  "houses": [],
  "warnings": [
    {
      "code": "UNKNOWN_BIRTH_TIME"
    }
  ]
}

There is no Rising sign in the evidence.

There is no house placement.

That’s much stronger than putting this sentence in the prompt:

Do not make up an Ascendant.

Prompt instructions are useful.

Structural absence is better.

I like evidence-based prompts more than giant context dumps

Another pattern I’ve been using is selecting chart facts as evidence instead of dumping every available field into every generation.

Conceptually:

[
  {
    "id": "moon.sign",
    "value": "Aquarius"
  },
  {
    "id": "moon.house",
    "value": 12
  },
  {
    "id": "moon.square.saturn",
    "orb": 3.2
  }
]

Now a piece of interpretation can be tied back to actual chart facts.

This is useful for the UI too.

A user can eventually ask:

Why are you saying this?

and the product has something better to show than:

The AI thought so.

It can show the relevant calculated evidence.

AI gets better when I give it less authority

This was a little counterintuitive.

The instinct with LLMs is to give them more.

More context.

More freedom.

More responsibility.

But I’ve found the product gets more reliable when the model owns fewer deterministic decisions.

I want code to handle:

timezone conversion
planet positions
houses
aspect geometry
retrograde
schema validation

I want the LLM to handle:

explanation
synthesis
comparison
follow-up reasoning
language

That division is much easier to test.

This isn't specific to astrology

The same architecture makes sense in other domains.

SQL query
   ↓
actual metrics
   ↓
AI explanation

or:

compiler / AST
   ↓
structured findings
   ↓
AI explanation

or:

deterministic pricing engine
   ↓
quote
   ↓
AI explains the quote

If something important can be calculated or retrieved deterministically, I increasingly prefer doing that before the model sees it.

Then the AI can work with evidence instead of pretending to be the evidence source.

The rule I use now

The rule is simple:

Code determines what is in the chart.
AI helps explain what the chart may mean.

That doesn’t eliminate hallucinations.

It doesn’t solve every quality problem.

But it gives the system a stable foundation.

And once you have that, everything from testing to UI explanations gets easier.

The calculation engine behind this architecture is open source here:

https://github.com/getbirthchart-com/gbc-astro-engine

The hosted product using it is:

https://getbirthchart.com/

How I Model Aspects and Orbs in a Python Astrology Engine

Luis Pham — Fri, 21 Aug 2026 06:18:47 +0000

I like working on aspect calculations because the astrology terminology disappears pretty quickly once you get into the code.

At the calculation level, an aspect is basically:

How close are two points on a circle to a configured angle?

That turns the problem into geometry, tolerances and a few interesting edge cases.

Start with angular distance

Suppose two planets have longitudes:

12°
102°

Their separation is 90°.

That’s easy.

But this pair is more interesting:

358°
2°

A normal absolute difference gives you 356°.

On a circle, they’re actually 4° apart.

So one of the basic utilities looks conceptually like this:

def angular_distance(a: float, b: float) -> float:
    delta = abs(a - b) % 360
    return min(delta, 360 - delta)

Now:

angular_distance(358, 2)

returns:

That simple normalization is the base of the rest of the aspect system.

Then define target angles

For the major aspects, you’re comparing against angles such as:

0°    conjunction
60°   sextile
90°   square
120°  trine
180°  opposition

If everything had to be exact, the implementation would be trivial.

But astrology uses orbs.

So a separation of 92° can still be treated as a square depending on the calculation profile.

The orb is basically:

orb = abs(actual_distance - target_angle)

Then:

if orb <= allowed_orb:
    # aspect matched

I keep orb rules in a profile

This is one of those places where hidden constants are really tempting.

Something like:

MAX_ORB = 8

and move on.

I prefer putting this kind of behavior into an explicit calculation profile.

That way the result isn’t just:

Venus square Saturn

It can be understood as:

Venus square Saturn
under this aspect profile
with this orb

That makes the methodology easier to inspect and makes future changes much less messy.

The engine reports geometry, not sentiment

This was another boundary I wanted to keep clean.

The core can calculate:

planet A
planet B
aspect type
orb
phase

It should not calculate:

good
bad
easy
terrible relationship

Those are interpretation-layer concepts.

I don’t want this in the chart model:

{
  "aspect": "square",
  "meaning": "negative"
}

The geometry doesn’t know that.

It knows there is a 90-degree relationship within the configured tolerance.

That separation makes the output usable by different interpretation systems later.

Applying vs separating

Once the static aspect is identified, there’s another useful piece of information: motion.

Is the pair moving toward exactness or away from it?

For that you need more than longitude.

You need the bodies’ motion as well.

The ephemeris provides longitudinal speed, which lets the engine derive whether the aspect is:

applying
exact
separating

Then the structured result can look conceptually like:

{
  "type": "square",
  "orb": 2.1,
  "phase": "applying"
}

The application can decide whether and how to interpret that.

Again, the core just reports the calculated state.

This code is nice to test

Aspect math gives you some good invariants.

For example:

distance(a, b) == distance(b, a)

The distance must always be in:

0° <= distance <= 180°

And wraparound behavior needs direct tests:

359° vs 1° = 2°

Orb boundaries are useful too:

orb == maximum → match
orb > maximum → no match

These are the kinds of tests I trust much more than checking a few screenshots from the frontend.

A pattern I keep using

This part of the engine is a good example of how I like to structure domain logic.

Start with the smallest deterministic representation.

Instead of:

Venus square Saturn means relationship restriction.

start with:

Venus longitude
Saturn longitude
angular separation
target angle
allowed tolerance
motion

Get that part right first.

Then let another layer decide what, if anything, the relationship means.

It keeps the calculation code boring.

I mean that as a compliment.

The aspect implementation is part of the open-source GetBirthChart Python engine:

https://github.com/getbirthchart-com/gbc-astro-engine

The Hard Part of Birth Chart Calculations Isn't the Zodiac. It's Time.

Luis Pham — Fri, 21 Aug 2026 06:16:17 +0000

The most annoying bugs I’ve dealt with while building a birth-chart engine were not about zodiac signs.

They were about time.

And the deeper I got into it, the more I realized that “birth time” is a much less simple input than it looks on a form.

A local datetime isn't enough

Take this:

1990-05-15 09:30

It looks precise.

But precise where?

Without a timezone, it doesn’t identify an instant.

So the calculation API I use takes both the local datetime and the IANA timezone:

chart = engine.natal(
    local_datetime="1990-05-15T09:30:00",
    timezone="Europe/London",
    latitude=51.5074,
    longitude=-0.1278,
)

I prefer an IANA zone like Europe/London over something like UTC+1.

The former describes a real timezone with historical rules.

The latter is just an offset.

DST makes this more interesting

During a daylight-saving fall-back transition, the same local clock time can occur twice.

So a value like:

01:30

may correspond to two different UTC instants.

That means the input looks exact to the user while still being ambiguous to the calculation engine.

There’s a strong temptation to quietly choose one.

I don’t like doing that.

If the input is genuinely ambiguous, I’d rather make the ambiguity explicit.

The same thing happens in the opposite direction during spring transitions.

Some local clock times never existed.

If the clock jumped directly from 01:59 to 03:00, then:

02:30

isn’t a valid local instant.

Again, silently “fixing” it is convenient.

But now the software has changed the user’s data.

Then there’s the bigger problem: no birth time

A lot of people simply don’t know what time they were born.

This creates a product decision.

You can say:

unknown → 12:00 PM

and suddenly everything works.

You get:

Ascendant
houses
house cusps
Midheaven

The object looks complete.

But none of those values are based on a birth time the person actually supplied.

That bothered me enough that I made unknown birth time a first-class state in the engine.

chart = engine.natal(
    local_datetime="1992-11-03",
    timezone="Asia/Ho_Chi_Minh",
    latitude=21.0285,
    longitude=105.8542,
    unknown_time=True,
)

The result intentionally omits time-dependent fields.

No fake Rising sign.

No fake houses.

No fake precision.

Incomplete output can be more correct

Developers generally like complete data structures.

Something like:

{
  "ascendant": "Cancer",
  "house": 7
}

feels satisfying.

This:

{
  "ascendant": null,
  "house": null
}

feels like a failure.

But if the user doesn’t know the time, the second object is actually saying something more truthful.

The system is distinguishing:

I know the value.

from:

I have a field available where a value could go.

Those aren’t the same thing.

The Moon makes it even more interesting

Even without a birth time, you can still calculate a lot from the date.

But not everything has the same level of certainty.

The Moon moves fast enough that its exact degree — and occasionally even its sign near a boundary — can depend on the time of day.

So unknown-time handling can’t just be:

remove the Ascendant and everything else is exact.

You need to communicate uncertainty where it actually exists.

That’s one reason I like carrying warnings as structured output from the core rather than bolting them onto the UI later.

The UI should be reflecting the calculation state, not inventing its own policy.

This changed how I think about UX

Initially, I thought timezone and missing-time behavior were backend concerns.

Now I think they’re part of the product experience.

When the site tells someone:

Rising sign requires a reliable birth time.

that should not be marketing copy.

It should describe an actual engine constraint.

That connection is important to me.

The best trust messages in software are usually backed by behavior.

Not promises.

This isn’t really an astrology-specific lesson

The same problem appears whenever software works with incomplete or uncertain inputs.

Geolocation.

Financial records.

Sensor data.

AI-extracted structured fields.

User demographics.

There’s always a temptation to turn missing data into complete-looking data because downstream code becomes easier.

Sometimes the better API is the one willing to say:

unknown

I’ve become much more comfortable with that while building this engine.

The Python core is open source here:

https://github.com/getbirthchart-com/gbc-astro-engine

If you work with timezone-heavy applications, the astrology part is probably the least interesting thing in that repo. The time-handling decisions are where a lot of the real engineering lives.

Building a Natal Chart Engine in Python: From Birth Data to Planetary Positions

Luis Pham — Thu, 20 Aug 2026 09:24:22 +0000

When I started working on a natal-chart engine, I assumed the interesting part would be zodiac calculations.

It wasn't.

Mapping a longitude to a zodiac sign is one of the easier parts.

The harder problem is building a pipeline where every step has an explicit meaning.

The input a user gives you is usually something like:

November 3, 1992
2:35 PM
Hanoi, Vietnam

The astronomical layer needs something much less human:

UTC instant
latitude
longitude
calculation profile
ephemeris

The job of the engine is to get from one to the other without quietly making decisions the caller didn't ask for.

Step 1: keep local time and timezone separate

One thing I deliberately avoid is treating a local datetime as if it already describes an absolute instant.

This:

1992-11-03 14:35

is incomplete.

You still need a timezone.

In the engine interface, they're separate:

chart = engine.natal(
    local_datetime="1992-11-03T14:35:00",
    timezone="Asia/Ho_Chi_Minh",
    latitude=21.0285,
    longitude=105.8542,
)

The timezone uses an IANA identifier rather than a fixed UTC offset.

That matters because historical timezone and DST rules aren't always equivalent to:

UTC+7

Step 2: convert the local civil time to an astronomical instant

Once the local datetime has been resolved, the calculation layer can convert it to UTC and then to the time representation expected by the ephemeris.

Conceptually:

local civil time
      ↓
timezone rules
      ↓
UTC
      ↓
Julian day

There are edge cases here that are easy to miss.

During a DST fall-back transition, the same clock time may occur twice.

During spring-forward, some clock times don't exist at all.

I prefer rejecting an ambiguous input to silently choosing one possibility.

This is a general engineering principle I've become more attached to:

Ambiguity should be represented in the API, not hidden inside a default.

Step 3: ask an ephemeris for planetary positions

The engine uses Swiss Ephemeris through pyswisseph.

For each supported body, the provider gives us values including ecliptic longitude and longitude speed.

A longitude might conceptually look like:

221.1415°

Now we're finally at the familiar astrology part.

Step 4: longitude → sign + degree

A zodiac is a 360° circle divided into 12 sections of 30°.

So the basic mapping is simple:

sign_index = int(longitude // 30)
degree_in_sign = longitude % 30

For example:

221.1415°

lands in the eighth 30° segment:

Scorpio 11.1415°

This part is deterministic and uncomplicated.

Which is exactly why I don't want an LLM doing it.

Step 5: calculate houses and angles

Now things get more sensitive to time and location.

For a known birth time, the engine can calculate:

Ascendant
Midheaven
Descendant
IC
house cusps
planet-to-house assignments

The default profile uses Placidus, although the core supports multiple house systems.

This is where latitude also becomes important.

Some house systems have geographic limits.

For example, I prefer raising an explicit calculation error in unsupported polar conditions rather than silently switching the user to another house system.

Again: no invisible fallback.

Step 6: derive aspects

Once the body positions are available, aspects become a circular-distance problem.

For two longitudes:

a = 358.0
b = 2.0

the distance is not 356°.

It's 4°.

A common normalization is conceptually:

delta = abs(a - b) % 360
distance = min(delta, 360 - delta)

Then the engine compares the distance to configured aspect angles.

For example:

conjunction   0°
sextile      60°
square       90°
trine       120°
opposition  180°

with different orb allowances.

The engine can then publish structured facts such as:

{
  "type": "square",
  "orb": 2.1,
  "phase": "applying"
}

instead of forcing the interpretation layer to rediscover the geometry.

Step 7: normalize everything into one chart model

This is one of the parts I underestimated.

The astronomy isn't enough.

The application needs a stable contract.

The engine eventually turns the calculations into a normalized chart object containing things like:

subject
meta
bodies
angles
houses
aspects
derived facts
warnings

That model is what the rest of GetBirthChart consumes.

The frontend shouldn't need to know how Swiss Ephemeris works.

The AI layer shouldn't need to know how to normalize circular angles.

The API shouldn't implement its own astrology math.

They all consume the same chart model.

Why this separation is useful

It creates a very clear dependency graph:

Swiss Ephemeris
      ↓
Python calculation core
      ↓
canonical chart model
      ↓
API / UI / interpretation

If a planet position is wrong, I debug the core.

If the API serialized it incorrectly, I debug the transport.

If an interpretation is poor, I debug the interpretation layer.

Without those boundaries, bugs become much harder to classify.

The surprising lesson

The interesting part of an astrology engine isn't really “how do I calculate Scorpio?”

It's how you handle everything around the calculation:

civil time
DST ambiguity
unknown inputs
geographic limitations
calculation profiles
structured errors
deterministic output
test fixtures

The zodiac mapping is maybe ten lines.

The trustworthiness of the software lives in everything around those ten lines.

Why I Open-Sourced the Python Calculation Engine Behind GetBirthChart

Luis Pham — Thu, 20 Aug 2026 09:21:32 +0000

I’ve been building GetBirthChart for a while, and one thing kept bothering me.

From the outside, a birth chart app can look like one big black box.

You enter a date, time and place. A chart appears. Then an interpretation appears.

But those are actually two very different problems.

One is calculation.

The other is interpretation.

I wanted that boundary to be obvious, not just in the UI, but in the architecture itself.

So I open-sourced the Python calculation engine behind GetBirthChart.

The part AI shouldn’t be doing

GetBirthChart uses AI for interpretation.

But I don’t want an LLM deciding where the Moon was when someone was born.

That belongs in deterministic code.

The architecture is roughly:

birth data
   ↓
Python calculation engine
   ↓
structured chart data
   ↓
application / interpretation layer
   ↓
AI + UI

The Python layer calculates the chart.

The AI layer receives the result and explains it.

That distinction sounds simple, but it changes a lot.

If the interpretation says someone has a Scorpio Moon, there should be a calculated Moon placement behind that statement.

The model shouldn’t “know” the placement from training data or try to reconstruct it itself.

What the engine handles

The core is written in Python and uses Swiss Ephemeris for the astronomical calculations.

It handles things such as:

planetary positions
zodiac placements
houses
Ascendant and Midheaven
aspects and orbs
retrograde state
normalized chart output

A basic calculation looks roughly like this:

from gbc_astro import AstrologyEngine

engine = AstrologyEngine()

chart = engine.natal(
    local_datetime="1992-11-03T14:35:00",
    timezone="Asia/Ho_Chi_Minh",
    latitude=21.0285,
    longitude=105.8542,
)

print(chart.bodies["sun"].sign)
print(chart.bodies["moon"].sign)

The interesting part is not really that you can turn 221 degrees of longitude into Scorpio.

That part is easy.

The difficult parts tend to be around the edges:

timezone conversion
daylight saving transitions
unknown birth times
house-system limits
circular angle math
aspect tolerances
making every assumption explicit

Those are also the things I wanted people to be able to inspect.

Why make it public?

Partly because I think calculation software should be inspectable.

If someone sees a chart result and asks:

Why did this calculator give me this Ascendant?

“Trust the website” isn’t a very useful answer.

With the engine public, the actual calculation path can be inspected and tested.

But there was another benefit I didn’t expect as much.

Open-sourcing it forced me to clean up the architecture.

Private code can survive with assumptions that only the original developer understands.

Public code is much less forgiving.

I had to make things like calculation profiles, errors, warnings and output structures clearer.

That made the production system better too.

Unknown birth time is a good example

This was one of the design choices I cared about from the beginning.

If someone says:

I don’t know what time I was born.

the easiest implementation is to pick a default.

Noon is common.

Midnight is common too.

That gives you a nice complete chart.

It also creates a Rising sign and houses from a birth time the user never gave you.

I didn’t want to do that.

The engine has an explicit unknown-time mode instead.

chart = engine.natal(
    local_datetime="1992-11-03",
    timezone="Asia/Ho_Chi_Minh",
    latitude=21.0285,
    longitude=105.8542,
    unknown_time=True,
)

Time-dependent parts of the chart are then omitted rather than silently fabricated.

That means the resulting object may be less complete.

I think that’s a feature.

I’d rather return:

Ascendant: unavailable
Houses: unavailable

than return confident-looking information based on a fake noon birth time.

Open source isn’t a claim that astrology is science

This is another boundary I want to keep clear.

Publishing the code makes the software inspectable.

It doesn’t prove astrology.

The engine answers a technical question:

Given these inputs and these calculation rules, what chart does the software produce?

Interpretation is a different layer.

GetBirthChart treats that layer as a reflective framework rather than a scientific prediction system.

I think the product becomes more honest when those two things are separated.

The bigger lesson for me

The part I like most about this architecture has very little to do with astrology.

It’s this:

deterministic domain logic
        ↓
structured evidence
        ↓
AI interpretation

I’m using the same idea more and more in products that involve LLMs.

If something has a deterministic answer, calculate it outside the model.

Give the model good evidence.

Then let the model do what it’s actually good at: explaining, comparing and synthesizing.

The Python engine is now public here:

GitHub: https://github.com/getbirthchart-com/gbc-astro-engine

And the hosted implementation is what powers:

GetBirthChart: https://getbirthchart.com/

I’ll probably write more about the less obvious parts of building it, especially timezone handling, unknown birth times and aspect calculations. Those turned out to be much more interesting engineering problems than I expected.