Skip to content

WaitNot.md

Latest commit

 

History

History
97 lines (76 loc) · 5.99 KB

WaitNot.md

File metadata and controls

97 lines (76 loc) · 5.99 KB
Raw

WaitNot — Buy or Wait? Financial Agent

WaitNot is an AI-powered financial decision agent built for the HackerRank Orchestrate (September 2026) challenge. Given a user's financial profile, transaction history, upcoming scheduled payments, and supporting evidence, it determines the safest and most optimal payment plan for a new purchase request over a 90-day forecasting window.

WaitNot operates as a 100% deterministic, pure-Python pipeline. It relies entirely on structured cash flow analysis, algorithmic forecasting, and robust regex heuristics rather than expensive or non-deterministic LLM generations.

🚀 How to Run

1. Prerequisites

Ensure you have Python 3.10 or higher installed, along with the required numerical processing libraries.

pip install pandas numpy

2. Generating the Final Output

To run the full pipeline on the evaluation dataset (requests.csv) and generate your predictions:

python code/main.py

What this does:

  • Loads all datasets from dataset/ (profiles, events, requests, fx rates, etc.).
  • Computes 90-day cash flow ledgers for all 250 requests.
  • Makes affordability decisions and formats them into the required schema.
  • Writes a validated output.csv to the root of the repository. (Execution time is typically under 10 seconds).

3. Evaluating the Model

To score the logic against the 25 public sample requests:

python code/evaluation/main.py

What this does:

  • Runs the WaitNot engine strictly against the users in dataset/sample_requests.csv.
  • Compares the engine's predicted plans, safe amounts, and dates against the known-good ground truth.
  • Outputs an accuracy breakdown per field and per row. Note: This is strictly for self-checking; main.py never uses this data to answer evaluation requests.

🧠 How It Works

WaitNot breaks the "Buy or Wait" decision into a five-stage pipeline:

1. Data Normalization & Evidence Parsing

  • Missing Amounts: loaders.py matches blank financial events against evidence_cache.json (amounts cleanly extracted from the provided images.csv receipts via manual mapping).
  • FX Conversion: All foreign currency events are converted into the user's home currency. If a direct exchange rate pair is missing on the required date, the engine automatically attempts an inverse lookup (1/rate) or a chained lookup (e.g., IDR → USD → INR).
  • Messages & Amendments: evidence.py scans messages.csv using strict multilingual (English & Indonesian) regex patterns to identify salary adjustments, cancellations, and delays. By treating all text as untrusted data, this completely mitigates prompt-injection attacks without needing LLM guardrails.

2. Recurring Cash Flow Detection

  • events.py analyzes the historical financial_events.csv to separate one-time spending from recurring cash flows.
  • Fixed Categories: Events like salary, rent, utilities, and insurance are automatically treated as recurring.
  • Dynamic Detection: For flexible expenses, the system looks for ≥3 settled occurrences falling within a consistent time interval (20-40 days) and with amount stability (±35% of the median).

3. 90-Day Forecasting Ledger

  • forecast.py projects the user's available balance across a 90-day window starting from the request date.
  • It applies scheduled events, pending debits, and projected recurring flows.
  • Conservation Rule: On any given day, debits are processed before credits.
  • amount_safe_to_pay is dynamically calculated by looking at the lowest future point in the ledger and ensuring the balance never drops below the user's minimum_balance_to_keep.

4. Plan Generation & Fallbacks

  • planner.py evaluates all candidate plans allowed by the user (full_payment, partial_payment, installments, or wait).
  • Spending Changes: If a plan falls slightly short of cash, the engine identifies eligible recurring expenses (non-protected categories) and proposes up to 3 stop or reduce_to (50%) actions to free up cash.
  • Ranking: Candidates are ranked rigorously. A plan is preferred if it: (1) meets the deadline, (2) requires no spending changes, (3) costs less overall, (4) starts earlier, and (5) requires fewer installments.

5. Explanation & Output Generation

  • explain.py generates concise, templated explanations based directly on the structured output (e.g., "Pay ZAR 25,256 today. This leaves at least ZAR 18,000 available...").
  • validate.py performs strict schema enforcement on the proposed rows, ensuring no format violations escape into the final output.csv.

📁 Repository Structure

WaitNot/
├── dataset/                   # Input CSVs and images (read-only)
├── output.csv                 # Final prediction output (generated by main.py)
└── code/
    ├── main.py                # Main orchestrator
    ├── loaders.py             # Data loading and FX conversion
    ├── events.py              # Recurring logic & scheduled event generation
    ├── forecast.py            # 90-day safe amount forecasting ledger
    ├── planner.py             # Plan generation and fallback strategies
    ├── evidence.py            # Regex-based message amendment extraction
    ├── explain.py             # Grounded, templated explanation generator
    ├── validate.py            # Strict schema verifier for output.csv
    ├── evidence_cache.json    # Verified event amounts from image receipts
    ├── README.md              # Documentation (you are here)
    └── evaluation/
        ├── main.py            # Sample row scoring harness
        └── usage_report.md    # Cost & token usage report

🛡️ Cost Guarantee

This architecture uses $0.00 in LLM API costs. Because financial decisions require rigid adherence to forecasting arithmetic and conflict-resolution rules, we built WaitNot as a pure data-science pipeline. This ensures execution is fast, 100% reproducible, and immune to hallucinatory rule-breaking.