catence 0.1.0 → 0.2.0-beta.10

package/python/catence/providers/garmin/worker.py

@@ -6,11 +6,16 @@ import hashlib
 import json
 from typing import Any, Callable, Mapping
 
+from .progress import ProgressReporter
 from .registry import GARMIN_READ_METHODS, assert_read_only_registry
 from .staging import StagingWriter
 from .streams import SAMPLE_COLUMNS, activity_details_to_samples, activity_power_bests, fit_archive_to_samples, write_parquet
 
 
+class WorkerInterrupted(Exception):
+    """Raised between extraction steps when the run is asked to stop."""
+
+
 def as_dict(value: Any) -> dict[str, Any]:
     return value if isinstance(value, dict) else {"value": value}
 
@@ -80,11 +85,23 @@ def payload_date(payload: Mapping[str, Any]) -> str | None:
 class GarminStagingWorker:
     """Extract Garmin data through the explicit read-only registry into JSONL/Parquet staging."""
 
-    def __init__(self, api: Any, writer: StagingWriter, data_dir: Path, known_activity_hashes: Mapping[str, str] | None = None) -> None:
+    def __init__(self, api: Any, writer: StagingWriter, data_dir: Path, known_activity_hashes: Mapping[str, str] | None = None, progress: ProgressReporter | None = None) -> None:
         self.api = api
         self.writer = writer
         self.data_dir = data_dir
         self.known_activity_hashes = dict(known_activity_hashes or {})
+        self.progress = progress
+        self._interrupted = False
+
+    def request_interrupt(self) -> None:
+        """Ask the worker to stop at the next safe boundary."""
+        self._interrupted = True
+
+    def _check_interrupted(self) -> None:
+        if self._interrupted:
+            if self.progress is not None:
+                self.progress.finish("interrupted")
+            raise WorkerInterrupted("Sync run interrupted between extraction steps")
 
     def sync(
         self,
@@ -100,17 +117,26 @@ class GarminStagingWorker:
         daily_end = daily_to_date or end
         activity_end = activity_to_date or end
         if include_non_historical:
+            self._check_interrupted()
             self._singletons()
         if daily_from_date and daily_from_date <= daily_end:
+            self._check_interrupted()
             self._daily(daily_from_date, daily_end)
+            self._check_interrupted()
             self._range(daily_from_date, daily_end)
+            self._check_interrupted()
             self._cycling_ftp_history(daily_from_date, daily_end)
+            self._check_interrupted()
             self._max_metrics_history(daily_from_date, daily_end)
+            self._check_interrupted()
             self._hrv_history(daily_from_date, daily_end)
+            self._check_interrupted()
             self._score_history(daily_from_date, daily_end)
         if activity_from_date and activity_from_date <= activity_end:
+            self._check_interrupted()
             self._activities(activity_from_date, activity_end)
         if include_non_historical:
+            self._check_interrupted()
             self._collections()
 
     def _capture(self, endpoint: str, action: Callable[[], Any], remote_id_value: str | None = None, scope: dict[str, Any] | None = None) -> tuple[Any | None, str | None]:
@@ -162,10 +188,18 @@ class GarminStagingWorker:
             "golf_user_stats": ("get_golf_user_stats", "golf_user_stat"),
             "golf_club_stats": ("get_golf_club_stats", "golf_club_stat"),
         }
-        for endpoint, (method, entity_type) in calls.items():
+        if self.progress is not None:
+            self.progress.set_stage("singletons")
+            self.progress.advance(total=len(calls))
+        for index, (endpoint, (method, entity_type)) in enumerate(calls.items(), start=1):
+            self._check_interrupted()
+            if self.progress is not None:
+                self.progress.advance(step=endpoint)
             payload, raw_hash = self._capture(endpoint, lambda method=method: getattr(self.api, method)())
             if payload is not None:
                 self._entity(endpoint, entity_type, payload, raw_hash)
+            if self.progress is not None:
+                self.progress.advance(completed=index)
 
     def _daily(self, from_date: date, to_date: date) -> None:
         calls = {
@@ -183,13 +217,26 @@ class GarminStagingWorker:
             "nutrition_food_log": ("get_nutrition_daily_food_log", "nutrition_log"), "nutrition_meals": ("get_nutrition_daily_meals", "nutrition_log"),
             "nutrition_settings": ("get_nutrition_daily_settings", "nutrition_setting"),
         }
