bulltrackers-module 1.0.995 → 1.0.997

package/functions/api-v3/routes/workspace.js

@@ -4,11 +4,32 @@
  */
 
 const express = require('express');
+const fs = require('fs');
+const path = require('path');
 const config = require('../config');
 const { requireVerifiedUser } = require('../middleware/identity');
 const { requireFirebaseAuth } = require('../middleware/auth');
 const { generateDynamicPaths } = require('./workspace-generator');
 
+const FRAMEWORK_ROOT = path.join(__dirname, '../../computation-system-v3/framework');
+
+// Read-only sample computation templates that we copy into each user's
+// editable `computations/` directory on first bootstrap.
+const SAMPLE_COMPUTATION_TEMPLATES = [
+    {
+        source: 'docs/authoring/sample-computations/grade1-portfolio-summary.js',
+        target: 'computations/Sample_PortfolioDailySummary_Grade1.js'
+    },
+    {
+        source: 'docs/authoring/sample-computations/grade2-entity-risk-change.js',
+        target: 'computations/Sample_EntityRiskChange_Grade2.js'
+    },
+    {
+        source: 'docs/authoring/sample-computations/grade3-alert-on-risk-spike.js',
+        target: 'computations/Sample_RiskSpikeAlerts_Grade3.js'
+    }
+];
+
 const MAX_PATHS_PER_USER = 500;
 const MAX_FILE_BYTES = 512 * 1024;
 const MAX_TOTAL_BYTES = 5 * 1024 * 1024;
@@ -147,21 +168,48 @@ function createWorkspaceRouter() {
         }
     });
 
