API Behavior

The Green Vectors API is designed to consolidate a collection of input vectors into a set of faceted or "categorized" vectors, ensuring dynamic handling of both existing and new facets.

1. Input Vector Assignment to Facets

   • Each input vector can contribute to one or more facets, as defined in its facetWeights object.

   • The contribution of the input vector to a facet is determined by the specified weight for that facet.

2. Handling Existing Facets

   • If the facet name from facetWeights exists in the facetVectors object:

     • The input vector is merged with the existing facet using the specified weight.

     • The result is a recalculated faceted vector embedding for that facet.

3. Creating New Facets

   • If the facet name from facetWeights does not exist in the facetVectors object:

     • A new facet is created with the name and vector embedding based on the input vector.

     • The new facet is included in the API response.

4. Merging Vectors

   • When merging input vectors to an existing facet, the API combines the vectors using the specified weights. This ensures the resulting facet embedding reflects the weighted contributions of all associated input vectors.

Example Workflow

Example Request:

{
  "facetVectors": [
    {
      "facet": "clothing",
      "vector": [0.1, 0.2, 0.3]
    },
     {
      "facet": "electronics",
      "vector": [0.4, 0.5, 0.6]
    }
  ]
  "inputVectors": [
    {
      "vector": [0.2, 0.3, 0.4],
      "facetWeights": {
        "clothing": 0.5,
        "furniture": 0.8
      }
    },
    {
      "vector": [0.3, 0.4, 0.5],
      "facetWeights": {
        "clothing": 0.7,
        "customers": 0.6
      }
    }
  ]
}

Example Response:

{
  "facetVectors": {
    "clothing": [0.33, 0.44, 0.55],      // Updated based on weighted contributions
    "electronics": [0.4, 0.5, 0.6],      // Unchanged
    "furniture": [0.11, 0.18, 0.22],     // Newly created facet
    "customers": [0.12, 0.19, 0.28]      // Newly created facet
  }
}

Developer Notes

• Dynamic Facet Management: The API dynamically handles the addition of new facets, making it flexible for datasets with evolving categories.

• Weighted Vector Contribution: The weights allow fine-grained control over how strongly each input vector influences the resulting faceted vector.

• Efficient Updates: Existing facets are updated in place, ensuring minimal overhead while maintaining the integrity of previous data.