Add happy-hour quota-preference windows and a default user configuration location #69

New issue

Closed

opened 2026-09-12 15:21:19 +00:00 by kilo · 1 comment

kilo commented

2026-09-12 15:21:19 +00:00

Member

Request

Two related owner-workflow improvements:

1. Happy hours (quota-preference windows)

In addition to the existing weekly blackout rules (issue #66), allow defining weekly happy-hour windows during which consuming quota from the targeted models is strongly preferable — e.g. vendor campaigns where usage is free or discounted for a limited period.

Concrete driver: the GLM-5.3-Flash Usage Campaign (owner-provided campaign text, all times Asia/Singapore):

Campaign period 2026-09-03 → 2026-09-20, daily 23:00 → 09:00 next day (weekends and holidays included).
Via ZCode: zero quota consumption; via other supported agents: quota doubled vs standard rules.
Applies only to GLM-5.3-Flash, not GLM-5.3.

So during the window the router should prefer zai/glm-5.3-flash for capable tasks and conserve paid quota (OpenAI Codex, GLM-5.3), without fabricating capacity and without bypassing any eligibility gate.

2. One default configuration location

Today the selector policy must be passed explicitly (--selector-policy / inline selector_policy), and the installed distribution does not include examples/, so the owner must maintain a copy at a stable path and wire flags into the MCP recipe. Wanted: a single default configuration location, e.g. ~/.config/scarcity-router, created during installation with default values taken from the checked-in example, so no files must be created by hand and no flags added to the MCP command.

Proposed semantics (to be refined during implementation)

WeeklyHappyHourRule mirrors WeeklyBlackoutRule schedule semantics (IANA zone, weekday vocabulary, strict HH:MM, half-open [start, end), cross-midnight support), plus optional inclusive local start_date/end_date bounds because campaigns are limited-time.
A matching window marks candidates as quota-preferred: a ranking-level preference only. It must never bypass blackout, hard constraints, capability sufficiency, capacity exhaustion/unknown policy or reservations; it never rewrites telemetry, scarcity or capability ratings (quota never changes a capability rating).
Serialized UserPolicy gains an additive optional happy_hours member; backwards compatibility recorded explicitly in docs/decisions.md.
Default config: $(XDG_CONFIG_HOME | ~/.config)/scarcity-router/selector-policy.json, provisioned from examples/selector-policy.json, never silently overwritten; explicit --selector-policy wins over the config file; the config file wins over the neutral policy; MCP/REST requests omitting selector_policy fall back to the server-configured default.

Scope guards

Recommendation only; no execution, no gateway behavior.
No credentials in the config file; new write access to ~/.config/scarcity-router requires an explicit security decision record.
Full validation gate (uv sync --only-dev, make check, uv run basedpyright, git diff --check) before the PR.

## Request Two related owner-workflow improvements: ### 1. Happy hours (quota-preference windows) In addition to the existing weekly blackout rules (issue #66), allow defining weekly **happy-hour** windows during which consuming quota from the targeted models is strongly preferable — e.g. vendor campaigns where usage is free or discounted for a limited period. Concrete driver: the GLM-5.3-Flash Usage Campaign (owner-provided campaign text, all times Asia/Singapore): - Campaign period **2026-09-03 → 2026-09-20**, daily **23:00 → 09:00 next day** (weekends and holidays included). - Via ZCode: **zero quota consumption**; via other supported agents: quota **doubled** vs standard rules. - Applies only to GLM-5.3-Flash, not GLM-5.3. So during the window the router should prefer `zai/glm-5.3-flash` for capable tasks and conserve paid quota (OpenAI Codex, GLM-5.3), without fabricating capacity and without bypassing any eligibility gate. ### 2. One default configuration location Today the selector policy must be passed explicitly (`--selector-policy` / inline `selector_policy`), and the installed distribution does not include `examples/`, so the owner must maintain a copy at a stable path and wire flags into the MCP recipe. Wanted: a single default configuration location, e.g. `~/.config/scarcity-router`, **created during installation with default values taken from the checked-in example**, so no files must be created by hand and no flags added to the MCP command. ## Proposed semantics (to be refined during implementation) - `WeeklyHappyHourRule` mirrors `WeeklyBlackoutRule` schedule semantics (IANA zone, weekday vocabulary, strict `HH:MM`, half-open `[start, end)`, cross-midnight support), plus optional inclusive local `start_date`/`end_date` bounds because campaigns are limited-time. - A matching window marks candidates as quota-preferred: a ranking-level preference only. It must never bypass blackout, hard constraints, capability sufficiency, capacity exhaustion/unknown policy or reservations; it never rewrites telemetry, scarcity or capability ratings (quota never changes a capability rating). - Serialized `UserPolicy` gains an additive optional `happy_hours` member; backwards compatibility recorded explicitly in `docs/decisions.md`. - Default config: `$(XDG_CONFIG_HOME | ~/.config)/scarcity-router/selector-policy.json`, provisioned from `examples/selector-policy.json`, never silently overwritten; explicit `--selector-policy` wins over the config file; the config file wins over the neutral policy; MCP/REST requests omitting `selector_policy` fall back to the server-configured default. ## Scope guards - Recommendation only; no execution, no gateway behavior. - No credentials in the config file; new write access to `~/.config/scarcity-router` requires an explicit security decision record. - Full validation gate (`uv sync --only-dev`, `make check`, `uv run basedpyright`, `git diff --check`) before the PR.

creatidy-admin referenced this issue from a commit

2026-09-12 15:57:25 +00:00

Ship happy-hour quota-preference windows and default user config (issue #69)

kilo referenced this issue

2026-09-12 15:57:45 +00:00

Ship happy-hour quota-preference windows and default user config (issue #69) #70

kilo commented

2026-09-12 15:57:53 +00:00

Author

Member

Implemented in PR #70 (feature/happy-hours-default-config → develop), left open for human review. Decisions recorded as D-035 (happy-hour quota-preference windows) and D-036 (default configuration location and provisioning) in docs/decisions.md. Validation: 972 tests OK, basedpyright clean, package-check green including the isolated install.

Implemented in PR #70 (`feature/happy-hours-default-config` → `develop`), left open for human review. Decisions recorded as D-035 (happy-hour quota-preference windows) and D-036 (default configuration location and provisioning) in `docs/decisions.md`. Validation: 972 tests OK, basedpyright clean, package-check green including the isolated install.

creatidy-admin referenced this issue from a commit

2026-09-12 16:44:44 +00:00

Remediation: provisioning note, compact happy-hour line, expired-campaign note (issue #69)