---
name: astro
description: 'The sky over a place and date -- moon phase, sunrise and sunset -- computed, not fetched. Tools: daylight, moon-phase, sun-times. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: world
  tools: daylight.py, moon-phase.py, sun-times.py
---

# Astro

The sky over a place and date -- moon phase, sunrise and sunset -- computed, not fetched.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/daylight.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `daylight.py`

How light it is outside right now at a latitude and longitude, as one number from 0 (night) to 1 (the sun overhead): the sine of the sun's altitude, computed with ephem (no network). A body can grow by it.

Use when an agent's body or a card wants daylight now as a single number, e.g. a plant that opens in the sun.

```sh
<skill-dir>/daylight.py -p lat="<lat>" -p lon="<lon>" --output light.txt
```

Parameters:
- `lat` (string, required) — Latitude in decimal degrees, e.g. 43.65
- `lon` (string, required) — Longitude in decimal degrees, east positive, e.g. -79.38

Outputs:
- `light.txt` — copy out with `--output light.txt[=<host path>]`

Runs in `ofthemachine/python3@sha256:59784cff1945b7d6093a591b5e5292b8c989f0691af0494fbbe1c6b8083a16cb`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `moon-phase.py`

The Moon's phase on a given UTC date, computed with ephem (no network): phase name, percent illuminated, and the dates of the next new and full moon. One line, ready for a dateline or an almanac box. The date is a parameter, never the clock, so the same inputs always give the same answer.

Use when the user asks what phase the moon is in or when the next full or new moon is, or an almanac, dateline, or caption needs the moon for a specific date.

```sh
<skill-dir>/moon-phase.py -p date="<date>"
```

Parameters:
- `date` (string, required) — UTC date as YYYY-MM-DD

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `sun-times.py`

Sunrise, sunset, and day length for a latitude, longitude, and UTC date, computed with ephem (no network). Times are printed in the given UTC offset so a caller can pass the local zone; the day-length delta against the day before says whether days are getting longer or shorter. Companion to net/ip-location.py, whose lat,lon this takes.

Use when the user asks when the sun rises or sets somewhere, how long the day is, or an almanac or weather box needs sun times for a place and date.

```sh
<skill-dir>/sun-times.py -p lat="<lat>" -p lon="<lon>" -p date="<date>" [-p utc_offset=0]
```

Parameters:
- `lat` (string, required) — Latitude in decimal degrees, e.g. 53.5457
- `lon` (string, required) — Longitude in decimal degrees, east positive, e.g. -113.5
- `date` (string, required) — UTC date as YYYY-MM-DD
- `utc_offset` (string, optional, default `0`) — Hours to add when printing times, e.g. -6 for Edmonton in September

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.
