DEV Community: Luis Pham

I Turned the GetBirthChart Astrology Engine Into a Python Package

Luis Pham — Sat, 22 Aug 2026 07:20:40 +0000

A few weeks ago, I open-sourced the Python calculation engine behind GetBirthChart.

The source was public, but using it still meant cloning the repository, setting up the environment, and understanding the internal package structure.

That is useful if you want to inspect the code.

It is less useful if you just want to use the engine.

So I packaged it properly.

Today, gbc-astro can be installed directly from PyPI:

pip install gbc-astro

The source remains open on GitHub.

But now the calculation engine can also behave like what it really is: a Python library.

I didn't want to create a second engine

This was the most important constraint.

GetBirthChart already had a working calculation engine.

Publishing to PyPI should not create another implementation.

I wanted this:

GetBirthChart
      ↓
  gbc-astro
      ↑
Python package

Not this:

GetBirthChart → engine A

PyPI           → engine B

So the public package is a thin interface around the same calculation code used by GetBirthChart.

A basic chart looks like this:

from gbc_astro import calculate_chart

chart = calculate_chart(
    date="1990-05-15",
    time="09:30",
    latitude=51.5074,
    longitude=-0.1278,
    timezone="Europe/London",
)

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

Underneath that function, the package still delegates to the existing engine.

calculate_chart(...)
        ↓
AstrologyEngine.natal(...)
        ↓
calculation providers
        ↓
Swiss Ephemeris

No separate astrology math was introduced for PyPI.

What the package calculates

The engine currently handles things like:

planetary positions
zodiac placements
houses
Ascendant and Midheaven
aspects
retrograde state
timezone-aware birth data
derived chart data
structured warnings

Swiss Ephemeris is accessed through pyswisseph.

One thing I wanted to preserve exactly was how the engine handles missing information.

Unknown birth time is still unknown

This has been one of the design decisions I care about most in GetBirthChart.

If the birth time is unknown, the library does not silently invent one.

For example:

from gbc_astro import calculate_chart

chart = calculate_chart(
    date="1990-05-15",
    time=None,
    latitude=51.5074,
    longitude=-0.1278,
    timezone="Europe/London",
)

time=None means the birth time is actually unknown.

The engine does not quietly substitute 12:00.

Time-dependent values are omitted instead.

Conceptually:

birth_time_known = False
angles = {}
houses = ()
rising = None

This matters because the Ascendant and houses depend on birth time.

A library should not turn missing input into fake precision just because a complete-looking result is easier to return.

The HTTP API is optional

GetBirthChart also uses the engine behind a FastAPI service.

But someone installing a calculation library should not need FastAPI and Uvicorn unless they actually want the HTTP layer.

The normal installation is:

pip install gbc-astro

For the API dependencies:

pip install "gbc-astro[api]"

So the architecture stays fairly simple:

Python application
       ↓
   gbc-astro

HTTP service
       ↓
FastAPI adapter
       ↓
   gbc-astro

Same engine, different interface.

Package version and engine version are not always the same thing

Packaging also forced me to separate two versions that are easy to confuse.

The current package version is:

1.12.2

The calculation engine version is:

1.12.1

That difference is intentional.

Version 1.12.2 was a packaging and distribution release.

It did not change the underlying astrology calculations.

So I did not bump the calculation engine version just to make the numbers look identical.

I would rather have the versions describe what actually changed.

Making a release traceable

Once the package was public, I also wanted a clear path from an installed Python package back to its source.

The project now has three public representations:

GitHub
  ↓
source code

PyPI
  ↓
installable package

Zenodo
  ↓
archived release

The 1.12.2 source release is archived on Zenodo with this DOI:

10.5281/zenodo.22052875

A DOI does not validate the astrology.

It does not prove that a calculation is correct.

It simply gives this particular software release a persistent, citable identifier.

For open-source infrastructure, that is useful.

Someone looking at the package later can trace it back to a specific archived release instead of relying only on whatever happens to be on the repository's main branch at that time.

Packaging exposed assumptions

The interesting part of turning the engine into a package wasn't uploading a wheel.

It was deciding what the public contract should be.

Which functions should be public?

Which exceptions should developers rely on?

