Update SKILL.md with new caching and parallel fetching documentation

Make page size calculation dynamic based on first API response
- Uses actual event count from page 1 to calculate total_pages - Removes hardcoded '5' for events per page - API changes to page size will be handled automatically - Updated tests to match real API behavior (5 events per page)
2026-03-26 17:19:03 +00:00 · 2026-03-26 17:15:28 +00:00 · 2026-03-26 17:06:25 +00:00 · 2026-03-26 16:54:41 +00:00 · 2026-03-26 16:43:13 +00:00 · 2026-03-26 16:29:25 +00:00
3 changed files with 2309 additions and 299 deletions
--- a/skills/polymarket-browse/SKILL.md
+++ b/skills/polymarket-browse/SKILL.md
@@ -34,7 +34,7 @@ hermes mcp add polymarket https://docs.polymarket.com/mcp
 ## Usage

 ```
-polymarket-browse [--category "Counter Strike"] [--limit 5] [--matches N] [--non-matches N] [--search "TeamName"] [--matches-only] [--non-matches-only] [--detail N] [--raw] [--telegram]
+polymarket-browse [--category "Counter Strike"] [--limit 5] [--matches N] [--non-matches N] [--search "TeamName"] [--matches-only] [--non-matches-only] [--detail N] [--raw] [--telegram] [--no-cache] [--max-total N]
 ```

 ## Arguments
