saeeol 1.0.9 → 1.1.1

package/src/provider/local/rag.ts

@@ -0,0 +1,112 @@
+/** RAG support — embedding models, rerankers, vector DB management */
+
+import { Effect } from "effect"
+import * as Log from "@saeeol/core/util/log"
+import type { RAGAsset, RAGAssetType } from "./types"
+import * as Hub from "./hub"
+import * as Manager from "./model-manager"
+
+const log = Log.create({ service: "local/rag" })
+
+/** Well-known embedding models with typical dimensions */
+export const EMBEDDING_MODELS: Array<{ id: string; repo: string; name: string; dimensions: number; sizeBytes: number }> = [
+  { id: "bge-small-en", repo: "BAAI/bge-small-en-v1.5", name: "BGE Small English", dimensions: 384, sizeBytes: 130_000_000 },
+  { id: "bge-base-en", repo: "BAAI/bge-base-en-v1.5", name: "BGE Base English", dimensions: 768, sizeBytes: 420_000_000 },
+  { id: "bge-large-en", repo: "BAAI/bge-large-en-v1.5", name: "BGE Large English", dimensions: 1024, sizeBytes: 1_300_000_000 },
+  { id: "bge-m3", repo: "BAAI/bge-m3", name: "BGE M3 Multilingual", dimensions: 1024, sizeBytes: 2_200_000_000 },
+  { id: "nomic-embed", repo: "nomic-ai/nomic-embed-text-v1.5", name: "Nomic Embed Text", dimensions: 768, sizeBytes: 550_000_000 },
+  { id: "all-minilm-l6", repo: "sentence-transformers/all-MiniLM-L6-v2", name: "MiniLM L6", dimensions: 384, sizeBytes: 80_000_000 },
+  { id: "gte-small", repo: "Alibaba-NLP/gte-base-en-v1.5", name: "GTE Base", dimensions: 768, sizeBytes: 430_000_000 },
+]
+
+/** Well-known reranker models */
+export const RERANKER_MODELS: Array<{ id: string; repo: string; name: string; sizeBytes: number }> = [
+  { id: "bge-reranker-base", repo: "BAAI/bge-reranker-base", name: "BGE Reranker Base", sizeBytes: 420_000_000 },
+  { id: "bge-reranker-large", repo: "BAAI/bge-reranker-large", name: "BGE Reranker Large", sizeBytes: 1_300_000_000 },
+  { id: "ms-marco-minilm", repo: "cross-encoder/ms-marco-MiniLM-L-6-v2", name: "MS MARCO MiniLM", sizeBytes: 80_000_000 },
+]
+
+/** Build a RAGAsset from a known embedding model */
+export function embeddingAsset(model: typeof EMBEDDING_MODELS[number]): RAGAsset {
+  return {
+    id: model.id,
+    name: model.name,
+    type: "embedding",
+    repo: model.repo,
+    format: "safetensors",
+    sizeBytes: model.sizeBytes,
+    dimensions: model.dimensions,
+  }
+}
+
+/** Build a RAGAsset from a known reranker model */
+export function rerankerAsset(model: typeof RERANKER_MODELS[number]): RAGAsset {
+  return {
+    id: model.id,
+    name: model.name,
+    type: "reranker",
+    repo: model.repo,
+    format: "safetensors",
+    sizeBytes: model.sizeBytes,
+  }
+}
+
+/** Install an embedding model for RAG */
+export async function installEmbedding(
+  model: typeof EMBEDDING_MODELS[number],
+  opts?: { onProgress?: (downloaded: number, total: number) => void; signal?: AbortSignal },
+): Promise<string> {
+  const asset = embeddingAsset(model)
+  log.info("installing embedding model", { repo: asset.repo })
+
+  // Download model config and weights
+  const files = ["config.json", "tokenizer.json", "tokenizer_config.json"]
+  let lastPath = ""
+  for (const file of files) {
+    try {
+      lastPath = await Manager.installRAG(
+        { repo: asset.repo, filename: file, sizeBytes: 0 },
+        opts,
+      )
+    } catch { /* non-critical */ }
+  }
+
+  // Download safetensors weights
+  const weightFile = "model.safetensors"
+  lastPath = await Manager.installRAG(
+    { repo: asset.repo, filename: weightFile, sizeBytes: asset.sizeBytes },
+    opts,
+  )
+
+  return lastPath
+}
+
+/** Install a reranker model */
+export async function installReranker(
+  model: typeof RERANKER_MODELS[number],
+  opts?: { onProgress?: (downloaded: number, total: number) => void; signal?: AbortSignal },
+): Promise<string> {
+  const asset = rerankerAsset(model)
+  log.info("installing reranker model", { repo: asset.repo })
+
+  const weightFile = "model.safetensors"
+  return Manager.installRAG(
+    { repo: asset.repo, filename: weightFile, sizeBytes: asset.sizeBytes },
+    opts,
+  )
+}
+
+/** List recommended RAG assets that fit in available VRAM */
+export async function recommendForVRAM(vramMB: number): Promise<{
+  embeddings: typeof EMBEDDING_MODELS
+  rerankers: typeof RERANKER_MODELS
+}> {
+  const embeddings = EMBEDDING_MODELS.filter((m) => m.sizeBytes * 1.2 <= vramMB * 1024 * 1024)
+  const rerankers = RERANKER_MODELS.filter((m) => m.sizeBytes * 1.2 <= vramMB * 1024 * 1024)
+  return { embeddings, rerankers }
+}
+
+/** Search for RAG-compatible models on HuggingFace */
+export async function search(query?: string, type?: RAGAssetType) {
+  return Hub.searchRAG(type ?? "embedding", query, 20)
+}