What happens when birth time is missing?

Which dependencies belong in the core package?

Should the HTTP layer be installed by default?

Can a clean Python environment reproduce a real chart?

Can a published package be traced back to its source?

Those questions already existed when the engine was private infrastructure.

Publishing it just made them harder to ignore.

And I think that's one of the useful side effects of open sourcing internal systems.

It forces implicit assumptions to become explicit interfaces.

Try it

Install the package:

pip install gbc-astro

PyPI:

https://pypi.org/project/gbc-astro/1.12.2/

Source code:

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

Archived release:

https://zenodo.org/records/22052875

DOI:

https://doi.org/10.5281/zenodo.22052875

GetBirthChart:

https://getbirthchart.com/

I'm going to keep documenting the less obvious parts of building this engine — especially time handling, house calculations, testing, uncertainty, and the boundary between deterministic calculations and AI interpretation.

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.

The goal is not to turn each placement into an isolated personality statement.

A useful interpretation looks at how placements, houses and aspects interact — where they reinforce one another, where they create tension, and where similar themes appear repeatedly across the chart.

The model can then synthesize those relationships into a more coherent reading instead of simply stitching together separate descriptions for the Sun, Moon, Venus or other placements.

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.

What I Learned About Latency While Building a Real-Time Voice AI Agent

Luis Pham — Fri, 08 May 2026 13:10:00 +0000

What I Learned About Latency While Building a Real-Time Voice AI Agent

When I started building a real-time voice AI agent, I thought about latency mostly as an engineering problem.

Reduce the delay.

Make the response faster.

Stream audio as quickly as possible.

That is still true.

But after working on RingBooker, an AI receptionist for salons, spas, med spas, and beauty clinics, I started to think about latency differently.

Latency is not only a technical metric.

On a phone call, latency is part of the user experience.

A small delay feels bigger on the phone

In a web app, a short delay is usually fine.

A button can show a loading state.

A page can display a spinner.

A chatbot can show typing dots.

The user understands that something is happening.

A phone call does not have that same visual feedback.

When the caller stops talking and the AI does not respond, even a short pause can feel strange.

The caller may wonder:

“Did it hear me?”

or:

“Is the call still connected?”

That emotional reaction matters.

The system might be working perfectly in the background, but the caller does not see that.

They only hear silence.

End-to-end latency matters more than one number

At first, it is tempting to measure only one part of the system.

Model response time.

Speech-to-text time.

Text-to-speech time.

Network delay.

But the caller experiences the whole chain.

For a voice AI agent, the real question is:

How long does it take from the moment the caller stops speaking to the moment they hear a useful response?

That path can include:

caller audio
voice activity detection
speech-to-text
intent understanding
model response
tool calls or retrieval
text-to-speech
audio streaming back to the caller
telephony network behavior

Optimizing one piece helps, but it does not always fix the felt experience.

The full loop is what matters.

“Fast” is not always the same as “natural”

This surprised me.

I assumed faster would always feel better.

But if the AI responds too instantly, it can feel unnatural.

Humans usually leave tiny pauses in conversation.

They breathe.

They process.

They acknowledge.

They sometimes say “okay” before moving forward.

A voice AI that snaps back too quickly can feel robotic, even if the latency is technically great.

So the goal is not always the lowest possible delay.

The goal is a response rhythm that feels alive and useful.

Some delays are more acceptable than others

Not all latency feels the same.

If the caller asks a simple question, they expect a quick answer.

Example:

“Are you open today?”

A long delay here feels bad.

But if the caller asks something more complex, a short pause can feel normal.

Example:

“Can you help me find an appointment for a color service next week?”

In that case, a small delay may be acceptable if the AI acknowledges what is happening:

“Let me get a few details first.”

or:

“I can help collect that request.”

The user experience depends on context.

This is where product design and engineering meet.

Silence needs design

One thing I learned is that silence cannot be ignored.

If the system needs time, the conversation should make that clear.

This does not mean adding filler everywhere.

Too much filler is annoying.

But the AI needs ways to keep the caller oriented.

For example:

acknowledge the request
ask one clear follow-up question
avoid long unexplained pauses
do not overtalk while processing
hand off when the request is too specific

