@vitness/fds-skill 0.1.0

package/knowledge/mappings.md

@@ -0,0 +1,354 @@
+# FDS Mapping Strategies
+
+## Common Source Formats
+
+### Format 1: Simple Exercise Database
+```json
+{
+  "id": "0001",
+  "name": "3/4 sit-up",
+  "bodyPart": "waist",
+  "equipment": "body weight",
+  "target": "abs",
+  "gifUrl": "http://example.com/0001.gif"
+}
+```
+
+**Mapping Strategy:**
+| Source Field | FDS Field | Transform |
+|--------------|-----------|-----------|
+| `id` | `metadata.externalRefs[0].id` | Keep as external ref |
+| - | `exerciseId` | Generate UUIDv4 |
+| `name` | `canonical.name` | `titleCase` |
+| `name` | `canonical.slug` | `slugify` |
+| - | `canonical.description` | AI enrichment |
+| `bodyPart` | Context for AI | Used in classification |
+| `equipment` | `equipment.required[0]` | Registry lookup |
+| `target` | `targets.primary[0]` | Registry lookup + AI |
+| `gifUrl` | `media[0]` | `toMediaArray` |
+| - | `classification.*` | AI enrichment |
+| - | `metrics.primary` | AI enrichment |
+
+### Format 2: Detailed Exercise with Categories
+```json
+{
+  "exercise_id": "ex-123",
+  "title": "Barbell Back Squat",
+  "description": "A compound lower body exercise...",
+  "category": "legs",
+  "subcategory": "quadriceps",
+  "difficulty": "intermediate",
+  "equipment_needed": ["barbell", "squat rack"],
+  "muscles_primary": ["quadriceps", "glutes"],
+  "muscles_secondary": ["hamstrings", "core"],
+  "video_url": "https://...",
+  "instructions": ["Step 1...", "Step 2..."]
+}
+```
+
+**Mapping Strategy:**
+| Source Field | FDS Field | Transform |
+|--------------|-----------|-----------|
+| `exercise_id` | `metadata.externalRefs[0].id` | External ref |
+| - | `exerciseId` | Generate UUIDv4 |
+| `title` | `canonical.name` | Direct |
+| `title` | `canonical.slug` | `slugify` |
+| `description` | `canonical.description` | Direct |
+| `difficulty` | `classification.level` | Map: intermediate→intermediate |
+| `equipment_needed` | `equipment.required[]` | Registry lookup (array) |
+| `muscles_primary` | `targets.primary[]` | Registry lookup (array) |
+| `muscles_secondary` | `targets.secondary[]` | Registry lookup (array) |
+| `video_url` | `media[0]` | `toMediaArray` type=video |
+| `category` + `subcategory` | `classification.*` | AI enrichment with context |
+
+---
+
+## Transform Functions
+
+### slugify
+Converts a string to a URL-safe slug.
+
+**Input:** `"Barbell Bench Press"`  
+**Output:** `"barbell-bench-press"`
+
+**Rules:**
+1. Lowercase
+2. Replace spaces with hyphens
+3. Remove special characters (keep alphanumeric and hyphens)
+4. Collapse multiple hyphens
+5. Trim hyphens from start/end
+
+**Edge Cases:**
+- Numbers: `"21s Bicep Curl"` → `"21s-bicep-curl"`
+- Special chars: `"Push-Up (Incline)"` → `"push-up-incline"`
+- Fractions: `"3/4 Sit-Up"` → `"three-quarter-sit-up"` (needs special handling)
+
+### titleCase
+Converts to title case for display names.
+
+**Input:** `"barbell bench press"`  
+**Output:** `"Barbell Bench Press"`
+
+**Rules:**
+1. Capitalize first letter of each word
+2. Keep acronyms: `"EZ Bar Curl"` stays `"EZ Bar Curl"`
+3. Handle hyphenated: `"Push-Up"` stays `"Push-Up"`
+
+### registryLookup
+Finds matching registry entry with fuzzy matching.
+
+**Options:**
+```json
+{
+  "registry": "muscles",
+  "matchField": "name",
+  "fuzzyMatch": true,
+  "threshold": 0.8,
+  "caseSensitive": false
+}
+```
+
+**Matching Priority:**
+1. Exact match on `name` or `slug`
+2. Exact match in `aliases`
+3. Fuzzy match on `name` (Levenshtein distance)
+4. AI fallback if not found
+
+**Examples:**
+- `"abs"` → Matches `"Abs"` (exact) or `"Rectus Abdominis"` (alias)
+- `"body weight"` → Matches `"Body Weight"` (fuzzy, space handling)
+- `"quads"` → Matches `"Quadriceps"` (alias)
+
+### toMediaArray
+Converts URL(s) to FDS media array format.
+
+**Options:**
+```json
+{
+  "type": "image",
+  "baseUrl": "file:///path/to/local/",
+  "urlTransform": {
+    "pattern": "http://old.cdn.com/(\\d+)\\.gif",
+    "replace": "https://new.cdn.com/$1.gif"
+  }
+}
+```
+
+**Input:** `"http://old.cdn.com/0001.gif"`  
+**Output:**
+```json
+[{
+  "type": "image",
+  "uri": "https://new.cdn.com/0001.gif"
+}]
+```
+
+### prefixUUID
+Generates or formats UUIDs with optional prefix.
+
+**Options:**
+```json
+{
+  "prefix": "ex-",
+  "generate": true
+}
+```
+
+**If source has ID:**
+- Input: `"0001"` → Output: `"ex-0001-{uuid}"` or preserve + add external ref
+
+**If generate:**
+- Output: `"ex-{generated-uuid-v4}"`
+
+### autoGenerate
+Auto-generates metadata fields.
+
+**Options:**
+```json
+{
+  "createdAt": "now",
+  "updatedAt": "now",
+  "status": "draft",
+  "source": "import-job-123"
+}
+```
+
+---
+
+## Mapping Configuration Examples
+
+### Basic Exercise Import
+```json
+{
+  "$schema": "https://spec.vitness.me/schemas/transformer/v1.0.0/mapping.schema.json",
+  "version": "1.0.0",
+  "targetSchema": {
+    "version": "1.0.0",
+    "entity": "exercise"
+  },
+  "registries": {
+    "muscles": { "source": "local", "local": "./registries/muscles.registry.json" },
+    "equipment": { "source": "local", "local": "./registries/equipment.registry.json" },
+    "muscleCategories": { "source": "local", "local": "./registries/muscle-categories.registry.json" }
+  },
+  "mappings": {
+    "schemaVersion": { "default": "1.0.0" },
+    "exerciseId": { "from": null, "transform": "uuid" },
+    "canonical.name": { "from": "name", "transform": "titleCase" },
+    "canonical.slug": { "from": "name", "transform": "slugify" },
+    "canonical.description": {
+      "from": null,
+      "enrichment": {
+        "enabled": true,
+        "prompt": "exercise_description",
+        "context": ["name", "bodyPart", "target", "equipment"]
+      }
+    },
+    "classification": {
+      "from": null,
+      "enrichment": {
+        "enabled": true,
+        "prompt": "exercise_classification",
+        "context": ["name", "bodyPart", "target", "equipment"]
+      }
+    },
+    "targets.primary": {
+      "from": "target",
+      "transform": "registryLookup",
+      "options": { "registry": "muscles", "fuzzyMatch": true }
+    },
+    "equipment.required": {
+      "from": "equipment",
+      "transform": "registryLookup",
+      "options": { "registry": "equipment", "fuzzyMatch": true }
+    },
+    "metrics.primary": {
+      "from": null,
+      "enrichment": {
+        "enabled": true,
+        "prompt": "exercise_metrics",
+        "context": ["name", "classification.exerciseType"]
+      }
+    },
+    "media": {
+      "from": "gifUrl",
+      "transform": "toMediaArray",
+      "options": { "type": "image" }
+    },
+    "metadata": {
+      "transform": "autoGenerate",
+      "options": {
+        "createdAt": "now",
+        "updatedAt": "now",
+        "status": "draft",
+        "source": "exercises-import"
+      }
+    },
+    "metadata.externalRefs": {
+      "from": "id",
+      "transform": "template",
+      "options": {
+        "template": [{ "system": "source-db", "id": "{{value}}" }]
+      }
+    }
+  },
+  "output": {
+    "format": "json",
+    "pretty": true,
+    "directory": "./output/exercises/",
+    "naming": "{{slug}}.json"
+  }
+}
+```
+
+---
+
+## Nested Path Mapping
+
+FDS uses nested structures. Use dot notation:
+
+- `canonical.name` → `{ canonical: { name: value } }`
+- `targets.primary` → `{ targets: { primary: value } }`
+- `metadata.externalRefs[0].id` → First item in array
+
+### Array Handling
+
+**Single value to array:**
+```json
+{
+  "targets.primary": {
+    "from": "target",
+    "transform": ["registryLookup", "toArray"]
+  }
+}
+```
+
+**Multiple source to array:**
+```json
+{
+  "targets.primary": {
+    "from": ["primary_muscle", "secondary_muscle"],
+    "transform": "registryLookup",
+    "options": { "registry": "muscles" }
+  }
+}
+```
+
+---
+
+## Conditional Mapping
+
+```json
+{
+  "classification.unilateral": {
+    "from": "name",
+    "transform": "template",
+    "options": {
+      "template": "{{value.toLowerCase().includes('single') || value.toLowerCase().includes('one arm') || value.toLowerCase().includes('one leg')}}"
+    },
+    "condition": "source.name != null"
+  }
+}
+```
+
+---
+
+## Default Values
+
+```json
+{
+  "classification.kineticChain": {
+    "from": null,
+    "default": "mixed"
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Required Fields
+Mark critical fields as required to fail early:
+```json
+{
+  "canonical.name": {
+    "from": "name",
+    "required": true
+  }
+}
+```
+
+### Fallback Chain
+```json
+{
+  "canonical.description": {
+    "from": ["description", "summary", "notes"],
+    "transform": "coalesce",
+    "enrichment": {
+      "enabled": true,
+      "when": "empty"
+    }
+  }
+}
+```

package/knowledge/schemas.md

@@ -0,0 +1,309 @@
+# FDS Schema Reference
+
+## Exercise Schema (v1.0.0)
+
+### Top-Level Structure
+
+```typescript
+interface FDSExercise {
+  schemaVersion: string;           // Required: "1.0.0"
+  exerciseId: string;              // Required: UUIDv4
+  canonical: Canonical;            // Required
+  classification: Classification;  // Required
+  targets: Targets;                // Required
+  equipment?: Equipment;           // Optional
+  constraints?: Constraints;       // Optional
+  relations?: Relation[];          // Optional
+  metrics: Metrics;                // Required
+  media?: Media[];                 // Optional
+  attributes?: Record<string, any>;// Optional: x: namespaced
+  extensions?: Record<string, any>;// Optional: x: namespaced
+  metadata: Metadata;              // Required
+}
+```
+
+### Canonical
+
+```typescript
+interface Canonical {
+  name: string;          // Required: Display name
+  slug: string;          // Required: URL-safe identifier, pattern: ^[a-z0-9-]{2,}$
+  description?: string;  // Optional: Detailed description
+  aliases?: string[];    // Optional: Alternative names
+  localized?: Localized[]; // Optional: Translations
+}
+
+interface Localized {
+  lang: string;          // Required: ISO 639-1 code
+  name: string;          // Required
+  description?: string;
+  aliases?: string[];
+}
+```
+
+### Classification
+
+```typescript
+interface Classification {
+  exerciseType: string;    // Required: strength, cardio, mobility, plyometric, balance
+  movement: Movement;      // Required: See enum
+  mechanics: Mechanics;    // Required: compound, isolation
+  force: Force;            // Required: push, pull, static, mixed
+  level: Level;            // Required: beginner, intermediate, advanced
+  unilateral?: boolean;    // Optional: default false
+  kineticChain?: KineticChain; // Optional: open, closed, mixed
+  tags?: string[];         // Optional: free-form tags
+  taxonomyRefs?: TaxonomyRef[]; // Optional: external taxonomy references
+}
+```
+
+### Targets
+
+```typescript
+interface Targets {
+  primary: MuscleRef[];    // Required: at least 1
+  secondary?: MuscleRef[]; // Optional
+}
+
+interface MuscleRef {
+  id: string;              // Required: UUIDv4
+  slug?: string;           // Optional
+  name: string;            // Required
+  categoryId: string;      // Required: muscle category UUID
+  aliases?: string[];      // Optional
+}
+```
+
+### Equipment
+
+```typescript
+interface Equipment {
+  required?: EquipmentRef[];
+  optional?: EquipmentRef[];
+}
+
+interface EquipmentRef {
+  id: string;              // Required: UUIDv4
+  slug?: string;           // Optional
+  name: string;            // Required
+  abbreviation?: string;   // Optional
+  categories?: string[];   // Optional
+  aliases?: string[];      // Optional
+}
+```
+
+### Metrics
+
+```typescript
+interface Metrics {
+  primary: MetricRef;      // Required
+  secondary?: MetricRef[]; // Optional
+}
+
+interface MetricRef {
+  type: MetricType;        // Required: See enum
+  unit: MetricUnit;        // Required: See enum
+}
+```
+
+### Metadata
+
+```typescript
+interface Metadata {
+  createdAt: string;       // Required: ISO 8601 datetime
+  updatedAt: string;       // Required: ISO 8601 datetime
+  source?: string;         // Optional: data source identifier
+  version?: string;        // Optional: record version
+  status: Status;          // Required: See enum
+  deprecated?: {
+    since?: string;        // Schema version when deprecated
+    replacedBy?: string;   // ID of replacement exercise
+  };
+  externalRefs?: ExternalRef[];
+  history?: HistoryEntry[];
+}
+
+interface ExternalRef {
+  system: string;          // Required: external system name
+  id: string;              // Required: ID in that system
+}
+```
+
+### Media
+
+```typescript
+interface MediaItem {
+  type: "image" | "video" | "doc" | "3d";  // Required
+  uri: string;             // Required: URI format
+  caption?: string;
+  license?: string;
+  attribution?: string;
+}
+```
+
+---
+
+## Equipment Schema (v1.0.0)
+
+```typescript
+interface FDSEquipment {
+  schemaVersion: string;   // Required
+  id: string;              // Required: UUIDv4
+  canonical: {
+    name: string;          // Required
+    slug: string;          // Required
+    abbreviation?: string;
+    description?: string;
+    aliases?: string[];
+    localized?: Localized[];
+  };
+  classification?: {
+    tags?: string[];
+  };
+  media?: Media[];
+  attributes?: Record<string, any>;
+  extensions?: Record<string, any>;
+  metadata: Metadata;      // Required
+}
+```
+
+---
+
+## Muscle Schema (v1.0.0)
+
+```typescript
+interface FDSMuscle {
+  schemaVersion: string;   // Required
+  id: string;              // Required: UUIDv4
+  canonical: {
+    name: string;          // Required
+    slug: string;          // Required
+    description?: string;
+    aliases?: string[];
+    localized?: Localized[];
+  };
+  classification: {
+    categoryId: string;    // Required: muscle category UUID
+    region: RegionGroup;   // Required: See enum
+    laterality?: Laterality;
+  };
+  heatmap?: {
+    atlasId: string;
+    areaIds: string[];
+  };
+  media?: Media[];
+  attributes?: Record<string, any>;
+  extensions?: Record<string, any>;
+  metadata: Metadata;      // Required
+}
+```
+
+---
+
+## Muscle Category Schema (v1.0.0)
+
+```typescript
+interface FDSMuscleCategory {
+  schemaVersion: string;   // Required
+  id: string;              // Required: UUIDv4
+  canonical: {
+    name: string;          // Required
+    slug: string;          // Required
+    description?: string;
+    aliases?: string[];
+    localized?: Localized[];
+  };
+  classification?: {
+    tags?: string[];
+  };
+  media?: Media[];
+  attributes?: Record<string, any>;
+  extensions?: Record<string, any>;
+  metadata: Metadata;      // Required
+}
+```
+
+---
+
+## Enumerations
+
+### Movement
+```typescript
+type Movement = 
+  | "squat"
+  | "hinge"
+  | "lunge"
+  | "push-horizontal"
+  | "push-vertical"
+  | "pull-horizontal"
+  | "pull-vertical"
+  | "carry"
+  | "core-anti-extension"
+  | "core-anti-rotation"
+  | "rotation"
+  | "locomotion"
+  | "isolation"
+  | "other";
+```
+
+### MetricType
+```typescript
+type MetricType =
+  | "reps"
+  | "weight"
+  | "duration"
+  | "distance"
+  | "speed"
+  | "pace"
+  | "power"
+  | "heartRate"
+  | "steps"
+  | "calories"
+  | "height"
+  | "tempo"
+  | "rpe";
+```
+
+### MetricUnit
+```typescript
+type MetricUnit =
+  | "count"
+  | "kg"
+  | "lb"
+  | "s"
+  | "min"
+  | "m"
+  | "km"
+  | "mi"
+  | "m_s"
+  | "km_h"
+  | "min_per_km"
+  | "min_per_mi"
+  | "W"
+  | "bpm"
+  | "kcal"
+  | "cm"
+  | "in";
+```
+
+### RegionGroup
+```typescript
+type RegionGroup =
+  | "upper-front"
+  | "upper-back"
+  | "lower-front"
+  | "lower-back"
+  | "core"
+  | "full-body"
+  | "n/a";
+```
+
+### Status
+```typescript
+type Status =
+  | "draft"
+  | "review"
+  | "active"
+  | "inactive"
+  | "deprecated";
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@vitness/fds-skill",
+  "version": "0.1.0",
+  "description": "FDS (Fitness Data Standard) AI skill and knowledge base for schema transformation and enrichment",
+  "type": "module",
+  "main": "./SKILL.md",
+  "files": [
+    "SKILL.md",
+    "CLAUDE.md",
+    "knowledge",
+    "prompts",
+    "examples"
+  ],
+  "keywords": [
+    "fds",
+    "fitness",
+    "data",
+    "standard",
+    "ai",
+    "skill",
+    "knowledge-base",
+    "llm",
+    "prompt"
+  ],
+  "author": "VITNESS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vitness-me/fds-spec-website.git",
+    "directory": "packages/fds-skill"
+  }
+}