group-planner 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Piotr Berlowski
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,336 @@
-# Temporary Holding Version
+# Group Planner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript library for competitor partitioning algorithms, designed to be integrated into Next.js applications. Provides multiple algorithmic approaches to partition competitors into balanced subsets based on equipment class, age category, and gender preferences.
+
+## Features
+
+- **Multiple Algorithm Approaches**: Mixed Integer Programming (Greedy & HiGHS), K-means Clustering
+- **Flexible Constraints**: Configurable subset sizes (3-6 competitors, prefer 4). A target is never size 1 or 2.
+- **Guardian Constraint Enforcement**: Competitors must be in the same subset as their guardians
+- **Multiple Optimization Criteria**: 
+  - Even gender distribution within subsets
+  - Age category homogeneity
+  - Equipment class grouping or distribution
+  - Guardian relationship handling
+- **TypeScript Support**: Full type safety and IntelliSense
+- **Performance Optimized**: Efficient algorithms suitable for up to 168 competitors
+
+## Installation
+
+```bash
+npm install group-planner
+```
+
+## Quick Start
+
+### Usage
+
+```typescript
+import { solve, type Competitor } from 'group-planner';
+
+const competitors: Competitor[] = [
+  { id: '001', equipmentClass: 'HB', ageCategory: 'J', gender: 'M' },
+  { id: '002', equipmentClass: 'HB', ageCategory: 'J', gender: 'F' },
+  { id: '003', equipmentClass: 'LB', ageCategory: 'A', gender: 'M' }, // Guardian
+  { id: '004', equipmentClass: 'LB', ageCategory: 'A', gender: 'F' },
+  { id: '005', equipmentClass: 'BBR', ageCategory: 'C', gender: 'M', guardianId: '003' }, // Must be with guardian 003
+  // ... more competitors
+];
+
+// Auto-select best algorithm (default)
+const result = await solve(competitors, {
+  groupByEquipmentClass: true,
+  preferredSubsetSize: 4,
+});
+
+// Or specify a particular algorithm
+const mipResult = await solve(competitors, { algorithm: 'mip' });
+const higgsResult = await solve(competitors, { algorithm: 'mip-lp' }); // HiGHS MIP solver
+const clusteringResult = await solve(competitors, { algorithm: 'clustering' });
+
+console.log(`Algorithm used: ${result.algorithmUsed}`);
+console.log(`Score: ${result.result.score}`);
+console.log(`Subsets:`, result.result.subsets);
+```
+
+### Algorithm Comparison
+
+If you want to compare all algorithms and see detailed results:
+
+```typescript
+import { compareAlgorithms } from 'group-planner';
+
+const { bestResult, allResults } = await compareAlgorithms(competitors, {
+  groupByEquipmentClass: true,
+  preferredSubsetSize: 4,
+});
+
+console.log(`Best algorithm: ${bestResult.algorithmUsed}`);
+allResults.forEach(result => {
+  console.log(`${result.algorithmUsed}: Score ${result.result.score} (${result.executionTime}ms)`);
+});
+```
+
+
+## Algorithm Approaches
+
+### 1. Mixed Integer Programming (MIP)
+Formulates the problem as an optimization problem with binary variables and constraints. Treats guardian families as atomic units that must be assigned together.
+
+```typescript
+import { solveMIP } from 'group-planner';
+
+const result = solveMIP(competitors, options);
+```
+
+### 2. K-means Clustering
+Uses feature encoding and weighted distance metrics to cluster guardian families based on similarity, then adjusts clusters to meet size constraints while keeping families together.
+
+```typescript
+import { solveClustering } from 'group-planner';
+
+const result = solveClustering(competitors, options);
+```
+
+### 3. Branch-and-bound
+Systematically searches the solution space by assigning guardian families (not individual competitors) to subsets, ensuring guardians and their dependents stay together.
+
+```typescript
+// Branch-and-bound algorithm has been removed due to performance issues
+// Use 'mip', 'mip-lp', or 'clustering' algorithms instead
+```
+
+## Configuration Options
+
+```typescript
+interface PartitionOptions {
+  /** Prefer grouping competitors of same equipment class together vs distributing evenly */
+  groupByEquipmentClass: boolean;
+  /** Maximum number of subsets allowed (default: 28) */
+  maxSubsets?: number;
+  /** Minimum subset size. Below 3 is raised to 3 (default: 3) */
+  minSubsetSize?: number;
+  /** Maximum subset size (default: 6) */
+  maxSubsetSize?: number;
+  /** Preferred subset size (default: 4) */
+  preferredSubsetSize?: number;
+  /** Weight for same gender preference (default: 1.0) */
+  genderWeight?: number;
+  /** Weight for same age category preference (default: 1.0) */
+  ageCategoryWeight?: number;
+  /** Weight for equipment class grouping preference (default: 1.0) */
+  equipmentClassWeight?: number;
+  /** Extra weight for subsets that are exactly preferredSubsetSize (default: 0) */
+  closedGroupWeight?: number;
+  /** Host labels for bowstyle, age, and gender. Defaults to the built-in IFAA lists. */
+  solutionSpace?: SolutionSpace;
+}
+```
+
+## Competitor Interface
+
+```typescript
+interface Competitor {
+  id: string;
+  equipmentClass: string; // IFAA code, or any label listed in solutionSpace
+  ageCategory: string;    // IFAA age code, or any label listed in solutionSpace
+  gender: string;         // F, M, or any label listed in solutionSpace
+  guardianId?: string;    // Reference to another competitor who is the guardian
+}
+```
+
+### Equipment Classes
+- **HB**: Heavy Bow
+- **LB**: Light Bow  
+- **TR**: Traditional Recurve
+- **BHR**: Barebow Heavy Recurve
+- **BBR**: Barebow Basic Recurve
+- **FSR**: Freestyle Recurve
+- **BBC**: Barebow Compound
+- **BL**: Barebow Longbow
+- **BU**: Barebow Unlimited
+- **FSC**: Freestyle Compound
+- **FU**: Freestyle Unlimited
+
+### Age Groups
+- **C**: Children
+- **J**: Juniors
+- **YA**: Young Adults
+- **A**: Adults
+- **V**: Veterans
+- **S**: Seniors
+
+### Gender
+- **F**: Female
+- **M**: Male
+
+## Algorithm Selection
+
+The library supports four algorithm options:
+
+### Algorithm Options
+
+```typescript
+type Algorithm = 'mip' | 'clustering' | 'branch-and-bound' | 'auto';
+```
+
+- **`'auto'` (default)**: Runs all three algorithms and returns the result with the highest score
+- **`'mip'`**: Mixed Integer Programming approach using greedy heuristic
+- **`'clustering'`**: K-means clustering with constraint adjustment
+- **`'branch-and-bound'`**: Systematic search with pruning
+
+### When to Use Each Algorithm
+
+- **Auto**: Best for production use when you want optimal results
+- **MIP**: Good balance of speed and quality, handles large datasets well
+- **Clustering**: Fast execution, good for real-time applications
+- **Branch-and-bound**: Most thorough search, best for smaller datasets (≤48 competitors)
+
+### Algorithm Performance Characteristics
+
+| Algorithm | Speed | Quality | Max Competitors | Memory Usage |
+|-----------|-------|---------|-----------------|--------------|
+| MIP | Fast | High | 168 | Low |
+| Clustering | Fastest | Good | 168 | Low |
+| Branch-and-bound | Slow | Highest | ~48 | Medium |
+| Auto | Slow | Highest | 168 | Medium |
+
+## Result Structure
+
+```typescript
+interface PartitionResult {
+  subsets: Competitor[][];
+  score: number;
+  metadata: {
+    totalCompetitors: number;
+    totalSubsets: number;
+    averageSubsetSize: number;
+    scoreBreakdown: {
+      sizeScore: number;
+      closedGroupScore: number;
+      genderScore: number;
+      ageCategoryScore: number;
+      equipmentClassScore: number;
+    };
+  };
+}
+```
+
+## Algorithm Selection
+
+The library supports different algorithms via the `algorithm` option:
+
+```typescript
+type Algorithm = 'mip' | 'mip-lp' | 'clustering' | 'auto';
+
+// Available algorithms:
+const mipResult = await solve(competitors, { algorithm: 'mip' });        // Greedy MIP solver
+const higgsResult = await solve(competitors, { algorithm: 'mip-lp' });   // HiGHS MIP solver (WebAssembly)
+const clusteringResult = await solve(competitors, { algorithm: 'clustering' }); // K-means clustering
+const autoResult = await solve(competitors, { algorithm: 'auto' });     // Auto-select best (default)
+```
+
+### Performance Guide
+
+- **MIP (Greedy)**: Fast, good for most cases, handles all constraint types
+- **MIP-LP (HiGHS)**: Most optimal results, slower, excellent constraint satisfaction
+- **Clustering**: Fast, good for large datasets, may need constraint post-processing
+- **Auto**: Runs all algorithms and returns the best result
+
+### Special Constraints
+
+- **≤112 competitors**: When `maxSubsetSize` is omitted, maximum subset size is limited to 4. An explicit `maxSubsetSize` is kept.
+- **Closed groups**: Raise `closedGroupWeight` to prefer subsets of exactly `preferredSubsetSize`. Gender, age, and equipment weights still trade off inside that size.
+- **No short targets**: Subset size is at least 3. A leftover archer is not placed on a target of 1 or 2.
+- **Guardian relationships**: Automatically preserved across all algorithms
+- **Maximum 28 subsets**: Hard limit enforced by all algorithms
+
+## Guardian Constraints
+
+The library automatically handles guardian relationships:
+
+```typescript
+import { 
+  createGuardianFamilies, 
+  validateGuardianConstraints,
+  validateCompetitors,
+  EQUIPMENT_CLASSES,
+  AGE_GROUPS 
+} from 'group-planner';
+
+// Validate competitor data before processing
+const validation = validateCompetitors(competitors);
+if (!validation.valid) {
+  console.log('Validation errors:', validation.errors);
+  return;
+}
+
+// View how competitors are grouped into families
+const families = createGuardianFamilies(competitors);
+console.log('Guardian families:', families);
+
+// Validate that a solution respects guardian constraints
+const guardianValidation = validateGuardianConstraints(competitors, subsets);
+if (!guardianValidation.valid) {
+  console.log('Guardian constraint violations:', guardianValidation.errors);
+}
+
+// Access available categories
+console.log('Equipment classes:', EQUIPMENT_CLASSES);
+console.log('Age groups:', AGE_GROUPS);
+```
+
+## Examples
+
+See `src/example.ts` for complete usage examples including:
+- Basic partitioning with all three algorithms
+- Guardian relationship handling and validation
+- Comparing equipment class grouping vs distribution strategies
+- Custom scoring weights
+
+## Development
+
+### Setup
+
+```bash
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm run dev
+```
+
+### Type Checking
+
+```bash
+npm run type-check
+```
+
+## Algorithm Performance
+
+- **MIP Solver**: Fast greedy heuristic, good for large datasets
+- **K-means Clustering**: Balanced approach, handles feature similarity well
+- **Branch-and-bound**: Most thorough search, best for smaller datasets (<50 competitors)
+
+## Release
+
+The package name `group-planner` is unscoped. `prepublishOnly` cleans and builds `dist` before publish:
+
+```bash
+npm test
+npm publish
+```
+
+Installing from git runs `prepare`, which builds `dist` as well.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,278 @@
+/**
+ * Core types for competitor partitioning algorithms
+ */
+/** Built-in IFAA catalogue. Callers can supply any other labels through SolutionSpace. */
+type EquipmentClass = 'HB' | 'LB' | 'TR' | 'BHR' | 'BBR' | 'FSR' | 'BBC' | 'BL' | 'BU' | 'FSC' | 'FU';
+type AgeGroup = 'C' | 'J' | 'YA' | 'A' | 'V' | 'S';
+type Gender = 'F' | 'M';
+type Algorithm = 'mip' | 'mip-lp' | 'clustering' | 'auto';
+/**
+ * Labels the solver is allowed to see. When omitted, the built-in IFAA lists are used.
+ * Pass the host application's own age, gender, and bowstyle ids here.
+ */
+interface SolutionSpace {
+    equipmentClasses: readonly string[];
+    ageCategories: readonly string[];
+    genders: readonly string[];
+}
+interface Competitor {
+    id: string;
+    equipmentClass: string;
+    ageCategory: string;
+    gender: string;
+    guardianId?: string;
+}
+interface PartitionOptions {
+    /** Algorithm to use for partitioning (default: 'auto') */
+    algorithm?: Algorithm;
+    /** Prefer grouping competitors of same equipment class together vs distributing evenly */
+    groupByEquipmentClass: boolean;
+    /** Maximum number of subsets allowed (default: 28) */
+    maxSubsets?: number;
+    /** Minimum subset size. Values below 3 are raised to 3. Size 1 and 2 are never a target. */
+    minSubsetSize?: number;
+    /** Maximum subset size (default: 6) */
+    maxSubsetSize?: number;
+    /** Preferred subset size (default: 4) */
+    preferredSubsetSize?: number;
+    /** Weight for same gender preference (default: 1.0) */
+    genderWeight?: number;
+    /** Weight for same age category preference (default: 1.0) */
+    ageCategoryWeight?: number;
+    /** Weight for equipment class grouping preference (default: 1.0) */
+    equipmentClassWeight?: number;
+    /**
+     * Extra weight for subsets whose size equals preferredSubsetSize.
+     * Zero keeps the historical size score. Raise it when full groups should outrank mix.
+     */
+    closedGroupWeight?: number;
+    /** When set, competitor labels are checked against these lists instead of the IFAA defaults. */
+    solutionSpace?: SolutionSpace;
+}
+interface PartitionResult {
+    subsets: Competitor[][];
+    score: number;
+    metadata: {
+        totalCompetitors: number;
+        totalSubsets: number;
+        averageSubsetSize: number;
+        scoreBreakdown: {
+            sizeScore: number;
+            closedGroupScore: number;
+            genderScore: number;
+            ageCategoryScore: number;
+            equipmentClassScore: number;
+        };
+    };
+}
+interface AlgorithmResult {
+    result: PartitionResult;
+    executionTime: number;
+    algorithmUsed: string;
+}
+
+/**
+ * Utility functions for competitor partitioning
+ */
+
+type ResolvedPartitionOptions = Omit<Required<PartitionOptions>, 'solutionSpace'> & {
+    solutionSpace?: SolutionSpace;
+};
+/**
+ * Default partition options
+ */
+declare const DEFAULT_OPTIONS: ResolvedPartitionOptions;
+/**
+ * Validates that a partition solution meets all constraints
+ */
+declare function validatePartition(competitors: Competitor[], subsets: Competitor[][], options?: Partial<PartitionOptions>): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * Calculates the quality score for a partition solution
+ */
+declare function calculateScore(subsets: Competitor[][], options?: Partial<PartitionOptions>): {
+    score: number;
+    breakdown: PartitionResult['metadata']['scoreBreakdown'];
+};
+/**
+ * Creates a partition result with metadata
+ */
+declare function createPartitionResult(subsets: Competitor[][], options?: Partial<PartitionOptions>): PartitionResult;
+/**
+ * Helper to get competitors by guardian relationship
+ */
+declare function getGuardianGroups(competitors: Competitor[]): Map<string, Competitor[]>;
+/**
+ * Groups competitors into guardian families (guardian + their dependents)
+ * Returns an array where each element is either a single competitor or a guardian family
+ */
+declare function createGuardianFamilies(competitors: Competitor[]): Competitor[][];
+/**
+ * Validates that guardian constraints are satisfied in the partition
+ */
+declare function validateGuardianConstraints(competitors: Competitor[], subsets: Competitor[][]): {
+    valid: boolean;
+    errors: string[];
+};
+declare function isValidCompetitor(competitor: unknown, space?: SolutionSpace): competitor is Competitor;
+/**
+ * Validates an array of competitors
+ */
+declare function validateCompetitors(competitors: any[], space?: SolutionSpace): {
+    valid: boolean;
+    errors: string[];
+};
+
+/** A target smaller than this is not a group. Size 1 and size 2 are never emitted. */
+declare const MINIMUM_SUBSET_SIZE = 3;
+declare function smallestAllowedSubset(requestedMin: number): number;
+/**
+ * Drops or repairs targets of size 1 or 2.
+ * A short group is filled from donors, merged into another group, or removed.
+ * Removed archers are not given a target.
+ */
+declare function retainLegalSubsets(subsets: Competitor[][], min: number, max: number): Competitor[][];
+
+/**
+ * Constants for competitor categories and validation
+ */
+
+/**
+ * Valid equipment classes
+ */
+declare const EQUIPMENT_CLASSES: readonly EquipmentClass[];
+/**
+ * Valid age groups (ordered from youngest to oldest)
+ */
+declare const AGE_GROUPS: readonly AgeGroup[];
+/**
+ * Valid genders
+ */
+declare const GENDERS: readonly Gender[];
+/**
+ * Equipment class descriptions for documentation
+ */
+declare const EQUIPMENT_CLASS_DESCRIPTIONS: Record<EquipmentClass, string>;
+/**
+ * Age group descriptions for documentation
+ */
+declare const AGE_GROUP_DESCRIPTIONS: Record<AgeGroup, string>;
+/**
+ * Gender descriptions for documentation
+ */
+declare const GENDER_DESCRIPTIONS: Record<Gender, string>;
+/**
+ * Checks if a value is a valid equipment class
+ */
+declare function isValidEquipmentClass(value: string, allowed?: readonly string[]): boolean;
+/**
+ * Checks if a value is a valid age group
+ */
+declare function isValidAgeGroup(value: string, allowed?: readonly string[]): boolean;
+/**
+ * Checks if a value is a valid gender
+ */
+declare function isValidGender(value: string, allowed?: readonly string[]): boolean;
+/**
+ * Gets the age group order for comparison (lower number = younger)
+ */
+declare function getAgeGroupOrder(ageGroup: AgeGroup): number;
+/**
+ * Compares two age groups (-1 if a is younger, 0 if same, 1 if a is older)
+ */
+declare function compareAgeGroups(a: AgeGroup, b: AgeGroup): number;
+
+/**
+ * Mixed Integer Programming approach for competitor partitioning
+ *
+ * This algorithm formulates the partitioning problem as a MIP problem where:
+ * - Binary variables x[i][j] indicate if competitor i is in subset j
+ * - Objective function maximizes the quality score based on preferences
+ * - Constraints ensure valid partitioning
+ */
+
+/**
+ * Solves the competitor partitioning problem using Mixed Integer Programming
+ */
+declare function solveMIP(competitors: Competitor[], options?: Partial<PartitionOptions>): AlgorithmResult;
+
+/**
+ * Mixed Integer Programming approach using HiGHS solver
+ *
+ * This algorithm formulates the partitioning problem as a proper MIP problem where:
+ * - Binary variables x[i][j] indicate if competitor i is in subset j
+ * - Objective function maximizes the quality score based on preferences
+ * - Constraints ensure valid partitioning and guardian relationships
+ */
+
+/**
+ * Solves the competitor partitioning problem using HiGHS MIP solver
+ */
+declare function solveMIPWithLP(competitors: Competitor[], options?: Partial<PartitionOptions>): Promise<AlgorithmResult>;
+
+/**
+ * Clustering approach for competitor partitioning
+ *
+ * This algorithm uses a modified K-means clustering approach where:
+ * - Competitors are represented as feature vectors
+ * - Distance metric considers gender, age category, and equipment class
+ * - Clusters are formed and then adjusted to meet size constraints
+ * - Post-processing ensures all constraints are satisfied
+ */
+
+/**
+ * Solves the competitor partitioning problem using clustering with guardian constraints
+ */
+declare function solveClustering(competitors: Competitor[], options?: Partial<PartitionOptions>): AlgorithmResult;
+
+/**
+ * Group Planner Library
+ *
+ * A TypeScript library for competitor partitioning algorithms.
+ * Provides three different approaches: Mixed Integer Programming,
+ * K-means Clustering, and Branch-and-bound.
+ */
+
+/**
+ * Main solver function - single API entry point for all algorithms
+ *
+ * @param competitors - Array of competitor objects to partition
+ * @param options - Configuration options including algorithm selection
+ * @returns Algorithm result with partitioned subsets
+ *
+ * @example
+ * ```typescript
+ * // Use specific algorithm
+ * const result = solve(competitors, { algorithm: 'mip' });
+ *
+ * // Use auto-selection (runs all algorithms, returns best)
+ * const result = solve(competitors, { algorithm: 'auto' });
+ *
+ * // Use default algorithm (auto)
+ * const result = solve(competitors);
+ * ```
+ */
+declare function solve(competitors: Competitor[], options?: Partial<PartitionOptions>): Promise<AlgorithmResult>;
+/**
+ * Runs all algorithms and returns detailed results for comparison
+ *
+ * @param competitors - Array of competitor objects to partition
+ * @param options - Configuration options (algorithm option is ignored)
+ * @returns Object with best result and all algorithm results
+ *
+ * @example
+ * ```typescript
+ * const { bestResult, allResults } = compareAlgorithms(competitors);
+ * console.log('Best:', bestResult.algorithmUsed);
+ * allResults.forEach(r => console.log(`${r.algorithmUsed}: ${r.result.score}`));
+ * ```
+ */
+declare function compareAlgorithms(competitors: Competitor[], options?: Partial<PartitionOptions>): Promise<{
+    bestResult: AlgorithmResult;
+    allResults: AlgorithmResult[];
+}>;
+declare const version = "0.1.0";
+
+export { AGE_GROUPS, AGE_GROUP_DESCRIPTIONS, type AgeGroup, type Algorithm, type AlgorithmResult, type Competitor, DEFAULT_OPTIONS, EQUIPMENT_CLASSES, EQUIPMENT_CLASS_DESCRIPTIONS, type EquipmentClass, GENDERS, GENDER_DESCRIPTIONS, type Gender, MINIMUM_SUBSET_SIZE, type PartitionOptions, type PartitionResult, type SolutionSpace, calculateScore, compareAgeGroups, compareAlgorithms, createGuardianFamilies, createPartitionResult, getAgeGroupOrder, getGuardianGroups, isValidAgeGroup, isValidCompetitor, isValidEquipmentClass, isValidGender, retainLegalSubsets, smallestAllowedSubset, solve, solveClustering, solveMIP, solveMIPWithLP, validateCompetitors, validateGuardianConstraints, validatePartition, version };