reminder

Documentation

Overview

Package reminder polls for due reminders and delivers them via the gateway.

Index

• func ParseLLMReminderJSON(raw string, now time.Time) (when time.Time, message string, err error)
• func ParseNaturalTime(text string, now time.Time, loc *time.Location) (time.Time, error)
• func ParseNaturalTimeFull(ctx context.Context, text string, now time.Time, loc *time.Location, ...) (time.Time, string, error)
• func ParseReminderText(ctx context.Context, text string, now time.Time, loc *time.Location, ...) (time.Time, string, error)
• type Sender
• type Service
  • func New(database *db.DB, sender Sender) *Service
  • func (s *Service) Run(ctx context.Context)
  • func (s *Service) WithSearcher(sr vault.Searcher) *Service
• type TimeParserFunc

Functions

func ParseLLMReminderJSON

func ParseLLMReminderJSON(raw string, now time.Time) (when time.Time, message string, err error)

ParseLLMReminderJSON parses the JSON output from a BuildReminderParsePrompt call. It extracts the JSON object even when the LLM wraps it in markdown code fences or prose. Returns zero time (with nil error) when "when" is null — caller should ask user for a time.

func ParseNaturalTime

func ParseNaturalTime(text string, now time.Time, loc *time.Location) (time.Time, error)

ParseNaturalTime parses human-written time expressions into an absolute time. now is the reference point; loc is the user's timezone (use time.Local if unknown).

Supported patterns (case-insensitive):

in N minutes/hours/days/weeks    (also "a"/"an" and English word numbers)
N minutes/hours/days/weeks [from now]
tomorrow [at TIME]
today at TIME
[next|this] <weekday> [at TIME]
at TIME                          (today, or tomorrow if time has already passed)
morning / afternoon / evening / night / tonight  (time-of-day shortcuts)
[this] morning / afternoon / evening / tonight
next week                        (Monday 9am of next week)
end of the/this week             (Friday 5pm)
end of the/this month            (last day of month at 9am)
<Month> <day> [at TIME]          (e.g. "July 15", "July 15 at 3pm")
<day>th [of <Month>] [at TIME]   (e.g. "the 15th", "15th of July")

TIME formats: 3pm, 3:30pm, 15:30, noon, midnight

func ParseNaturalTimeFull

func ParseNaturalTimeFull(ctx context.Context, text string, now time.Time, loc *time.Location, llm TimeParserFunc, workspaceID string) (time.Time, string, error)

ParseNaturalTimeFull tries the fast regex parser first, then falls back to llm. It returns (parsedTime, cleanedMessage, error) where:

• parsedTime is zero when no time was found (llm returned null "when")
• cleanedMessage is the input unchanged when regex succeeds, or the LLM-extracted message
• error is non-nil only on a hard failure (LLM call error or both parsers failed with no llm)

func ParseReminderText

func ParseReminderText(ctx context.Context, text string, now time.Time, loc *time.Location, llm TimeParserFunc, workspaceID string) (time.Time, string, error)

ParseReminderText extracts (when, message) from one natural-language string like "remind me in 10 minutes to call the doctor" or "buy milk tomorrow 9am".

It is pure: no state, no prompting. The resolution strategy is (in order):

1. strip a leading "remind me"/"reminder"/"me" filler prefix;
2. a " to " split → regex/duration parse of the left, message = the right;
3. the LLM parser on the whole (stripped) string;
4. a legacy first-word-duration fallback ("30m stretch break").

Returns:

• when: the resolved time; ZERO when no time was found.
• message: the cleaned reminder text (time expression removed).
• err: non-nil ONLY when the LLM call itself fails.

A zero `when` with a non-empty `message` and nil err means "understood the message but found no time" — the caller decides whether to prompt for a time (Telegram) or reject with a 400 (web).

Types

type Sender

type Sender interface {
	// SendToUser looks up the user's connected platform and sends the message.
	// It picks the first active platform gateway for the user.
	SendToUser(workspaceID, text string) error
}

Sender delivers a message to a user on their connected platform.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service polls for due reminders and sends them.

It writes nothing to the vault — hence no Reflector. Reminders live only in the DB and the reminders UI tab.

func New

func New(database *db.DB, sender Sender) *Service

New creates a Service.

func (*Service) Run

func (s *Service) Run(ctx context.Context)

Run starts the polling loop and blocks until ctx is cancelled.

func (*Service) WithSearcher

func (s *Service) WithSearcher(sr vault.Searcher) *Service

WithSearcher enables enriching fired reminder messages with related vault notes.

type TimeParserFunc

type TimeParserFunc func(ctx context.Context, workspaceID, input string, now time.Time, loc *time.Location) (when time.Time, message string, err error)

TimeParserFunc is an LLM-backed time + message extractor. It receives the user's raw input (may contain both time expression and message) and returns:

• when: the parsed absolute time (zero value if no time was found in the input)
• message: the reminder text with the time expression stripped (same as input if no time found)
• err: non-nil only when the LLM call itself failed; zero time with nil err means "no time in input"