fix(docs): verify all Python examples in README + AGENTS against spec, add agent quality guidelines

Author: ph33nx

AGENTS.md

@@ -16,6 +16,16 @@ roxy = create_roxy("your-api-key")
 
 `create_roxy` sets the base URL (`https://roxyapi.com/api/v2`) and auth header automatically. Returns a `Roxy` instance with namespaced domain properties.
 
+## Quality guidelines for agents
+
+- Every method returns `dict[str, Any]`. Access fields with `result["key"]["subkey"]`, never `result.key.subkey` (Python will raise `AttributeError: 'dict' object has no attribute ...`).
+- Method names are snake_case versions of the OpenAPI operationId (e.g. `castThreeCard` -> `cast_three_card`, `analyzeNumberSequence` -> `analyze_number_sequence`). Every sync method has an `_async` variant; use `await` with the async variants.
+- Param names are snake_case versions of the spec param names (`fullName` -> `full_name`, `birthDate` -> `birth_date`, `houseSystem` -> `house_system`). All params are keyword-only.
+- When in doubt about a method or kwarg, check `roxy_sdk.factory` directly or run `python -c "from roxy_sdk import Roxy; help(Roxy)"` - the generated signatures are the contract.
+- Response field names match the OpenAPI spec's response schema exactly. Never invent or pluralize. If a field isn't in the spec, it isn't in the response.
+- Strings everywhere: `date` is `"YYYY-MM-DD"`, `time` is `"HH:MM:SS"`, `timezone` is an IANA name (`"Asia/Kolkata"`, `"America/New_York"`) - the server resolves DST for the chart date. `number` (angel) is `"1111"`, `month` (birthstone) is `"4"`, `number` (hexagram) is `"1"`. Numeric kwargs are only `latitude`, `longitude`, `year`, `month` (numerology), `day`, `count` (tarot draw).
+- Inside `person1` / `person2` dicts any value type works because the kwarg is typed `dict[str, Any]`; only the top-level `timezone` kwarg needs string form.
+
 ## Critical rule: geocode before any chart endpoint
 
 Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint needs `latitude`, `longitude`, and (for Western) `timezone`. **Never ask the user for coordinates.** Always call `roxy.location.search_cities` first.