-    // POST /workspace/bootstrap — Only initializes user directories now!
+    // POST /workspace/bootstrap — Initializes user directories and sample computations.
     router.post('/bootstrap', requireVerifiedUser, async (req, res, next) => {
         try {
             const userId = (req.identity && req.identity.cid) || req.targetUserId;
             const ref = req.services.db.collection('users').doc(userId).collection('workspace_files');
             const snap = await ref.get();
 
-            // We only need to bootstrap user-editable files now. 
+            // We only need to bootstrap user-editable files now.
             // The read-only registry is automatically served in /tree and /file.
-            const userPaths = [
-                { path: 'computations', kind: 'directory', content: null }
-            ];
+            const userPaths = [{ path: 'computations', kind: 'directory', content: null }];
+
+            // Pre-populate the computations/ directory with three fully documented,
+            // valid sample computations. The source of truth lives under
+            // computation-system-v3/framework/docs/authoring/sample-computations/*.
+            const sampleFiles = [];
+            for (const template of SAMPLE_COMPUTATION_TEMPLATES) {
+                const absolute = path.join(FRAMEWORK_ROOT, template.source);
+                try {
+                    if (fs.existsSync(absolute)) {
+                        const content = fs.readFileSync(absolute, 'utf8');
+                        sampleFiles.push({
+                            path: template.target,
+                            kind: 'file',
+                            content
+                        });
+                    }
+                } catch (e) {
+                    // If a template cannot be read, skip it; bootstrap should still succeed.
+                    // The admin can fix the underlying file and re-bootstrap later.
+                    // eslint-disable-next-line no-console
+                    console.error(
+                        '[workspace.bootstrap] Failed to read sample computation template',
+                        template.source,
+                        e && e.message
+                    );
+                }
+            }
 
             const now = new Date().toISOString();
-            for (const item of userPaths) {
+            const bootstrapItems = [...userPaths, ...sampleFiles];
+
+            for (const item of bootstrapItems) {
                 const existing = snap.docs.find((d) => (d.data().path || d.id.replace(/__/g, '/')) === item.path);
                 if (existing) continue;
 

package/functions/computation-system-v3/framework/doc-registry.js

@@ -49,6 +49,13 @@ const REGISTERED_FILES = [
     'docs/modules/trades.md',
     'docs/modules/userMetrics.md',
 
+    // ── Authoring Samples ──────────────────────────────────────────────────────────
+    // These are read-only, fully documented example computations that are also used
+    // as templates for pre-populating the user's `computations/` directory.
+    'docs/authoring/sample-computations/grade1-portfolio-summary.js',
+    'docs/authoring/sample-computations/grade2-entity-risk-change.js',
+    'docs/authoring/sample-computations/grade3-alert-on-risk-spike.js',
+
     // ── SQL Reference ─────────────────────────────────────────────────────────────
     'docs/sql/annotated-sql.md',
 

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade1-portfolio-summary.js

@@ -0,0 +1,108 @@
+/**
+ * Grade 1 sample computation — basic per‑user portfolio snapshot using SDK helpers.
+ *
+ * This is intentionally the smallest realistic example of a V3 computation:
+ *   - Minimal `config`: only `name`, `type`, and `storage`.
+ *   - No manual `config.requires`: the engine infers it from the code using
+ *     DataContracts (`__contracts`) attached to `lib.*` helpers.
+ *   - Straight‑line `process(ctx)` that reads a single table and returns a
+ *     small, envelope‑compatible result object.
+ *
+ * It is designed to be copied, modified, and extended by users.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `name` is unique per tenant and is used for scheduling and storage paths.
+ * - `type: 'per-entity'` means the computation runs once per entity ID
+ *   (e.g. once per signed‑in user or PI, depending on the calling DAG).
+ * - `storage.bigquery: true` persists the result into the standard
+ *   `computation_results_v3` dataset for this tenant.
+ *
+ * NOTE: We deliberately do NOT define `config.requires` here. The engine
+ * analyses the code in `process(ctx)` and infers a safe `requires` block
+ * from the `ctx.lib.portfolio.*` calls and `ctx.data.portfolio_snapshots`
+ * access (see `docs/authoring/config-resolution.md`).
+ */
+exports.config = {
+    name: 'Sample_PortfolioSnapshot_Grade1',
+    type: 'per-entity',
+    category: 'examples',
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — summarises the latest portfolio snapshot for one entity.
+ *
+ * For the current `entityId` and `date`, this function:
+ *   1. Uses `lib.dataHelpers.getEntityRows` to get rows from
+ *      `ctx.data.portfolio_snapshots` that belong to the current entity.
+ *   2. Sorts those rows by date ascending using `lib.dataHelpers.sortByDateAsc`.
+ *   3. Extracts the latest `portfolio_data` payload via `lib.portfolio.extractPortfolioData`.
+ *   4. Derives simple metrics using `lib.portfolio` helpers:
+ *        - `calculateTotalInvested`
+ *        - `calculateTotalValue`
+ *        - `calculateWinRatio`
+ *   5. Returns a compact result object with no reserved keys (`status`, `error`).
+ *
+ * This pattern matches how production computations in `../computations` use the SDK.
+ *
+ * @param {import('../core/ContextBuilder').ComputationContext} ctx
+ */
+exports.process = function process(ctx) {
+    const { data, entityId, date, lib, log } = ctx;
+
+    const rows = lib.dataHelpers.getEntityRows(data['portfolio_snapshots'], entityId);
+    const sorted = lib.dataHelpers.sortByDateAsc(rows);
+    const latest = sorted.length > 0 ? sorted[sorted.length - 1] : null;
+
+    if (!latest) {
+        if (log) {
+            log(
+                `[Sample_PortfolioSnapshot_Grade1] No portfolio_snapshots rows for entity ${String(
+                    entityId
+                )} on ${date}`
+            );
+        }
+
+        return {
+            outcome: 'NO_DATA',
+            asOfDate: date,
+            entityId: entityId ?? null,
+            totalInvested: 0,
+            totalValue: 0,
+            winRatioPercent: 0
+        };
+    }
+
+    const portfolioData = lib.portfolio.extractPortfolioData(latest);
+    const positions = lib.portfolio.extractPositions(portfolioData);
+
+    const totalInvested = lib.portfolio.calculateTotalInvested(positions);
+    const totalValue = lib.portfolio.calculateTotalValue(positions);
+    const winRatioPercent = lib.portfolio.calculateWinRatio(positions);
+
+    if (log) {
+        log(
+            `[Sample_PortfolioSnapshot_Grade1] entity=${String(
+                entityId
+            )} invested=${totalInvested.toFixed(2)} value=${totalValue.toFixed(
+                2
+            )} winRatio=${winRatioPercent.toFixed(2)}%`
+        );
+    }
+
+    return {
+        // Domain‑level outcome; do not use reserved keys like `status` or `error`.
+        outcome: 'OK',
+        asOfDate: date,
+        entityId: entityId ?? null,
+        totalInvested: Number(totalInvested.toFixed(2)),
+        totalValue: Number(totalValue.toFixed(2)),
+        winRatioPercent: Number(winRatioPercent.toFixed(2))
+    };
+};
+

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade2-entity-risk-change.js

@@ -0,0 +1,116 @@
+/**
+ * Grade 2 sample computation — PI risk and AUM summary over a short window.
+ *
+ * This example builds directly on the real `pi_rankings` table and uses the
+ * `lib.rankings` and `lib.dataHelpers` modules exactly as production recipes do.
+ *
+ * It demonstrates:
+ *   - Per‑entity operation (`type: 'per-entity'` for PI entities).
+ *   - A small but explicit `config.requires` override to control lookback,
+ *     fields, and mandatory flags.
+ *   - Safe handling of missing data across days.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `name` and `type` follow the same pattern as `RiskScoreIncrease`.
+ * - `requires.pi_rankings` is kept intentionally small but explicit so the
+ *   author can see and tune lookback/fields in one place.
+ * - `storage.bigquery: true` persists results for later dashboard use.
+ */
+exports.config = {
+    name: 'Sample_PIRiskAndAum_Grade2',
+    type: 'per-entity',
+    category: 'examples',
+
+    requires: {
+        pi_rankings: {
+            // 7‑day window of rankings for this PI, similar to DashboardPage.
+            lookback: 7,
+            mandatory: false,
+            fields: ['pi_id', 'rankings_data', 'username', 'date']
+        }
+    },
+
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — summarises basic risk and AUM information for a single PI.
+ *
+ * For each PI (`entityId`) this function:
+ *   1. Pulls that PI's `pi_rankings` rows via `lib.dataHelpers.getEntityRows`.
+ *   2. Sorts the rows by date, then picks the latest one in the lookback window.
+ *   3. Uses `lib.rankings` helpers to extract:
+ *        - current risk score and risk tier,
+ *        - total gain,
+ *        - AUM value and tier label.
+ *   4. Returns a compact result object, suitable for direct consumption by
+ *      dashboards or downstream computations.
+ *
+ * @param {import('../core/ContextBuilder').ComputationContext} ctx
+ */
+exports.process = function process(ctx) {
+    const { data, entityId, date, lib, log } = ctx;
+
+    const rows = lib.dataHelpers.getEntityRows(data['pi_rankings'], entityId);
+    const sorted = lib.dataHelpers.sortByDateAsc(rows);
+    const latest = sorted.length > 0 ? sorted[sorted.length - 1] : null;
+
+    if (!latest) {
+        if (log) {
+            log(
+                `[Sample_PIRiskAndAum_Grade2] No pi_rankings rows for entity ${String(
+                    entityId
+                )} in window ending ${date}`
+            );
+        }
+
+        return {
+            outcome: 'NO_DATA',
+            asOfDate: date,
+            entityId: entityId ?? null,
+            username: null,
+            riskScore: null,
+            riskTier: null,
+            totalGain: null,
+            aumValue: null,
+            aumTierLabel: null
+        };
+    }
+
+    const rankingsData = lib.rankings.extractRankingsData(latest);
+    const username = lib.rankings.getUsername(latest);
+
+    const riskScore = lib.rankings.getRiskScore(rankingsData);
+    const riskTier = lib.rankings.getRiskTier(riskScore);
+
+    const totalGain = lib.rankings.getTotalGain(rankingsData);
+    const aumValue = lib.rankings.getAUM(rankingsData);
+    const aumTierId = lib.rankings.getAUMTier(rankingsData);
+    const aumTierLabel = lib.rankings.getAUMTierLabel(aumTierId);
+
+    if (log) {
+        log(
+            `[Sample_PIRiskAndAum_Grade2] entity=${String(
+                entityId
+            )} risk=${riskScore} (${riskTier}), AUM=${aumValue}, gain=${totalGain}`
+        );
+    }
+
+    return {
+        outcome: 'OK',
+        asOfDate: date,
+        entityId: entityId ?? null,
+        username: username || null,
+        riskScore,
+        riskTier,
+        totalGain,
+        aumValue,
+        aumTierLabel
+    };
+};
+

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade3-alert-on-risk-spike.js

@@ -0,0 +1,162 @@
+/**
+ * Grade 3 sample computation — asset + PI risk alerts (composed from real tables).
+ *
+ * This example shows an end‑to‑end, production‑style pattern:
+ *   - Depends on the existing `GlobalAumPerAsset30D` computation so it runs first.
+ *   - Reads its materialised results from the `results` table via data helpers.
+ *   - Combines that with live `pi_rankings` data to build two alert feeds:
+ *       • high‑AUM assets
+ *       • high‑risk, high‑AUM Popular Investors
+ *
+ * The intent is to be a “perfect role model”: everything is grounded in the
+ * current framework, no invented tables, and every step is documented.
+ */
+
+/**
+ * Configuration for the computation.
+ *
+ * Key points:
+ *   - `type: 'global'` because we aggregate across all entities.
+ *   - `dependencies` ensures `GlobalAumPerAsset30D` has written its output to
+ *     the `results` table before this computation runs.
+ *   - `requires.results` explicitly filters that table to only the parent
+ *     computation’s rows, mirroring `GlobalAumPerAsset30D`.
+ *   - `requires.pi_rankings` gives us current PI risk/AUM data for scoring.
+ */
+exports.config = {
+    name: 'Sample_AssetAndRiskAlerts_Grade3',
+    type: 'global',
+    category: 'examples',
+
+    // Ensure the upstream aggregation has run before this computation executes.
+    dependencies: ['globalaumperasset30d'],
+
+    requires: {
+        // Parent computation results, constrained to GlobalAumPerAsset30D.
+        results: {
+            lookback: 0,
+            mandatory: true,
+            fields: ['result_data', 'computation_name', 'date', 'entity_id'],
+            filter: { computation_name: 'globalaumperasset30d' }
+        },
+        // Current PI rankings window; used to identify high‑risk, high‑AUM PIs.
+        pi_rankings: {
+            lookback: 7,
+            mandatory: false,
+            fields: ['pi_id', 'rankings_data', 'username', 'date']
+        }
+    },
+
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — produces alert lists for assets and PIs.
+ *
+ * High‑level behaviour:
+ *
+ *   1. Reads `results` for `GlobalAumPerAsset30D` using:
+ *        - `lib.dataHelpers.normaliseParentResults` to flatten rows
+ *        - `lib.dataHelpers.parseResultData` to parse `result_data`
+ *      and emits **asset AUM alerts** where total AUM exceeds a fixed threshold.
+ *
+ *   2. Reads `pi_rankings` via `lib.dataHelpers.toArray` and `lib.rankings`
+ *      helpers to construct **PI risk alerts** for Popular Investors that are
+ *      both high‑risk and above a minimum AUM tier.
+ *
+ *   3. Returns a single, envelope‑compatible result object:
+ *        - `outcome`: `"OK"` or `"NO_ALERTS"`
+ *        - `asOfDate`: target date
+ *        - `assetAlerts`: array of asset‑level alerts
+ *        - `piRiskAlerts`: array of PI‑level alerts
+ *
+ * @param {import('../core/ContextBuilder').ComputationContext} ctx
+ */
+exports.process = function process(ctx) {
+    const { data, date, lib, log } = ctx;
+
+    const { normaliseParentResults, parseResultData, toArray } = lib.dataHelpers;
+
+    // -------------------------------------------------------------------------
+    // 1. Asset‑level alerts from GlobalAumPerAsset30D parent results
+    // -------------------------------------------------------------------------
+    const parentRows = normaliseParentResults(data['results']);
+    const assetAlerts = [];
+
+    // Example threshold: only alert on assets with at least 50k AUM.
+    const ASSET_AUM_THRESHOLD = 50000;
+
+    for (const row of parentRows) {
+        const parsed = parseResultData(row) || row;
+
+        // GlobalAumPerAsset30D returns an array of { symbol, amount } entries
+        // as its top‑level `result`. We tolerate both raw arrays and envelopes.
+        const items = Array.isArray(parsed)
+            ? parsed
+            : (Array.isArray(parsed.result) ? parsed.result : []);
+
+        for (const item of items) {
+            if (!item || item.symbol == null || item.amount == null) continue;
+            const amount = Number(item.amount);
+            if (!Number.isFinite(amount) || amount < ASSET_AUM_THRESHOLD) continue;
+
+            assetAlerts.push({
+                type: 'ASSET_AUM',
+                symbol: item.symbol,
+                amount: Number(amount.toFixed(2)),
+                asOfDate: date
+            });
+        }
+    }
+
+    // -------------------------------------------------------------------------
+    // 2. PI‑level risk alerts from pi_rankings
+    // -------------------------------------------------------------------------
+    const rankings = toArray(data['pi_rankings'] || []);
+    const piRiskAlerts = [];
+
+    // Example policy: alert on "high" or above risk and mid‑tier AUM or higher.
+    const MIN_RISK_SCORE = 6;
+    const MIN_AUM_TIER = 3;
+
+    rankings.forEach((row) => {
+        const rData = lib.rankings.extractRankingsData(row);
+        if (!rData) return;
+
+        const riskScore = lib.rankings.getRiskScore(rData);
+        const riskTier = lib.rankings.getRiskTier(riskScore);
+        const aumValue = lib.rankings.getAUM(rData);
+        const aumTierId = lib.rankings.getAUMTier(rData);
+
+        if (riskScore < MIN_RISK_SCORE || aumTierId < MIN_AUM_TIER) {
+            return;
+        }
+
+        piRiskAlerts.push({
+            type: 'PI_RISK',
+            piId: lib.rankings.getPiId(row),
+            username: lib.rankings.getUsername(row),
+            riskScore,
+            riskTier,
+            aumValue,
+            aumTierLabel: lib.rankings.getAUMTierLabel(aumTierId)
+        });
+    });
+
+    if (log) {
+        log(
+            `[Sample_AssetAndRiskAlerts_Grade3] generated ${assetAlerts.length} asset alert(s) and ${piRiskAlerts.length} PI risk alert(s) for ${date}`
+        );
+    }
+
+    return {
+        // Use a domain‑level outcome; never return reserved keys `status` or `error`.
+        outcome: assetAlerts.length === 0 && piRiskAlerts.length === 0 ? 'NO_ALERTS' : 'OK',
+        asOfDate: date,
+        assetAlerts,
+        piRiskAlerts
+    };
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.995",
+  "version": "1.0.997",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [