@forwardimpact/model 0.1.0

package/lib/modifiers.js

@@ -0,0 +1,158 @@
+/**
+ * Skill Modifier Expansion Functions
+ *
+ * This module provides pure functions for expanding capability-based skill modifiers
+ * to individual skill modifiers. Tracks define modifiers by capability only
+ * (e.g., "delivery: 1", "scale: -1") - individual skill modifiers are not allowed.
+ */
+
+import { CAPABILITY_ORDER } from "@forwardimpact/schema/levels";
+
+/**
+ * Valid skill capability names for modifier expansion
+ * @type {Set<string>}
+ */
+const VALID_CAPABILITIES = new Set(CAPABILITY_ORDER);
+
+/**
+ * Check if a key is a skill capability
+ * @param {string} key - The key to check
+ * @returns {boolean} True if the key is a valid skill capability
+ */
+export function isCapability(key) {
+  return VALID_CAPABILITIES.has(key);
+}
+
+/**
+ * Get skills by capability from a skills array
+ * @param {import('./levels.js').Skill[]} skills - Array of all skills
+ * @param {string} capability - The capability to filter by
+ * @returns {import('./levels.js').Skill[]} Skills in the specified capability
+ */
+export function getSkillsByCapability(skills, capability) {
+  return skills.filter((skill) => skill.capability === capability);
+}
+
+/**
+ * Build a map of capability to skill IDs
+ * @param {import('./levels.js').Skill[]} skills - Array of all skills
+ * @returns {Object<string, string[]>} Map of capability to array of skill IDs
+ */
+export function buildCapabilityToSkillsMap(skills) {
+  const capabilityMap = {};
+
+  for (const capability of VALID_CAPABILITIES) {
+    capabilityMap[capability] = [];
+  }
+
+  for (const skill of skills) {
+    if (skill.capability && capabilityMap[skill.capability]) {
+      capabilityMap[skill.capability].push(skill.id);
+    }
+  }
+
+  return capabilityMap;
+}
+
+/**
+ * Expand capability-based skill modifiers to individual skill modifiers
+ *
+ * Takes a skillModifiers object containing capability-based modifiers only
+ * (e.g., { delivery: 1, scale: -1 }). Individual skill modifiers are not allowed.
+ *
+ * Returns an object with individual skill modifiers expanded from capabilities.
+ *
+ * @param {Object<string, number>} skillModifiers - The capability skill modifiers
+ * @param {import('./levels.js').Skill[]} skills - Array of all skills (for capability lookup)
+ * @returns {Object<string, number>} Expanded skill modifiers with individual skill IDs
+ */
+export function expandSkillModifiers(skillModifiers, skills) {
+  if (!skillModifiers) {
+    return {};
+  }
+
+  const capabilityMap = buildCapabilityToSkillsMap(skills);
+  const expanded = {};
+
+  // Expand capability modifiers to individual skills
+  for (const [key, modifier] of Object.entries(skillModifiers)) {
+    if (isCapability(key)) {
+      // This is a capability - expand to all skills in that capability
+      const skillIds = capabilityMap[key] || [];
+      for (const skillId of skillIds) {
+        expanded[skillId] = modifier;
+      }
+    }
+    // Non-capability keys are ignored (validation should catch these)
+  }
+
+  return expanded;
+}
+
+/**
+ * Extract capability modifiers from a skillModifiers object
+ * @param {Object<string, number>} skillModifiers - The skill modifiers
+ * @returns {Object<string, number>} Only the capability-based modifiers
+ */
+export function extractCapabilityModifiers(skillModifiers) {
+  if (!skillModifiers) {
+    return {};
+  }
+
+  const result = {};
+  for (const [key, modifier] of Object.entries(skillModifiers)) {
+    if (isCapability(key)) {
+      result[key] = modifier;
+    }
+  }
+  return result;
+}
+
+/**
+ * Extract individual skill modifiers from a skillModifiers object
+ * @param {Object<string, number>} skillModifiers - The skill modifiers
+ * @returns {Object<string, number>} Only the individual skill modifiers
+ */
+export function extractIndividualModifiers(skillModifiers) {
+  if (!skillModifiers) {
+    return {};
+  }
+
+  const result = {};
+  for (const [key, modifier] of Object.entries(skillModifiers)) {
+    if (!isCapability(key)) {
+      result[key] = modifier;
+    }
+  }
+  return result;
+}
+
+/**
+ * Get the effective skill modifier for a specific skill
+ *
+ * Looks up the capability modifier for the skill's capability.
+ * Returns 0 if no modifier applies.
+ *
+ * @param {string} skillId - The skill ID to get modifier for
+ * @param {Object<string, number>} skillModifiers - The capability skill modifiers
+ * @param {import('./levels.js').Skill[]} skills - Array of all skills
+ * @returns {number} The effective modifier for this skill
+ */
+export function resolveSkillModifier(skillId, skillModifiers, skills) {
+  if (!skillModifiers) {
+    return 0;
+  }
+
+  // Find the skill's capability
+  const skill = skills.find((s) => s.id === skillId);
+  if (!skill || !skill.capability) {
+    return 0;
+  }
+
+  // Check for capability modifier
+  if (skill.capability in skillModifiers) {
+    return skillModifiers[skill.capability];
+  }
+
+  return 0;
+}

