Shapeshift is a TypeScript library designed to transform JSON objects by semantically matching keys using vector embeddings. It targets developers needing to map data between APIs or datasets with differing, potentially nested, structures, offering a flexible alternative to rigid mapping rules.

How It Works

Shapeshift leverages vector embeddings to understand the semantic meaning of JSON keys. It flattens both source and target objects, creating dot-notation keys for nested structures. Embeddings are generated for these flattened keys using providers like Cohere, OpenAI, or Voyage. Cosine similarity is then used to match source keys to the most semantically similar target keys. If the similarity exceeds a configurable threshold, the value from the source object is mapped to the target structure, which is then reconstructed.

Quick Start & Requirements

• Install: npm install @rectanglehq/shapeshift
• Prerequisites: API key for Cohere, OpenAI, or Voyage.
• Usage example: https://github.com/rectanglehq/Shapeshift#usage

Highlighted Details

• Supports multiple embedding providers: Cohere, OpenAI, and Voyage.
• Handles nested JSON objects by flattening and reconstructing structures.
• Customizable embedding models and similarity thresholds.
• TypeScript support for type safety.

Maintenance & Community

• Contributions are welcome via Pull Requests.

Licensing & Compatibility

• MIT License. Permissive for commercial use and closed-source linking.

Limitations & Caveats

Mapping quality is dependent on the semantic similarity of key names; dissimilar names may not map correctly. Extremely deep nesting could potentially impact performance.