---
name: astro-engine-search
description: Use when Alex asks to search astrology charts or time for placements, aspects, similar charts, historical/future planetary configurations, or Astro Engine chart-browser UI/time-dial work.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [astrology, astro-engine, search, corpus, similarity, transits]
    related_skills: [astral-chart-api, astrology-reading-compose]
---

# 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:

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

Local app path:

```text
/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

```text
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:

```bash
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°:

```json
{
  "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:

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

By raw placements:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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