A lot of voice UX is about making the caller feel that the system is still present.

Tool calls make latency more complicated

For a simple conversation, the AI can respond directly.

But real products often need tools.

For local businesses, a voice agent may need to:

check business hours
understand service rules
collect appointment details
look up knowledge base information
prepare a call summary
decide whether to hand off

Every tool call can add delay.

This creates a tradeoff.

More context can make the answer better.

But too much waiting can make the call feel worse.

The question becomes:

Does this tool call improve the caller experience enough to justify the delay?

That is not only an engineering question.

It is a product question.

Call summaries changed how I thought about latency

Early on, I wanted the AI to answer as much as possible during the call.

But for local businesses, the after-call summary is often just as important.

The caller needs a fast, useful interaction.

The business needs structured context after the call.

That means the AI does not always need to solve everything live.

Sometimes it is better to keep the call simple, collect the right information, and give the business a clear next step.

This reduces pressure on the live conversation.

It also avoids forcing the caller to wait while the AI tries to do too much.

Latency affects trust

This is probably the most important lesson.

When a voice AI pauses awkwardly, talks over the caller, or responds too slowly, the problem is not just speed.

The problem is trust.

The caller may start to feel:

“This is not reliable.”

For salons, spas, med spas, and other appointment-based businesses, that matters.

A caller might be trying to book a same-day service, ask about a consultation, reschedule, or decide whether the business feels responsive.

The phone call is part of the trust-building process.

If the AI feels slow or confused, the business may feel slow or confused too.

That is why latency is not just a backend concern.

It is a brand experience.

What I would measure

If I were starting from scratch, I would measure latency in layers.

Not only:

How fast did the model respond?

But also:

how long until speech was detected
how long until the caller’s intent was understood
how long until the first useful audio came back
how often the AI talked over the caller
how often the caller interrupted
how often the AI needed to recover
how often a human handoff was needed

The raw timing is useful.

But the conversation outcome matters more.

A fast bad answer is still a bad answer.

Final thought

Latency in voice AI is not just about making the system faster.

It is about making the conversation feel responsive.

The caller should feel heard.

The AI should avoid awkward silence.

The system should not overtalk.

The business should receive useful context.

That is the hard part.

The best voice AI products will not only optimize milliseconds.

They will optimize the feeling of the call.

The Hidden UX Problem in Voice AI: When Should the AI Stop Talking?

Luis Pham — Sun, 03 May 2026 13:08:00 +0000

The Hidden UX Problem in Voice AI: When Should the AI Stop Talking?

One of the hardest parts of building a voice AI product is not making the AI talk.

It is knowing when the AI should stop talking.

I did not fully appreciate this at the beginning.

When I started building RingBooker, an AI receptionist for salons, spas, med spas, beauty clinics, I was focused on the obvious problems:

Latency.

Speech recognition.

Call routing.

Booking intent.

Call summaries.

Those are all important.

But the more I worked on real phone-call flows, the more I realized that silence, interruption, and timing are part of the product.

Text AI can explain. Voice AI has to pace itself.

In a text interface, long answers can still work.

The user can skim.

They can scroll.

They can reread.

They can ignore parts of the answer.

On a phone call, the user cannot skim.

They have to listen in real time.

That means every extra sentence costs attention.

A voice agent that gives a complete answer may still feel bad if it talks for too long.

This is especially true for local business calls.

A caller usually does not want a long explanation. They want to know what to do next.

The AI should not fill every silence

This was one of my early mistakes.

I assumed silence was always bad.

So I wanted the AI to respond quickly, keep the conversation moving, and avoid awkward pauses.

But not every pause needs to be filled.

Sometimes the caller is thinking.

Sometimes they are checking their calendar.

Sometimes they are asking someone next to them.

Sometimes they are about to correct themselves.

If the AI jumps in too quickly, it feels pushy.

If it waits too long, it feels broken.

That middle ground is harder than it sounds.

Interruptions are not edge cases

In voice AI, interruption handling is not a feature you add later.

It is core UX.

People interrupt naturally.

They say:

“Actually, wait...”

or:

“No, I meant tomorrow.”

or:

“Can I ask something else?”