+        total_days = (to_date - from_date).days + 1
+        if self.progress is not None:
+            self.progress.set_stage("daily")
+            self.progress.advance(total=total_days)
         current = from_date
+        completed_days = 0
         while current <= to_date:
+            self._check_interrupted()
             day = current.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=day)
             for endpoint, (method, entity_type) in calls.items():
+                if self.progress is not None:
+                    self.progress.advance(step=f"{day} {endpoint}")
                 payload, raw_hash = self._capture(endpoint, lambda method=method, day=day: getattr(self.api, method)(day), day, {"date": day})
                 if payload is not None:
                     self._entity(endpoint, entity_type, payload, raw_hash, day)
+            completed_days += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_days)
             current += timedelta(days=1)
 
     def _range(self, from_date: date, to_date: date) -> None:
@@ -198,7 +245,10 @@ class GarminStagingWorker:
             "blood_pressure": ("get_blood_pressure", "blood_pressure"), "weigh_ins": ("get_weigh_ins", "body_composition"),
             "progress_summary": ("get_progress_summary_between_dates", "progress_summary"), "menstrual_calendar": ("get_menstrual_calendar_data", "menstrual"),
         }
-        for endpoint, (method, entity_type) in calls.items():
+        if self.progress is not None:
+            self.progress.set_stage("range")
+            self.progress.advance(total=len(calls))
+        for index, (endpoint, (method, entity_type)) in enumerate(calls.items(), start=1):
             # Garmin rejects broad body-battery and menstrual-calendar ranges.
             # Keep every request inside the provider's 92-day limit.
             window_start = from_date
@@ -206,23 +256,36 @@ class GarminStagingWorker:
             # ranges. Keep it deliberately small; the captures are
             # content-addressed so overlapping retry windows are harmless.
             window_days = 7 if endpoint == "body_battery" else (90 if endpoint == "menstrual_calendar" else (to_date - from_date).days + 1)
+            if self.progress is not None:
+                self.progress.advance(step=endpoint)
             while window_start <= to_date:
+                self._check_interrupted()
                 window_end = min(to_date, window_start + timedelta(days=window_days - 1))
                 start, end = window_start.isoformat(), window_end.isoformat()
                 payload, raw_hash = self._capture(endpoint, lambda method=method, start=start, end=end: getattr(self.api, method)(start, end), None, {"from": start, "to": end})
                 if payload is not None:
                     self._entity(endpoint, entity_type, payload, raw_hash, fallback_scope=start)
                 window_start = window_end + timedelta(days=1)
