Reminder Agent

Your LLM can parse in 3 business days from a message. But is today Friday? Does the count skip weekends and holidays? Biruni resolves business-day expressions into exact ISO 8601 timestamps using the default us_federal calendar, so your agent doesn't have to.

The agent

import httpx, os
from datetime import date

BIRUNI_URL = "https://biruni.dev/v1/resolve"


# ── Stubs: replace with your integrations ────────────────────

async def schedule_reminder(user_id: str, task: str, fire_at: str):
    """Queue a push notification. (APNs, FCM, email, Slack ...)"""
    ...

async def reply(text: str):
    """Send a response back to the user. (Slack, chat UI, email ...)"""
    ...

def extract(message: str) -> dict:
    """
    Use your LLM to pull structured fields from the raw message.
    Returns: { "task": str, "phrase": str, "tz": str, "user_id": str }
    """
    ...


# ── Biruni integration ──────────────────────────────────────

async def resolve_time(phrase: str, tz: str) -> dict:
    async with httpx.AsyncClient() as client:
        r = await client.post(
            BIRUNI_URL,
            headers={"Authorization": f"Bearer {os.environ['BIRUNI_API_KEY']}"},
            json={
                "expression": phrase,
                "reference_date": date.today().isoformat(),
                "timezone": tz,
                "options": {"business_calendar": "us_federal"},
            },
        )
        r.raise_for_status()
        return r.json()


# ── Agent entry point ────────────────────────────────────────

async def handle(message: str):
    fields = extract(message)

    result = await resolve_time(fields["phrase"], fields["tz"])

    match result["status"]:
        case "resolved":
            await schedule_reminder(
                fields["user_id"], fields["task"], result["resolved"],
            )
            await reply(
                f"Got it — I'll remind you to {fields['task']} "
                f"on {result['resolved']}."
            )

        case "ambiguous":
            opts = "\n".join(
                f"  {i+1}. {a['interpretation']}"
                for i, a in enumerate(result["alternatives"])
            )
            await reply(f"That timing is ambiguous:\n{opts}")

        case _:
            await reply("Couldn't parse that time — could you rephrase?")