@@ -49,6 +49,8 @@ polymarket-browse [--category "Counter Strike"] [--limit 5] [--matches N] [--non
 - `--detail` : Index of match event (1-indexed) to show detailed markets. Default: 1. Set to 0 to disable.
 - `--list-categories` : List available game categories and exit
 - `--raw` : Show all events without tradeable filter (for debugging). Includes fetch stats.
+- `--no-cache` : Disable caching and fetch fresh data from the API.
+- `--max-total` : Maximum total events to fetch before early exit. Default: no limit. Useful for quick snapshots.
 - `--telegram` : Send results to Telegram. Requires `BOT_TOKEN` and `CHAT_ID` in environment variables.

 ## Output Format
@@ -120,11 +122,30 @@ Use `--raw` to disable the tradeable filter and see all match markets regardless

 The script fetches **ALL pages** until the API runs out of results (up to 100 pages as a safety cap).

+### Parallel Fetching
+
+Pages are fetched in **parallel batches of 5** using ThreadPoolExecutor. This significantly reduces fetch time:
+
+| Scenario | Without Parallelization | With Parallelization |
+|----------|------------------------|---------------------|
+| 10 pages (50 events) | ~20s (2s per page × 10) | ~4s (2s per batch × 2 batches) |
+| 20 pages (100 events) | ~40s | ~8s |
+
+The script first fetches page 1 to determine total pages, then fetches remaining pages in parallel batches of 5.
+
 ## Rate Limiting

 - Exponential backoff: 2s → 4s → 8s → 16s → 32s
 - Max 5 retries before aborting

+## Caching
+
+Results are cached in `~/.cache/polymarket-browse/` with a **5-minute TTL** to reduce redundant API calls.
+
+- Use `--no-cache` to bypass the cache and fetch fresh data
+- Cached data is automatically used when available and not expired
+- Useful when running the script repeatedly (e.g., for monitoring)
+
 ## Odds Format

 All odds are shown in **cents** format:
--- a/skills/polymarket-browse/scripts/browse.py
+++ b/skills/polymarket-browse/scripts/browse.py
--- a/skills/polymarket-browse/tests/test_browse.py
+++ b/skills/polymarket-browse/tests/test_browse.py
Author	SHA1	Message	Date
shoko	c75d123dfd	Update SKILL.md with new caching and parallel fetching documentation	2026-03-26 17:19:03 +00:00
shoko	9d1e328f53	Make page size calculation dynamic based on first API response - Uses actual event count from page 1 to calculate total_pages - Removes hardcoded '5' for events per page - API changes to page size will be handled automatically - Updated tests to match real API behavior (5 events per page)	2026-03-26 17:15:28 +00:00
shoko	09f3cb9066	Add comment explaining total_pages ceiling division calculation	2026-03-26 17:06:25 +00:00
shoko	1ae60f5661	Fix total_pages calculation bug and add tests - Fixed total_pages calculation: API returns 5 events/page, not PAGE_SIZE - This was causing partial=false positives when max_total was used - Updated tests to use correct pagination values	2026-03-26 16:54:41 +00:00
shoko	bab373ab8f	Add unit tests for parallelization, cache, and max_total - TestParallelFetchConcurrency: verify batch size of 5 and concurrency limit - TestCacheFunctions: test cache read/write error handling - TestMaxTotalParameter: test max_total event limiting	2026-03-26 16:43:13 +00:00
shoko	eafbdba4a5	Add parallel fetching, caching, and max_total parameter - Parallel page fetching with ThreadPoolExecutor (concurrency=5) - File-based cache with 5 min TTL in ~/.cache/polymarket-browse/ - New --no-cache flag to bypass cache - New --max-total parameter for early exit - Updated tests to work with new implementation	2026-03-26 16:29:25 +00:00
shoko	0a7911653b	Merge pull request 'Fix line lengths in browse.py' (#24 ) from fix/line-lengths into master	2026-03-26 16:42:53 +01:00
shoko	bae69043f8	Merge pull request 'Add type hints to browse.py' (#23 ) from feat/add-type-hints into master	2026-03-26 16:42:08 +01:00
shoko	d6c0342c0f	Fix line lengths in browse.py Split 2 lines that exceeded 120 chars in print_detail function. All 62 tests pass.	2026-03-26 15:40:21 +00:00
shoko	ce526b1aa3	Add type hints to browse.py - Added TypedDict classes for typed event/market structures - Added type annotations to all functions - Used Python 3.10+ union syntax (str \| None, dict[str, Any]) - All 62 tests pass	2026-03-26 15:35:18 +00:00
shoko	ae50fd14f0	Merge pull request 'Fix #14 : Refactor print_browse/send_to_telegram into single pipeline' (#22 ) from fix/issue-14-refactor-browse into master	2026-03-25 20:11:07 +01:00
shoko	c348d6daa1	tests: Add unit tests for browse_events, fetch_all_pages, filter_events, is_match_market, get_ml_market, get_ml_volume, sort_events New test classes: - TestIsMatchMarket: 5 tests for is_match_market() classification - TestGetMlMarket: 5 tests for get_ml_market() and get_ml_volume() - TestFilterEvents: 5 tests for filter_events() and sort_events() - TestFetchAllPages: 4 tests for fetch_all_pages() early-exit logic - TestBrowseEvents: 5 tests for browse_events() sort_by parameter Total: 24 new tests (62 total, all passing)	2026-03-25 19:08:36 +00:00
shoko	764c75e712	Fix: Switch fetch_page from subprocess to urllib, add early-exit to fetch_all_pages, add sort_by to browse_events - fetch_page: replace subprocess.run(curl) with urllib (stdlib, cleaner) - fetch_all_pages: add matches_max/non_matches_max params for early-exit. When both are set, stop fetching once quotas are satisfied. - browse_events: add sort_by param (None='fast' early-exit, 'volume'=full fetch+sort). Early-exit only used when sort_by=None (no client-side sort needed). - Remove subprocess import (no longer needed after migration)	2026-03-25 18:53:11 +00:00
shoko	3a9f8fb365	Fix #14 : Refactor print_browse/send_to_telegram into single pipeline Replace duplicate inline formatting with unified format+render pipeline. New functions: - format_match_event(e) — canonical dict for match events - format_non_match_event(e) — canonical dict for non-match events - render_match_lines(event_dict, i, mode) — text/HTML renderer - render_non_match_lines(event_dict, i, mode) — text/HTML renderer - send_chunked(...) — extracted Telegram chunking logic Also fixed send_chunked() chunking bug: the original '. ' in line check never matched event lines (period is followed by '</b>' not space). Tests: 38 total, all passing. Fixes: #14	2026-03-25 17:50:54 +00:00
shoko	a7837cec0f	Merge #15 : Unify duplicate time functions	2026-03-25 14:34:05 +00:00
shoko	b2180a4a34	Merge pull request 'Fix #5 : HTML injection in Telegram messages' (#20 ) from fix/issue-5-html-injection-telegram into master	2026-03-25 13:13:52 +01:00