Skip to main content

Embedding API

The Embedding API converts schemas into vector representations. These vectors capture structural meaning: schemas that are functionally similar produce vectors that are close together, regardless of surface-level differences like naming or ordering.

POST /embed​

Returns an embedding vector for a given schema.

Request:

curl -X POST https://api.masar.almadar.io/embed \
  -H "Authorization: Bearer $MASAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": {
      "name": "App",
      "orbitals": [{"entity": "Ticket", "traits": ["Triage"], "pages": ["Dashboard"]}]
    }
  }'

Response:

{
  "vector": [0.123, -0.456, 0.789, ...],
  "dimension": 256
}

Use Case: Golden Behavior Matching​

Find which built-in behavior is most similar to a user's description or partial schema:

from masar import MasarClient

client = MasarClient()

# Embed the user's partial work
user_embedding = client.embed(schema=user_partial_schema)

# Compare against golden behaviors
matches = client.find_similar_behaviors(
    vector=user_embedding.vector,
    limit=3
)

for match in matches:
    print(f"{match.behavior_name}: {match.similarity:.2f}")
    # std-helpdesk: 0.94
    # std-task-manager: 0.71
    # std-kanban: 0.68

Use Case: Deduplication​

Before storing a new behavior, check if a near-duplicate already exists:

embedding = client.embed(schema=new_behavior)
existing = client.find_similar_behaviors(vector=embedding.vector, limit=1)

if existing and existing[0].similarity > 0.95:
    print(f"Near-duplicate of {existing[0].behavior_name}, skipping storage")
else:
    client.memory.store(schema=new_behavior, domain="behaviors")

Use Case: Clustering​

Embed multiple schemas and cluster them to discover structural categories in your organization's work:

schemas = load_all_project_schemas()
embeddings = [client.embed(schema=s) for s in schemas]
vectors = [e.vector for e in embeddings]

# Use any clustering library on the vectors
# Schemas in the same cluster share structural patterns

Notes​

  • Embedding is deterministic: the same schema always produces the same vector
  • Vectors are normalized, so cosine similarity and dot product give equivalent rankings
  • The embedding captures structural relationships (entities, traits, transitions, bindings), not surface names

Next Steps​