Home / Engine / Agents and Council Architecture
Updated May 21, 2026 · Affirmology_AgentArchitecture_v1.md
Purpose: Walk Jeff (novice mode, engineering literate) through standing up an agent system that takes name + birth date + birth location and produces a verifiably accurate astrology, numerology, Gene Keys, and Human Design report. Then layer affirmation generation, then a personalized voice-over and video pipeline. Desktop first. Mac mini or cloud later.
Reading order: read this doc top to bottom once. Then open the affirmology-agent/ folder I scaffolded next to it and follow the README to install. The doc explains the why. The code is the how.
The default failure mode of an LLM asked for "my astrology" is plausible-sounding fabrication. The model has read a lot of astrology text, so it pattern-matches your birth data into something that reads like a chart, but the planetary positions, the house cusps, the Human Design gates, and the Gene Keys hexagrams are not calculated. They are guessed from training data and confabulated to be internally consistent. They are often wrong by 5 to 15 degrees, which changes signs, houses, gates, and lines.
The fix is structural, not prompting. The agent never produces a chart fact from its own knowledge. It calls a tool that runs deterministic ephemeris math (Swiss Ephemeris), gets back a JSON of exact positions, and only then interprets. Interpretation is where the LLM adds value. Calculation is where it adds error.
This is the single most important rule in the architecture. The agent is forbidden from speaking about chart positions, gates, lines, profiles, or numerology numbers that did not come back from a tool call. If a tool fails, the agent says so. It does not improvise.
Underneath every agent there are four deterministic calculation engines. They are pure functions. Birth data in, structured chart out. No LLM in the loop yet.
Engine 1: Astrology. Geocodes the birth location to latitude, longitude, and timezone. Converts birth datetime to UTC. Calls Swiss Ephemeris via the pyswisseph Python package for planetary longitudes, house cusps (Placidus by default), aspects, and angles. Output: a JSON of planets with sign, degree, minute, house, retrograde flag.
Engine 2: Human Design. Takes the same ephemeris call result for the Personality (birth moment). Then computes the Design moment, which is the time when the Sun was exactly 88 degrees of solar arc earlier (roughly 88 days before birth, but you must use degrees of arc, not calendar days). Calls Swiss Ephemeris again for the Design moment. Maps each of the thirteen planetary positions (Personality and Design) onto the Rave Mandala gate wheel to produce gate.line activations. Derives type, authority, profile, definition, defined and undefined centers, channels, and incarnation cross from the activated gates.
Engine 3: Gene Keys. Reuses the Human Design gate activations. The Activation Sequence comes from the Personality Sun and Earth (Life's Work and Evolution) and the Design Sun and Earth (Radiance and Purpose). The Venus Sequence (Purpose, Vocation, Culture, Brand) comes from Venus positions in both Personality and Design. The Pearl Sequence (Pearl, IQ, EQ, SQ) comes from Jupiter positions. The Star Pearl extends from Mars positions. Each gate has a shadow, gift, and siddhi frequency in Gene Keys language. The mapping table is static and ships with the codebase.
Engine 4: Numerology. Pure math. Pythagorean system. Life Path from birth date sum-reduced to a single digit or master number (11, 22, 33). Expression Number from full birth name letters mapped to numbers 1 through 9. Soul Urge from vowels only. Personality from consonants only. Current Personal Year, Personal Month, Personal Day from birth date plus current date. Pinnacles and Challenges from period-of-life math. No external API needed. Just a function.
The four engines share one input contract (name, birth_date, birth_time, birth_location) and produce one merged output: a Chart dataclass with sub-objects for astrology, human_design, gene_keys, and numerology. Everything downstream consumes that one object.
The Claude Agent SDK runs an Orchestrator agent that does three things and only three things.
A separate Verification agent runs after generation. It re-reads the report and checks every chart claim in the text against the JSON. Any mismatch fails the run.
This two-agent pattern (generate then verify) is the architectural guard against drift. It is cheap to run because the verifier is a fast small-model call, and it catches the failure mode that destroys credibility in this domain.
Accuracy is a claim, not a feeling. We prove it three ways.
Way 1: known-good fixtures. Jeff's existing chart (Affirmology_AstrologyChart_v1.md) and Josh Parini's Richard Beaumont Human Design report (Affirmology_JoshParini_HumanDesignProfile_v1.md) are encoded as pytest fixtures. Every chart calculation has a test that runs Jeff's and Josh's birth data through the engines and asserts the output matches the human-verified report to within tolerance (1 minute of arc on planets, exact match on gates and lines). If the code drifts, the tests fail before the agent ever runs.
Way 2: external oracle cross-check. A separate verification script lets you paste in the same birth data, get the output, and compare it to:
The verification script produces a side-by-side diff. Anything off by more than tolerance is a bug.
Way 3: edge-case suite. Charts that historically trip up calculators: birth times within an hour of midnight, births in polar latitudes (Placidus fails above ~66 degrees, we fall back to Whole Sign), births during DST transitions, births in cities with historical timezone changes. The test suite includes one chart per edge case with the expected output. Passing this suite is the bar for "accurate enough to put a stranger's data through."
The README in the code project tells you the exact commands to run all three.
What you build: the four engines, the Orchestrator agent, the Verification agent, the test suite, a CLI that takes birth data and prints the four reports to stdout or saves them as markdown files.
What "done" looks like: you can run python -m affirmology.cli --name "Josh Parini" --date 1985-10-21 --time 06:00 --location "San Jose, Costa Rica" and get four markdown reports back. The HD report matches the Richard Beaumont report in the folder. You run it for yourself and the astrology matches the chart we already have on file. You run it for one stranger and check against MyBodyGraph and Astro.com manually. Three for three, no drift.
Time estimate: if I scaffold the code and you wire your API keys, two to four focused sessions to get Phase 1 fully verified.
Cost to run: about $0.05 to $0.20 per full report run (one Claude API call per engine, plus the verifier).
Phase 2 reuses the verified Chart object from Phase 1 and adds a Script Generator agent. The Script Generator gets the chart JSON plus a structured prompt that mirrors the Sacred Audio format you have already validated with Josh (Affirmology_JoshParini_Script_v1.md is the reference structure). The Script Generator outputs a script JSON, with each line tagged to a specific chart element (Gate, planet, line, life-path number). The tagging is the receipts layer.
A second pass calls a Web Research tool (Anthropic web search) to enrich the script with sourced affirmation language and modern context where appropriate. The tool calls return citations, which we keep in the script metadata so the final audio's accompanying methodology PDF can show sources.
The Script Verification agent then checks the script against the chart and refuses anything where a line claims a chart fact not present in the JSON. Same pattern as Phase 1.
Output of Phase 2: a tagged script JSON ready to feed into ElevenLabs.
Each generated chart is a unique permutation of roughly 13 planetary positions, 64 gates, six lines, plus numerology numbers. The combinatorial space is huge but most users cluster around common configurations. Phase 3 caches every generated Chart, Script, and Audio to a Postgres database (Supabase recommended) keyed on a hash of the birth data. Repeat birth data fetches from cache instantly. Near-miss birth data (same city, same hour, different minute) can offer the cached version as a starting point with a re-render flag for personal variation.
Phase 3 also adds a Web Research caching layer. The affirmation enrichment queries for "Virgo Sun 8th house affirmation themes" run once per cluster of users and then serve from cache, with periodic refresh. This is what turns the agent from a per-user expense into a flat-cost system.
Infrastructure: Supabase Postgres for the database. Cloudflare R2 or AWS S3 for the audio and video files. A simple Next.js or FastAPI backend exposes the cache.
Phase 4 takes the verified script JSON and produces the deliverable.
Voice synthesis. ElevenLabs API call with a chosen voice (defaults from your demo build plan: Sarah, Charlotte, Brian, or Will). The script is chunked by section, each section rendered to MP3, then stitched. Cost reference from your existing notes: about $1.50 to $2.50 per audio.
Music bed. Phase 4a uses a pre-generated library of 30 to 50 Suno tracks tagged by mood and tempo. The agent picks the closest match to the chart's tone profile. Phase 4b switches to Suno API when their API access opens up.
Mix. FFmpeg programmatic mix. Voice on top, music at minus 18 dB underneath, fade in and out. About one second of compute per render.
Methodology report. A Claude call generates the Josh Parini-style accompanying report explaining what the chart says and why each script section was chosen. PDF output via the pdf skill.
Video overlay. Remotion is the recommended tool. Each script line's chart tag becomes an on-screen overlay synced to the audio waveform. The user's name appears in the opening frame. Output MP4. Cost reference: $0.10 to $0.50 per render depending on resolution.
Delivery. Output files uploaded to R2, signed URLs generated, email or web dashboard surfaces the link, plus a QR code for events.
Right now: your Mac, in your terminal. The Claude Agent SDK ships as a Python package. You run python -m affirmology.cli and it executes locally. API calls go out over your home internet. This is fine for development, demos to Josh and Colin, and the initial Faena conversations.
Next: a Mac mini in your house or office. Same code, same Python install, but the machine is always on. You set up a launchd service (macOS background process) so the agent boots when the Mac mini boots and exposes a small HTTP endpoint on your local network. You hit it from your phone or laptop and get reports back. This is the "always-on" intermediate step before cloud.
Eventually: a cloud server (Fly.io, Railway, or AWS). Same code, same Python, but containerized in Docker and deployed to a cloud provider. Now anyone on the internet (with your URL) can hit the endpoint. You add Supabase for users and Stripe for payments and you have a product. Fly.io is the smoothest first-cloud step because it deploys Docker containers globally with one command and bills you per second of CPU.
The architectural rule: every phase runs the same Python code. The only thing that changes is where the Python process lives and what front-end calls into it. This is intentional. It means the work you do this week on your laptop becomes the work that runs the company in two years.
Tools you need on your machine. Homebrew (if you do not have it), Python 3.11 or newer, Git, a code editor (VS Code or Cursor).
Accounts and API keys you need.
The README in the code project tells you the exact install commands. I am keeping them out of this doc on purpose so this doc stays the "why" and the README stays the "how."
Before you ever show a generated report to a stranger, you run this protocol.
pytest. All green.Affirmology_AstrologyChart_v1.md next to it. Eyeball every line. Should match.Affirmology_JoshParini_HumanDesignProfile_v1.md next to it. Eyeball every gate, line, channel, profile.This is the protocol that lets you stand on a stage and say "this is calculated, not generated" without flinching.
In the same folder you will find a subfolder called affirmology-agent/. It contains:
README.md: install and run instructions.pyproject.toml: Python dependencies..env.example: where to put your API keys (copy to .env and fill in).src/affirmology/chart/: the four calculation engines (astrology, human_design, gene_keys, numerology).src/affirmology/agents/: the Orchestrator and Verifier agents using the Claude Agent SDK.src/affirmology/reports/: the markdown report templates.src/affirmology/verification/: known-good chart fixtures and the cross-check helpers.src/affirmology/cli.py: the command-line entry point.tests/: the pytest suite that verifies against Jeff's and Josh's known charts.It is a working starter. Some pieces are stubbed (the gate wheel constants need to be verified against an authoritative source, the report templates are seed text not finished prose, and the ElevenLabs hooks are Phase 4 work). The structure is real and runnable today. You install the dependencies, fill in your API keys, run the tests, and you have an honest accuracy verification system on your laptop tonight.
The single next action is to open affirmology-agent/README.md, follow the install steps, and run pytest. The tests will tell you immediately whether the chart math is matching Jeff's and Josh's known reports. From there we iterate on whatever drifts.
After Phase 1 is verified, we have an investor-grade demo of accuracy. After Phase 2, we have the affirmation script generator that produces the JSON for the audio pipeline. After Phase 4, we have the full product that ships at Faena.
The work that gets us to Phase 1 done is roughly two to four focused sessions with me. I would suggest we do session one tonight or tomorrow: you install, we run the tests together, we look at the first failures, we fix them, we get to green.
End of architecture doc. Open the README in affirmology-agent/ next.