Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us