siiha-sdk 0.1.8

SIIHA SDK — Natural language → Google Calendar create-event with dedupe

SIIHA - SDK

What is SIIHA SDK?

SIIHA is a micro-resilience assistant that blends emotional awareness × suggestion maps × workspace tools.
SIIHA SDK v0.1.8 exposes focused capabilities:

• Parse natural language → structured event (parse_event, beta)
• Create Google Calendar events (create_calendar_event) with built-in dedupe
  It’s designed for local OAuth, terminal-first workflows, and consistent behavior across CLI / UI integrations.

---

Features (v0.1.8)

• 🗓️ Google Calendar – Create Event
  • zh/EN natural-language parsing for dates/times, location, attendees.
  • Cross-day handling (e.g., 晚上11點到凌晨1點).
  • 下個月 [date] with month-end clamp; explicit year (e.g., 2026/1/2).
  • Location markers 地點：/location:、@ Zoom / at ...；attendees extraction & dedupe.
• 🧠 Parser (beta) parse_event(text, tz='Asia/Taipei')
  • Supports relative time
    • EN: now + 90 min, 90 minutes from now, 90 minutes later, 1.5 hours from now
    • ZH: 現在+90分鐘, 此刻+90分鐘, 90分鐘後, 一個半小時後, 現在+1.5小時
  • Duration phrases (for 30 minutes / 1.5 小時) and bare hour ranges 9-10 → 09:00–10:00.
  • Auto roll to next day when a “today-only time” has already passed (with a brief grace window). For now/later patterns, start time anchors to “now” without roll.
  • Returns flags (e.g., rolled_to_next_day) and a heuristic confidence.
• 🔁 Idempotent creation (dedupe): same instant (timezone-normalized) + normalized title within the same day → treated as duplicate.
• 🧩 Configurable: DEFAULT_TIMEZONE, DEFAULT_CALENDAR_ID, GOOGLE_SEND_UPDATES.

---

Example (natural input)

Meet with Marketing team tomorrow 3PM, location: HQ Meeting Room 2, attendees: [e-mail]

---

Quickstart

0) Prerequisite

python --version           # >= 3.10 (3.11 recommended)
python -m pip install -U pip
python -m pip install -U build twine pytest

1) OAuth setup (Desktop app)

1. In Google Cloud Console, create OAuth 2.0 Client (Desktop).
2. Download the client secrets as credentials.json and place it at the project root.
3. Run a one-time bootstrap to generate token.json (also kept at root):

python quickstart.py

Required scopes (minimum):

• https://www.googleapis.com/auth/calendar.events
• (or the broader) https://www.googleapis.com/auth/calendar Keep credentials.json and token.json private. They are in .gitignore by default.

2) Install (editable for development)

cd C:\Users\(YOURFOLDER)\siiha-sdk
python -m build                 # (optional) build wheel & sdist into dist/
python -m pip install -e .      # recommended for local dev

---

Usage

A) Parse → Create (minimal)

from siiha_sdk.calendar import parse_event, create_calendar_event

text = "下個月 5號 下午3點到4點 和Joshua討論 OAuth，地點：Teams，邀請 [e-mail]
"
parsed = parse_event(text, tz="Asia/Taipei")
# parsed keys: title, body, location, attendees, start, end, timeZone, confidence, flags

res = create_calendar_event(
  title = parsed["title"],
  start_iso = parsed["start"],
  end_iso = parsed["end"],
  location = parsed["location"] or None,
  attendees = parsed["attendees"],
  description= parsed["body"] or None,
  timezone = parsed["timeZone"],
  dedupe = True,
)
print(res) # {'ok': True, 'eventId': ..., 'deduped': False/True, ...}

B) Relative “now” examples

from siiha_sdk.calendar import parse_event
for s in [
    "now + 90 min",
    "90 minutes from now",
    "現在+90分鐘",
    "一個半小時後",
]:
    print(s, "=>", parse_event(s, tz="Asia/Taipei"))

C) Target a test calendar (avoid polluting primary)

• Set environment variable SIIHA_TEST_CALENDAR_ID=your_test_calendar_id or
• Override in code:

from siiha_sdk import config
config.DEFAULT_CALENDAR_ID = "your_test_calendar_id"

---

Dedupe behavior

A newly created event is considered a duplicate iff:

1. the start instant matches an existing event (RFC3339-equivalent across timezones), and 2 the normalized title matches (trim, whitespace collapse, comma normalization, case-fold).

Location / attendees differences do not affect dedupe.

---

Tests

Parser smoke test

python tests/quickstart_create_event.py

Dedupe scenarios (creates events)

# (optional) direct events to a test calendar
# PowerShell:
$env:SIIHA_TEST_CALENDAR_ID="your_test_calendar_id"
# Bash:
export SIIHA_TEST_CALENDAR_ID=your_test_calendar_id

python tests/dedupe_scenarios.py

(Tip) You can tag test events by passing description="#SDK_TEST" to create_calendar_event(...) and clean them later via a small script.

---

Configuration

These live in siiha_sdk/config.py:

• DEFAULT_TIMEZONE = "Asia/Taipei"
• DEFAULT_CALENDAR_ID = "primary"
• GOOGLE_SEND_UPDATES = "all" (Google will email updates to attendees)

Override at runtime:

from siiha_sdk import config
config.DEFAULT_TIMEZONE = "Asia/Tokyo"
config.DEFAULT_CALENDAR_ID = "your_cal_id"
config.GOOGLE_SEND_UPDATES = "none"  # or "externalOnly" / "all"

---

Known limitations

• All-day events, recurrence, reminders, and conferenceData (Meet links) are not supported yet.
• Language coverage is focused on common zh/EN patterns; other languages/phrases may need extensions.
• Description is optional and not auto-generated (except when you pass one).
• Dedupe checks only within the same local day window at creation time.
• confidence is a heuristic guidance score.
• For explicit dash ranges that cross midnight (e.g., 11pm-1am), the parser ensures end > start by duration rules; it does not automatically add a day. Provide explicit date or AM/PM on both sides if needed.
• confidence is a heuristic guidance score.

---

Security

• Do not commit credentials.json or token.json.
• Use a test calendar for automated tests.
• Principle of least privilege for your Google account.

---

Versioning & License

• Versioning: SemVer (MAJOR.MINOR.PATCH). Current: v0.1.8.
• License: MIT (see LICENSE).