catence 0.1.0 → 0.2.0-beta.10

package/docs/llm-providers.md

@@ -0,0 +1,467 @@
+# Console LLM providers
+
+Catence Console talks to a model through [LiteLLM](https://docs.litellm.ai/).
+There are exactly three provider shapes: **OpenAI**, **Anthropic**, and a
+generic **OpenAI-compatible** profile. Azure is not a special case in the code:
+it is reached through the OpenAI-compatible profile. OpenCode Go can be reached
+the same way through a local gateway, or directly at its own OpenAI-compatible
+endpoint with native `openai/…` and `anthropic/…` model names; the steps for
+each are documented below.
+
+## How configuration is split
+
+Catence never stores a credential value in `config.json`. A Console profile
+records only a LiteLLM model name and the *names* of the environment variables
+that hold the key, base URL, and (optionally) API version. The values
+themselves stay in the Console process environment.
+
+```jsonc
+// ~/.catence/config.json (or /data/config.json inside the Docker image)
+{
+  "console": {
+    "defaultProfile": "openai",
+    "profiles": {
+      "openai": {
+        "label": "OpenAI",
+        "model": "openai/gpt-5-mini",
+        "apiKeyEnv": "OPENAI_API_KEY"
+      },
+      "anthropic": {
+        "label": "Anthropic",
+        "model": "anthropic/claude-sonnet-4-5",
+        "apiKeyEnv": "ANTHROPIC_API_KEY"
+      },
+      "openai-compatible": {
+        "label": "OpenAI-compatible",
+        "model": "openai/your-model-name",
+        "apiKeyEnv": "OPENAI_API_KEY",
+        "apiBaseEnv": "OPENAI_API_BASE"
+      }
+    }
+  }
+}
+```
+
+The supported profile fields are `label`, `model` (or `models` + `defaultModel`
+for multiple deployments), `defaultReasoningEffort`, `apiKeyEnv`, `apiBaseEnv`,
+and `apiVersionEnv`. Every `*Env` value must be an uppercase environment
+variable name; a raw secret there is rejected.
+
+| Profile field | Environment variable it reads |
+| --- | --- |
+| `apiKeyEnv` | API key |
+| `apiBaseEnv` | Base URL (OpenAI-compatible endpoints) |
+| `apiVersionEnv` | Optional API version, only for endpoints that require one |
+
+## OpenAI
+
+Point the profile at the public OpenAI API. Only a key is required.
+
+```sh
+export OPENAI_API_KEY='sk-…'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "openai",
+    "profiles": {
+      "openai": {
+        "label": "OpenAI",
+        "model": "openai/gpt-5-mini",
+        "apiKeyEnv": "OPENAI_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Anthropic
+
+Only a key is required.
+
+```sh
+export ANTHROPIC_API_KEY='sk-ant-…'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "anthropic",
+    "profiles": {
+      "anthropic": {
+        "label": "Anthropic",
+        "model": "anthropic/claude-sonnet-4-5",
+        "apiKeyEnv": "ANTHROPIC_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## OpenAI-compatible
+
+Use this one profile for any endpoint that speaks the OpenAI Chat Completions
+API: Azure, Opencode, Ollama, LM Studio, a LiteLLM proxy, and so on. Set the
+key and the base URL; the model name is whatever the endpoint expects.
+
+```sh
+export OPENAI_API_KEY='…'
+export OPENAI_API_BASE='https://host.example/v1'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "openai-compatible",
+    "profiles": {
+      "openai-compatible": {
+        "label": "OpenAI-compatible",
+        "model": "openai/your-model-name",
+        "apiKeyEnv": "OPENAI_API_KEY",
+        "apiBaseEnv": "OPENAI_API_BASE"
+      }
+    }
+  }
+}
+```
+
+LiteLLM appends `/chat/completions` to `OPENAI_API_BASE`, so point it at the
+`…/v1` root of the endpoint, not the full completions path.
+
+### Azure
+
+Azure OpenAI's unified v1 API is OpenAI-compatible, so it uses the same
+`openai-compatible` profile. Use the **Azure deployment name** as the model.
+
+```sh
+export OPENAI_API_KEY='your-azure-openai-api-key'
+export OPENAI_API_BASE='https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "openai-compatible",
+    "profiles": {
+      "openai-compatible": {
+        "label": "Azure OpenAI",
+        "model": "openai/gpt-4.1-nano",   // your deployment name
+        "apiKeyEnv": "OPENAI_API_KEY",
+        "apiBaseEnv": "OPENAI_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- `OPENAI_API_BASE` also accepts the Foundry models form
+  `https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/`.
+- With the v1 API the `api-version` query parameter is no longer required, so
+  `apiVersionEnv` stays unset. If an older endpoint still needs one, add
+  `"apiVersionEnv": "OPENAI_API_VERSION"` and export
+  `OPENAI_API_VERSION='2024-06-01'` (or your API version).
+- `OPENAI_API_KEY` holds the Azure OpenAI API key. If you use Microsoft Entra
+  ID instead, a keyless token provider can be passed in the same variable.
+
+### Opencode
+
+[OpenCode Go](https://opencode.ai) publishes an OpenAI-compatible API at
+`https://opencode.ai/zen/go/v1`; its `GET /v1/models` listing is public and does
+not require a key. The Console can use it directly, so most setups do not need a
+local gateway.
+
+The repository includes a discovery script that fetches the live model list and
+merges ready-made Console profiles into `config.json`. From a Catence checkout:
+
+```sh
+npm run discover:opencode-go -- --write ~/.catence/config.json
+```
+
+The script adds two profiles, because OpenCode Go routes model families through
+different API shapes:
+
+- `opencode-go` — chat and responses models, base
+  `https://opencode.ai/zen/go/v1` (LiteLLM `openai/…` names).
+- `opencode-go-messages` — messages models, base `https://opencode.ai/zen/go`
+  (LiteLLM `anthropic/…` names).
+
+| Family | Profile prefix | Example |
+| --- | --- | --- |
+| Chat | `openai/<id>` | `openai/deepseek-v4-flash` |
+| Responses | `openai/responses/<id>` | `openai/responses/grok-4.5` |
+| Messages | `anthropic/<id>` | `anthropic/minimax-m2.5` |
+
+The script warns on stderr and skips any model that does not fit one of these
+families. Rerun it to refresh the model lists; existing profiles, limits, and
+`defaultProfile` are preserved unless `--set-default` is passed.
+
+```sh
+export OPENCODE_GO_API_KEY='…'                      # any non-empty value satisfies the key check
+export OPENCODE_GO_API_BASE='https://opencode.ai/zen/go/v1'
+export OPENCODE_GO_MESSAGES_API_BASE='https://opencode.ai/zen/go'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "opencode-go",
+    "profiles": {
+      "opencode-go": {
+        "label": "OpenCode Go",
+        "defaultModel": "flash",
+        "models": {
+          "flash": { "label": "DeepSeek V4 flash", "model": "openai/deepseek-v4-flash" },
+          "grok": { "label": "Grok 4.5", "model": "openai/responses/grok-4.5" }
+        },
+        "apiKeyEnv": "OPENCODE_GO_API_KEY",
+        "apiBaseEnv": "OPENCODE_GO_API_BASE"
+      },
+      "opencode-go-messages": {
+        "label": "OpenCode Go messages",
+        "defaultModel": "minimax",
+        "models": {
+          "minimax": { "label": "MiniMax M2.5", "model": "anthropic/minimax-m2.5" }
+        },
+        "apiKeyEnv": "OPENCODE_GO_API_KEY",
+        "apiBaseEnv": "OPENCODE_GO_MESSAGES_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Verify with `catence-console doctor`. The `responses` models
+(`openai/responses/…`) go through LiteLLM's responses bridge and are the least
+battle-tested path; smoke-test one chat turn before relying on them.
+
+If you instead want to reuse the providers already configured in your local
+Opencode CLI, run an OpenAI-compatible gateway such as the
+[`opencode-llm-proxy`](https://github.com/KochC/opencode-llm-proxy) plugin, which
+serves Chat Completions at `http://127.0.0.1:4010/v1` and lists every configured
+model as `provider/model`.
+
+```sh
+export OPENAI_API_KEY='unused'           # or your OPENCODE_LLM_PROXY_TOKEN
+export OPENAI_API_BASE='http://127.0.0.1:4010/v1'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "openai-compatible",
+    "profiles": {
+      "openai-compatible": {
+        "label": "Opencode",
+        "model": "openai/github-copilot/claude-sonnet-4.6",  // provider/model
+        "apiKeyEnv": "OPENAI_API_KEY",
+        "apiBaseEnv": "OPENAI_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- Use the fully qualified `provider/model` id from the gateway's
+  `GET /v1/models` listing.
+- If the gateway requires a bearer token, set `OPENAI_API_KEY` to the
+  `OPENCODE_LLM_PROXY_TOKEN`; otherwise any non-empty value satisfies the
+  profile's required-environment check.
+
+### Opencode Zen
+
+[OpenCode Zen](https://opencode.ai/zen) is a hosted model API with a curated
+selection of coding and reasoning models. It exposes an OpenAI-compatible
+endpoint at `https://opencode.ai/zen/v1` with a public `GET /v1/models`
+listing. Several models are available for free (no billing details required);
+paid models require an API key from [opencode.ai/auth](https://opencode.ai/auth).
+
+The repository includes a discovery script that fetches the live model list and
+merges ready-made Console profiles into `config.json`. From a Catence checkout:
+
+```sh
+npm run discover:opencode-zen -- --write ~/.catence/config.json
+```
+
+Add `--free-only` to include only the free models.
+
+The script adds two profiles, because OpenCode Zen routes model families through
+different API shapes:
+
+- `opencode-zen` — chat/completions models (most models, including all free
+  models), base `https://opencode.ai/zen/v1` (LiteLLM `openai/<id>` names).
+- `opencode-zen-responses` — responses API models (GPT-5.x series), base
+  `https://opencode.ai/zen/v1` (LiteLLM `openai/responses/<id>` names).
+
+| Family | Profile prefix | Example |
+| --- | --- | --- |
+| Chat | `openai/<id>` | `openai/deepseek-v4-flash-free` |
+| Responses | `openai/responses/<id>` | `openai/responses/gpt-5.6-luna` |
+
+Free models carry a `-free` suffix (e.g., `deepseek-v4-flash-free`,
+`nemotron-3-ultra-free`, `big-pickle`). The discovery script recognises them
+automatically; `--free-only` filters the list to free models only.
+
+```sh
+export OPENCODE_API_KEY='…'                         # required for paid models; any non-empty value for free
+export OPENCODE_ZEN_API_BASE='https://opencode.ai/zen/v1'
+export OPENCODE_ZEN_RESPONSES_API_BASE='https://opencode.ai/zen/v1'
+```
+
+```jsonc
+{
+  "console": {
+    "defaultProfile": "opencode-zen",
+    "profiles": {
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": { "label": "DeepSeek V4 Flash Free", "model": "openai/deepseek-v4-flash-free" },
+          "nemotron-3-ultra-free": { "label": "Nemotron 3 Ultra Free", "model": "openai/nemotron-3-ultra-free" },
+          "big-pickle": { "label": "Big Pickle", "model": "openai/big-pickle" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      },
+      "opencode-zen-responses": {
+        "label": "OpenCode Zen (Responses)",
+        "defaultModel": "gpt-5.6-luna",
+        "models": {
+          "gpt-5.6-luna": { "label": "GPT 5.6 Luna", "model": "openai/responses/gpt-5.6-luna" },
+          "gpt-5.6-terra": { "label": "GPT 5.6 Terra", "model": "openai/responses/gpt-5.6-terra" }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_RESPONSES_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Verify with `catence-console doctor`. The `responses` models
+(`openai/responses/…`) go through LiteLLM's responses bridge and are the least
+battle-tested path; smoke-test one chat turn before relying on them.
+
+The same `OPENCODE_API_KEY` works for both Opencode Go and Opencode Zen.
+
+## Multiple deployments per provider
+
+A profile can list several models under one set of credentials; the Console
+settings then offer a per-deployment choice.
+
+```jsonc
+{
+  "console": {
+    "profiles": {
+      "openai-compatible": {
+        "label": "Azure OpenAI",
+        "defaultModel": "nano",
+        "models": {
+          "nano": { "label": "GPT-4.1 nano", "model": "openai/gpt-4.1-nano" },
+          "mini": { "label": "GPT-5 mini", "model": "openai/gpt-5-mini" }
+        },
+        "apiKeyEnv": "OPENAI_API_KEY",
+        "apiBaseEnv": "OPENAI_API_BASE"
+      }
+    }
+  }
+}
+```
+
+## Reasoning effort
+
+Models expose a per-chat **Thinking effort** dropdown in the Console settings.
+By default it offers the OpenAI-standard levels — `minimal`, `low`, `medium`,
+`high`, `xhigh` — which suit OpenAI and most OpenAI-compatible endpoints.
+
+Some models (for example DeepSeek V4 Flash) use their own reasoning-effort
+scheme rather than the OpenAI-standard list. For those, declare `variants` on
+the model: a mapping of dropdown label to the exact value sent to the provider.
+The chat dropdown then shows `Provider default` plus each label instead of the
+OpenAI-standard list.
+
+```jsonc
+{
+  "console": {
+    "profiles": {
+      "opencode-zen": {
+        "label": "OpenCode Zen",
+        "defaultModel": "deepseek-v4-flash-free",
+        "models": {
+          "deepseek-v4-flash-free": {
+            "label": "DeepSeek V4 Flash Free",
+            "model": "openai/deepseek-v4-flash-free",
+            "variants": { "High": "high", "Max": "max" }
+          }
+        },
+        "apiKeyEnv": "OPENCODE_API_KEY",
+        "apiBaseEnv": "OPENCODE_ZEN_API_BASE"
+      }
+    }
+  }
+}
+```
+
+Selecting a variant sends that value verbatim as `reasoning_effort` (with
+`allowed_openai_params` so LiteLLM forwards it for OpenAI-compatible models).
+The `Provider default` option sends no reasoning effort at all.
+
+An explicitly empty `variants` map disables reasoning effort for that model:
+no `reasoning_effort` is sent (the agent guards against it) and the chat
+**Thinking effort** dropdown is disabled in the UI. This suits models that
+reject the parameter, such as MiMo, which expects its own `thinking` toggle
+instead. `variants: {}` cannot be combined with a fixed `reasoningEffort` on
+the same model.
+
+You can also pin a fixed level with `reasoningEffort` on the model, or a
+profile-wide default with `defaultReasoningEffort` (OpenAI-standard values
+only). Precedence: per-chat dropdown selection > model `reasoningEffort` >
+profile `defaultReasoningEffort` > provider default. The **Thinking effort**
+dropdown is rebuilt whenever the **Model** dropdown changes, so its options
+(and disabled state) always reflect the selected model.
+
+## Verifying a profile
+
+`catence-console doctor` reports, for each profile, which environment variables
+are still missing and whether the local Catence runtime is reachable. It never
+prints credential values.
+
+```sh
+catence-console doctor --home "$HOME/.catence" --mcp-url http://127.0.0.1:8787/mcp
+```
+
+On Docker, the deploy scaffold includes a helper that runs it inside the
+running container (`exec`, not `run` — the container's loopback hosts the live
+MCP server and the `.env` provider keys are in its environment):
+
+```sh
+./catence-deploy/doctor.sh
+```
+
+## Docker: generating the Console login hash
+
+`deploy-console.sh` writes a small helper into the deployment directory. Run it
+once after the script to generate the bcrypt hash for
+`CATENCE_CONSOLE_PASSWORD_HASH` — it prompts for the password on the terminal,
+never echoes it, and uses the compose project so it works no matter what image
+tag the script built:
+
+```sh
+./catence-deploy/hash-password.sh
+```
+
+Paste the output into `CATENCE_CONSOLE_PASSWORD_HASH` in `catence-deploy/.env`,
+then start the stack (`./deploy-console.sh beta` again, or
+`docker compose -f catence-deploy/docker-compose.yml --env-file catence-deploy/.env up -d`).
+
+If you prefer, re-run the deploy script with `--generate-secrets` instead and
+answer the interactive password prompt; it saves the hash to `.env` for you.
+Without the helper (for example an older deployment), the equivalent command
+is `docker run --rm -it --entrypoint /opt/catence-console/bin/catence-console
+<image-tag> auth hash-password`, where `<image-tag>` is the tag printed by the
+script.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catence",
-  "version": "0.1.0",
+  "version": "0.2.0-beta.10",
   "description": "Local MCP access to normalized Garmin, Intervals.icu, and targeted Strava fitness data.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -28,6 +28,8 @@
     "README.md",
     "config.example.json",
     "docs",
+    "scripts/discover-opencode-go.mjs",
+    "scripts/discover-opencode-zen.mjs",
     "pyproject.toml",
     "uv.lock",
     "python/__init__.py",
@@ -55,6 +57,8 @@
     "mcp": "tsx src/interfaces/mcp/main.ts",
     "console": "uv run --project console catence-console serve",
     "console:doctor": "uv run --project console catence-console doctor",
+    "discover:opencode-go": "node scripts/discover-opencode-go.mjs",
+    "discover:opencode-zen": "node scripts/discover-opencode-zen.mjs",
     "package:check": "npm pack --dry-run",
     "release:check": "node scripts/release-artifacts.mjs check",
     "mcpb:validate": "npm exec --yes --package @anthropic-ai/mcpb -- mcpb validate mcpb/manifest.json",
@@ -80,6 +84,6 @@
   "overrides": {
     "fast-uri": "3.1.5",
     "hono": "4.12.34",
-    "nanoid": "3.3.17"
+    "nanoid": "3.3.18"
   }
 }

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

@@ -4,11 +4,14 @@ import argparse
 import getpass
 import json
 import os
+import signal
+import sys
 from datetime import date
 from pathlib import Path
 
+from .progress import ProgressReporter
 from .staging import StagingWriter
-from .worker import GarminStagingWorker
+from .worker import GarminStagingWorker, WorkerInterrupted
 
 
 def parse_args() -> argparse.Namespace:
@@ -43,19 +46,37 @@ def main() -> None:
     token_store.parent.mkdir(parents=True, exist_ok=True)
     client = Garmin(email, password, prompt_mfa=lambda: input("Garmin MFA code: "))
     client.login(str(token_store))
+    reporter = ProgressReporter(args.run_id)
+    reporter.set_stage("login")
+    reporter.finish("login")
     known_hashes: dict[str, str] = {}
     if args.known_activities and args.known_activities.exists():
         loaded = json.loads(args.known_activities.read_text(encoding="utf-8"))
         if isinstance(loaded, dict):
             known_hashes = {str(key): str(value) for key, value in loaded.items()}
-    GarminStagingWorker(client, writer, args.data_dir, known_hashes).sync(
-        daily_from_date=None if args.skip_daily else args.daily_from_date or args.from_date,
-        activity_from_date=None if args.skip_activities else args.activity_from_date or args.from_date,
-        to_date=args.to_date,
-        daily_to_date=args.daily_to_date,
-        activity_to_date=args.activity_to_date,
-        include_non_historical=not args.historical_only,
-    )
+    worker = GarminStagingWorker(client, writer, args.data_dir, known_hashes, progress=reporter)
+    interrupt_signal: int | None = None
+
+    def _request_interrupt(signum: int, _frame: object) -> None:
+        nonlocal interrupt_signal
+        interrupt_signal = signum
+        worker.request_interrupt()
+
+    signal.signal(signal.SIGINT, _request_interrupt)
+    signal.signal(signal.SIGTERM, _request_interrupt)
+    try:
+        worker.sync(
+            daily_from_date=None if args.skip_daily else args.daily_from_date or args.from_date,
+            activity_from_date=None if args.skip_activities else args.activity_from_date or args.from_date,
+            to_date=args.to_date,
+            daily_to_date=args.daily_to_date,
+            activity_to_date=args.activity_to_date,
+            include_non_historical=not args.historical_only,
+        )
+    except WorkerInterrupted:
+        reporter.finish("interrupted")
+        raise SystemExit(130 if interrupt_signal == signal.SIGINT else 143)
+    reporter.finish("completed")
 
 
 if __name__ == "__main__":

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

@@ -0,0 +1,85 @@
+"""Progress reporting for Garmin sync runs.
+
+Emits single-line JSON progress records (kind: 'progress') on stdout so the
+Node management layer can persist heartbeats without parsing the staging
+JSONL consumed by the importer.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+
+class ProgressReporter:
+    """Throttled progress publisher writing NDJSON records to stdout."""
+
+    def __init__(
+        self,
+        run_id: str,
+        provider: str = "garmin",
+        emit: Callable[[str], None] = lambda line: print(line, flush=True),
+        interval_seconds: float = 2.0,
+    ) -> None:
+        self.run_id = run_id
+        self.provider = provider
+        self.emit = emit
+        self.interval_seconds = interval_seconds
+        self._started = time.monotonic()
+        self._last_emitted = 0.0
+        self.stage = "starting"
+        self.current_step: str | None = None
+        self.completed_units = 0
+        self.total_units: int | None = None
+
+    def set_stage(self, stage: str) -> None:
+        """Switch phases, resetting phase-local counters and forcing a publish."""
+        if stage != self.stage:
+            self.stage = stage
+            self.current_step = None
+            self.completed_units = 0
+            self.total_units = None
+            self.publish(force=True)
+
+    def advance(self, completed: int | None = None, total: int | None = None, step: str | None = None) -> None:
+        if completed is not None:
+            self.completed_units = completed
+        if total is not None:
+            self.total_units = total
+        if step is not None:
+            self.current_step = step
+        self.publish()
+
+    def publish(self, force: bool = False) -> None:
+        now = time.monotonic()
+        if not force and now - self._last_emitted < self.interval_seconds:
+            return
+        self._last_emitted = now
+        elapsed = now - self._started
+        percent = 0.0
+        eta: float | None = None
+        if self.total_units and self.total_units > 0:
+            percent = min(100.0, max(0.0, self.completed_units / self.total_units * 100.0))
+            if self.completed_units > 0 and self.completed_units < self.total_units:
+                rate = elapsed / self.completed_units
+                eta = rate * (self.total_units - self.completed_units)
+        record = {
+            "kind": "progress",
+            "runId": self.run_id,
+            "provider": self.provider,
+            "stage": self.stage,
+            "currentStep": self.current_step,
+            "completedUnits": self.completed_units,
+            "totalUnits": self.total_units,
+            "percentComplete": round(percent, 2),
+            "elapsedSeconds": round(elapsed, 1),
+            "estimatedRemainingSeconds": round(eta, 1) if eta is not None else None,
+            "heartbeatAt": datetime.now(timezone.utc).isoformat(),
+        }
+        self.emit(json.dumps(record, separators=(",", ":")))
+
+    def finish(self, stage: str = "completed") -> None:
+        self.stage = stage
+        self.publish(force=True)