{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Cosmic Ephemeris Python quickstart\n",
    "\n",
    "This notebook uses synthetic inputs and requires `cosmicephemeris-client==0.5.0`. It makes two billable requests: one birth chart and one event calendar. Admitted failures also consume quota, so the notebook does not retry automatically.\n",
    "\n",
    "Keep credentials out of notebook cells and outputs. Set `COSMICEPHEMERIS_KEY` in the private environment of the machine running Jupyter before opening this file. Clear outputs before sharing a modified notebook.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install --disable-pip-version-check --quiet cosmicephemeris-client==0.5.0\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import json\n",
    "import os\n",
    "from pathlib import Path\n",
    "\n",
    "from cosmicephemeris_client import CosmicEphemerisClient\n",
    "\n",
    "if not os.environ.get(\"COSMICEPHEMERIS_KEY\"):\n",
    "    raise RuntimeError(\"Set COSMICEPHEMERIS_KEY in the private Jupyter server environment, then restart the kernel.\")\n",
    "\n",
    "# Version 0.4.0 retains event_calendar's 35-second deadline for its 30-second engine budget.\n",
    "# 35 seconds covers its 30-second engine budget; it is not a response-time promise.\n",
    "client = CosmicEphemerisClient(timeout=35)\n",
    "print(\"Client ready. The API key was read from the environment and was not displayed.\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Calculate a synthetic birth chart\n",
    "\n",
    "Replace synthetic inputs only with data you are authorized to process.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "birth_input = {\n",
    "    \"date\": \"2000-01-01\",\n",
    "    \"time\": \"12:00\",\n",
    "    \"timezone\": \"UTC\",\n",
    "    \"lat\": 0,\n",
    "    \"lon\": 0,\n",
    "    \"zodiac\": \"tropical\",\n",
    "}\n",
    "birth_chart = client.birth_chart(birth_input)\n",
    "print(\"Calculated chart type:\", birth_chart.get(\"type\"))\n",
    "print(\"Planet count:\", len(birth_chart[\"chart\"][\"planets\"]))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Create a spreadsheet-ready event calendar\n",
    "\n",
    "The event-calendar route can return an opt-in, fixed-column UTF-8 CSV string. CSV is not a generic API input format, and most operations return JSON only. The client above uses an explicit 35-second deadline to cover this route's 30-second engine budget.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "calendar_input = {\n",
    "    \"start_utc\": \"2026-11-01T00:00:00Z\",\n",
    "    \"end_utc\": \"2026-11-08T00:00:00Z\",\n",
    "    \"event_types\": [\"moon_phase\", \"aspect\"],\n",
    "    \"bodies\": [\"sun\", \"moon\"],\n",
    "    \"aspects\": [\"conjunction\"],\n",
    "    \"display_timezone\": \"UTC\",\n",
    "    \"include_csv\": True,\n",
    "}\n",
    "event_calendar = client.event_calendar(calendar_input)\n",
    "csv_text = event_calendar[\"result\"][\"csv\"]\n",
    "with open(\"cosmic-ephemeris-events.csv\", \"w\", encoding=\"utf-8\", newline=\"\") as output:\n",
    "    output.write(csv_text)\n",
    "print(\"Wrote cosmic-ephemeris-events.csv with\", event_calendar[\"result\"][\"event_count\"], \"events.\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Save the complete JSON responses\n",
    "\n",
    "The CSV is convenient for spreadsheets. Preserve JSON when you need full metadata, exact response structure, or fields that are not represented in a route-specific CSV export.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "output_path = Path(\"cosmic-ephemeris-results.json\")\n",
    "output_path.write_text(\n",
    "    json.dumps({\"birth_chart\": birth_chart, \"event_calendar\": event_calendar}, indent=2, ensure_ascii=False),\n",
    "    encoding=\"utf-8\",\n",
    ")\n",
    "print(\"Wrote\", output_path)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
