@fallom/trace 0.2.4 → 0.2.6

package/README.md

@@ -187,6 +187,59 @@ const model = await models.get("summarizer-config", sessionId, {
 });
 ```
 
+### User Targeting (LaunchDarkly-style)
+
+Override weighted distribution for specific users or segments. Targeting rules are evaluated client-side for zero latency.
+
+```typescript
+import { models } from "@fallom/trace";
+
+// Target specific users to specific variants
+const model = await models.get("my-config", sessionId, {
+  fallback: "gpt-4o-mini",
+  customerId: "user-123",           // For individual targeting
+  context: {                         // For rule-based targeting
+    plan: "enterprise",
+    region: "us-west",
+  },
+});
+```
+
+**Evaluation order:**
+1. **Individual Targets** - Exact match on `customerId` or any field
+2. **Rules** - Condition-based targeting (all conditions must match)
+3. **Fallback** - Weighted random distribution
+
+**Configure targeting in the dashboard:**
+
+```json
+{
+  "enabled": true,
+  "individualTargets": [
+    { "field": "customerId", "value": "vip-user-123", "variantIndex": 1 }
+  ],
+  "rules": [
+    {
+      "conditions": [
+        { "field": "plan", "operator": "eq", "value": "enterprise" }
+      ],
+      "variantIndex": 1
+    }
+  ]
+}
+```
+
+**Supported operators:**
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equals | `plan = "enterprise"` |
+| `neq` | Not equals | `plan ≠ "free"` |
+| `in` | In list | `plan in ["enterprise", "business"]` |
+| `nin` | Not in list | `region not in ["cn", "ru"]` |
+| `contains` | Contains substring | `email contains "@acme.com"` |
+| `startsWith` | Starts with | `region starts with "eu-"` |
+| `endsWith` | Ends with | `email ends with ".gov"` |
+
 ## Prompt Management
 
 Manage prompts centrally and A/B test them.
@@ -295,11 +348,22 @@ Get model assignment for A/B testing.
 
 ```typescript
 const model = await models.get("my-config", sessionId, {
-  fallback: "gpt-4o-mini",  // used if config not found
-  version: 2,               // pin to specific config version
+  fallback: "gpt-4o-mini",           // used if config not found
+  version: 2,                         // pin to specific config version
+  customerId: "user-123",             // for individual targeting
+  context: { plan: "enterprise" },    // for rule-based targeting
+  debug: false,                       // enable debug logging
 });
 ```
 
+| Option | Type | Description |
+|--------|------|-------------|
+| `fallback` | `string` | Model to return if config not found |
+| `version` | `number` | Pin to specific config version |
+| `customerId` | `string` | User ID for individual targeting |
+| `context` | `Record<string, string>` | Context for rule-based targeting |
+| `debug` | `boolean` | Enable debug logging |
+
 ### `fallom.prompts.get(promptKey, options?)`
 
 Get a managed prompt.

package/dist/{chunk-W6M2RQ3W.mjs → chunk-KFD5AQ7V.mjs}

@@ -24,6 +24,57 @@ function log(msg) {
     console.log(`[Fallom] ${msg}`);
   }
 }
+function evaluateTargeting(targeting, customerId, context) {
+  if (!targeting || targeting.enabled === false) {
+    return null;
+  }
+  const evalContext = {
+    ...context || {},
+    ...customerId ? { customerId } : {}
+  };
+  log(`Evaluating targeting with context: ${JSON.stringify(evalContext)}`);
+  if (targeting.individualTargets) {
+    for (const target of targeting.individualTargets) {
+      const fieldValue = evalContext[target.field];
+      if (fieldValue === target.value) {
+        log(`Individual target matched: ${target.field}=${target.value} -> variant ${target.variantIndex}`);
+        return target.variantIndex;
+      }
+    }
+  }
+  if (targeting.rules) {
+    for (const rule of targeting.rules) {
+      const allConditionsMatch = rule.conditions.every((condition) => {
+        const fieldValue = evalContext[condition.field];
+        if (fieldValue === void 0) return false;
+        switch (condition.operator) {
+          case "eq":
+            return fieldValue === condition.value;
+          case "neq":
+            return fieldValue !== condition.value;
+          case "in":
+            return Array.isArray(condition.value) && condition.value.includes(fieldValue);
+          case "nin":
+            return Array.isArray(condition.value) && !condition.value.includes(fieldValue);
+          case "contains":
+            return typeof condition.value === "string" && fieldValue.includes(condition.value);
+          case "startsWith":
+            return typeof condition.value === "string" && fieldValue.startsWith(condition.value);
+          case "endsWith":
+            return typeof condition.value === "string" && fieldValue.endsWith(condition.value);
+          default:
+            return false;
+        }
+      });
+      if (allConditionsMatch) {
+        log(`Rule matched: ${JSON.stringify(rule.conditions)} -> variant ${rule.variantIndex}`);
+        return rule.variantIndex;
+      }
+    }
+  }
+  log("No targeting rules matched, falling back to weighted random");
+  return null;
+}
 function init(options = {}) {
   apiKey = options.apiKey || process.env.FALLOM_API_KEY || null;
   baseUrl = options.baseUrl || process.env.FALLOM_CONFIGS_URL || process.env.FALLOM_BASE_URL || "https://configs.fallom.com";
@@ -112,7 +163,7 @@ async function fetchSpecificVersion(configKey, version, timeout = SYNC_TIMEOUT)
   return null;
 }
 async function get(configKey, sessionId, options = {}) {
-  const { version, fallback, debug = false } = options;
+  const { version, fallback, customerId, context, debug = false } = options;
   debugMode = debug;
   ensureInit();
   log(
@@ -181,6 +232,12 @@ async function get(configKey, sessionId, options = {}) {
         variants
       )}`
     );
