siiha-sdk 0.1.7

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.7 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.7)

• 🗓️ 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 (in 3 hours / 3 小時後), duration (for 30 minutes / 1.5 小時), bare hour ranges like 9-10 → 09:00–10:00, and auto roll to next day when a "today-only time" is already past. 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) 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"

C) Dedupe behavior

• Duplicate if and only if:

1. Same instant (RFC3339 compared as actual instant; timezone forms like +08:00 vs Z still dedupe), and
2. Normalized title equals (trim/whitespace collapse/commas normalized/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.
• 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.7.
• License: MIT (see LICENSE).