Embeddings

Manage embedding inputs in AveniECA

The Embedding API manages embedding inputs, which are text representations of states that can be mapped to and from state vectors.

Embedding Models

EmbeddingInputInsert

Used to create or update embedding inputs:

from avenieca.api.model import EmbeddingInputInsert
import avenieca

# Generate hash for the input
input_hash = avenieca.encode("my_secret", "the inputs")

embedding = EmbeddingInputInsert(
    module_id="air_conditioner",  # Required: Module identifier
    input="the inputs",            # Required: Input text
    hash=input_hash                # Required: HMAC hash of input
)

EmbeddingInputResponse

Returned when retrieving embedding inputs:

@dataclass
class EmbeddingInputResponse(Base):
    id: int            # Database ID
    module_id: str     # Module identifier
    input: str         # Input text
    hash: str          # HMAC hash
    created_at: str    # Creation timestamp
    updated_at: str    # Last update timestamp

Hash Generation

Embedding inputs require a hash for deduplication and verification. Use the avenieca.encode() function:

import avenieca

# Generate hash using HMAC-SHA256
input_hash = avenieca.encode(
    msg="the inputs",      # The input text
    secret="my_secret",    # Your secret key
    algorithm="sha256"     # Optional: hash algorithm (default: sha256)
)

Supported Hash Algorithms

• sha256 (default)
• sha384
• sha512
• sha224
• sha1
• sha3_256
• sha3_224
• sha3_512
• md5

Embedding Methods

create()

Create a new embedding input:

import avenieca
from avenieca.api.model import EmbeddingInputInsert

input_hash = avenieca.encode("my_secret", "the inputs")

embedding = EmbeddingInputInsert(
    module_id="air_conditioner",
    input="the inputs",
    hash=input_hash
)

res, status = eca.embedding.create(data=embedding)
if status == 201:
    print(f"Created embedding input with ID: {res.id}")
    print(f"Hash: {res.hash}")

get_all()

Retrieve all embedding inputs for a module:

res, status = eca.embedding.get_all(module_id="air_conditioner")
if status == 200:
    for emb in res:
        print(f"Embedding {emb.id}: {emb.input}")

get_one()

Get a specific embedding input by database ID:

res, status = eca.embedding.get_one(
    module_id="air_conditioner",
    db_id=1
)
if status == 200:
    print(f"Input: {res.input}")
    print(f"Hash: {res.hash}")

get_one_with_hash()

Get an embedding input using its hash:

import avenieca
from avenieca.api.model import EmbeddingInputHash

input_hash = avenieca.encode("my_secret", "the inputs")
hash_query = EmbeddingInputHash(hash=input_hash)

res, status = eca.embedding.get_one_with_hash(
    module_id="air_conditioner",
    data=hash_query
)
if status == 200:
    print(f"Found: {res.input}")

update()

Update an existing embedding input:

import avenieca
from avenieca.api.model import EmbeddingInputInsert

new_hash = avenieca.encode("my_secret", "updated inputs")

updated_embedding = EmbeddingInputInsert(
    module_id="air_conditioner",
    input="updated inputs",
    hash=new_hash
)

res, status = eca.embedding.update(
    module_id="air_conditioner",
    db_id=1,
    data=updated_embedding
)
if status == 200:
    print(f"Updated embedding {res.id}")

delete()

Delete an embedding input:

res, status = eca.embedding.delete(
    module_id="air_conditioner",
    db_id=1
)
if status == 200:
    print("Embedding input deleted successfully")

Complete Example

import os
import avenieca
from avenieca.api.eca import ECA
from avenieca.api.model import Config, EmbeddingInputInsert, EmbeddingInputHash

# Initialize client
config = Config(
    uri="http://localhost:2580/v1",
    username=os.getenv("USERNAME"),
    password=os.getenv("PASSWORD")
)
eca = ECA(config)

# Define secret for hashing
SECRET = "my_secret_key"

# Create embedding input
input_text = "temperature: 25 degrees"
input_hash = avenieca.encode(SECRET, input_text)

embedding = EmbeddingInputInsert(
    module_id="air_conditioner",
    input=input_text,
    hash=input_hash
)

res, status = eca.embedding.create(data=embedding)
if status == 201:
    emb_id = res.id
    print(f"Created embedding {emb_id}")
    
    # Retrieve by ID
    res, status = eca.embedding.get_one(
        module_id="air_conditioner",
        db_id=emb_id
    )
    print(f"Retrieved: {res.input}")
    
    # Retrieve by hash
    hash_query = EmbeddingInputHash(hash=input_hash)
    res, status = eca.embedding.get_one_with_hash(
        module_id="air_conditioner",
        data=hash_query
    )
    print(f"Found by hash: {res.input}")
    
    # Get all for module
    res, status = eca.embedding.get_all(module_id="air_conditioner")
    print(f"Total embeddings: {len(res)}")

Best Practices

• Consistent secrets - Use the same secret key across your application
• Unique inputs - The hash ensures deduplication of identical inputs
• Module organization - Group related inputs by module_id
• Hash verification - Use get_one_with_hash() to verify inputs haven’t changed

Use Cases

• State mapping - Map human-readable text to state vectors
• Deduplication - Prevent duplicate embedding inputs
• Input tracking - Track what inputs generated which states
• Context preservation - Maintain semantic meaning of states