If the AI ignores that and keeps talking, the user immediately feels that they are not being heard.

This is different from text.

In text, the assistant can finish its response and the user can reply after.

On a call, the timing itself communicates whether the AI is listening.

A good voice agent needs shorter answers

This is one of the product rules I keep coming back to.

For phone calls, shorter is usually better.

Not because the user is impatient, but because voice is linear.

The caller cannot jump ahead.

For example, if someone calls a salon and asks:

“Do you have anything today?”

The AI does not need to explain the entire booking process.

It probably needs to say something like:

“I can help check the request. What service are you looking for?”

Then collect the useful details.

The goal is not to sound smart.

The goal is to move the call forward.

The AI should ask one thing at a time

This is another lesson from phone UX.

In a chatbot, you can ask multiple questions at once:

What service do you need, what day works best, and do you have a preferred provider?

That can work in text.

On a call, it often fails.

The caller may answer only one part.

Or they may forget the first question.

Or they may respond vaguely.

For voice, one question at a time usually works better.

Bad:

“What service are you looking for, what time do you prefer, and is there a specific stylist?”

Better:

“What service are you looking for?”

Then:

“Do you have a preferred day or time?”

Then:

“Do you have a preferred stylist?”

It feels slower on paper, but it is often smoother in conversation.

Knowing when to hand off is part of the UX

Sometimes the best thing the AI can do is stop trying to solve the call.

This is especially true when the caller asks for something sensitive, complex, or very specific.

For example:

a medical-aesthetic treatment question that needs professional judgment
a pricing question that depends on consultation
a complaint
a caller who repeatedly asks for a human
a policy exception
a complicated reschedule

In those moments, continuing to talk can hurt trust.

A good voice agent should be comfortable saying:

“I’ll pass this to the team so they can follow up with the right answer.”

That is not failure.

That is good product behavior.

The summary should replace unnecessary talking

Another thing I learned: the AI does not need to explain everything to the caller if the real value is in the follow-up.

For local businesses, the call often has two users:

The caller.

The business team.

The caller wants a quick response.

The business wants clean context.

So instead of making the AI over-explain, the product can capture the details and send the team a useful summary.

That means the AI can keep the call shorter while still creating value.

Voice AI needs boundaries, not just intelligence

A lot of AI products are designed to show how capable the model is.

But on the phone, capability without restraint can feel uncomfortable.

The AI should know:

When to answer.

When to ask a follow-up.

When to pause.

When to stop.

When to hand off.

Those decisions shape the user experience as much as the model quality.

Maybe more.

What I am trying to optimize for

For RingBooker, I am not trying to make the AI sound like the most impressive receptionist in the world.

I am trying to make it useful in the calls a beauty business normally misses:

After-hours calls.

Peak-hour overflow.

Same-day requests.

Reschedules.

Consultation inquiries.

Human handoff requests.

In those moments, the AI does not need to dominate the conversation.

It needs to help the caller feel heard and give the business enough context to act.

Final thought

The hidden UX problem in voice AI is restraint.

Knowing what to say matters.

But knowing when to stop talking may matter even more.

A voice AI agent should not try to win the conversation.

It should help the caller get to the next step.

Why Voice AI for Local Businesses Is Harder Than a Chatbot

Luis Pham — Thu, 30 Apr 2026 12:06:00 +0000

Why Voice AI for Local Businesses Is Harder Than a Chatbot

I used to think a voice AI agent was basically a chatbot with audio.

User speaks.

AI understands.

AI replies.

That was the simple version in my head.

But after working on RingBooker, an AI receptionist for salons, spas, med spas, and beauty clinics, I started to see voice AI very differently.

A chatbot can be useful even when it feels a little slow.

A phone call cannot.

Text gives the user more patience

When someone uses a chatbot, they expect a short delay.

They can see the answer being generated.

They can reread the message.

They can scroll back.

They can pause before replying.

The experience gives them space.

A phone call does not.

On a call, silence feels uncomfortable almost immediately.

If the AI waits too long, the caller may think the call dropped.

If the AI replies too quickly, it can feel unnatural.

If the AI talks too much, the caller interrupts.

That makes the timing much harder to get right.

Voice AI has to feel alive