package/src/provider/local/types.ts

@@ -0,0 +1,142 @@
+/** Local model orchestration — shared types */
+
+import { Schema } from "effect"
+import { optionalOmitUndefined } from "@/util/schema"
+
+// ── GPU ──
+
+export const GPUInfo = Schema.Struct({
+  index: Schema.Number,
+  name: Schema.String,
+  vramTotalMB: Schema.Number,
+  vramUsedMB: Schema.Number,
+  vramFreeMB: Schema.Number,
+  computeCapability: optionalOmitUndefined(Schema.String),
+  driverVersion: optionalOmitUndefined(Schema.String),
+  cudaVersion: optionalOmitUndefined(Schema.String),
+})
+export type GPUInfo = Schema.Schema.Type<typeof GPUInfo>
+
+export const GPUProfile = Schema.Struct({
+  gpus: Schema.Array(GPUInfo),
+  totalVRAMMB: Schema.Number,
+  availableVRAMMB: Schema.Number,
+  cudaAvailable: Schema.Boolean,
+})
+export type GPUProfile = Schema.Schema.Type<typeof GPUProfile>
+
+// ── Model Artifact ──
+
+export const Quantization = Schema.Literals([
+  "q2_k", "q3_k_s", "q3_k_m", "q3_k_l",
+  "q4_0", "q4_1", "q4_k_s", "q4_k_m",
+  "q5_0", "q5_1", "q5_k_s", "q5_k_m",
+  "q6_k", "q8_0", "fp16", "bf16", "fp32",
+])
+export type Quantization = Schema.Schema.Type<typeof Quantization>
+
+export const ModelFormat = Schema.Literals(["gguf", "safetensors", "pytorch", "onnx", "awq", "gptq"])
+export type ModelFormat = Schema.Schema.Type<typeof ModelFormat>
+
+export const ModelArtifact = Schema.Struct({
+  id: Schema.String,
+  repo: Schema.String,                     // e.g. "meta-llama/Llama-3.1-8B-Instruct"
+  filename: Schema.String,                 // e.g. "model-q4_k_m.gguf"
+  format: ModelFormat,
+  quantization: Quantization,
+  sizeBytes: Schema.Number,
+  sha256: optionalOmitUndefined(Schema.String),
+})
+export type ModelArtifact = Schema.Schema.Type<typeof ModelArtifact>
+
+// ── Model Instance (running process) ──
+
+export const ModelStatus = Schema.Literals(["stopped", "starting", "running", "error", "downloading"])
+export type ModelStatus = Schema.Schema.Type<typeof ModelStatus>
+
+export const ModelInstance = Schema.Struct({
+  id: Schema.String,
+  artifact: ModelArtifact,
+  status: ModelStatus,
+  pid: optionalOmitUndefined(Schema.Number),
+  port: optionalOmitUndefined(Schema.Number),
+  gpuIndex: optionalOmitUndefined(Schema.Number),
+  vramUsageMB: optionalOmitUndefined(Schema.Number),
+  endpoint: optionalOmitUndefined(Schema.String),
+  error: optionalOmitUndefined(Schema.String),
+})
+export type ModelInstance = Schema.Schema.Type<typeof ModelInstance>
+
+// ── Backend (Ollama, LM Studio, vLLM, etc.) ──
+
+export const BackendType = Schema.Literals(["ollama", "lmstudio", "vllm", "llama.cpp", "text-generation-webui"])
+export type BackendType = Schema.Schema.Type<typeof BackendType>
+
+export const BackendStatus = Schema.Struct({
+  type: BackendType,
+  available: Schema.Boolean,
+  endpoint: Schema.String,
+  version: optionalOmitUndefined(Schema.String),
+  loadedModels: Schema.Array(Schema.String),
+})
+export type BackendStatus = Schema.Schema.Type<typeof BackendStatus>
+
+// ── RAG / Vector DB ──
+
+export const RAGAssetType = Schema.Literals(["embedding", "reranker", "vectordb"])
+export type RAGAssetType = Schema.Schema.Type<typeof RAGAssetType>
+
+export const RAGAsset = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  type: RAGAssetType,
+  repo: Schema.String,
+  format: ModelFormat,
+  sizeBytes: Schema.Number,
+  dimensions: optionalOmitUndefined(Schema.Number),
+})
+export type RAGAsset = Schema.Schema.Type<typeof RAGAsset>
+
+// ── Download Progress ──
+
+export const DownloadState = Schema.Struct({
+  id: Schema.String,
+  bytesDownloaded: Schema.Number,
+  bytesTotal: Schema.Number,
+  speedMBps: Schema.Finite,
+  eta: optionalOmitUndefined(Schema.Number),
+  done: Schema.Boolean,
+  error: optionalOmitUndefined(Schema.String),
+})
+export type DownloadState = Schema.Schema.Type<typeof DownloadState>
+
+// ── HuggingFace Hub ──
+
+export const HFModelSearch = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  author: Schema.String,
+  downloads: Schema.Number,
+  likes: Schema.Number,
+  tags: Schema.Array(Schema.String),
+  pipelineTag: optionalOmitUndefined(Schema.String),
+  libraryName: optionalOmitUndefined(Schema.String),
+})
+export type HFModelSearch = Schema.Schema.Type<typeof HFModelSearch>
+
+export const HFSibling = Schema.Struct({
+  rfilename: Schema.String,
+})
+export type HFSibling = Schema.Schema.Type<typeof HFSibling>
+
+export const HFModelInfo = Schema.Struct({
+  id: Schema.String,
+  modelId: Schema.String,
+  sha: Schema.String,
+  siblings: Schema.Array(HFSibling),
+  tags: Schema.Array(Schema.String),
+  downloads: Schema.Number,
+  likes: Schema.Number,
+  private: Schema.Boolean,
+})
+export type HFModelInfo = Schema.Schema.Type<typeof HFModelInfo>

