@aliou/pi-synthetic 0.18.0 → 0.18.1

package/README.md

@@ -56,6 +56,8 @@ Once installed, select `synthetic` as your provider and choose from available mo
 
 All models are accessed through Synthetic's API. Some models are hosted by Synthetic directly (`provider: "synthetic"` in the model config); others are proxied by Synthetic to upstream backends such as Fireworks or Together.
 
+Synthetic also provides permanent aliases (`syn:large:text`, `syn:small:text`, `syn:large:vision`, `syn:small:vision`) that route to the current best model for each category. These aliases are stable across model rotations — using an alias means no reconfiguration when models change. Alias models are always visible even when Proxied Models is disabled.
+
 By default, new installs show only Synthetic-hosted models. You can enable proxied models in `/synthetic:settings` under **Models > Proxied Models**. Existing configurations keep proxied models enabled to preserve prior behavior.
 
 The `provider` field in `src/extensions/provider/models.ts` is for maintenance only and is stripped before registering models with Pi, so users always select the `synthetic` provider.
@@ -109,13 +111,24 @@ The **Proxied Models** setting is not a loadable extension feature. It is a regu
 
 ## Adding or Updating Models
 
-Models are hardcoded in `src/extensions/provider/models.ts`. To add or update models:
+Models are hardcoded in `src/extensions/provider/models.ts`. Entries are a union of concrete models and thin aliases (`syn:*` IDs).
+
+### Adding a concrete model
 
 1. Edit `src/extensions/provider/models.ts`
-2. Add the model configuration following the `SyntheticModelConfig` interface
+2. Append a concrete model following the `SyntheticModelConfig` interface
 3. Set `provider` to the upstream backend Synthetic uses for that model, such as `synthetic`, `fireworks`, or `together`
 4. Run `pnpm run typecheck` to verify
 
+### Adding an alias model
+
+1. Add a thin `{ id, name, aliasFor }` entry at the top of `SYNTHETIC_MODELS`
+2. Set `id` and `name` from the Synthetic API
+3. Set `aliasFor` to `"hf:" + hugging_face_id` from the Synthetic API
+4. The resolved alias inherits all fields from the target at build time
+
+When Synthetic changes which model an alias routes to, update only the `aliasFor` field.
+
 ## Development
 
 ### Setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-synthetic",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "license": "MIT",
   "type": "module",
   "private": false,

package/src/extensions/provider/index.ts

@@ -28,19 +28,46 @@ import {
 } from "../../types/quotas";
 import { fetchQuotas } from "../../utils/quotas";
 import { SYNTHETIC_OVERFLOW_PATTERN } from "./context-overflow";
