@aliou/pi-synthetic 0.17.4 → 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.17.4",
+  "version": "0.18.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -29,7 +29,8 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "!src/**/*.test.ts"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "0.74.0",
@@ -40,8 +41,8 @@
     "@aliou/pi-utils-ui": "^0.4.0"
   },
   "devDependencies": {
-    "@aliou/biome-plugins": "^0.7.0",
-    "@biomejs/biome": "^2.4.2",
+    "@aliou/biome-plugins": "^0.8.1",
+    "@biomejs/biome": "^2.4.15",
     "@changesets/cli": "^2.27.11",
     "@earendil-works/pi-coding-agent": "0.74.0",
     "typebox": "^1.1.37",

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,
     },

package/src/extensions/provider/index.test.ts

@@ -1,46 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { buildSyntheticProviderModels } from "./index";
-import { SYNTHETIC_MODELS } from "./models";
-
-describe("buildSyntheticProviderModels", () => {
-  it("excludes proxied models when includeProxiedModels is false", () => {
-    const models = buildSyntheticProviderModels(false);
-    for (const model of models) {
-      const source = SYNTHETIC_MODELS.find((m) => m.id === model.id);
-      expect(source).toBeDefined();
-      expect(source?.provider).toBe("synthetic");
-    }
-  });
-
-  it("includes all models when includeProxiedModels is true", () => {
-    const models = buildSyntheticProviderModels(true);
-    expect(models).toHaveLength(SYNTHETIC_MODELS.length);
-  });
-
-  it("does not expose the internal provider field", () => {
-    const models = buildSyntheticProviderModels(true);
-    for (const model of models) {
-      expect(model).not.toHaveProperty("provider");
-    }
-  });
-
-  it("sets default compat fields on every model", () => {
-    const models = buildSyntheticProviderModels(true);
-    for (const model of models) {
-      expect(model.compat).toMatchObject({
-        supportsDeveloperRole: false,
-      });
-      expect(model.compat).toHaveProperty("maxTokensField");
-    }
-  });
-
-  it("preserves model-specific compat overrides", () => {
-    const models = buildSyntheticProviderModels(true);
-    const miniMax = models.find((m) => m.id === "hf:MiniMaxAI/MiniMax-M2.5");
-    expect(miniMax).toBeDefined();
-    expect(miniMax?.compat).toMatchObject({
-      supportsDeveloperRole: false,
-      maxTokensField: "max_completion_tokens",
-    });
-  });
-});

package/src/extensions/provider/models.test.ts

