astro-engine-search

Astro Engine Search

Overview

Astro Engine search is the astrology-search backend for Astral Hermes. Use it for natural-language questions like:

• “Show me everyone with Moon in Taurus.”
• “Find charts with Mars square Mercury within 4°.”
• “Who is most similar to this chart?”
• “Find dates when Mars, Mercury, and Uranus were conjunct.”
• “Search history for Sun-Moon conjunction windows.”

The service lives at:

https://astro-engine.apps.poofc.com

Local app path:

/home/avalon/apps/astro-engine

UI/client notes

• For Astro Engine chart-browser UI, time stepping, wheel-dial gestures, and SVG inspection pitfalls, see references/chart-browser-ui-and-time-dial.md.

Core Endpoints

GET /api/search/stats
GET /api/charts
GET /api/charts/:id
POST /api/search/corpus
POST /api/search/similar
POST /api/search/time

For the live chart corpus browser/API slice and verification workflow, see references/chart-corpus-browser.md.

Corpus Search

Use corpus search for saved/indexed charts, currently including HD Prism imports.

Example: Moon in Taurus:

curl -sS -X POST https://astro-engine.apps.poofc.com/api/search/corpus \
  -H 'Content-Type: application/json' \
  --data '{"mode":"corpus_search","source":["hd-prism"],"conditions":[{"type":"placement","body":"Moon","sign":"Taurus"}],"limit":10}'

Example: Mars square Mercury within 5°:

{
  "mode": "corpus_search",
  "source": ["hd-prism"],
  "conditions": [
    { "type": "aspect", "bodyA": "Mars", "aspect": "square", "bodyB": "Mercury", "orbMax": 5 }
  ],
  "limit": 10
}

Placement fields:

• body
• sign
• element: fire, earth, air, water
• modality: cardinal, fixed, mutable
• decan: 1, 2, 3
• degreeMin, degreeMax: degree inside sign
• zodiacMin, zodiacMax: absolute longitude 0–360
• retrograde: boolean

Aspect fields:

• bodyA
• bodyB
• aspect: conjunction, sextile, square, trine, opposition
• orbMax

Use exclude for NOT conditions.

Similarity Search

Use similarity search to find charts angularly closest to a chart or to raw placements.

By indexed chart id:

{
  "chartId": 123,
  "source": ["hd-prism"],
  "bodies": ["Sun", "Moon", "Mercury", "Venus", "Mars"],
  "limit": 10
}

By raw placements:

{
  "placements": { "Sun": 183.2, "Moon": 44.5, "Mercury": 350.1 },
  "source": ["hd-prism"],
  "limit": 10
}

Ephemeral Time Search

Use time search for dates/times that match a pattern, not saved charts.

Aspect example:

{
  "start": "2026-06-01T00:00:00Z",
  "end": "2026-06-30T00:00:00Z",
  "coarseHours": 12,
  "refineHours": 2,
  "orbMax": 5,
  "conditions": [
    { "type": "aspect", "bodyA": "Sun", "aspect": "conjunction", "bodyB": "Moon" }
  ],
  "limit": 5
}

Multi-conjunction example:

{
  "start": "2026-01-01T00:00:00Z",
  "end": "2030-01-01T00:00:00Z",
  "coarseHours": 24,
  "refineHours": 1,
  "orbMax": 3,
  "conditions": [
    { "type": "multi_conjunction", "bodies": ["Mars", "Mercury", "Uranus"] }
  ],
  "limit": 20
}

Interpretation Workflow

1. Translate the user’s natural-language request into one of the structured query types.
2. Call Astro Engine.
3. Report the matched labels/times and exact matching facts.
4. If results are empty, loosen orb/range or ask whether to widen the time window.
5. Do not invent chart facts; use API output as source truth.

Verification

For local deployment checks:

cd /home/avalon/apps/astro-engine
npm test
npm run smoke
curl -sS https://astro-engine.apps.poofc.com/api/search/stats