@openpalm/lib 0.9.5 → 0.9.7

package/src/control-plane/stack-spec.ts

@@ -0,0 +1,64 @@
+/**
+ * Stack specification file (openpalm.yaml) management.
+ *
+ * The stack spec is a YAML document that captures the high-level
+ * configuration of an OpenPalm installation: connections, capability
+ * assignments, and feature flags. It lives in CONFIG_HOME.
+ */
+import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { stringify as yamlStringify, parse as yamlParse } from "yaml";
+
+// ── Types ──────────────────────────────────────────────────────────────
+
+export type StackSpecConnection = {
+  id: string;
+  name: string;
+  provider: string;
+  baseUrl: string;
+};
+
+export type StackSpecAssignments = {
+  llm: { connectionId: string; model: string; smallModel?: string };
+  embeddings: { connectionId: string; model: string; embeddingDims?: number };
+};
+
+export type StackSpec = {
+  version: 3;
+  connections: StackSpecConnection[];
+  assignments: StackSpecAssignments;
+  ollamaEnabled: boolean;
+  voice?: { tts?: string; stt?: string };
+  channels?: string[];
+  services?: Record<string, boolean>;
+};
+
+// ── Constants ──────────────────────────────────────────────────────────
+
+export const STACK_SPEC_FILENAME = "openpalm.yaml";
+
+// ── Read / Write ────────────────────────────────────────────────────────
+
+export function stackSpecPath(configDir: string): string {
+  return `${configDir}/${STACK_SPEC_FILENAME}`;
+}
+
+export function writeStackSpec(configDir: string, spec: StackSpec): void {
+  mkdirSync(configDir, { recursive: true });
+  const content = yamlStringify(spec, { indent: 2 });
+  writeFileSync(stackSpecPath(configDir), content);
+}
+
+export function readStackSpec(configDir: string): StackSpec | null {
+  const path = stackSpecPath(configDir);
+  if (!existsSync(path)) return null;
+  let raw: unknown;
+  try {
+    raw = yamlParse(readFileSync(path, "utf-8"));
+  } catch {
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null) return null;
+  const obj = raw as Record<string, unknown>;
+  if (obj.version !== 3) return null;
+  return obj as unknown as StackSpec;
+}

package/src/control-plane/staging.ts