@@ -90,7 +100,7 @@ Most valuable endpoints are POST:
 ```python
 natal = roxy.astrology.generate_natal_chart(
     date="1990-01-15", time="14:30:00",
-    latitude=28.6139, longitude=77.209, timezone=5.5,
+    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
 )
 
 kundli = roxy.vedic_astrology.generate_birth_chart(
@@ -175,7 +185,7 @@ Ordered by domain priority (Western, Vedic, Numerology, Tarot, Biorhythm, I Chin
 | Biorhythm compatibility | `roxy.biorhythm.calculate_bio_compatibility(person1, person2)` |
 | Daily hexagram | `roxy.iching.get_daily_hexagram(seed="user-123")` |
 | Cast I Ching reading | `roxy.iching.cast_reading()` |
-| Hexagram detail | `roxy.iching.get_hexagram(number=1)` |
+| Hexagram detail | `roxy.iching.get_hexagram(number="1")` |
 | Crystal by zodiac | `roxy.crystals.get_crystals_by_zodiac(sign="aries")` |
 | Crystal by chakra | `roxy.crystals.get_crystals_by_chakra(chakra="heart")` |
 | Dream symbol lookup | `roxy.dreams.get_dream_symbol(id="flying")` |
@@ -191,7 +201,7 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 
 | Field | Format | Good | Bad |
 |-------|--------|------|-----|
-| `timezone` | Decimal hours (float) OR IANA string | `5.5`, `-5`, `0` (decimal) OR `"Asia/Kolkata"`, `"America/New_York"` (IANA, resolved to DST-correct offset for the chart date) | `"5:30"`, `"+0530"`, `"GMT-5"`, partial names |
+| `timezone` | IANA string (typed kwarg) OR decimal number (inside a `dict[str, Any]`) | `"Asia/Kolkata"`, `"America/New_York"`, `"Europe/London"` as the top-level `timezone=` kwarg (server resolves to the DST-correct offset for the chart date). Decimal hours (`5.5`, `-5`, `0`) work as JSON numbers and are accepted only inside `person1`/`person2` dicts because the dict is typed `dict[str, Any]` - the top-level `timezone=` kwarg is typed `str`, so a quoted decimal like `"5.5"` is rejected server-side (validation_error). | `"5.5"` as `timezone=` (rejected, server expects IANA string or a JSON number), `"5:30"`, `"+0530"`, `"GMT-5"` |
 | `date` | ISO date string | `"1990-01-15"` | `"Jan 15 1990"`, `datetime.now()`, `"15/01/1990"`, `"1990-1-15"` |
 | `time` | 24-hour string | `"14:30:00"`, `"09:00:00"` | `"2:30 PM"`, `"14:30"` (no seconds), `"9:0:0"` (no leading zeros) |
 | `latitude` | Decimal degrees (float) | `28.6139` (Delhi), `-33.8688` (Sydney), `40.7128` (NYC) | `"28°36'N"`, `"28 36 50"`, strings |
@@ -212,6 +222,9 @@ These are the fields AI agents most often get wrong. Copy the format column exac
 
 ### Timezone cheat sheet (most-asked locations)
 
+Values are decimal hours. For the typed top-level `timezone=` kwarg, pass the IANA name from `roxy.location.search_cities` (`timezone="Asia/Kolkata"`) - the server resolves it to the correct DST offset for the chart date. Inside a `person1`/`person2` dict the bare decimal works because the dict is typed `dict[str, Any]`, so the JSON-number form below is accepted.
+
+
 | Region | Decimal | Region | Decimal |
 |--------|---------|--------|---------|
 | UTC / London (winter) | `0` | Dubai | `4` |
@@ -260,7 +273,7 @@ Use the SDK for typed Python apps. Use MCP for AI agents (Claude Desktop, Cursor
 - **Async methods end with `_async`.** Every sync method has a matching async variant.
 - **Do not expose API keys client-side.** Call Roxy from server code only.
 - **Date format is `YYYY-MM-DD`, time is `HH:MM:SS`.** Both are strings.
-- **Western `timezone` is required** (decimal hours, `-5` for EST, `5.5` for IST, `0` for UTC). Vedic endpoints accept an optional `timezone` that defaults to `5.5` (IST).
+- **Western `timezone` is required** as an IANA string (`"Asia/Kolkata"`, `"America/New_York"`, `"Europe/London"`, `"UTC"`); the server resolves it to the DST-correct offset for the chart date. Vedic endpoints accept an optional `timezone` (same form) that defaults to IST when omitted. The decimal-number form (`5.5`) is also accepted by the API, but only inside `person1`/`person2` dicts - the top-level `timezone=` kwarg is typed `str`.
 - **Errors raise `RoxyAPIError`.** Catch it and check `e.code`, `e.error`, and `e.status_code`.
 - **Switch on `code`, not `error`.** Codes are stable. Messages may change.
 

README.md

@@ -114,7 +114,7 @@ The global astrology app market is $6.27B and almost entirely Western. These end
 # Natal chart. The #1 Western query, called on every onboarding.
 natal = roxy.astrology.generate_natal_chart(
     date="1990-01-15", time="14:30:00",
-    latitude=28.6139, longitude=77.209, timezone=5.5,
+    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
 )
 
 # Daily horoscope. Highest per-user call frequency in the catalog, drives DAUs and push.
@@ -126,7 +126,7 @@ synastry = roxy.astrology.calculate_synastry(
     person1={"date": "1990-01-15", "time": "14:30:00", "latitude": 28.61, "longitude": 77.20, "timezone": 5.5},
     person2={"date": "1992-07-22", "time": "09:00:00", "latitude": 19.07, "longitude": 72.87, "timezone": 5.5},
 )
-# synastry["compatibilityScore"], synastry["interAspects"], synastry["strengths"]
+# synastry["compatibilityScore"], synastry["interAspects"], synastry["analysis"]["strengths"]
 
 # Moon phase. Viral for wellness, cycle-tracking, meditation apps.
 moon = roxy.astrology.get_current_moon_phase()
@@ -140,7 +140,7 @@ The depth moat. India astrology market: $163M in 2024, projected $1.8B by 2030 (
 # Vedic kundli. Top India astrology keyword. Entry point for every Jyotish product.
 kundli = roxy.vedic_astrology.generate_birth_chart(
     date="1990-01-15", time="14:30:00",
-    latitude=28.6139, longitude=77.209, timezone=5.5,
+    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
 )
 
 # Panchang. Tithi, nakshatra, yoga, karana, rahu kaal, abhijit muhurta in one call.
@@ -151,13 +151,13 @@ panchang = roxy.vedic_astrology.get_detailed_panchang(
 # Vimshottari dasha. Highest-value single-shot Vedic query.
 dasha = roxy.vedic_astrology.get_current_dasha(
     date="1990-01-15", time="14:30:00",
-    latitude=28.6139, longitude=77.209, timezone=5.5,
+    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
 )
 
 # Mangal Dosha. Most-asked matrimonial question in India.
 dosha = roxy.vedic_astrology.check_manglik_dosha(
     date="1990-01-15", time="14:30:00",
-    latitude=28.6139, longitude=77.209, timezone=5.5,
+    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
 )
 
 # Guna Milan. 36-point Ashtakoota matrimonial compatibility score.
@@ -168,7 +168,7 @@ milan = roxy.vedic_astrology.calculate_gun_milan(
 
 # KP ruling planets. Horary answers for "will X happen" questions in real time.
 kp = roxy.vedic_astrology.get_kp_ruling_planets(
-    latitude=28.6139, longitude=77.209, timezone=5.5,
+    latitude=28.6139, longitude=77.209, timezone="Asia/Kolkata",
 )
 ```
 
@@ -197,7 +197,7 @@ High search volume, evergreen. The tarot card database is the highest per-endpoi
 ```python
 # Daily card. Stickiest tarot feature. Seed per user for deterministic once-per-day behavior.
 card = roxy.tarot.get_daily_card(seed="user-42")
-# card["card"]["name"], card["card"]["imageUrl"], card["interpretation"]
+# card["card"]["name"], card["card"]["imageUrl"], card["dailyMessage"]
 
 # Celtic Cross. Professional-reader spread. Premium-tier, ten positions.
 cc = roxy.tarot.cast_celtic_cross(question="What should I focus on?", seed="user-42")
@@ -251,7 +251,7 @@ by_sign = roxy.crystals.get_crystals_by_zodiac(sign="scorpio")
 by_chakra = roxy.crystals.get_crystals_by_chakra(chakra="heart")
 
 # Birthstone. Evergreen gift and jewelry SEO.
-birthstone = roxy.crystals.get_birthstones(month=4)
+birthstone = roxy.crystals.get_birthstones(month="4")
 ```
 
 ### 8. Dream interpretation API (symbol dictionary, search)