feat: add model specs

specs/DESIGN.md

@@ -8,7 +8,8 @@ Component-level design docs live under `specs/designs/`, organized by category:
 specs/designs/
 ├── 00-foundation/     — core server infrastructure (server lifecycle, auth, config)
 ├── 01-data/           — external data sources (Git, Kubernetes)
-└── 10-layout/         — overall UI designs
+├── 10-layout/         — overall UI designs
+└── 11-models/         — model page designs
 ```
 
 ---

specs/designs/11-models/detail.md

@@ -0,0 +1,80 @@
+# Model Detail Page
+
+## Overview
+
+Single model detail view. Branches on `model.mode` for external vs managed layout.
+
+Follows the layout of `specs/designs/10-layout/detail.md`, only the details are documented in this spec.
+
+## Page Name
+
+"{model.name}" for title and breadcrumb
+
+## User Flows
+
+### Edit Model
+
+- Click "Edit" button
+- Go to `/workloads/models/[id]/edit`
+
+### Delete Model
+
+- Click "More" menu button
+- Click "Delete" button
+- Confirm deletion with a dialog
+- If confirmed, delete the model then go to `/workloads/models`
+
+### Test Model (External Model or Deployed Managed Model)
+
+- Click "More" menu button
+- Click "Test" button
+
+### Deploy Model (Not Deployed Managed Model)
+
+- Click "More" menu button
+- Click "Deploy" button
+
+## Page Header
+
+```
+[Icon] Model Name                       [status badge] [Edit] [⋮]
+       External | Managed
+```
+
+- Icon: provider logo or custom icon
+- Model name (primary)
+- Mode label below the name: `External` or `Managed`
+- Status badge (right)
+- Edit button: navigates to the edit page
+- ⋮ menu: includes Delete and a context action (`Test` for external or deployed models, `Deploy` for not-deployed managed models)
+
+## Configuration Panel
+
+Always shown.
+
+- Category
+- External mode: provider, model id, endpoint/auth settings, and default inference settings when present
+- Managed mode: source/runtime settings and runtime inference settings when present
+
+## Basic Information Panel
+
+Always shown. Includes base model information.
+
+## Capabilities Panel
+
+Hidden when empty.
+
+- Family
+- Base Model ID
+- Release Date
+- Context / embedding fields by category
+- Inputs / Outputs / Capabilities (language models)
+- Languages
+
+## Deployment Panel (Managed Mode)
+
+Always shown for managed models. Shows deployment/runtime configuration.
+
+## Management Tabs
+
+Always shown.

specs/designs/11-models/domain.md

@@ -0,0 +1,43 @@
+# Model Domain
+
+Models are either external endpoints or managed deployments.
+
+## Core Fields
+
+All models share these core fields:
+
+- identity: id, name
+- presentation: icon, description, tags
+- classification: mode, category
+- metadata: info
+
+## Metadata (info)
+
+Model metadata is grouped under info.
+
+- common metadata: family, baseModelId, releaseDate, parameterCount, languages
+- language metadata: contextWindow, inputs, outputs, capabilities
+- embedding metadata: embeddingDimensions, maxInputTokens
+
+## External Model
+
+External models define how to call a provider-hosted model.
+
+- provider and providerModel
+- optional endpoint overrides: apiBase, apiVersion
+- auth configuration
+- optional default inference settings
+- optional availability status
+
+## Managed Model
+
+Managed models define deployment/runtime configuration.
+
+- optional huggingFace source info (endpoint, repo, revision, fileName)
+- runtime template
+- optional runtime inference settings
+- optional deployment status
+
+## Model Union
+
+- Model = ExternalModel | ManagedModel

specs/designs/11-models/form.md

@@ -0,0 +1,67 @@
+# Model Form Page
+
+## Overview
+
+Shared `<ModelForm>` handles both create and edit. The `mode` toggle (External vs Managed) is chosen at the top in create mode and is locked in edit mode.
+
+Follows the form layout in `specs/designs/10-layout/form.md`, only the details are documented in this spec.
+
+## Form Layout
+
+### Basic Information (shared)
+
+Beyond the standard Icon + Name + Mode fields described in the layout spec:
+
+- **Icon**: default `language`
+- **Name**: placeholder `e.g. DeepSeek R1 Production`
+- **Model Category**: `Language` | `Embedding` | `Reranker`; default `Language`
+
+Description and tags are supported in Basic Information.
+
+Two optional sub-sections:
+
+#### Provider (nested, collapsible)
+
+- **Base Model ID**
+- **Family**
+- **Release Date**
+- **Parameter Count**
+
+#### Capabilities (nested, collapsible)
+
+- **Inputs**: `Text` | `Image` | `Video` | `Audio`; default `[text]`
+- **Outputs**: `Text` | `Image` | `Video` | `Audio`; default `[text]`
+- **Language models**: context window, max output tokens, inputs, outputs
+- **Embedding models**: embedding dimensions, max input tokens
+- **Languages**: list input (e.g. English, Chinese, Spanish)
+- **Tags**: list input (e.g. Reasoning, Tool Use, Code Generation)
+
+### Deployment (managed only)
+
+- **Hugging Face Endpoint**
+- **Hugging Face Repository** (required)
+- **Revision**
+- **File**
+- **Runtime Settings**
+
+### Endpoint (external mode)
+
+- **Provider**
+- **Model ID** (`providerModel`)
+- **API Base**
+- **API Version**
+- Auth fields
+
+### Inference Settings
+
+- External language models: optional default sampling (`temperature`, `maxTokens`, `topP`)
+- Managed models: context window and optional runtime sampling (`temperature`, `topK`, `topP`) for language category
+
+## Validation
+
+- Name is required
+
+## Breadcrumb
+
+- Create: `Models / [New Model]`
+- Edit: `Models / Edit [{model.name}]`

specs/designs/11-models/list.md

@@ -0,0 +1,79 @@
+# Models List Page
+
+## Overview
+
+Card grid list of all models (external + managed).
+
+Follows the layout of `specs/designs/10-layout/list.md`, only the details are documented in this spec.
+
+## Page Name
+
+"Models" for title and breadcrumb
+
+## Filters
+
+| Row        | Mode   | Values                             | Default | Extra             |
+| ---------- | ------ | ---------------------------------- | ------- | ----------------- |
+| Mode       | Single | All, External, Managed             | All     | shows count badge |
+| Category   | Multi  | Language, Embedding, Reranker      | None    |                   |
+| Modalities | Multi  | Text, Image, Video, Audio          | None    |                   |
+| Tags       | Multi  | the tags present across all models | None    |                   |
+
+## Card Anatomy
+
+Model icon sits at the left, a fixed 48 px square, vertically centered. All others are on the right side of the card vertically positioned.
+
+The card is wider than it is tall, the width to height ratio should be at least 2:1.
+
+The information on the card is essential.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ ┌────────┐  Model Name                          [status]    │
+│ │        │  [Provider (external) or runtime (managed)]      │
+│ │        │  base model id (when available)                  │
+│ │  icon  │  [text icon], [image icon]                       │
+│ │        │                                                  │
+│ └────────┘  [reasoning] [tool call]                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Icon
+
+When using providers' logo, use plain image. When using custom icon, add background color and border.
+
+### Header
+
+- Large text for the model name
+- Status badge (right, when status is set)
+
+### Second Line
+
+- bordered box: provider name (external) / runtime name (managed)
+- base model id (when set)
+
+### Body
+
+- input modalities icons
+
+### Footer
+
+- tags
+
+## Empty States
+
+**No models at all:**
+
+```
+CpuIcon (muted)
+"No models yet."
+[New Model button]
+```
+
+**No match:**
+
+```
+CpuIcon (muted)
+"No models match your filters."
+[Clear filters link]
+```

specs/designs/11-models/testing.md

@@ -0,0 +1,52 @@
+# Model Test Page
+
+## Overview
+
+A sandbox for testing any model via the configured gateway proxy. The page lets a user select one model, then renders a category-specific tester (`language`, `embedding`, `reranker`).
+
+## Route
+
+`/utilities/testing/model`
+
+Optional query parameter `?model=<modelId>` pre-selects the model on load.
+
+The selected model determines which tester is shown:
+
+- language: chat tester
+- embedding: embedding tester
+- reranker: rerank tester
+
+## Model Selector
+
+The selected model is shown in the top selector button (icon + name). If no model is selected, the page shows a placeholder prompt to select a model.
+
+## Language Mode (Chat)
+
+Behavior:
+
+- Sends `POST /api/workspaces/[workspaceId]/models/[id]/test` with `{ messages, parameters }`.
+- Assistant output is streamed and rendered incrementally.
+- While request is in-flight, Send becomes Stop and cancels via `AbortController`.
+- `Clear session` resets thread, system prompt, errors, and parameter values.
+
+## Embedding Mode
+
+Behavior:
+
+- Sends `POST /api/workspaces/[workspaceId]/models/[id]/test` with a plain string body.
+- UI shows latency, dimensions, token usage, and raw vector data.
+
+## Reranker Mode
+
+Behavior:
+
+- Sends `POST /api/workspaces/[workspaceId]/models/[id]/test` with `{ query, documents }`.
+- UI displays sorted documents by relevance score and latency/token usage metadata.
+
+## API Behavior
+
+The test endpoint routes requests by model category and returns category-appropriate responses:
+
+- language: streaming chat response
+- embedding: embedding result with metadata
+- reranker: ranked documents with metadata