# API Behavior

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:

```json
{
  "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:

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://morphos.gitbook.io/morphos-ai/getting-started/api-behavior.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.