-import { SYNTHETIC_MODELS } from "./models";
+import {
+  type ConcreteSyntheticModelConfig,
+  isAlias,
+  SYNTHETIC_MODELS,
+} from "./models";
 
 export function buildSyntheticProviderModels(includeProxiedModels: boolean) {
-  return SYNTHETIC_MODELS.filter(
-    (model) => includeProxiedModels || model.provider === "synthetic",
-  ).map(({ provider: _provider, ...model }) => ({
-    ...model,
-    compat: {
-      supportsDeveloperRole: false,
-      maxTokensField: "max_tokens" as const,
-      ...model.compat,
-    },
-  }));
+  const concreteModels = SYNTHETIC_MODELS.filter(
+    (m): m is ConcreteSyntheticModelConfig => !isAlias(m),
+  );
+  const byId = new Map(concreteModels.map((m) => [m.id, m]));
+
+  const resolved = SYNTHETIC_MODELS.map((entry) => {
+    if (!isAlias(entry)) return entry;
+
+    const target = byId.get(entry.aliasFor);
+    if (!target) {
+      throw new Error(
+        `Synthetic alias "${entry.id}" references missing model "${entry.aliasFor}"`,
+      );
+    }
+
+    return {
+      ...target,
+      id: entry.id,
+      name: entry.name,
+      provider: "synthetic" as const,
+    };
+  });
+
+  return resolved
+    .filter((model) => includeProxiedModels || model.provider === "synthetic")
+    .map(({ provider: _provider, ...model }) => ({
+      ...model,
+      compat: {
+        supportsDeveloperRole: false,
+        maxTokensField: "max_tokens" as const,
+        ...model.compat,
+      },
+    }));
 }
 
 interface RegisterSyntheticProviderOptions {

package/src/extensions/provider/models.ts

@@ -9,14 +9,68 @@ export interface SyntheticModelConfig extends ProviderModelConfig {
   provider: string;
 }
 
-export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
+/** A thin alias that resolves to a concrete model at build time. */
+export interface SyntheticModelAliasConfig {
+  id: string;
+  name: string;
+  /** Full model ID of the concrete target this alias resolves to. */
+  aliasFor: string;
+}
+
+/** Concrete model with full spec; aliases are excluded. */
+export type ConcreteSyntheticModelConfig = SyntheticModelConfig & {
+  aliasFor?: never;
+};
+
+export function isAlias(
+  entry: ConcreteSyntheticModelConfig | SyntheticModelAliasConfig,
+): entry is SyntheticModelAliasConfig {
+  return "aliasFor" in entry;
+}
+
+export type SyntheticModelEntry =
+  | ConcreteSyntheticModelConfig
+  | SyntheticModelAliasConfig;
+
+export const SYNTHETIC_MODELS: SyntheticModelEntry[] = [
+  // API: syn:large:text → alias for hf:zai-org/GLM-5.1
+  {
+    id: "syn:large:text",
+    name: "syn:large:text",
+    aliasFor: "hf:zai-org/GLM-5.1",
+  },
+  // API: syn:small:text → alias for hf:zai-org/GLM-4.7-Flash
+  {
+    id: "syn:small:text",
+    name: "syn:small:text",
+    aliasFor: "hf:zai-org/GLM-4.7-Flash",
+  },
+  // API: syn:large:vision → alias for hf:moonshotai/Kimi-K2.6
+  {
+    id: "syn:large:vision",
+    name: "syn:large:vision",
+    aliasFor: "hf:moonshotai/Kimi-K2.6",
+  },
+  // API: syn:small:vision → alias for hf:moonshotai/Kimi-K2.6
+  {
+    id: "syn:small:vision",
+    name: "syn:small:vision",
+    aliasFor: "hf:moonshotai/Kimi-K2.6",
+  },
   // API: hf:zai-org/GLM-4.7 → ctx=202752
   {
     id: "hf:zai-org/GLM-4.7",
     name: "zai-org/GLM-4.7",
     provider: "synthetic",
     reasoning: true,
-    thinkingLevelMap: { minimal: null, xhigh: null },
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
     compat: {
       supportsReasoningEffort: true,
     },
@@ -36,7 +90,14 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "zai-org/GLM-5",
     provider: "synthetic",
     reasoning: true,
-    thinkingLevelMap: { minimal: null, xhigh: null },
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
     compat: {
       supportsReasoningEffort: true,
     },
@@ -56,7 +117,14 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "zai-org/GLM-5.1",
     provider: "synthetic",
     reasoning: true,
-    thinkingLevelMap: { minimal: null, xhigh: null },
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
     compat: {
       supportsReasoningEffort: true,
       supportsDeveloperRole: false,
@@ -77,7 +145,14 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "zai-org/GLM-4.7-Flash",
     provider: "synthetic",
     reasoning: true,
-    thinkingLevelMap: { minimal: null, xhigh: null },
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
     compat: {
       supportsReasoningEffort: true,
     },
@@ -97,6 +172,17 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "deepseek-ai/DeepSeek-V3.2",
     provider: "fireworks",
     reasoning: true,
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
+    compat: {
+      supportsReasoningEffort: true,
+    },
     input: ["text"],
     cost: {
       input: 0.56,
@@ -145,7 +231,14 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "moonshotai/Kimi-K2.6",
     provider: "synthetic",
     reasoning: true,
-    thinkingLevelMap: { minimal: null, low: null, xhigh: null },
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
     compat: {
       supportsReasoningEffort: true,
     },
@@ -165,6 +258,17 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "Qwen/Qwen3.5-397B-A17B",
     provider: "together",
     reasoning: true,
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
+    compat: {
+      supportsReasoningEffort: true,
+    },
     input: ["text", "image"],
     cost: {
       input: 0.6,
@@ -181,7 +285,14 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "MiniMaxAI/MiniMax-M2.5",
     provider: "synthetic",
     reasoning: true,
-    thinkingLevelMap: { off: null, minimal: null, low: null, xhigh: null },
+    thinkingLevelMap: {
+      off: null,
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
     input: ["text"],
     cost: {
       input: 0.4,
@@ -202,7 +313,14 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     name: "nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4",
     provider: "synthetic",
     reasoning: true,
-    thinkingLevelMap: { minimal: null, low: null, xhigh: null },
+    thinkingLevelMap: {
+      off: "none",
+      minimal: null,
+      low: null,
+      medium: "medium",
+      high: null,
+      xhigh: null,
+    },
     compat: {
       supportsReasoningEffort: true,
     },
@@ -216,85 +334,4 @@ export const SYNTHETIC_MODELS: SyntheticModelConfig[] = [
     contextWindow: 262144,
     maxTokens: 65536,
   },
-  // API: syn:large:text → alias for hf:zai-org/GLM-5.1 → ctx=196608, out=65536
-  {
-    id: "syn:large:text",
-    name: "syn:large:text",
-    provider: "synthetic",
-    reasoning: true,
-    thinkingLevelMap: { minimal: null, xhigh: null },
-    compat: {
-      supportsReasoningEffort: true,
-      supportsDeveloperRole: false,
-    },
-    input: ["text"],
-    cost: {
-      input: 1,
-      output: 3,
-      cacheRead: 1,
-      cacheWrite: 0,
-    },
-    contextWindow: 196608,
-    maxTokens: 65536,
-  },
-  // API: syn:small:text → alias for hf:zai-org/GLM-4.7-Flash → ctx=196608, out=65536
-  {
-    id: "syn:small:text",
-    name: "syn:small:text",
-    provider: "synthetic",
-    reasoning: true,
-    thinkingLevelMap: { minimal: null, xhigh: null },
-    compat: {
-      supportsReasoningEffort: true,
-    },
-    input: ["text"],
-    cost: {
-      input: 0.1,
-      output: 0.5,
-      cacheRead: 0.1,
-      cacheWrite: 0,
-    },
-    contextWindow: 196608,
-    maxTokens: 65536,
-  },
-  // API: syn:large:vision → alias for hf:moonshotai/Kimi-K2.6 → ctx=262144, out=65536
-  {
-    id: "syn:large:vision",
-    name: "syn:large:vision",
-    provider: "synthetic",
-    reasoning: true,
-    thinkingLevelMap: { minimal: null, low: null, xhigh: null },
-    compat: {
-      supportsReasoningEffort: true,
-    },
-    input: ["text", "image"],
-    cost: {
-      input: 0.95,
-      output: 4,
-      cacheRead: 0.95,
-      cacheWrite: 0,
-    },
-    contextWindow: 262144,
-    maxTokens: 65536,
-  },
-  // API: syn:small:vision → alias for hf:moonshotai/Kimi-K2.6 → ctx=262144, out=65536
-  {
-    id: "syn:small:vision",
-    name: "syn:small:vision",
-    provider: "synthetic",
-    reasoning: true,
-    thinkingLevelMap: { minimal: null, low: null, xhigh: null },
-    compat: {
-      supportsReasoningEffort: true,
-    },
-    input: ["text", "image"],
-    cost: {
-      input: 0.95,
-      output: 4,
-      cacheRead: 0.95,
-      cacheWrite: 0,
-    },
-    contextWindow: 262144,
-    maxTokens: 65536,
-  },
 ];