In text, the user judges the quality mostly by the final answer.

In voice, the user judges the whole interaction.

The pause before the answer.

The tone.

The interruption handling.

The confidence.

The moment when the AI says “Let me check that.”

The way it handles uncertainty.

Even when the underlying model is good, the experience can still feel bad if the voice flow is awkward.

This was one of the first things I had to accept:

The model is only one part of the product.

The conversation design is just as important.

Interruptions are normal, not edge cases

In a chatbot, the flow is usually clean.

The user sends a message.

The assistant replies.

Then the user sends another message.

Phone calls are not like that.

People interrupt.

They correct themselves.

They ask a second question before the first one is answered.

They start with one intent and change it halfway through.

For local businesses, this happens all the time.

A salon caller might say:

“Do you have anything today? Actually, tomorrow morning would be better.”

A med spa caller might say:

“I’m interested in laser. Wait, is that the same as IPL?”

A spa caller might ask:

“How much is a massage? Also, do you have couples appointments?”

If the AI cannot handle interruptions, the caller feels trapped inside a script.

That is not a good experience.

The input is messy

Most AI demos happen in clean environments.

Real phone calls do not.

People call from cars.

They call from busy rooms.

They speak quietly.

They use vague words.

They ask incomplete questions.

They may not know the correct service name.

For a chatbot, messy input is annoying.

For a phone agent, messy input is the default.

This changes the product design.

The AI has to ask follow-up questions, but not too many.

It has to collect useful information, but not sound like a form.

It has to be helpful, but not overconfident.

That balance is difficult.

Local businesses need boundaries

One mistake I see in many AI product ideas is trying to make the AI do everything.

Answer every question.

Book every appointment.

Handle every exception.

Replace every human step.

For local businesses, I think that is the wrong starting point.

A salon, spa, or med spa does not need an AI that pretends to be perfect.

They need an AI that can reliably help with the calls the team cannot always answer.

That might mean:

answering after-hours calls
collecting booking intent
asking for preferred time
capturing service details
summarizing the call
handing off when needed

The handoff is not a failure.

Sometimes the handoff is the product working correctly.

Trust is more fragile on the phone

In a chatbot, a wrong answer is bad.

On a phone call, a wrong answer can feel worse.

The caller is giving attention in real time. They may be trying to book something, ask about pricing, reschedule, or decide whether the business feels trustworthy.

If the AI sounds too confident about something it should not promise, trust drops.

If it pretends to know a policy it does not know, trust drops.

If it refuses to hand off when the caller asks for a human, trust drops.

For appointment-based businesses, trust matters because the call is often part of the buying decision.

This is especially true for services like hair color, skin treatments, injections, laser, massage, or first-time consultations.

The caller is not only asking for information.

They are testing whether the business feels responsive.

The transcript is not enough

At first, I thought the transcript would be one of the most important outputs.

But the more I thought about the workflow, the more I realized most business owners do not want to read long transcripts.

They want the useful summary.

Who called?

What did they want?

How urgent was it?

What service were they asking about?

What should the team do next?

A clean summary can be more useful than a perfect transcript.

This is one of the biggest differences between building a demo and building a product.

The demo is about showing that the AI can talk.

The product is about helping the business take action after the call.

The goal is not to sound impressive

A good voice AI product should not be measured only by how smart it sounds.

For local businesses, I think the better questions are:

Did it answer quickly?

Did it understand the caller’s intent?

Did it avoid making promises it should not make?

Did it know when to ask a follow-up question?

Did it know when to hand off?

Did it send the team something useful?

That is a more practical benchmark.

It is also harder than it sounds.

What I would build around first

If I were starting again, I would not start with the most complex booking flow.

I would start with the most common missed-call situations:

After-hours callers.

Busy-hour overflow.

Same-day appointment requests.

Reschedules.

Basic pricing questions.

Consultation inquiries.

Human handoff requests.

These are not the most glamorous flows, but they are the ones that happen every day.

And for a local business, capturing one missed opportunity can matter more than having a perfect AI demo.

Final thought

Voice AI is not just chatbot logic plus speech.

It is a different product surface.

The user experience is faster, messier, and less forgiving.

That is what makes it hard.

