# TaskCapture

Natural language parser for rapid task capture — turns a single sentence into a structured task.

---

## Table of Contents

1. [Overview](#overview)
2. [Features](#features)
3. [Usage](#usage)
4. [API Reference](#api-reference)
5. [Parsing Pipeline](#parsing-pipeline)
6. [Supported Patterns](#supported-patterns)
7. [Troubleshooting](#troubleshooting)
8. [Related Documentation](#related-documentation)

---

## Overview

`TaskCapture` is a pure functional module with no state or process dependencies. It takes a natural language string like `"buy groceries tomorrow #home !!"` and extracts structured fields (title, tags, priority, recurrence, due date) into a map ready for `TaskManager.create/2`.

The parser runs a sequential pipeline of extractors, each consuming recognized tokens from the input and passing the remainder to the next stage. Order matters — tags and priority are extracted before dates to avoid ambiguity.

Date/time parsing uses manual computation for common patterns (tomorrow, next monday, in 2 hours) and falls back to the `Chronic` library for more complex expressions (feb 25 at 2pm, friday).

## Features

| Feature | Syntax | Example |
|---------|--------|---------|
| Tags | `#word` | `#home`, `#work`, `#urgent` |
| Priority (explicit) | `p1` through `p10` | `p8` → priority 8 |
| Priority (bangs) | `!`, `!!`, `!!!` | `!!` → priority 5 |
| Recurrence | keywords | `daily`, `weekly`, `monthly`, `weekdays`, `hourly` |
| Recurrence (interval) | `every N unit` | `every 10 seconds`, `every 5 minutes`, `every 2 hours`, `every 3 days`, `every 2 weeks` |
| Recurrence (singular) | `every unit` | `every second`, `every minute`, `every hour` |
| Recurrence (named days) | `every day,day,...` | `every monday,wednesday,friday` |
| Relative time | `in N unit` | `in 20 seconds`, `in 2 hours`, `in 30 minutes`, `in 3 days` |
| Standalone time | `at <time>` | `at 3pm`, `at 10:30`, `at 14:00` (today, or tomorrow if past) |
| Named dates | day names | `today`, `tonight`, `tomorrow`, `monday`, `next friday` |
| Calendar dates | month + day | `feb 25`, `march 3 at 2pm` |
| Periods | `next week/month` | `next week` → next Monday 9am |
| Auto due_at | on recurrence | Recurrence without explicit time defaults `due_at` to now |
| Auto Pushover | on capture | Tasks with `due_at` automatically get a Pushover notification |

## Usage

### Basic Capture

```elixir
{:ok, result} = TaskCapture.parse("buy groceries tomorrow #home !!")
# => %{title: "buy groceries", due_at: 1771725600, tags: ["#home"], priority: 5}
```

### With Timezone

```elixir
{:ok, result} = TaskCapture.parse("call dentist next monday at 10am", "Asia/Ho_Chi_Minh")
# => %{title: "call dentist", due_at: 1771815600}
```

### Recurring Task

```elixir
{:ok, result} = TaskCapture.parse("meditate daily #health p3")
# => %{title: "meditate", recur: "daily", due_at: <now>, tags: ["#health"], priority: 3}
# due_at defaults to now when recurrence is set without an explicit time
```

### Recurring with Start Time

```elixir
{:ok, result} = TaskCapture.parse("standup daily at 9am", "Asia/Ho_Chi_Minh")
# => %{title: "standup", recur: "daily", due_at: <today 9am or tomorrow 9am>}

{:ok, result} = TaskCapture.parse("check server every 10 seconds")
# => %{title: "check server", recur: "every 10 seconds", due_at: <now>}
```

### Standalone Time

```elixir
{:ok, result} = TaskCapture.parse("call bob at 3pm", "Asia/Ho_Chi_Minh")
# => %{title: "call bob", due_at: <today 3pm, or tomorrow 3pm if past>}
```

### Time-Only Parsing

```elixir
{:ok, unix} = TaskCapture.parse_time("next monday", "America/New_York")
# => {:ok, 1771812000}

{:ok, unix} = TaskCapture.parse_time("in 2 hours")
# => {:ok, <now + 7200>}
```

### Via MCP Tool

The `task_capture` MCP tool wraps this module:

```
task_capture("deploy v2.0 feb 28 #deploy p10")
```

### Via REST API

```
POST /api/tasks/capture
Content-Type: application/json

{"text": "buy groceries tomorrow #home !!"}
```

## API Reference

### `parse/2`

Parse a natural language task string into a structured map.

**Parameters:**
- `text` (string) — the natural language task description
- `tz` (string, optional) — IANA timezone, defaults to `"Etc/UTC"`

**Returns:** `{:ok, map}` or `{:error, reason}`

The returned map includes only keys with non-nil values:

| Key | Type | Description |
|-----|------|-------------|
| `:title` | string | Cleaned task title (always present) |
| `:tags` | list of strings | Extracted `#hashtags` |
| `:priority` | integer 0-10 | From `!`/`!!`/`!!!` or `p1`-`p10` |
| `:recur` | string | Recurrence pattern (e.g. `"daily"`, `"every 3 days"`) |
| `:due_at` | integer | Unix timestamp in seconds |

```elixir
{:ok, task} = TaskCapture.parse("review PR in 2 hours #work p8", "Asia/Ho_Chi_Minh")
# => %{title: "review PR", due_at: ..., tags: ["#work"], priority: 8}

{:error, reason} = TaskCapture.parse("#work !!")
# => {:error, "empty title"}
```

### `parse_time/2`

Parse a time/date string into a Unix timestamp without full task capture.

**Parameters:**
- `str` (string) — natural language time expression
- `tz` (string, optional) — IANA timezone, defaults to `"Etc/UTC"`

**Returns:** `{:ok, unix_seconds}` or `{:error, reason}`

```elixir
{:ok, unix} = TaskCapture.parse_time("tomorrow", "Asia/Ho_Chi_Minh")
{:ok, unix} = TaskCapture.parse_time("in 30 minutes")
{:ok, unix} = TaskCapture.parse_time("next friday at 3pm", "America/New_York")
```

Used by `TaskRest.snooze/4` for natural language snooze durations.

## Parsing Pipeline

The parser runs five stages in order. Each takes `{accumulated_map, remaining_text}` and returns the same shape:

```
Input text
  │
  ├─ 1. extract_tags     — pull #hashtags via regex
  ├─ 2. extract_priority  — pull !/!!/!!!/p1-p10
  ├─ 3. extract_recur     — pull recurrence keywords
  ├─ 4. extract_datetime  — pull date/time expressions
  └─ 5. clean_title       — trim whitespace, collapse spaces
  │
  ▼
{:ok, %{title: ..., tags: [...], priority: N, recur: "...", due_at: N}}
```

**Why this order?** Tags and priority use simple, unambiguous patterns. Extracting them first simplifies datetime matching — e.g., `p5` won't be confused with a date token.

## Supported Patterns

### Priority

| Input | Priority Value |
|-------|---------------|
| `!!!` | 8 (urgent) |
| `!!` | 5 (high) |
| `!` | 3 (medium) |
| `p0` - `p10` | literal value |
| *(none)* | not set (defaults to 0 in TaskManager) |

> `!` only matches standalone — `don't` won't trigger it.

### Recurrence

| Input | Stored Value |
|-------|-------------|
| `hourly` | `"hourly"` |
| `daily` | `"daily"` |
| `weekly` | `"weekly"` |
| `monthly` | `"monthly"` |
| `weekdays` | `"weekdays"` |
| `every second` / `every sec` | `"every 1 seconds"` |
| `every minute` / `every min` | `"every 1 minutes"` |
| `every hour` / `every hr` | `"every 1 hours"` |
| `every 10 seconds` / `every 10 secs` | `"every 10 seconds"` |
| `every 5 minutes` / `every 5 min` | `"every 5 minutes"` |
| `every 2 hours` / `every 2 hrs` | `"every 2 hours"` |
| `every 3 days` | `"every 3 days"` |
| `every 2 weeks` | `"every 2 weeks"` |
| `every monday,wednesday,friday` | `"every monday,wednesday,friday"` |

> When recurrence is set without an explicit time, `due_at` defaults to now.

### Date/Time

Patterns are matched most-specific first to avoid partial matches:

| Input | Resolves To |
|-------|------------|
| `feb 25 at 2pm` | Feb 25, 14:00 (via Chronic) |
| `tomorrow at 3pm` | tomorrow 15:00 (via Chronic) |
| `next friday at 10am` | next Friday 10:00 |
| `next monday` | next Monday 9:00 |
| `today` | now |
| `tonight` | today 20:00 |
| `tomorrow` | tomorrow 9:00 |
| `monday` | next occurring Monday (via Chronic) |
| `in 20 seconds` | now + 20s |
| `in 2 hours` | now + 7200s |
| `in 30 minutes` | now + 1800s |
| `in 3 days` | now + 259200s |
| `at 3pm` | today 15:00 (tomorrow if past) |
| `at 10:30` | today 10:30 (tomorrow if past) |
| `at 14:00` | today 14:00 (tomorrow if past) |
| `next week` | next Monday 9:00 |
| `next month` | 1st of next month 9:00 |

## Troubleshooting

### Empty title error

If all tokens are consumed by extractors, the title will be empty:

```elixir
TaskCapture.parse("#work !!")
# => {:error, "empty title"}
```

**Fix:** Include at least one word that isn't a tag, priority, date, or recurrence keyword.

### Chronic parse failures

Some natural language patterns aren't supported by the Chronic library. The module handles common ones (tomorrow, next monday, in N hours) natively, but unusual expressions may fail silently and be left in the title.

### Timezone matters

Without a timezone, all date calculations use UTC. For accurate "tomorrow" or "tonight" resolution, pass the user's timezone:

```elixir
# Wrong: "tomorrow" at UTC midnight, not local midnight
TaskCapture.parse("do laundry tomorrow")

# Right: "tomorrow" at 9am Ho Chi Minh time
TaskCapture.parse("do laundry tomorrow", "Asia/Ho_Chi_Minh")
```

## Related Documentation

- [NisTask](nis_task.md) — database layer, CRUD, queries
- [NisTaskRest](nis_task_rest.md) — REST bridge with auto-alarm on capture
- [TaskRecurrence](task_recurrence.md) — recurrence engine for recurring tasks

---

*Source: `lib/task_capture.ex` — Last updated: 2026-03-03*