Aheadly — Deadline Rescue

Evidence-backed personal deadline agent for Alexa+. Turns buried bills, trials, and policies into verified follow-through tasks with verbatim proof, genuine MCP tools, and zero cloud costs.

Comment

Inspiration

Every month, millions of consumers lose hard-earned money to subscription "trial traps," late payment penalties on utility bills, and lapsed insurance policies. Why? Because the critical dates are buried deep inside multi-page PDF statements, informal SMS notifications, and dense confirmation emails.

Standard reminder apps are purely passive: they force you to remember to schedule the task and guess the date yourself. Meanwhile, generic LLMs tend to hallucinate dates, confuse billing cycle dates with payment due dates, or silently invent current-year assumptions for future deadlines.

We built Aheadly (Deadline Rescue) to solve this: an evidence-backed personal deadline agent designed for the Alexa+ track that ingests raw documents, grounds every single date in verbatim character-level evidence, refuses false certainty, and uses a self-hosted Model Context Protocol (MCP) server to guide users through follow-through actions.

What it does

Aheadly acts as an autonomous personal assistant for all your recurring financial and service obligations:

  1. Multi-Source Ingestion: Ingests digital PDFs, .eml emails, SMS text, and manual pastes with a strict 10 MiB security ceiling and MIME type validation.
  2. Sub-Millisecond Extraction: A deterministic parsing engine extracts candidate dates, Indian Lakhs/thousands currency amounts, and obligation types with a median latency of 0.09 ms.
  3. Verbatim Evidence Grounding: Every extracted date is anchored to exact character coordinates [start : end] in the original source. The interactive Evidence Grounding Inspector highlights the exact substring, eliminating hallucinations.
  4. Refusal to Invent Dates: When facing ambiguous expressions ("payment due sometime this month"), Aheadly categorizes the date as UNVERIFIED and blocks calendar alarms until explicitly confirmed by the user.
  5. Actionable Follow-Through: Prepares step-by-step checklists, surfaces curated verified provider portals (Netflix, Airtel, Tata Power, Jio, HDFC Life, etc.), and exports RFC 5545 .ics calendar events.
  6. Advance Alert Scheduling: A local background worker monitors obligations every 60 seconds against the UTC clock, queuing advance alerts at 7 days, 3 days, and 1 day prior without external paid APIs.
  7. Live MCP Protocol Observability: An integrated protocol console exposes real JSON-RPC 2.0 tool calls, request/response payloads, latencies, and Server-Sent Events (SSE) live to developers and judges.

How we built it

Aheadly was built completely from the ground up adhering to a strict ₹0 out-of-pocket budget constraint:

  • MCP Architecture (Spec 2025-11-25+): We implemented a self-hosted Model Context Protocol server over Streamable HTTP exposing 8 genuine business tools: ingest_source, find_deadline_candidates, get_deadline_evidence, confirm_or_correct_deadline, create_follow_up, prepare_next_step, update_deadline_status, and list_deadlines. It features full Mcp-Session-Id session lifecycle management and an asynchronous SSE subscriber queue for live tool execution broadcasting.
  • Backend & Agent Host: Built with Python 3.11+ and FastAPI, backed by local SQLite operating in WAL mode with transactional DDL migrations and foreign-key integrity constraints.
  • Deterministic Extraction Engine: Uses high-precision regex state machines and grammar rules that correctly preserve commas, decimal amounts (e.g. 50.00), and explicit future years without cloud LLM token latency. Optional local Ollama (llama3.2) is supported for offline conversational assistance.
  • Frontend Visualizer: Developed with React 19 and Vite, featuring an editorial warm theme, live candidate review queue, character-level evidence modal, and real-time MCP activity inspector.

Challenges we ran into

  1. Streamable HTTP & SSE Lifecycle: Handling Server-Sent Events with proxy buffering and client disconnections required configuring explicit streaming headers (Cache-Control: no-transform, X-Accel-Buffering: no), heartbeat pings every 15s, and session tracking across asynchronous worker loops.
  2. Evidence Offset Integrity Across Formatting: Normalizing line breaks, Windows/Unix carriage returns, and currency decimals without offsetting the original character indices required strict regex lookbehinds and dual-string tracking.
  3. Deduplication vs. Legitimate Multi-Obligations: A single document can legitimately contain multiple obligations on the same date. We built a composite deduplication key matching (source_id, provider_name, obligation_type, evidence_span) to prevent duplicates upon repeated extractions while preserving user edits.
  4. Security on a ₹0 Budget: Without expensive cloud WAFs, we engineered local-first security: in-memory MCP log redaction to scrub raw text and account numbers, strict file extension checks, 10 MiB upload limits, and CSRF protection on demo reset endpoints.

Accomplishments that we're proud of

  • 100% Benchmark Accuracy: Verified against 25 synthetic benchmark documents across subscriptions, utility bills, and insurance premiums with 100% exact date match accuracy and 0 false positives.
  • Zero Hallucination Policy: If a date cannot be grounded in verbatim source evidence, Aheadly explicitly refuses to fabricate it.
  • 116/116 Automated Regression Tests: Comprehensive test coverage spanning unit, database migration, MCP protocol compliance, security, and end-to-end integration scenarios.
  • Strict ₹0 Cost: Zero paid APIs, zero Amazon Bedrock credits, zero third-party databases. 100% functional locally and offline.
  • Detailed MCP Developer Friction Log: Compiled a 1,600+ word technical friction log documenting 8 actionable architectural recommendations for the Amazon and Anthropic MCP developer teams.

What we learned

  • The Model Context Protocol provides an exceptionally clean separation between client reasoning and tool execution, but requires careful session and error translation when integrated with asynchronous web frameworks.
  • Deterministic regex and grammar parsers remain vastly superior to generative LLMs for extraction tasks where exact calendar dates and financial numbers cannot tolerate probabilistic hallucinations.
  • Evidence grounding with character-bounded offsets dramatically increases user trust in autonomous AI agents.

What's next for Aheadly

  • Native Alexa+ Skill Integration: Deploying Aheadly as an official certified Alexa+ smart screen skill with multi-turn voice confirmation.
  • On-Device Scanned OCR: Lightweight local WebAssembly / ONNX OCR integration for scanned paper receipts without cloud dependencies.
  • Bank & UPI Statement Aggregation: Secure local-only ingestion of monthly bank and UPI passbooks to proactively identify recurring subscription creeps before the next billing cycle.

Built With

  • alexa
  • fast-api
  • javascirpt
  • mcp
  • model-context-protocol
  • pydantic
  • pytest
  • python
  • react
  • render
  • rest-api
  • sqlite
  • uvicorn
  • vercel
  • vite
Share this project:

Updates

Submission history