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 facet_weights 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 facet_weights exists in the facet_vectors 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 facet_weights does not exist in the facet_vectors 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:

{
  "facet_vectors": [
    {
      "facet": "clothing",
      "vector": [0.1, 0.2, 0.3],
      "count": 1,
      "average_weight": 0.5
    },
    {
      "facet": "electronics",
      "vector": [0.4, 0.5, 0.6],
      "count": 1,
      "average_weight": 0.5
    }
  ],
  "input_vectors": [
    {
      "vector": [0.2, 0.3, 0.4],
      "facet_weights": {
        "clothing": 0.5,
        "electronics": 0.8
      }
    },
    {
      "vector": [0.3, 0.4, 0.5],
      "facet_weights": {
        "clothing": 0.3
      }
    }
  ]
}

Example Response:

{
  "facet_vectors": {
    "clothing": [0.33, 0.44, 0.55],
    "electronics": [0.4, 0.5, 0.6]
  }
}

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.