From 7ab17e03d7fbbd193b681e232f03970f3a193ff0 Mon Sep 17 00:00:00 2001
From: Kagamine Rin <rin.kagamine@captcouch.xyz>
Date: Sat, 13 Jun 2026 16:46:21 -0400
Subject: [PATCH] docs: update ARCHITECTURE.md and README.md for v1.2.0

- ARCHITECTURE.md: Added natural language date resolution section,
  hide_zero_spend parameter docs, updated example output, changelog
- README.md: Added changelog section with v1.2.0 and v1.1.0 entries
- Updated version metadata and creation date
---
 ARCHITECTURE.md | 39 +++++++++++++++++++++++++++++++++++++--
 README.md       | 15 ++++++++++++++-
 2 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 3d4b432..a967335 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -1,6 +1,8 @@
 # LiteLLM Dashboard Tool — Architecture & Design
 
 **Created:** 2026-06-04
+**Updated:** 2026-06-13
+**Version:** 1.2.0
 **Authors:** Kagamine Rin (Chief Engineer) & Ryan Neef (General / Co-Processor)
 
 ## Product Definition
@@ -91,7 +93,25 @@ Healthy: 8  |  Unhealthy: 0
 
 **LiteLLM Endpoint:** `GET {litellm_url}/user/daily/activity`
 **Auth:** `Authorization: Bearer {litellm_master_key}`
-**Params:** `start_date` (YYYY-MM-DD), `end_date` (YYYY-MM-DD)
+**Params:** `start_date` (YYYY-MM-DD or natural language shortcut), `end_date` (YYYY-MM-DD or natural language shortcut), `hide_zero_spend` (bool, default False)
+
+### Natural Language Date Resolution
+
+The `_resolve_date()` helper converts natural language shortcuts to YYYY-MM-DD before calling the API. This makes the tool easier for SLMs to use without requiring exact date formatting.
+
+**Supported shortcuts:**
+- `today`, `yesterday`, `tomorrow`
+- `N days ago` (e.g., `two days ago`)
+- `monday`-`sunday` (most recent occurrence)
+- `last monday`-`last sunday`
+- `this week`, `last week`
+- `this month`, `last month`
+
+Already-formatted YYYY-MM-DD strings pass through unchanged. Unrecognized strings are passed to the API, which will reject them with a clear error.
+
+### hide_zero_spend Parameter
+
+When `hide_zero_spend=True`, models with sub-$0.001 spend are filtered from the per-model breakdown. This is useful when free-tier or subscription models (e.g., Ollama Cloud) dominate the report with high token counts but negligible cost. Hidden models are summarized as `... (N model(s) with sub-$0.001 spend hidden)`.
 
 ### Response Processing
 
@@ -125,6 +145,7 @@ By Model:
   Model                      Spend |       Requests |    Tokens
   gemini-3.5-flash          $1.20 |  26 ok, 0 fail | 2,003,116 tokens
   gemini-3.1-flash-image    $0.45 |   5 ok, 0 fail |     8,085 tokens
+  ... (3 model(s) with sub-$0.001 spend hidden)
 
 By Date:
   2026-06-04: $1.28 | 27 ok, 0 fail | 2,004,642 tokens
@@ -137,8 +158,9 @@ By Date:
 - Token counts (prompt, completion, total)
 - Cache hit rate (cache_read_input_tokens / total_input_tokens)
 - Request counts (successful + failed)
-- Per-model breakdown (sorted by spend, descending)
+- Per-model breakdown (sorted by spend, descending; optionally filtered by hide_zero_spend)
 - Per-date breakdown
+- Hidden model count summary (when hide_zero_spend is active)
 
 ### Condensed/Stripped
 
@@ -230,6 +252,19 @@ Showing 20 of 4560 total requests (most recent first)
 
 These are documented but not in scope for v1. The two-function design is the right scope.
 
+## Changelog
+
+### v1.2.0 (2026-06-13)
+- **feat:** Natural language date shortcuts for `litellm_cost()` — `today`, `yesterday`, `monday`, `last week`, etc.
+- **feat:** `hide_zero_spend` parameter for `litellm_cost()` — filters sub-$0.001 models from breakdown
+- **fix:** Cost report header shows resolved YYYY-MM-DD dates instead of raw shortcuts
+
+### v1.1.0 (2026-06-13)
+- Initial public release
+- Three functions: `litellm_health`, `litellm_cost`, `litellm_history`
+- Valve-based configuration (no hardcoded keys)
+- Token-efficient response formatting
+
 ## Design Principles
 
 1. **Three functions, that's it.** No scope creep. Health check, cost breakdown, request history.
diff --git a/README.md b/README.md
index 4b5d3b8..10548cd 100644
--- a/README.md
+++ b/README.md
@@ -56,9 +56,22 @@ Both valves are passed at runtime — no hardcoded keys. The tool is portable to
 
 ## Documentation
 
-- **[ARCHITECTURE.md](ARCHITECTURE.md)** — Full architecture and design doc: API endpoints, response processing, stripped fields, error paths, future considerations.
+- **[ARCHITECTURE.md](ARCHITECTURE.md)** — Full architecture and design doc: API endpoints, response processing, stripped fields, error paths, future considerations, changelog.
 - **This README** — Quick reference: install, functions, valves, design principles.
 
+## Changelog
+
+### v1.2.0 (2026-06-13)
+- **feat:** Natural language date shortcuts for `litellm_cost()` — `today`, `yesterday`, `monday`, `last week`, etc.
+- **feat:** `hide_zero_spend` parameter for `litellm_cost()` — filters sub-$0.001 models from breakdown
+- **fix:** Cost report header shows resolved YYYY-MM-DD dates instead of raw shortcuts
+
+### v1.1.0 (2026-06-13)
+- Initial public release
+- Three functions: `litellm_health`, `litellm_cost`, `litellm_history`
+- Valve-based configuration (no hardcoded keys)
+- Token-efficient response formatting
+
 ## License
 
 MIT
\ No newline at end of file