@@ -1,217 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { SYNTHETIC_MODELS } from "./models";
-
-interface ApiModel {
-  id: string;
-  name: string;
-  provider: string | null;
-  input_modalities: string[];
-  output_modalities: string[];
-  context_length: number;
-  max_output_length: number;
-  pricing: {
-    prompt: string;
-    completion: string;
-    input_cache_reads: string;
-    input_cache_writes: string;
-  };
-  supported_features?: string[];
-}
-
-interface ApiResponse {
-  data: ApiModel[];
-}
-
-interface Discrepancy {
-  model: string;
-  field: string;
-  hardcoded: unknown;
-  api: unknown;
-}
-
-async function fetchApiModels(): Promise<ApiModel[]> {
-  // Making ourselves known
-  const response = await fetch("https://api.synthetic.new/openai/v1/models", {
-    headers: {
-      Referer: "https://github.com/aliou/pi-synthetic",
-    },
-  });
-
-  if (!response.ok) {
-    throw new Error(
-      `API request failed: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const data: ApiResponse = await response.json();
-  return data.data;
-}
-
-function parsePrice(priceStr: string): number {
-  // Convert "$0.0000006" to 0.6 (dollars per million tokens)
-  const match = priceStr.match(/\$?(\d+\.?\d*)/);
-  if (!match) return 0;
-  const pricePerToken = Number.parseFloat(match[1]);
-  // API prices are per token, hardcoded prices are per million tokens
-  return pricePerToken * 1_000_000;
-}
-
-function compareModels(
-  apiModels: ApiModel[],
-  hardcodedModels: typeof SYNTHETIC_MODELS,
-): Discrepancy[] {
-  const discrepancies: Discrepancy[] = [];
-
-  for (const hardcoded of hardcodedModels) {
-    const apiModel = apiModels.find((m) => m.id === hardcoded.id);
-
-    if (!apiModel) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "exists",
-        hardcoded: true,
-        api: false,
-      });
-      continue;
-    }
-
-    // Check input modalities (text vs image support)
-    const apiInputs = apiModel.input_modalities.sort();
-    const hardcodedInputs = [...hardcoded.input].sort();
-    if (JSON.stringify(apiInputs) !== JSON.stringify(hardcodedInputs)) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "input",
-        hardcoded: hardcodedInputs,
-        api: apiInputs,
-      });
-    }
-
-    // Check context window
-    if (apiModel.context_length !== hardcoded.contextWindow) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "contextWindow",
-        hardcoded: hardcoded.contextWindow,
-        api: apiModel.context_length,
-      });
-    }
-
-    // Check max output tokens (skip if API doesn't provide it)
-    if (
-      apiModel.max_output_length !== undefined &&
-      apiModel.max_output_length !== hardcoded.maxTokens
-    ) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "maxTokens",
-        hardcoded: hardcoded.maxTokens,
-        api: apiModel.max_output_length,
-      });
-    }
-
-    // Check input cost (convert API price to per-million rate)
-    const apiInputCost = parsePrice(apiModel.pricing.prompt);
-    const epsilon = 0.001; // Small tolerance for floating point
-    if (Math.abs(apiInputCost - hardcoded.cost.input) > epsilon) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "cost.input",
-        hardcoded: hardcoded.cost.input,
-        api: apiInputCost,
-      });
-    }
-
-    // Check output cost
-    const apiOutputCost = parsePrice(apiModel.pricing.completion);
-    if (Math.abs(apiOutputCost - hardcoded.cost.output) > epsilon) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "cost.output",
-        hardcoded: hardcoded.cost.output,
-        api: apiOutputCost,
-      });
-    }
-
-    // Check cache read cost
-    const apiCacheReadCost = parsePrice(apiModel.pricing.input_cache_reads);
-    if (Math.abs(apiCacheReadCost - hardcoded.cost.cacheRead) > epsilon) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "cost.cacheRead",
-        hardcoded: hardcoded.cost.cacheRead,
-        api: apiCacheReadCost,
-      });
-    }
-
-    // Check reasoning capability from supported_features (skip if API doesn't provide it)
-    if (apiModel.supported_features !== undefined) {
-      const apiSupportsReasoning =
-        apiModel.supported_features.includes("reasoning");
-      if (apiSupportsReasoning !== hardcoded.reasoning) {
-        discrepancies.push({
-          model: hardcoded.id,
-          field: "reasoning",
-          hardcoded: hardcoded.reasoning,
-          api: apiSupportsReasoning,
-        });
-      }
-    }
-
-    // Check provider
-    if (
-      apiModel.provider !== null &&
-      apiModel.provider !== hardcoded.provider
-    ) {
-      discrepancies.push({
-        model: hardcoded.id,
-        field: "provider",
-        hardcoded: hardcoded.provider,
-        api: apiModel.provider,
-      });
-    }
-  }
-
-  // Check for API models not in hardcoded list
-  for (const apiModel of apiModels) {
-    const hardcoded = hardcodedModels.find((m) => m.id === apiModel.id);
-    if (!hardcoded) {
-      discrepancies.push({
-        model: apiModel.id,
-        field: "exists",
-        hardcoded: false,
-        api: true,
-      });
-    }
-  }
-
-  return discrepancies;
-}
-
-describe("Synthetic models", () => {
-  it("should match API model definitions", { timeout: 30000 }, async () => {
-    const apiModels = await fetchApiModels();
-    const discrepancies = compareModels(apiModels, SYNTHETIC_MODELS);
-
-    if (discrepancies.length > 0) {
-      console.error("\nModel discrepancies found:");
-      console.error("==========================");
-      for (const d of discrepancies) {
-        if (d.field === "exists") {
-          if (d.hardcoded) {
-            console.error(`  ${d.model}: Missing from API`);
-          } else {
-            console.error(`  ${d.model}: Missing from hardcoded models (NEW)`);
-          }
-        } else {
-          console.error(`  ${d.model}.${d.field}:`);
-          console.error(`    hardcoded: ${JSON.stringify(d.hardcoded)}`);
-          console.error(`    api:       ${JSON.stringify(d.api)}`);
-        }
-      }
-      console.error("==========================\n");
-    }
-
-    expect(discrepancies).toHaveLength(0);
-  });
-});