@@ -20,6 +20,7 @@ import {
   readCoreCaddyfile,
   readCoreCompose,
   readOllamaCompose,
+  readAdminCompose,
   ensureSecretsSchema,
   ensureStackSchema,
   PUBLIC_ACCESS_IMPORT,
@@ -53,9 +54,23 @@ export function isOllamaEnabled(state: ControlPlaneState): boolean {
   return match?.[1]?.trim().toLowerCase() === "true";
 }
 
+// ── Admin State ──────────────────────────────────────────────────────
+
+/**
+ * Check whether admin is enabled in the stack by reading the
+ * OPENPALM_ADMIN_ENABLED flag from DATA_HOME/stack.env.
+ */
+export function isAdminEnabled(state: ControlPlaneState): boolean {
+  const stackEnvPath = `${state.dataDir}/stack.env`;
+  if (!existsSync(stackEnvPath)) return false;
+  const content = readFileSync(stackEnvPath, "utf-8");
+  const match = content.match(/^OPENPALM_ADMIN_ENABLED=(.+)$/m);
+  return match?.[1]?.trim().toLowerCase() === "true";
+}
+
 // ── Caddyfile Staging ─────────────────────────────────────────────────
 
-function withDefaultLanOnly(rawCaddy: string): string | null {
+export function withDefaultLanOnly(rawCaddy: string): string | null {
   if (rawCaddy.includes(PUBLIC_ACCESS_IMPORT) || rawCaddy.includes(LAN_ONLY_IMPORT)) {
     return rawCaddy;
   }
@@ -75,7 +90,7 @@ function withDefaultLanOnly(rawCaddy: string): string | null {
   return null;
 }
 
-function stageChannelCaddyfiles(state: ControlPlaneState): void {
+export function stageChannelCaddyfiles(state: ControlPlaneState): void {
   const stagedChannelsDir = `${state.stateDir}/artifacts/channels`;
   const stagedPublicDir = `${stagedChannelsDir}/public`;
   const stagedLanDir = `${stagedChannelsDir}/lan`;
@@ -126,7 +141,7 @@ function stageCompose(_state: ControlPlaneState, assets: CoreAssetProvider): str
 
 // ── Env Staging ───────────────────────────────────────────────────────
 
-function stageSecretsEnv(state: ControlPlaneState): void {
+export function stageSecretsEnv(state: ControlPlaneState): void {
   const artifactDir = `${state.stateDir}/artifacts`;
   mkdirSync(artifactDir, { recursive: true });
 
@@ -168,8 +183,12 @@ function stageStackEnv(state: ControlPlaneState): void {
     writeFileSync(dataStackEnv, base);
   }
 
+  // Preserve existing OPENPALM_SETUP_COMPLETE=true from stack.env;
+  // only mark complete if it was already true (not inferred from token presence).
+  const alreadyComplete = /^OPENPALM_SETUP_COMPLETE=true$/mi.test(base);
+
   const adminManaged: Record<string, string> = {
-    OPENPALM_SETUP_COMPLETE: state.adminToken ? "true" : "false"
+    OPENPALM_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
   };
   for (const [ch, secret] of Object.entries(state.channelSecrets)) {
     adminManaged[`CHANNEL_${ch.toUpperCase()}_SECRET`] = secret;
@@ -223,7 +242,7 @@ function generateFallbackStackEnv(state: ControlPlaneState): string {
 
 // ── Channel YML Staging ───────────────────────────────────────────────
 
-function stageChannelYmlFiles(state: ControlPlaneState): void {
+export function stageChannelYmlFiles(state: ControlPlaneState): void {
   const stagedChannelsDir = `${state.stateDir}/artifacts/channels`;
   mkdirSync(stagedChannelsDir, { recursive: true });
 
@@ -268,7 +287,7 @@ function validateAutomationContent(content: string, fileName: string): boolean {
   return parseAutomationYaml(content, fileName) !== null;
 }
 
-function stageAutomationFiles(state: ControlPlaneState): void {
+export function stageAutomationFiles(state: ControlPlaneState): void {
   const stagedDir = `${state.stateDir}/automations`;
   mkdirSync(stagedDir, { recursive: true });
 
@@ -355,6 +374,10 @@ export function persistArtifacts(
     writeFileSync(`${artifactDir}/ollama.yml`, readOllamaCompose(assets));
   }
 
+  if (isAdminEnabled(state)) {
+    writeFileSync(`${artifactDir}/admin.yml`, readAdminCompose(assets));
+  }
+
   const allChannels = discoverChannels(state.configDir);
   for (const ch of allChannels) {
     if (!state.channelSecrets[ch.name]) {

package/src/control-plane/types.ts

@@ -8,10 +8,9 @@ export type CoreServiceName =
   | "assistant"
   | "guardian"
   | "memory"
-  | "caddy"
   | "scheduler";
 
-export type OptionalServiceName = "admin" | "docker-socket-proxy";
+export type OptionalServiceName = "admin" | "caddy" | "docker-socket-proxy";
 
 export type AccessScope = "host" | "lan";
 export type CallerType = "assistant" | "cli" | "ui" | "system" | "test" | "unknown";
@@ -133,7 +132,6 @@ export type ControlPlaneState = {
 // ── Constants ──────────────────────────────────────────────────────────
 
 export const CORE_SERVICES: CoreServiceName[] = [
-  "caddy",
   "memory",
   "assistant",
   "guardian",
@@ -141,6 +139,7 @@ export const CORE_SERVICES: CoreServiceName[] = [
 ];
 
 export const OPTIONAL_SERVICES: OptionalServiceName[] = [
+  "caddy",
   "admin",
   "docker-socket-proxy",
 ];

package/src/index.ts

@@ -196,6 +196,8 @@ export {
   readCoreCompose,
   ensureOllamaCompose,
   readOllamaCompose,
+  ensureAdminCompose,
+  readAdminCompose,
   ensureOpenCodeSystemConfig,
   ensureAdminOpenCodeConfig,
   ensureCoreAutomations,
@@ -207,6 +209,7 @@ export {
   sha256,
   randomHex,
   isOllamaEnabled,
+  isAdminEnabled,
   stagedEnvFile,
   stagedStackEnvFile,
   buildEnvFiles,
@@ -214,6 +217,11 @@ export {
   stageArtifacts,
   buildArtifactMeta,
   persistArtifacts,
+  withDefaultLanOnly,
+  stageChannelCaddyfiles,
+  stageChannelYmlFiles,
+  stageSecretsEnv,
+  stageAutomationFiles,
 } from "./control-plane/staging.js";
 
 // ── Lifecycle ───────────────────────────────────────────────────────────
@@ -278,6 +286,19 @@ export {
 export type { LocalProviderDetection } from "./control-plane/model-runner.js";
 export { detectLocalProviders } from "./control-plane/model-runner.js";
 
+// ── Stack Spec ───────────────────────────────────────────────────────────
+export type {
+  StackSpec,
+  StackSpecConnection,
+  StackSpecAssignments,
+} from "./control-plane/stack-spec.js";
+export {
+  STACK_SPEC_FILENAME,
+  stackSpecPath,
+  writeStackSpec,
+  readStackSpec,
+} from "./control-plane/stack-spec.js";
+
 // ── Setup ────────────────────────────────────────────────────────────────
 export type {
   SetupConnection,
@@ -285,6 +306,10 @@ export type {
   SetupInput,
   SetupResult,
   DetectedProvider,
+  SetupConfig,
+  SetupConfigAssignments,
+  ChannelCredentials,
+  ServiceConfig,
 } from "./control-plane/setup.js";
 export {
   validateSetupInput,
@@ -292,4 +317,9 @@ export {
   buildConnectionEnvVarMap,
   performSetup,
   detectProviders,
+  CHANNEL_CREDENTIAL_ENV_MAP,
+  validateSetupConfig,
+  normalizeToSetupInput,
+  performSetupFromConfig,
+  buildChannelCredentialEnvVars,
 } from "./control-plane/setup.js";

package/src/provider-constants.ts

@@ -8,7 +8,8 @@
 /** Supported LLM providers. */
 export const LLM_PROVIDERS = [
   "openai", "anthropic", "ollama", "groq", "together",
-  "mistral", "deepseek", "xai", "lmstudio", "model-runner"
+  "mistral", "deepseek", "xai", "lmstudio", "model-runner",
+  "google", "huggingface"
 ] as const;
 
 /** Default base URLs per provider. */
@@ -22,6 +23,8 @@ export const PROVIDER_DEFAULT_URLS: Record<string, string> = {
   lmstudio: "http://host.docker.internal:1234",
   ollama: "http://host.docker.internal:11434",
   "model-runner": "http://model-runner.docker.internal/engines",
+  google: "https://generativelanguage.googleapis.com",
+  huggingface: "https://router.huggingface.co/v1",
 };
 
 /** Map provider name → env var for the API key. */
@@ -31,6 +34,10 @@ export const PROVIDER_KEY_MAP: Record<string, string> = {
   groq: "GROQ_API_KEY",
   mistral: "MISTRAL_API_KEY",
   google: "GOOGLE_API_KEY",
+  deepseek: "DEEPSEEK_API_KEY",
+  together: "TOGETHER_API_KEY",
+  xai: "XAI_API_KEY",
+  huggingface: "HF_TOKEN",
 };
 
 /** Known embedding model dimensions (cloud providers). */
@@ -42,6 +49,8 @@ export const EMBEDDING_DIMS: Record<string, number> = {
   "ollama/mxbai-embed-large": 1024,
   "ollama/all-minilm": 384,
   "ollama/snowflake-arctic-embed": 1024,
+  "google/text-embedding-004": 768,
+  "huggingface/sentence-transformers/all-MiniLM-L6-v2": 384,
 };
 
 /** Provider display labels for UI. */
@@ -56,17 +65,21 @@ export const PROVIDER_LABELS: Record<string, string> = {
   xai: "xAI (Grok)",
   lmstudio: "LM Studio",
   "model-runner": "Docker Model Runner",
+  google: "Google AI",
+  huggingface: "Hugging Face",
 };
 
 /**
- * Map provider name → mem0-compatible provider name.
- * mem0 doesn't know "model-runner" or "lmstudio" — both speak OpenAI protocol.
- * Ollama also maps to "openai" because Ollama exposes an OpenAI-compatible API
- * at /v1, and using provider "ollama" in mem0 requires the `ollama` Python
- * package which we don't install in the memory container.
+ * Map provider name → memory-package-compatible provider name.
+ * The memory package (@openpalm/memory) has native adapters for openai,
+ * ollama, and lmstudio. model-runner speaks OpenAI protocol so it maps
+ * to "openai". Ollama has its own adapter. LM Studio has its own adapter
+ * that avoids response_format (which LM Studio doesn't reliably support).
  */
 export function mem0ProviderName(provider: string): string {
-  if (provider === "model-runner" || provider === "lmstudio" || provider === "ollama") return "openai";
+  if (provider === "model-runner") return "openai";
+  if (provider === "ollama") return "ollama";
+  if (provider === "lmstudio") return "lmstudio";
   return provider;
 }
 
@@ -82,7 +95,7 @@ export function mem0BaseUrlConfig(
   const trimmed = baseUrl.trim();
   if (!trimmed) return null;
 
-  const normalized = trimmed.replace(/\/+$/, "");
+  const normalized = trimmed.replace(/\/+$/, "").replace(/\/v1$/, "");
   return { key: "openai_base_url", value: `${normalized}/v1` };
 }