Skip to main content

​
Overview

The Embedding class provides methods for creating, retrieving, updating, and deleting embedding inputs. Embedding inputs map numerical state vectors to human-readable string representations, making predictions and states more interpretable.

​
Methods

​
create(data: EmbeddingInputInsert)

Create a new embedding input.
​
data
EmbeddingInputInsert
required
The embedding input data to create
​
response
tuple
Returns a tuple of (EmbeddingInputResponse | Error, status_code)
Example: 
import avenieca
from avenieca.api.model import EmbeddingInputInsert

# Generate hash for the input
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}")

​
get_all(module_id: str)

Get all embedding inputs for a specific module.
​
module_id
str
required
The module identifier to retrieve embedding inputs for
​
response
tuple
Returns a tuple of (List[EmbeddingInputResponse] | Error, status_code)
Example: 
res, status = eca.embedding.get_all(module_id="air_conditioner")
if status == 200:
    for emb in res:
        print(f"ID: {emb.id}, Input: {emb.input}")

​
get_one(module_id: str, db_id: int)

Get a specific embedding input by its database ID.
​
module_id
str
required
The module identifier
​
db_id
int
required
The database ID of the embedding input
​
response
tuple
Returns a tuple of (EmbeddingInputResponse | Error, status_code)
Example: 
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(module_id: str, data: EmbeddingInputHash)

Get an embedding input using its hash value.
​
module_id
str
required
The module identifier
​
data
EmbeddingInputHash
required
Object containing the hash value
​
response
tuple
Returns a tuple of (EmbeddingInputResponse | Error, status_code)
Example: 
import avenieca
from avenieca.api.model import EmbeddingInputHash

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

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

​
update(module_id: str, db_id: int, data: EmbeddingInputInsert)

Update an existing embedding input.
​
module_id
str
required
The module identifier
​
db_id
int
required
The database ID of the embedding input to update
​
data
EmbeddingInputInsert
required
The updated embedding input data
​
response
tuple
Returns a tuple of (EmbeddingInputResponse | Error, status_code)
Example: 
import avenieca
from avenieca.api.model import EmbeddingInputInsert

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

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

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

​
delete(module_id: str, db_id: int)

Delete an embedding input.
​
module_id
str
required
The module identifier
​
db_id
int
required
The database ID of the embedding input to delete
​
response
tuple
Returns a tuple of (response | Error, status_code)
Example: 
res, status = eca.embedding.delete(
    module_id="air_conditioner",
    db_id=1
)
if status == 200:
    print("Embedding input deleted successfully")

​
Understanding Embedding Inputs

Embedding inputs serve as a mapping layer between numerical state vectors and human-readable values. This is particularly useful for:
  1. Making predictions interpretable: Instead of seeing [25.0], you see "temperature: 25°C"
  2. Documenting state meanings: Each state dimension can have a descriptive label
  3. Building user interfaces: Display meaningful information to end users

​
Hash Generation

The hash is used to uniquely identify an embedding input. Use the avenieca.encode() function: 
import avenieca

# Generate a hash from a secret and the input text
hash_value = avenieca.encode("my_secret_key", "temperature: 25°C")

​
Complete Workflow Example

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

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

# Create embedding inputs for temperature values
temperature_values = [
    "18°C - Cold",
    "22°C - Comfortable",
    "25°C - Warm",
    "28°C - Hot"
]

embedding_ids = []

for temp_str in temperature_values:
    input_hash = avenieca.encode("temp_secret", temp_str)
    
    embedding = EmbeddingInputInsert(
        module_id="temperature",
        input=temp_str,
        hash=input_hash
    )
    
    res, status = eca.embedding.create(data=embedding)
    if status == 201:
        embedding_ids.append(res.id)
        print(f"Created embedding: {res.input} (ID: {res.id})")

# Create an ESS that references an embedding input
ess = ESSInsert(
    module_id="temperature",
    state=[25.0],
    valence=50.0,
    score=10,
    embedding_input=embedding_ids[2]  # "25°C - Warm"
)

ess_res, ess_status = eca.ess.create(data=ess)
print(f"\nCreated ESS with embedding reference")

# When you get this ESS in "pretty" format, the state will be mapped
pretty_res, pretty_status = eca.ess.get_one_pretty(
    module_id="temperature",
    db_id=ess_res.id
)
if pretty_status == 200:
    print(f"Pretty state: {pretty_res.state}")

# List all embedding inputs for the module
all_emb, all_status = eca.embedding.get_all(module_id="temperature")
print(f"\nTotal embedding inputs: {len(all_emb)}")
for emb in all_emb:
    print(f"  - ID {emb.id}: {emb.input}")

Build docs developers (and LLMs) love

Get started for freeTalk to us