+    const targetedVariantIndex = evaluateTargeting(config.targeting, customerId, context);
+    if (targetedVariantIndex !== null && variants[targetedVariantIndex]) {
+      const assignedModel2 = variants[targetedVariantIndex].model;
+      log(`\u2705 Assigned model via targeting: ${assignedModel2}`);
+      return returnModel(configKey, sessionId, assignedModel2, configVersion);
+    }
     const hashBytes = createHash("md5").update(sessionId).digest();
     const hashVal = hashBytes.readUInt32BE(0) % 1e6;
     log(`Session hash: ${hashVal} (out of 1,000,000)`);
@@ -197,7 +254,7 @@ async function get(configKey, sessionId, options = {}) {
         break;
       }
     }
-    log(`\u2705 Assigned model: ${assignedModel}`);
+    log(`\u2705 Assigned model via weighted random: ${assignedModel}`);
     return returnModel(configKey, sessionId, assignedModel, configVersion);
   } catch (e) {
     if (e instanceof Error && e.message.includes("not found")) {

package/dist/index.d.mts

@@ -261,6 +261,8 @@ declare function init$2(options?: {
  * @param options - Optional settings
  * @param options.version - Pin to specific version (1, 2, etc). undefined = latest
  * @param options.fallback - Model to return if config not found or Fallom is down
+ * @param options.customerId - User ID for individual targeting (e.g., "user-123")
+ * @param options.context - Additional context for rule-based targeting (e.g., { plan: "enterprise" })
  * @param options.debug - Enable debug logging
  * @returns Model string (e.g., "claude-opus", "gpt-4o")
  * @throws Error if config not found AND no fallback provided
@@ -268,6 +270,8 @@ declare function init$2(options?: {
 declare function get$1(configKey: string, sessionId: string, options?: {
     version?: number;
     fallback?: string;
+    customerId?: string;
+    context?: Record<string, string>;
     debug?: boolean;
 }): Promise<string>;
 

package/dist/index.d.ts

@@ -261,6 +261,8 @@ declare function init$2(options?: {
  * @param options - Optional settings
  * @param options.version - Pin to specific version (1, 2, etc). undefined = latest
  * @param options.fallback - Model to return if config not found or Fallom is down
+ * @param options.customerId - User ID for individual targeting (e.g., "user-123")
+ * @param options.context - Additional context for rule-based targeting (e.g., { plan: "enterprise" })
  * @param options.debug - Enable debug logging
  * @returns Model string (e.g., "claude-opus", "gpt-4o")
  * @throws Error if config not found AND no fallback provided
@@ -268,6 +270,8 @@ declare function init$2(options?: {
 declare function get$1(configKey: string, sessionId: string, options?: {
     version?: number;
     fallback?: string;
+    customerId?: string;
+    context?: Record<string, string>;
     debug?: boolean;
 }): Promise<string>;
 

package/dist/index.js

@@ -31,6 +31,57 @@ function log3(msg) {
     console.log(`[Fallom] ${msg}`);
   }
 }
+function evaluateTargeting(targeting, customerId, context) {
+  if (!targeting || targeting.enabled === false) {
+    return null;
+  }
+  const evalContext = {
+    ...context || {},
+    ...customerId ? { customerId } : {}
+  };
+  log3(`Evaluating targeting with context: ${JSON.stringify(evalContext)}`);
+  if (targeting.individualTargets) {
+    for (const target of targeting.individualTargets) {
+      const fieldValue = evalContext[target.field];
+      if (fieldValue === target.value) {
+        log3(`Individual target matched: ${target.field}=${target.value} -> variant ${target.variantIndex}`);
+        return target.variantIndex;
+      }
+    }
+  }
+  if (targeting.rules) {
+    for (const rule of targeting.rules) {
+      const allConditionsMatch = rule.conditions.every((condition) => {
+        const fieldValue = evalContext[condition.field];
+        if (fieldValue === void 0) return false;
+        switch (condition.operator) {
+          case "eq":
+            return fieldValue === condition.value;
+          case "neq":
+            return fieldValue !== condition.value;
+          case "in":
+            return Array.isArray(condition.value) && condition.value.includes(fieldValue);
+          case "nin":
+            return Array.isArray(condition.value) && !condition.value.includes(fieldValue);
+          case "contains":
+            return typeof condition.value === "string" && fieldValue.includes(condition.value);
+          case "startsWith":
+            return typeof condition.value === "string" && fieldValue.startsWith(condition.value);
+          case "endsWith":
+            return typeof condition.value === "string" && fieldValue.endsWith(condition.value);
+          default:
+            return false;
+        }
+      });
+      if (allConditionsMatch) {
+        log3(`Rule matched: ${JSON.stringify(rule.conditions)} -> variant ${rule.variantIndex}`);
+        return rule.variantIndex;
+      }
+    }
+  }
+  log3("No targeting rules matched, falling back to weighted random");
+  return null;
+}
 function init2(options = {}) {
   apiKey2 = options.apiKey || process.env.FALLOM_API_KEY || null;
   baseUrl2 = options.baseUrl || process.env.FALLOM_CONFIGS_URL || process.env.FALLOM_BASE_URL || "https://configs.fallom.com";
@@ -119,7 +170,7 @@ async function fetchSpecificVersion(configKey, version, timeout = SYNC_TIMEOUT)
   return null;
 }
 async function get(configKey, sessionId, options = {}) {
-  const { version, fallback, debug = false } = options;
+  const { version, fallback, customerId, context, debug = false } = options;
   debugMode2 = debug;
   ensureInit();
   log3(
@@ -188,6 +239,12 @@ async function get(configKey, sessionId, options = {}) {
         variants
       )}`
     );
+    const targetedVariantIndex = evaluateTargeting(config.targeting, customerId, context);
+    if (targetedVariantIndex !== null && variants[targetedVariantIndex]) {
+      const assignedModel2 = variants[targetedVariantIndex].model;
+      log3(`\u2705 Assigned model via targeting: ${assignedModel2}`);
+      return returnModel(configKey, sessionId, assignedModel2, configVersion);
+    }
     const hashBytes = (0, import_crypto.createHash)("md5").update(sessionId).digest();
     const hashVal = hashBytes.readUInt32BE(0) % 1e6;
     log3(`Session hash: ${hashVal} (out of 1,000,000)`);
@@ -204,7 +261,7 @@ async function get(configKey, sessionId, options = {}) {
         break;
       }
     }
-    log3(`\u2705 Assigned model: ${assignedModel}`);
+    log3(`\u2705 Assigned model via weighted random: ${assignedModel}`);
     return returnModel(configKey, sessionId, assignedModel, configVersion);
   } catch (e) {
     if (e instanceof Error && e.message.includes("not found")) {

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   __export,
   init,
   models_exports
-} from "./chunk-W6M2RQ3W.mjs";
+} from "./chunk-KFD5AQ7V.mjs";
 
 // src/trace.ts
 var trace_exports = {};
@@ -1602,7 +1602,7 @@ var FallomSession = class {
       configKey = this.ctx.configKey;
       opts = configKeyOrOptions || {};
     }
-    const { get: get2 } = await import("./models-JKMOBZUO.mjs");
+    const { get: get2 } = await import("./models-SEFDGZU2.mjs");
     return get2(configKey, this.ctx.sessionId, opts);
   }
   /**

package/dist/{models-JKMOBZUO.mjs → models-SEFDGZU2.mjs}

@@ -1,7 +1,7 @@
 import {
   get,
   init
-} from "./chunk-W6M2RQ3W.mjs";
+} from "./chunk-KFD5AQ7V.mjs";
 export {
   get,
   init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fallom/trace",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Model A/B testing and tracing for LLM applications. Zero latency, production-ready.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",