+            if self.progress is not None:
+                self.progress.advance(completed=index)
 
     def _cycling_ftp_history(self, from_date: date, to_date: date) -> None:
         """Stage daily cycling FTP setting history from Garmin's range endpoint."""
         endpoint = "functional_threshold_power_range"
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("ftp_history")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             # This private Connect endpoint is not documented with a maximum
             # range. Keep requests aligned with other conservative range calls.
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture(
                 endpoint,
                 lambda start=start, end=end: self.api.get_functional_threshold_power_range(
@@ -251,14 +314,25 @@ class GarminStagingWorker:
                         raw_hash,
                         occurred_on=occurred_on,
                     )
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _max_metrics_history(self, from_date: date, to_date: date) -> None:
         """Stage range max-metric responses by their actual calendar date."""
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("max_metrics")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture(
                 "max_metrics_range",
                 lambda start=start, end=end: self.api.get_max_metrics_range(start, end),
@@ -286,14 +360,25 @@ class GarminStagingWorker:
                         for item in as_items(fallback):
                             self.writer.source_entity("max_metric", f"max_metrics:{day}", item, fallback_hash, occurred_on=day)
                 current += timedelta(days=1)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _hrv_history(self, from_date: date, to_date: date) -> None:
         """Stage the PR-402 HRV range API, retaining daily fallback coverage."""
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("hrv_history")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture(
                 "hrv_range",
                 lambda start=start, end=end: self.api.get_hrv_data_range(start, end),
@@ -315,14 +400,25 @@ class GarminStagingWorker:
                     if fallback is not None:
                         self.writer.source_entity("daily_health", f"hrv:{day}", as_dict(fallback), fallback_hash, occurred_on=day)
                 current += timedelta(days=1)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _score_history(self, from_date: date, to_date: date) -> None:
         """Stage daily-capable endurance-adjacent metrics from range endpoints."""
         window_start = from_date
+        total_windows = (to_date - from_date).days // 89 + 1
+        if self.progress is not None:
+            self.progress.set_stage("scores")
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=89))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             for endpoint, method, entity_type in (
                 ("hill_score", lambda: self.api.get_hill_score(start, end), "hill_score"),
                 ("running_tolerance", lambda: self.api.get_running_tolerance(start, end, aggregation="daily"), "running_tolerance"),
@@ -333,33 +429,56 @@ class GarminStagingWorker:
                         item_day = payload_date(item)
                         if item_day:
                             self.writer.source_entity(entity_type, f"{endpoint}:{item_day}:{index}", item, raw_hash, occurred_on=item_day)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
         # Garmin limits daily race-prediction windows to one year.
         window_start = from_date
+        total_windows = (to_date - from_date).days // 365 + 1
+        if self.progress is not None:
+            self.progress.advance(total=total_windows)
+        completed_windows = 0
         while window_start <= to_date:
+            self._check_interrupted()
             window_end = min(to_date, window_start + timedelta(days=365))
             start, end = window_start.isoformat(), window_end.isoformat()
+            if self.progress is not None:
+                self.progress.advance(step=start)
             payload, raw_hash = self._capture("race_predictions", lambda start=start, end=end: self.api.get_race_predictions(start, end, "daily"), None, {"from": start, "to": end, "aggregation": "daily"})
             if payload is not None:
                 for index, item in enumerate(as_items(payload)):
                     item_day = payload_date(item) or start
                     self.writer.source_entity("race_prediction", f"race_prediction:{item_day}:{index}", item, raw_hash, occurred_on=item_day)
+            completed_windows += 1
+            if self.progress is not None:
+                self.progress.advance(completed=completed_windows)
             window_start = window_end + timedelta(days=1)
 
     def _activities(self, from_date: date, to_date: date) -> None:
         start, end = from_date.isoformat(), to_date.isoformat()
+        if self.progress is not None:
+            self.progress.set_stage("activities")
         payload, raw_hash = self._capture("activities", lambda: self.api.get_activities_by_date(start, end), None, {"from": start, "to": end})
         if payload is None:
             return
         self._entity("activities", "activity", payload, raw_hash)
-        for summary in as_items(payload):
+        summaries = as_items(payload)
+        if self.progress is not None:
+            self.progress.advance(total=len(summaries))
+        for index, summary in enumerate(summaries, start=1):
+            self._check_interrupted()
             activity_id = remote_id(summary, "unknown")
+            if self.progress is not None:
+                self.progress.advance(step=activity_id)
             summary_hash = hashlib.sha256(json.dumps(summary, sort_keys=True, separators=(",", ":"), default=str).encode()).hexdigest()
             details_fetched = self.known_activity_hashes.get(activity_id) != summary_hash
             if details_fetched:
                 self._activity_details(activity_id, summary)
             self.writer.activity_sync_state(activity_id, summary_hash, details_fetched)
+            if self.progress is not None:
+                self.progress.advance(completed=index)
 
     def _multisport_children(self, parent_activity_id: str, activity: dict[str, Any]) -> None:
         if not activity.get("isMultiSportParent"):
@@ -444,7 +563,15 @@ class GarminStagingWorker:
             "workouts": ("get_workouts", (), "workout"), "scheduled_workouts": ("get_scheduled_workouts", (today.year, today.month), "scheduled_workout"),
             "goals": ("get_goals", (), "goal"), "golf_summary": ("get_golf_summary", (), "golf_scorecard"),
         }
-        for endpoint, (method, arguments, entity_type) in calls.items():
+        if self.progress is not None:
+            self.progress.set_stage("collections")
+            self.progress.advance(total=len(calls))
+        for index, (endpoint, (method, arguments, entity_type)) in enumerate(calls.items(), start=1):
+            self._check_interrupted()
+            if self.progress is not None:
+                self.progress.advance(step=endpoint)
             payload, raw_hash = self._capture(endpoint, lambda method=method, arguments=arguments: getattr(self.api, method)(*arguments))
             if payload is not None:
                 self._entity(endpoint, entity_type, payload, raw_hash)
+            if self.progress is not None:
+                self.progress.advance(completed=index)

package/scripts/discover-opencode-go.mjs

@@ -0,0 +1,210 @@
+// Discover OpenCode Go models and emit Catence Console profiles for them.
+//
+// OpenCode Go serves its catalog through three APIs: most models speak the
+// OpenAI Chat Completions API, Grok and GPT-5.6 Luna speak the OpenAI
+// Responses API, and MiniMax and Qwen speak the Anthropic Messages API. The
+// public `GET /models` endpoint returns only model ids, not which API each
+// model needs, so routing comes from the trusted table below and is intersected
+// with the live list (the same "live discovery + trusted metadata" approach
+// OpenClaw uses).
+//
+// Usage:
+//   node scripts/discover-opencode-go.mjs [--base-url <url>] [--write <config.json>] [--set-default]
+//
+// Flags:
+//   --base-url <url>   Root of the OpenCode Go API (default https://opencode.ai/zen/go/v1).
+//   --write <path>     Merge the two profiles into an existing config.json instead of printing to stdout.
+//   --set-default      With --write, set console.defaultProfile to opencode-go even when one already exists.
+
+import process from 'node:process';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const DEFAULT_BASE_URL = 'https://opencode.ai/zen/go/v1';
+const API_KEY_ENV = 'OPENCODE_GO_API_KEY';
+const API_BASE_ENV = 'OPENCODE_GO_API_BASE';
+const MESSAGES_BASE_ENV = 'OPENCODE_GO_MESSAGES_API_BASE';
+
+// LiteLLM appends a fixed suffix to the profile base URL per provider, so the
+// three APIs need different prefixes and two base URLs:
+//   openai/<id>             -> {base}/chat/completions
+//   openai/responses/<id>   -> {base}/responses
+//   anthropic/<id>          -> {base minus /v1}/v1/messages
+const RESPONSES_MODELS = new Set(['grok-4.5', 'gpt-5.6-luna']);
+const MESSAGES_MODELS = new Set([
+  'minimax-m2.5',
+  'minimax-m2.7',
+  'minimax-m3',
+  'qwen3.5-plus',
+  'qwen3.6-plus',
+  'qwen3.7-plus',
+  'qwen3.7-max',
+  'qwen3.8-max',
+]);
+
+const BRAND_NAMES = new Map([
+  ['deepseek', 'DeepSeek'],
+  ['glm', 'GLM'],
+  ['gpt', 'GPT'],
+  ['grok', 'Grok'],
+  ['hy3', 'Hy3'],
+  ['kimi', 'Kimi'],
+  ['mimo', 'MiMo'],
+  ['minimax', 'MiniMax'],
+  ['qwen', 'Qwen'],
+]);
+
+function classify(id) {
+  if (RESPONSES_MODELS.has(id)) return { route: 'responses', guessed: false };
+  if (MESSAGES_MODELS.has(id)) return { route: 'messages', guessed: false };
+  if (/^(grok-|gpt-)/.test(id)) return { route: 'responses', guessed: true };
+  if (/^(minimax-|qwen)/.test(id)) return { route: 'messages', guessed: true };
+  return { route: 'chat', guessed: false };
+}
+
+function modelReference(id, route) {
+  if (route === 'responses') return `openai/responses/${id}`;
+  if (route === 'messages') return `anthropic/${id}`;
+  return `openai/${id}`;
+}
+
+function labelFor(id) {
+  return id
+    .split('-')
+    .map((segment) => BRAND_NAMES.get(segment) ?? segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(' ');
+}
+
+function usage() {
+  process.stderr.write(
+    'Usage: node scripts/discover-opencode-go.mjs [--base-url <url>] [--write <config.json>] [--set-default]\n',
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let baseUrl = DEFAULT_BASE_URL;
+  let writePath = null;
+  let setDefault = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--base-url') {
+      baseUrl = args[i + 1];
+      if (!baseUrl) throw new Error('--base-url requires a URL.');
+      i += 1;
+    } else if (arg === '--write') {
+      writePath = args[i + 1];
+      if (!writePath) throw new Error('--write requires a config.json path.');
+      i += 1;
+    } else if (arg === '--set-default') {
+      setDefault = true;
+    } else if (arg === '--help' || arg === '-h') {
+      usage();
+      return;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!baseUrl.endsWith('/v1')) {
+    process.stderr.write(`Warning: --base-url ${baseUrl} does not end in /v1; chat and responses URLs may be wrong.\n`);
+  }
+  const modelsUrl = `${baseUrl.replace(/\/$/, '')}/models`;
+  const messagesBase = baseUrl.replace(/\/v1\/?$/, '');
+
+  let response;
+  try {
+    response = await fetch(modelsUrl, { headers: { accept: 'application/json' } });
+  } catch (error) {
+    throw new Error(`Could not reach ${modelsUrl}: ${error.message}`);
+  }
+  if (!response.ok) {
+    throw new Error(`GET ${modelsUrl} returned HTTP ${response.status}.`);
+  }
+  const payload = await response.json();
+  const ids = (payload.data ?? []).map((entry) => entry.id).filter((id) => typeof id === 'string' && id);
+
+  const groups = { chat: [], responses: [], messages: [] };
+  const guessed = [];
+  for (const id of ids) {
+    const { route, guessed: wasGuessed } = classify(id);
+    if (!(route in groups)) continue;
+    groups[route].push(id);
+    if (wasGuessed) guessed.push(`${id} -> ${route}`);
+  }
+  for (const route of Object.keys(groups)) groups[route].sort();
+
+  const chatProfileModels = {};
+  for (const id of groups.chat) {
+    chatProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'chat') };
+  }
+  for (const id of groups.responses) {
+    chatProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'responses') };
+  }
+  const messagesProfileModels = {};
+  for (const id of groups.messages) {
+    messagesProfileModels[id] = { label: labelFor(id), model: modelReference(id, 'messages') };
+  }
+
+  const chatDefault = groups.chat[0] ?? groups.responses[0];
+  const profiles = {};
+  profiles['opencode-go'] = {
+    label: 'OpenCode Go',
+    ...(chatDefault ? { defaultModel: chatDefault } : {}),
+    models: chatProfileModels,
+    apiKeyEnv: API_KEY_ENV,
+    apiBaseEnv: API_BASE_ENV,
+  };
+  if (messagesProfileModels && groups.messages.length) {
+    profiles['opencode-go-messages'] = {
+      label: 'OpenCode Go (Anthropic)',
+      defaultModel: groups.messages[0],
+      models: messagesProfileModels,
+      apiKeyEnv: API_KEY_ENV,
+      apiBaseEnv: MESSAGES_BASE_ENV,
+    };
+  }
+
+  const consoleSection = { defaultProfile: 'opencode-go', profiles };
+
+  if (guessed.length) {
+    process.stderr.write('Routed by prefix heuristic (verify before use):\n');
+    for (const line of guessed) process.stderr.write(`  ${line}\n`);
+  }
+  process.stderr.write(
+    `Discovered ${ids.length} models (${groups.chat.length} chat, ${groups.responses.length} responses, ${groups.messages.length} messages).\n`,
+  );
+
+  if (writePath) {
+    let root = {};
+    try {
+      root = JSON.parse(await readFile(writePath, 'utf8'));
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw new Error(`Could not read ${writePath}: ${error.message}`);
+    }
+    if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+      throw new Error(`${writePath} must contain a JSON object.`);
+    }
+    const existingConsole = typeof root.console === 'object' && root.console !== null ? root.console : {};
+    const mergedProfiles = { ...(existingConsole.profiles ?? {}), ...profiles };
+    const defaultProfile =
+      existingConsole.defaultProfile && !setDefault ? existingConsole.defaultProfile : 'opencode-go';
+    root.console = { ...existingConsole, defaultProfile, profiles: mergedProfiles };
+    await writeFile(writePath, `${JSON.stringify(root, null, 2)}\n`);
+    process.stderr.write(`Merged profiles into ${writePath} (defaultProfile: ${defaultProfile}).\n`);
+    return;
+  }
+
+  process.stderr.write(
+    `Export the key and base URLs, then add the JSON below under "console" in config.json:\n` +
+      `  export ${API_KEY_ENV}='sk-…'\n` +
+      `  export ${API_BASE_ENV}='${baseUrl}'\n` +
+      `  export ${MESSAGES_BASE_ENV}='${messagesBase}'\n` +
+      `(or rerun with --write ~/.catence/config.json to merge into an existing config.)\n`,
+  );
+  process.stdout.write(`${JSON.stringify(consoleSection, null, 2)}\n`);
+}
+
+await main().catch((error) => {
+  process.stderr.write(`Error: ${error.message}\n`);
+  process.exit(1);
+});