cyberia 3.2.12 → 3.2.70

package/src/projects/cyberia/catalog-cyberia.js

@@ -0,0 +1,81 @@
+/**
+ * Cyberia CLI content catalog.
+ *
+ * A per-deploy product catalog: pure data, loaded dynamically by deploy id via
+ * {@link module:src/server/catalog} so the base build and template assembly never
+ * statically depend on it. Exports the uniform product-catalog shape:
+ *
+ *   - `sourceMoves`       — public `[src, dest]` pairs moved into the engine tree before a build.
+ *   - `privateConfPaths`  — extra payloads synced into the deploy's private repo.
+ *   - `templatePaths`     — engine paths packaged into the standalone product CLI template.
+ *   - `stripPaths`        — paths removed from the base `pwa-microservices-template`.
+ *   - `moves`             — `[src, dest]` pairs moved into the template during assembly (like sourceMoves but into the template target).
+ *   - `copies`            — `[src, dest]` pairs copied into the template during assembly (like moves but copied instead of moved).
+ *   - `keywords`          — npm keywords for the standalone product CLI package.
+ *   - `description`       — npm description for the standalone product CLI package.
+ *
+ * @module src/projects/cyberia/catalog-cyberia.js
+ * @namespace CyberiaCatalog
+ */
+
+export default {
+  sourceMoves: [],
+  privateConfPaths: ['cyberia-instances/amethyst-strata-expansion'],
+  templatePaths: [
+    '/src/grpc/cyberia',
+    '/src/client/ssr/views/CyberiaServerMetrics.js',
+    '/test/cyberia-instance-conf-defaults.test.js',
+    '/test/shape-generator.test.js',
+    '/src/projects/cyberia',
+    '/src/runtime/cyberia-server',
+    '/src/runtime/cyberia-client',
+    '/src/runtime/engine-cyberia',
+    '/.github/workflows/hardhat.ci.yml',
+    '/src/client/public/cyberia-docs',
+    '/src/api/cyberia-server-defaults',
+    '/.github/workflows/docker-image.cyberia-client.ci.yml',
+    '/.github/workflows/docker-image.cyberia-client.dev.ci.yml',
+    '/.github/workflows/docker-image.cyberia-server.ci.yml',
+    '/.github/workflows/docker-image.cyberia-server.dev.ci.yml',
+    '/.github/workflows/cyberia-client.cd.yml',
+    '/.github/workflows/cyberia-server.cd.yml',
+  ],
+  stripPaths: [
+    './src/projects/cyberia',
+    './src/grpc/cyberia',
+    './src/runtime/cyberia-server',
+    './src/runtime/cyberia-client',
+    './src/runtime/engine-cyberia',
+    './test/cyberia-instance-conf-defaults.test.js',
+    './test/shape-generator.test.js',
+    './src/client/public/cyberia-docs',
+    'bin/cyberia.js',
+    './hardhat',
+  ],
+  moves: [],
+  copies: [
+    ['./src/runtime/engine-cyberia/docker-compose.yml', './docker-compose.yml'],
+    ['./src/runtime/engine-cyberia/compose.env', './.env.example'],
+    ['./src/runtime/engine-cyberia/.', './'],
+  ],
+  keywords: [
+    'cyberia',
+    'cyberia-cli',
+    'engine-cyberia',
+    'sidecar',
+    'data-layer',
+    'object-layer',
+    'atlas-sprite-sheet',
+    'ipfs',
+    'erc-1155',
+    'object-layer-token',
+    'hardhat',
+    'hyperledger-besu',
+    'blockchain',
+    'web3',
+    'underpost-platform',
+    'mmorpg',
+  ],
+  description:
+    'Cyberia CLI — toolchain for the Cyberia MMO data layer, content pipeline, persistence, gRPC services, and ERC-1155 lifecycle on Hyperledger Besu.',
+};

package/src/projects/cyberia/gemini-client.js