But that is also what makes it interesting.

For local businesses, the phone is still where many high-intent customers show up. If AI can help answer those calls without pretending to replace the human team, I think there is a real product there.

Building an AI Receptionist for Salons: What Was Harder Than I Expected

Luis Pham — Tue, 28 Apr 2026 06:47:08 +0000

Building an AI Receptionist for Salons: What Was Harder Than I Expected

I’m building RingBooker, an AI receptionist for salons, spas, med spas, and other appointment-based businesses.

When I started, I thought the product was mostly about the AI.

Answer the phone.

Understand the caller.

Collect the booking details.

Send the business a summary.

Simple enough.

It turned out the hard part was not only the AI model. The hard part was the phone call itself.

A phone call has no “loading state”

With a chatbot, a user can wait.

They can see the message is generating. They can scroll back. They can reread the answer.

On a phone call, silence feels broken.

Even a short delay can make the caller wonder:

“Is this still listening?”

That changed how I thought about latency.

At first I was looking at latency like a normal backend metric. How fast is the response? How long does the model take? How quickly can the audio come back?

But in a real phone call, the user does not care about the number.

They care about whether the conversation feels alive.

The caller will interrupt

This was another thing I underestimated.

In text, the flow is clean. User sends a message. Assistant replies.

On a call, people interrupt constantly.

They start with one request, then change it halfway through.

“Do you have anything today? Actually tomorrow is better.”

“I need a refill. Wait, maybe a full set.”

“Can I speak to someone? No, actually I just want to know the price first.”

If the AI keeps talking when the caller is trying to correct something, the whole experience feels wrong.

Barge-in is not a small feature. It is part of the core UX.

Local business calls are messy

A lot of AI demos assume the user gives clean input.

Real callers do not.

They speak from cars.

They call from noisy rooms.

They use vague phrases.

They ask two questions at once.

They sometimes do not know the exact service name.

For salons and spas, this is common.

A caller may say “nails” when they mean acrylic full set.

A med spa caller may ask about “laser” without knowing which treatment.

A hair salon caller may ask for “color” without knowing whether it is highlights, root touch-up, or correction.

So the AI cannot just collect form fields. It has to ask enough follow-up questions without making the call feel like an interrogation.

That balance is harder than I expected.

The summary matters more than the transcript

At first I cared a lot about the transcript.

Then I realized the business owner probably does not want to read a full call transcript.

They want the useful part:

who called
what they wanted
how urgent it was
what questions they asked
what should happen next

For a busy salon owner, a clean summary is more valuable than a perfect transcript.

This changed the product direction for me.

The call itself is only half the product. The handoff to the business is the other half.

The AI should not try to handle everything

This is probably the biggest lesson so far.

It is tempting to make the AI answer every question and complete every flow.

But for real businesses, that is risky.

Some calls should go to a human.

Some questions depend on policy.

Some prices depend on consultation.

Some callers just want reassurance.

A useful AI phone agent needs to know its boundary.

For RingBooker, I started thinking less about “AI replacing the front desk” and more about “AI covering the calls the team cannot answer.”

That framing feels much healthier.

The existing phone number is part of the product

This was not obvious to me at the beginning.

For many local businesses, the phone number is everywhere:

Google Business Profile, website, ads, Instagram, business cards, printed signs, old customers’ phones.

Asking them to change that number is a huge ask.

So call forwarding became an important part of the product idea.

The business should be able to keep the number customers already know, while RingBooker sits behind the front-desk line for missed, overflow, or after-hours calls.

It sounds like a small detail, but for local businesses it is a big trust issue.

What I would tell another builder

If you are building a voice AI product, do not start only with the model.

Start with the awkward parts of the call.

What happens when the caller interrupts?

What happens when the audio is bad?

What happens when the AI is unsure?

What happens when the caller asks for a human?

What happens after the call ends?

Those edge cases are not edge cases for long. They become the product.

Final thought

I still think voice AI will become very important for local businesses.

But I no longer think the goal is to make the AI sound impressive.

The goal is simpler and harder:

Answer quickly.

Be clear.

Do not overpromise.

Know when to hand off.

Give the business a useful next step.

That is the version of the product I’m trying to build.