package/src/provider/provider-conversion.ts

@@ -115,6 +115,7 @@ export function fromModelsDevProvider(provider: ModelsDev.Provider): Info {
     id: ProviderID.make(provider.id),
     source: "custom",
     name: provider.name,
+    category: "custom" as const,
     env: [...(provider.env ?? [])],
     options: {},
     models,
@@ -135,6 +136,7 @@ export function applyConfigModels(
       env: provider.env ?? existing?.env ?? [],
       options: mergeDeep(existing?.options ?? {}, provider.options ?? {}),
       source: "config",
+      category: existing?.category ?? "cloud",
       models: existing?.models ?? {},
     }
 

package/src/provider/provider-schema.ts

@@ -79,17 +79,22 @@ export const Model = Schema.Struct({
   .pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Model = Types.DeepMutable<Schema.Schema.Type<typeof Model>>
 
+// Provider categories
+export const ProviderCategory = Schema.Literals(["local", "custom", "cloud"])
+export type ProviderCategory = typeof ProviderCategory.Type
+
 export const Info = Schema.Struct({
   id: ProviderID,
   name: Schema.String,
+  category: ProviderCategory,
   source: Schema.Literals(["env", "config", "custom", "api"]),
   env: Schema.Array(Schema.String),
   key: optionalOmitUndefined(Schema.String),
   options: Schema.Record(Schema.String, Schema.Any),
   models: Schema.Record(Schema.String, Model),
 })
-  .annotate({ identifier: "Provider" })
-  .pipe(withStatics((s) => ({ zod: zod(s) })))
+.annotate({ identifier: "Provider" })
+.pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Info = Types.DeepMutable<Schema.Schema.Type<typeof Info>>
 
 const DefaultModelIDs = Schema.Record(Schema.String, Schema.String)
@@ -99,11 +104,21 @@ export const ListResult = Schema.Struct({
   default: DefaultModelIDs,
   connected: Schema.Array(Schema.String),
   failed: Schema.Array(Schema.String),
+  categories: Schema.Struct({
+    local: Schema.Array(Schema.String),
+    custom: Schema.Array(Schema.String),
+    cloud: Schema.Array(Schema.String),
+  }),
 }).pipe(withStatics((s) => ({ zod: zod(s) })))
 export type ListResult = Types.DeepMutable<Schema.Schema.Type<typeof ListResult>>
 
 export const ConfigProvidersResult = Schema.Struct({
   providers: Schema.Array(Info),
   default: DefaultModelIDs,
+  categories: Schema.Struct({
+    local: Schema.Array(Schema.String),
+    custom: Schema.Array(Schema.String),
+    cloud: Schema.Array(Schema.String),
+  }),
 }).pipe(withStatics((s) => ({ zod: zod(s) })))
 export type ConfigProvidersResult = Types.DeepMutable<Schema.Schema.Type<typeof ConfigProvidersResult>>

package/src/provider/provider-schemas.ts

@@ -25,8 +25,11 @@ export const Model = Schema.Struct({
 }).annotate({ identifier: "Model" }).pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Model = Types.DeepMutable<Schema.Schema.Type<typeof Model>>
 
+export const ProviderCategory = Schema.Literals(["local", "custom", "cloud"])
+export type ProviderCategory = typeof ProviderCategory.Type
+
 export const Info = Schema.Struct({
-  id: ProviderID, name: Schema.String, source: Schema.Literals(["env", "config", "custom", "api"]), env: Schema.Array(Schema.String),
+  id: ProviderID, name: Schema.String, category: ProviderCategory, source: Schema.Literals(["env", "config", "custom", "api"]), env: Schema.Array(Schema.String),
   key: optionalOmitUndefined(Schema.String), options: Schema.Record(Schema.String, Schema.Any), models: Schema.Record(Schema.String, Model),
 }).annotate({ identifier: "Provider" }).pipe(withStatics((s) => ({ zod: zod(s) })))
 export type Info = Types.DeepMutable<Schema.Schema.Type<typeof Info>>
@@ -38,7 +41,11 @@ export const ConfigProvidersResult = Schema.Struct({ providers: Schema.Array(Inf
 export type ConfigProvidersResult = Types.DeepMutable<Schema.Schema.Type<typeof ConfigProvidersResult>>
 
 export function defaultModelIDs<T extends { models: Record<string, { id: string }> }>(providers: Record<string, T>) {
-  return mapValues(providers, (item) => sortModels(Object.values(item.models))[0].id)
+  return mapValues(providers, (item) => {
+    const models = Object.values(item.models ?? {})
+    if (models.length === 0) return undefined
+    return sortModels(models)[0].id
+  })
 }
 
 function cost(c: ModelsDev.Model["cost"]): Model["cost"] {
@@ -79,7 +86,7 @@ export function fromModelsDevProvider(provider: ModelsDev.Provider): Info {
       }
     }
   }
-  return { id: ProviderID.make(provider.id), source: "custom", name: provider.name, env: [...(provider.env ?? [])], options: {}, models }
+  return { id: ProviderID.make(provider.id), source: "custom", name: provider.name, category: "custom" as const, env: [...(provider.env ?? [])], options: {}, models }
 }
 
 const priority = ["gpt-5", "claude-sonnet-4", "big-pickle", "gemini-3-pro"]

package/src/provider/provider-state.ts

@@ -4,10 +4,11 @@ import * as Log from "@saeeol/core/util/log"
 import { EffectBridge } from "@/effect/bridge"
 import { InstanceState } from "@/effect/instance-state"
 import { applyConfigModels, cleanupProviders, fromModelsDevProvider } from "./provider-conversion"
-import { custom } from "./custom-loaders"
+import { custom, LOCAL_PROVIDERS, CUSTOM_PROVIDERS, CLOUD_PROVIDERS } from "./custom-loaders"
 import { ModelID, ProviderID } from "./schema"
 import type { State, CustomModelLoader, CustomVarsLoader, CustomDiscoverModels } from "./provider-types"
-import type { Info } from "./provider-schema"
+import type { Info } from "./provider-schemas"
+import type { ProviderCategory } from "./provider-schemas"
 import {
   saeeolCustomLoaders,
   patchCustomLoaderResult,
@@ -53,8 +54,15 @@ export function initState(deps: {
 
       log.info("init")
 
+      function getCategory(id: string): ProviderCategory {
+        if (LOCAL_PROVIDERS.includes(id as any)) return "local"
+        if (CUSTOM_PROVIDERS.includes(id as any)) return "custom"
+        return "cloud"
+      }
+
       function mergeProvider(providerID: ProviderID, provider: Partial<Info>) {
         const existing = providers[providerID]
+        if (!provider.category) provider.category = getCategory(providerID)
         if (existing) {
           // @ts-expect-error
           providers[providerID] = mergeDeep(existing, provider)

package/src/provider/provider.ts

@@ -31,6 +31,7 @@ export const ModelNotFoundError = namedSchemaError("ProviderModelNotFoundError",
 export const InitError = namedSchemaError("ProviderInitError", { providerID: ProviderID })
 
 export { defaultLayer, list, getModelExport as getModel, getLanguage, getSmallModel, defaultModel } from "./provider-layer"
-export { fromModelsDevProvider } from "./provider-schemas"
+export { fromModelsDevProvider, ProviderCategory } from "./provider-schemas"
+export { LOCAL_PROVIDERS, CUSTOM_PROVIDERS, CLOUD_PROVIDERS } from "./custom-loaders"
 
 export * as Provider from "./provider"

package/src/saeeol/plugins/sidebar-usage.tsx

@@ -22,7 +22,7 @@ function View(props: { api: TuiPluginApi; session_id: string }) {
     const last = messages.findLast((item): item is AssistantMessage => item.role === "assistant" && item.tokens.output > 0)
     if (!last) return null
     const tokens = last.tokens.input + last.tokens.output + last.tokens.reasoning + last.tokens.cache.read + last.tokens.cache.write
-    const model = props.api.state.provider.find((item) => item.id === last.providerID)?.models[last.modelID]
+    const model = props.api.state.provider.find((item) => item.id === last.providerID)?.models?.[last.modelID]
     const limit = model?.limit.context ?? 0
     if (!limit) return { pct: 0, label: "", color: theme().textMuted }
     const pct = Math.round((tokens / limit) * 100)

package/src/server/routes/instance/config.ts

@@ -115,7 +115,7 @@ export const ConfigRoutes = lazy(() =>
             const token = saeeolAuth?.type === "oauth" ? saeeolAuth.access : saeeolAuth?.key
             const organizationId = saeeolAuth?.type === "oauth" ? saeeolAuth.accountId : undefined
             const saeeolApiDefault = yield* Effect.promise(() => fetchDefaultModel(token, organizationId))
-            if (saeeolApiDefault && providers[ProviderID.saeeol]?.models[saeeolApiDefault]) {
+            if (saeeolApiDefault && providers[ProviderID.saeeol]?.models?.[saeeolApiDefault]) {
               defaults[ProviderID.saeeol] = ModelID.make(saeeolApiDefault)
             }
           }

package/src/server/routes/instance/httpapi/api.ts

@@ -2,6 +2,7 @@ import { Schema } from "effect"
 import { HttpApi } from "effect/unstable/httpapi"
 import { BusEvent } from "@/bus/bus-event"
 import { SyncEvent } from "@/sync"
+import { LocalApi } from "./groups/local"
 import { ConfigApi } from "./groups/config"
 import { ControlApi } from "./groups/control"
 import { EventApi } from "./event"
@@ -34,6 +35,7 @@ export const InstanceHttpApi = HttpApi.make("saeeol-instance")
   .addHttpApi(ExperimentalApi)
   .addHttpApi(FileApi)
   .addHttpApi(InstanceApi)
+  .addHttpApi(LocalApi)
   .addHttpApi(McpApi)
   .addHttpApi(ProjectApi)
   .addHttpApi(PtyApi)

package/src/server/routes/instance/httpapi/groups/local.ts

@@ -0,0 +1,87 @@
+import { Schema } from "effect"
+import { HttpApi, HttpApiEndpoint, HttpApiError, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { Authorization } from "../middleware/authorization"
+import { InstanceContextMiddleware } from "../middleware/instance-context"
+import { WorkspaceRoutingMiddleware } from "../middleware/workspace-routing"
+import { described } from "./metadata"
+import {
+  GPUProfile, BackendStatus, ModelInstance,
+  RAGAsset, HFModelSearch,
+} from "@/provider/local/types"
+
+const root = "/local"
+
+// Request schemas
+const InstallPayload = Schema.Struct({
+  repo: Schema.String,
+  filename: Schema.String,
+  format: Schema.String,
+  quantization: Schema.String,
+  sizeBytes: Schema.Number,
+  sha256: Schema.optional(Schema.String),
+})
+const LoadPayload = Schema.Struct({
+  repo: Schema.String,
+  filename: Schema.String,
+  backend: Schema.optional(Schema.String),
+  gpuIndex: Schema.optional(Schema.Number),
+})
+const UnloadPayload = Schema.Struct({ instanceId: Schema.String })
+const InstallRAGPayload = Schema.Struct({ id: Schema.String, repo: Schema.String, type: Schema.String })
+const InstalledModel = Schema.Struct({ repo: Schema.String, filename: Schema.String, path: Schema.String, sizeBytes: Schema.Number })
+const RAGRecommendResult = Schema.Struct({ embeddings: Schema.Array(RAGAsset), rerankers: Schema.Array(RAGAsset) })
+
+export const LocalApi = HttpApi.make("local")
+  .add(
+    HttpApiGroup.make("local")
+      .add(
+        HttpApiEndpoint.get("gpu", `${root}/gpu`, {
+          success: described(GPUProfile, "GPU profile with VRAM info"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.gpu", summary: "Get GPU profile" })),
+        HttpApiEndpoint.get("backends", `${root}/backends`, {
+          success: described(Schema.Array(BackendStatus), "Detected local backends"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.backends", summary: "List detected backends" })),
+        HttpApiEndpoint.get("models", `${root}/models`, {
+          success: described(Schema.Array(InstalledModel), "Installed local models"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.models", summary: "List installed models" })),
+        HttpApiEndpoint.get("instances", `${root}/instances`, {
+          success: described(Schema.Array(ModelInstance), "Running model instances"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.instances", summary: "List running instances" })),
+        HttpApiEndpoint.get("hub_search", `${root}/hub/search`, {
+          requestSearchParams: Schema.Struct({ q: Schema.String, limit: Schema.String }),
+          success: described(Schema.Array(HFModelSearch), "Search results from HuggingFace Hub"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.hub.search", summary: "Search HuggingFace Hub" })),
+        HttpApiEndpoint.get("rag_recommend", `${root}/rag/recommend`, {
+          requestSearchParams: Schema.Struct({ vramMB: Schema.String }),
+          success: described(RAGRecommendResult, "RAG recommendations"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.rag.recommend", summary: "Get RAG model recommendations" })),
+        HttpApiEndpoint.post("install", `${root}/models/install`, {
+          payload: InstallPayload,
+          success: described(Schema.String, "Installed file path"),
+          error: HttpApiError.BadRequest,
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.install", summary: "Install model from HuggingFace" })),
+        HttpApiEndpoint.post("uninstall", `${root}/models/uninstall`, {
+          payload: InstallPayload,
+          success: described(Schema.Boolean, "Success"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.uninstall", summary: "Uninstall a local model" })),
+        HttpApiEndpoint.post("load", `${root}/instances/load`, {
+          payload: LoadPayload,
+          success: described(ModelInstance, "Started model instance"),
+          error: HttpApiError.BadRequest,
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.load", summary: "Load and start a model" })),
+        HttpApiEndpoint.post("unload", `${root}/instances/unload`, {
+          payload: UnloadPayload,
+          success: described(Schema.Boolean, "Success"),
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.unload", summary: "Stop a running model" })),
+        HttpApiEndpoint.post("rag_install", `${root}/rag/install`, {
+          payload: InstallRAGPayload,
+          success: described(Schema.String, "Installed path"),
+          error: HttpApiError.BadRequest,
+        }).annotateMerge(OpenApi.annotations({ identifier: "local.rag.install", summary: "Install RAG asset" })),
+      )
+      .annotateMerge(OpenApi.annotations({ title: "local", description: "Local model management API" }))
+      .middleware(InstanceContextMiddleware)
+      .middleware(WorkspaceRoutingMiddleware)
+      .middleware(Authorization),
+  )
+  .annotateMerge(OpenApi.annotations({ title: "saeeol local models", version: "0.0.1" }))

package/src/server/routes/instance/httpapi/groups/mcp.ts

@@ -30,6 +30,7 @@ export class UnsupportedOAuthError extends Schema.ErrorClass<UnsupportedOAuthErr
 
 export const McpPaths = {
   status: "/mcp",
+  refresh: "/mcp/refresh",
   auth: "/mcp/:name/auth",
   authCallback: "/mcp/:name/auth/callback",
   authAuthenticate: "/mcp/:name/auth/authenticate",
@@ -125,6 +126,15 @@ export const McpApi = HttpApi.make("mcp")
             description: "Disconnect an MCP server.",
           }),
         ),
+        HttpApiEndpoint.post("refresh", McpPaths.refresh, {
+          success: described(StatusMap, "MCP servers refreshed"),
+        }).annotateMerge(
+          OpenApi.annotations({
+            identifier: "mcp.refresh",
+            summary: "Refresh MCP servers",
+            description: "Re-read config and reconnect all MCP servers.",
+          }),
+        ),
       )
       .annotateMerge(
         OpenApi.annotations({

package/src/server/routes/instance/httpapi/handlers/local.ts

@@ -0,0 +1,95 @@
+import { Effect } from "effect"
+import { HttpApiBuilder, HttpApiError } from "effect/unstable/httpapi"
+import { InstanceHttpApi } from "../api"
+import * as GPU from "@/provider/local/gpu"
+import * as Hub from "@/provider/local/hub"
+import * as Manager from "@/provider/local/model-manager"
+import * as Orchestrator from "@/provider/local/orchestrator"
+import * as RAG from "@/provider/local/rag"
+import type { ModelArtifact } from "@/provider/local/types"
+
+function toArtifact(payload: { repo: string; filename: string; format: string; quantization: string; sizeBytes: number; sha256?: string }): ModelArtifact {
+  return Hub.buildArtifact(payload.repo, payload.filename, payload.sizeBytes, payload.sha256)
+}
+
+export const localHandlers = HttpApiBuilder.group(InstanceHttpApi, "local", (handlers) =>
+  Effect.gen(function* () {
+    const gpu = Effect.fn("LocalHttpApi.gpu")(function* () {
+      return yield* GPU.profile
+    })
+
+    const backends = Effect.fn("LocalHttpApi.backends")(function* () {
+      return yield* Effect.promise(() => Orchestrator.detectBackends())
+    })
+
+    const models = Effect.fn("LocalHttpApi.models")(function* () {
+      return yield* Effect.promise(() => Manager.list())
+    })
+
+    const instances = Effect.fn("LocalHttpApi.instances")(function* () {
+      return Orchestrator.runningInstances()
+    })
+
+    const hubSearch = Effect.fn("LocalHttpApi.hubSearch")(function* (ctx: { requestSearchParams: { q: string; limit?: string } }) {
+      return yield* Effect.promise(() => Hub.search(ctx.requestSearchParams.q, { limit: Number(ctx.requestSearchParams.limit ?? "20") }))
+    })
+
+    const ragRecommend = Effect.fn("LocalHttpApi.ragRecommend")(function* (ctx: { requestSearchParams: { vramMB: string } }) {
+      return yield* Effect.promise(() => RAG.recommendForVRAM(Number(ctx.requestSearchParams.vramMB)))
+    })
+
+    const install = Effect.fn("LocalHttpApi.install")(function* (ctx: { payload: { repo: string; filename: string; format: string; quantization: string; sizeBytes: number; sha256?: string } }) {
+      const artifact = toArtifact(ctx.payload)
+      return yield* Effect.promise(() => Manager.install(artifact))
+    })
+
+    const uninstall = Effect.fn("LocalHttpApi.uninstall")(function* (ctx: { payload: { repo: string; filename: string; format: string; quantization: string; sizeBytes: number; sha256?: string } }) {
+      const artifact = toArtifact(ctx.payload)
+      yield* Effect.promise(() => Manager.uninstall(artifact))
+      return true
+    })
+
+    const load = Effect.fn("LocalHttpApi.load")(function* (ctx: { payload: { repo: string; filename: string; backend?: string; gpuIndex?: number } }) {
+      // Find or create artifact from installed models
+      const installed = yield* Effect.promise(() => Manager.list())
+      const match = installed.find((m) => m.repo === ctx.payload.repo && m.filename === ctx.payload.filename)
+      if (!match) {
+        return yield* Effect.fail(new HttpApiError.BadRequest({}))
+      }
+      const artifact = Hub.buildArtifact(ctx.payload.repo, ctx.payload.filename, match.sizeBytes)
+      return yield* Effect.promise(() => Orchestrator.load(artifact, { backend: ctx.payload.backend as any, gpuIndex: ctx.payload.gpuIndex }))
+    })
+
+    const unload = Effect.fn("LocalHttpApi.unload")(function* (ctx: { payload: { instanceId: string } }) {
+      yield* Effect.promise(() => Orchestrator.unload(ctx.payload.instanceId))
+      return true
+    })
+
+    const ragInstall = Effect.fn("LocalHttpApi.ragInstall")(function* (ctx: { payload: { id: string; repo: string; type: string } }) {
+      const allEmbeddings = RAG.EMBEDDING_MODELS
+      const allRerankers = RAG.RERANKER_MODELS
+      const emb = allEmbeddings.find((m) => m.id === ctx.payload.id)
+      if (emb) {
+        return yield* Effect.promise(() => RAG.installEmbedding(emb))
+      }
+      const reranker = allRerankers.find((m) => m.id === ctx.payload.id)
+      if (reranker) {
+        return yield* Effect.promise(() => RAG.installReranker(reranker))
+      }
+      return yield* Effect.fail(new HttpApiError.BadRequest({}))
+    })
+
+    return handlers
+      .handle("gpu", gpu)
+      .handle("backends", backends)
+      .handle("models", models)
+      .handle("instances", instances)
+      .handle("hub_search", hubSearch)
+      .handle("rag_recommend", ragRecommend)
+      .handle("install", install)
+      .handle("uninstall", uninstall)
+      .handle("load", load)
+      .handle("unload", unload)
+      .handle("rag_install", ragInstall)
+  }),
+)

package/src/server/routes/instance/httpapi/handlers/mcp.ts

@@ -55,6 +55,10 @@ export const mcpHandlers = HttpApiBuilder.group(InstanceHttpApi, "mcp", (handler
       return true
     })
 
+    const refresh = Effect.fn("McpHttpApi.refresh")(function* () {
+      return yield* mcp.refresh()
+    })
+
     return handlers
       .handle("status", status)
       .handle("add", add)
@@ -64,5 +68,6 @@ export const mcpHandlers = HttpApiBuilder.group(InstanceHttpApi, "mcp", (handler
       .handle("authRemove", authRemove)
       .handle("connect", connect)
       .handle("disconnect", disconnect)
+      .handle("refresh", refresh)
   }),
 )

package/src/server/routes/instance/httpapi/handlers/provider.ts

@@ -40,7 +40,7 @@ export const providerHandlers = HttpApiBuilder.group(InstanceHttpApi, "provider"
       )
       return {
         all: Object.values(validProviders),
-        default: Provider.defaultModelIDs(pickBy(validProviders, (item) => Object.keys(item.models).length > 0)),
+        default: Provider.defaultModelIDs(pickBy(validProviders, (item) => Object.keys(item.models ?? {}).length > 0)),
         connected: Object.keys(connected),
         failed,
       }