package/lib/profile.js

@@ -0,0 +1,262 @@
+/**
+ * Unified Profile Derivation
+ *
+ * Shared functions for deriving skill and behaviour profiles for both
+ * human jobs and AI agents. This module provides:
+ *
+ * 1. Filtering functions - reusable filters for skills and behaviours
+ * 2. Sorting functions - sort by level/maturity for display
+ * 3. prepareBaseProfile() - shared profile derivation used by both job.js and agent.js
+ *
+ * The core derivation (deriveSkillMatrix, deriveBehaviourProfile) remains in
+ * derivation.js. This module adds post-processing for specific use cases.
+ *
+ * Agent filtering keeps only skills at the highest derived level. This ensures
+ * track modifiers are respected—a broad skill boosted by a +1 track modifier
+ * may reach the same level as primary skills and thus be included.
+ */
+
+import {
+  SKILL_LEVEL_ORDER,
+  BEHAVIOUR_MATURITY_ORDER,
+} from "@forwardimpact/schema/levels";
+import {
+  deriveSkillMatrix,
+  deriveBehaviourProfile,
+  deriveResponsibilities,
+} from "./derivation.js";
+
+// =============================================================================
+// Skill Filters
+// =============================================================================
+
+/**
+ * Build set of capabilities with positive track modifiers
+ * @param {Object} track - Track definition
+ * @returns {Set<string>} Set of capability IDs with positive modifiers
+ */
+export function getPositiveTrackCapabilities(track) {
+  return new Set(
+    Object.entries(track.skillModifiers || {})
+      .filter(([_, modifier]) => modifier > 0)
+      .map(([capability]) => capability),
+  );
+}
+
+/**
+ * Filter out human-only skills
+ * Human-only skills are those requiring human presence/experience
+ * @param {Array} skillMatrix - Skill matrix entries
+ * @returns {Array} Filtered skill matrix
+ */
+export function filterHumanOnlySkills(skillMatrix) {
+  return skillMatrix.filter((entry) => !entry.isHumanOnly);
+}
+
+/**
+ * Filter skills to keep only those at the highest derived level
+ * After track modifiers are applied, some skills will be at higher levels
+ * than others. This filter keeps only the skills at the maximum level.
+ * @param {Array} skillMatrix - Skill matrix entries with derived levels
+ * @returns {Array} Filtered skill matrix containing only highest-level skills
+ */
+export function filterByHighestLevel(skillMatrix) {
+  if (skillMatrix.length === 0) return [];
+
+  // Find the highest level index in the matrix
+  const maxLevelIndex = Math.max(
+    ...skillMatrix.map((entry) => SKILL_LEVEL_ORDER.indexOf(entry.level)),
+  );
+
+  // Keep only skills at that level
+  return skillMatrix.filter(
+    (entry) => SKILL_LEVEL_ORDER.indexOf(entry.level) === maxLevelIndex,
+  );
+}
+
+/**
+ * Apply agent-specific skill filters
+ * Filters to human-only skills and keeps only skills at the highest derived level.
+ * This approach respects track modifiers—a broad skill boosted to the same level
+ * as primary skills will be included.
+ * @param {Array} skillMatrix - Skill matrix entries with derived levels
+ * @returns {Array} Filtered skill matrix
+ */
+export function filterSkillsForAgent(skillMatrix) {
+  // First exclude human-only skills
+  const withoutHumanOnly = filterHumanOnlySkills(skillMatrix);
+
+  // Then keep only skills at the highest level
+  return filterByHighestLevel(withoutHumanOnly);
+}
+
+// =============================================================================
+// Sorting Functions
+// =============================================================================
+
+/**
+ * Sort skills by level (highest first)
+ * Used for agent profiles where top skills should appear first
+ * @param {Array} skillMatrix - Skill matrix entries
+ * @returns {Array} Sorted skill matrix (new array)
+ */
+export function sortByLevelDescending(skillMatrix) {
+  return [...skillMatrix].sort((a, b) => {
+    const aIndex = SKILL_LEVEL_ORDER.indexOf(a.level);
+    const bIndex = SKILL_LEVEL_ORDER.indexOf(b.level);
+    return bIndex - aIndex;
+  });
+}
+
+/**
+ * Sort behaviours by maturity (highest first)
+ * Used for agent profiles where top behaviours should appear first
+ * @param {Array} behaviourProfile - Behaviour profile entries
+ * @returns {Array} Sorted behaviour profile (new array)
+ */
+export function sortByMaturityDescending(behaviourProfile) {
+  return [...behaviourProfile].sort((a, b) => {
+    const aIndex = BEHAVIOUR_MATURITY_ORDER.indexOf(a.maturity);
+    const bIndex = BEHAVIOUR_MATURITY_ORDER.indexOf(b.maturity);
+    return bIndex - aIndex;
+  });
+}
+
+// =============================================================================
+// Profile Derivation
+// =============================================================================
+
+/**
+ * @typedef {Object} ProfileOptions
+ * @property {boolean} [excludeHumanOnly=false] - Filter out human-only skills
+ * @property {boolean} [keepHighestLevelOnly=false] - Keep only skills at the highest derived level
+ * @property {boolean} [sortByLevel=false] - Sort skills by level descending
+ * @property {boolean} [sortByMaturity=false] - Sort behaviours by maturity descending
+ */
+
+/**
+ * @typedef {Object} BaseProfile
+ * @property {Array} skillMatrix - Derived skill matrix
+ * @property {Array} behaviourProfile - Derived behaviour profile
+ * @property {Array} derivedResponsibilities - Derived responsibilities (if capabilities provided)
+ * @property {Object} discipline - The discipline
+ * @property {Object} track - The track
+ * @property {Object} grade - The grade
+ */
+
+/**
+ * Prepare a base profile shared by jobs and agents
+ *
+ * This is the unified entry point for profile derivation. Both human jobs
+ * and AI agents use this function, with different options:
+ *
+ * - Human jobs: No filtering, default sorting by type
+ * - AI agents: Filter humanOnly, keep only highest-level skills, sort by level
+ *
+ * @param {Object} params
+ * @param {Object} params.discipline - The discipline
+ * @param {Object} params.track - The track
+ * @param {Object} params.grade - The grade
+ * @param {Array} params.skills - All available skills
+ * @param {Array} params.behaviours - All available behaviours
+ * @param {Array} [params.capabilities] - Optional capabilities for responsibility derivation
+ * @param {ProfileOptions} [params.options={}] - Filtering and sorting options
+ * @returns {BaseProfile} The prepared profile
+ */
+export function prepareBaseProfile({
+  discipline,
+  track,
+  grade,
+  skills,
+  behaviours,
+  capabilities,
+  options = {},
+}) {
+  const {
+    excludeHumanOnly = false,
+    keepHighestLevelOnly = false,
+    sortByLevel = false,
+    sortByMaturity = false,
+  } = options;
+
+  // Core derivation
+  let skillMatrix = deriveSkillMatrix({ discipline, grade, track, skills });
+  let behaviourProfile = deriveBehaviourProfile({
+    discipline,
+    grade,
+    track,
+    behaviours,
+  });
+
+  // Apply skill filters
+  if (excludeHumanOnly) {
+    skillMatrix = filterHumanOnlySkills(skillMatrix);
+  }
+  if (keepHighestLevelOnly) {
+    skillMatrix = filterByHighestLevel(skillMatrix);
+  }
+
+  // Apply sorting
+  if (sortByLevel) {
+    skillMatrix = sortByLevelDescending(skillMatrix);
+  }
+  if (sortByMaturity) {
+    behaviourProfile = sortByMaturityDescending(behaviourProfile);
+  }
+
+  // Derive responsibilities if capabilities provided
+  let derivedResponsibilities = [];
+  if (capabilities && capabilities.length > 0) {
+    derivedResponsibilities = deriveResponsibilities({
+      skillMatrix,
+      capabilities,
+      track,
+    });
+  }
+
+  return {
+    skillMatrix,
+    behaviourProfile,
+    derivedResponsibilities,
+    discipline,
+    track,
+    grade,
+  };
+}
+
+/**
+ * Preset options for agent profile derivation
+ * Excludes human-only skills, keeps only skills at the highest derived level,
+ * and sorts by level/maturity descending
+ */
+export const AGENT_PROFILE_OPTIONS = {
+  excludeHumanOnly: true,
+  keepHighestLevelOnly: true,
+  sortByLevel: true,
+  sortByMaturity: true,
+};
+
+/**
+ * Prepare a profile optimized for agent generation
+ * Convenience function that applies AGENT_PROFILE_OPTIONS
+ * @param {Object} params - Same as prepareBaseProfile, without options
+ * @returns {BaseProfile} The prepared profile
+ */
+export function prepareAgentProfile({
+  discipline,
+  track,
+  grade,
+  skills,
+  behaviours,
+  capabilities,
+}) {
+  return prepareBaseProfile({
+    discipline,
+    track,
+    grade,
+    skills,
+    behaviours,
+    capabilities,
+    options: AGENT_PROFILE_OPTIONS,
+  });
+}