@@ -0,0 +1,175 @@
+/**
+ * Minimal Google Gemini (Generative Language API) chat client.
+ *
+ * Kept intentionally thin: a single text/JSON completion helper used by the
+ * Top-Down PCG saga generator. No streaming, no tool-calls — the saga
+ * orchestration only needs one structured JSON payload per request.
+ *
+ * General purpose, but for now only the `:generateContent` endpoint is wired,
+ * matching the Gemma model family (e.g. `gemma-4-26b-a4b-it`). Authentication
+ * uses the `x-goog-api-key` header sourced from `GEMINI_API_KEY`.
+ *
+ * @module src/projects/cyberia/gemini-client.js
+ * @namespace GeminiClient
+ */
+
+import axios from 'axios';
+import { loggerFactory } from '../../server/logger.js';
+
+const logger = loggerFactory(import.meta);
+
+/** Generative Language API model base. The model id + `:generateContent` is appended. */
+const GEMINI_API_BASE = 'https://generativelanguage.googleapis.com/v1beta/models';
+
+/** Default model id (Gemma instruction-tuned model). */
+const GEMINI_DEFAULT_MODEL = 'gemma-4-26b-a4b-it';
+
+/**
+ * Best-effort extraction of a single JSON object from a model text response.
+ * Tolerates markdown fences and leading/trailing prose.
+ *
+ * @param {string} text
+ * @returns {Object}
+ */
+function parseJsonLoose(text) {
+  let candidate = String(text || '').trim();
+
+  // Strip a ```json ... ``` (or bare ``` ... ```) fence if present.
+  const fence = candidate.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence) candidate = fence[1].trim();
+
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    // Fall back to the widest {...} span.
+    const start = candidate.indexOf('{');
+    const end = candidate.lastIndexOf('}');
+    if (start !== -1 && end > start) {
+      return JSON.parse(candidate.slice(start, end + 1));
+    }
+    throw new Error('Failed to parse JSON from Gemini response.');
+  }
+}
+
+class GeminiClient {
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.apiKey] - Gemini API key. Falls back to `process.env.GEMINI_API_KEY`.
+   * @param {string} [options.model] - Model id (default: `gemma-4-26b-a4b-it`).
+   * @param {string} [options.baseURL] - Override the model base URL.
+   * @param {number} [options.timeout] - Request timeout in ms (default: 300000).
+   * @param {number} [options.maxRetries] - Retry attempts on transient failure (default: 2).
+   */
+  constructor({
+    apiKey,
+    model = GEMINI_DEFAULT_MODEL,
+    baseURL = GEMINI_API_BASE,
+    timeout = 300000,
+    maxRetries = 2,
+  } = {}) {
+    this.apiKey = apiKey || process.env.GEMINI_API_KEY;
+    this.model = model;
+    this.baseURL = baseURL;
+    this.timeout = timeout;
+    this.maxRetries = maxRetries;
+    if (!this.apiKey) {
+      throw new Error('GEMINI_API_KEY is not set. Export it or add it to your --env-path file.');
+    }
+  }
+
+  /**
+   * Run a single `:generateContent` request and return the answer text,
+   * skipping any thinking parts the model emits.
+   *
+   * @async
+   * @param {Object} params
+   * @param {string} params.prompt - Full prompt text (system + user merged).
+   * @param {Object} [params.generationConfig] - Passed through to the API.
+   * @returns {Promise<string>} The concatenated answer text.
+   */
+  async generateContent({ prompt, generationConfig = {} }) {
+    const url = `${this.baseURL}/${this.model}:generateContent`;
+    logger.info(`Gemini request → model=${this.model}`);
+
+    const { data } = await axios.post(
+      url,
+      {
+        contents: [{ parts: [{ text: prompt }] }],
+        generationConfig,
+      },
+      {
+        headers: { 'x-goog-api-key': this.apiKey, 'Content-Type': 'application/json' },
+        timeout: this.timeout,
+      },
+    );
+
+    const parts = data?.candidates?.[0]?.content?.parts || [];
+    const text = parts
+      .filter((p) => p && typeof p.text === 'string' && !p.thought)
+      .map((p) => p.text)
+      .join('');
+
+    if (!text) throw new Error('Gemini returned an empty completion.');
+
+    const usage = data?.usageMetadata;
+    if (usage) {
+      logger.info(
+        `Gemini usage → prompt=${usage.promptTokenCount} candidates=${usage.candidatesTokenCount} ` +
+          `total=${usage.totalTokenCount}`,
+      );
+    }
+
+    return text;
+  }
+
+  /**
+   * Run a single completion and parse the answer as JSON.
+   *
+   * Gemma models do not support a dedicated JSON response mode, so the schema
+   * is requested in-prompt and the response is parsed leniently.
+   *
+   * @async
+   * @param {Object} params
+   * @param {string} params.system - System prompt (defines the output ontology / schema).
+   * @param {string} params.user - User prompt (the high-level theme seed).
+   * @param {string} [params.thinkingLevel='high'] - Gemini thinking level.
+   * @param {number} [params.temperature] - Sampling temperature (higher = more varied).
+   * @returns {Promise<Object>} Parsed JSON object from the model response.
+   */
+  async chatJson({ system, user, thinkingLevel = 'high', temperature }) {
+    const prompt = [
+      system,
+      '',
+      user,
+      '',
+      'Respond with ONLY a single valid JSON object. Do not wrap it in markdown fences and do not add any prose.',
+    ].join('\n');
+
+    const generationConfig = { thinkingConfig: { thinkingLevel } };
+    if (typeof temperature === 'number') generationConfig.temperature = temperature;
+
+    // Retry on transient failures (timeouts, 5xx, empty/invalid JSON) which the
+    // generateContent endpoint surfaces intermittently under load.
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const text = await this.generateContent({ prompt, generationConfig });
+        return parseJsonLoose(text);
+      } catch (error) {
+        console.error(error);
+        lastError = error;
+        if (attempt < this.maxRetries) {
+          const backoffMs = 1000 * (attempt + 1);
+          logger.warn(
+            `Gemini attempt ${attempt + 1}/${this.maxRetries + 1} failed (${error.message}); ` +
+              `retrying in ${backoffMs}ms`,
+          );
+          await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        }
+      }
+    }
+    throw lastError;
+  }
+}
+
+export { GeminiClient, GEMINI_API_BASE, GEMINI_DEFAULT_MODEL, parseJsonLoose };