Skip to main content

​
Overview

The ESS class provides methods for creating, retrieving, updating, and searching twins and aggregates in the Embodied State Space. ESS represents discrete states with associated valence scores.

​
Methods

​
create(data: ESSInsert)

Create a new ESS (twin or aggregate).
​
data
ESSInsert
required
The ESS data to create
​
response
tuple
Returns a tuple of (ESSResponse | Error | AggregateError, status_code)
Example: 
from avenieca.api.model import ESSInsert

ess = ESSInsert(
    module_id="air_conditioner",
    state=[25.0],
    valence=90.0,
    score=18,
    embedding_input=1
)

res, status = eca.ess.create(data=ess)
if status == 201:
    print(f"Created ESS with ID: {res.id}")

​
get_all(module_id: str)

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

​
get_one(module_id: str, db_id: int)

Get a specific ESS by its database ID.
​
module_id
str
required
The module identifier
​
db_id
int
required
The database ID of the ESS
​
response
tuple
Returns a tuple of (ESSResponse | Error, status_code)
Example: 
res, status = eca.ess.get_one(module_id="air_conditioner", db_id=8)
if status == 200:
    print(f"State: {res.state}, Valence: {res.valence}")

​
get_one_with_embedding(module_id: str, emb_input: int)

Get an ESS using its embedding input ID.
​
module_id
str
required
The module identifier
​
emb_input
int
required
The embedding input ID
​
response
tuple
Returns a tuple of (ESSResponse | Error, status_code)
Example: 
res, status = eca.ess.get_one_with_embedding(
    module_id="air_conditioner",
    emb_input=1
)

​
get_one_pretty(module_id: str, db_id: int)

Get an ESS with the state mapped to a vector of the original input values.
​
module_id
str
required
The module identifier
​
db_id
int
required
The database ID of the ESS
​
response
tuple
Returns a tuple of (PrettyESS | Error, status_code). PrettyESS contains state values mapped to their original string representations.
Example: 
res, status = eca.ess.get_one_pretty(module_id="gwp_record", db_id=1)
if status == 200:
    print(f"Human-readable state: {res.state}")

​
get_one_sequence(module_id: str, sequence_id: int)

Get the reference ESS for a specific sequence.
​
module_id
str
required
The module identifier
​
sequence_id
int
required
The sequence database ID
​
response
tuple
Returns a tuple of (ESSResponse | Error, status_code)
Example: 
res, status = eca.ess.get_one_sequence(
    module_id="air_conditioner",
    sequence_id=3
)

​
get_all_sequence(module_id: str)

Get all ESS from all sequences for a module. Returns ESS ordered in descending order from the most recent sequence.
​
module_id
str
required
The module identifier
​
response
tuple
Returns a tuple of (List[ESSResponse] | Error, status_code)
Example: 
res, status = eca.ess.get_all_sequence(module_id="air_conditioner")
if status == 200:
    for ess in res:
        print(f"Sequence ESS: {ess.id}")

​
get_all_aggregates(module_id: str, aggregate_module_id: str, ess_id: int)

Get all aggregates that have the given ESS as a constituent (in-twin).
​
module_id
str
required
The module identifier of the constituent ESS
​
aggregate_module_id
str
required
The module identifier of the aggregate
​
ess_id
int
required
The ESS database ID
​
response
tuple
Returns a tuple of (List[ESSResponse] | Error, status_code)
Example: 
res, status = eca.ess.get_all_aggregates(
    module_id="team",
    aggregate_module_id="gwp_aggregate",
    ess_id=1
)

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

Update an existing ESS.
​
module_id
str
required
The module identifier
​
db_id
int
required
The database ID of the ESS to update
​
data
ESSInsert
required
The updated ESS data
​
response
tuple
Returns a tuple of (ESSResponse | Error | AggregateError, status_code)
Example: 
ess = ESSInsert(
    module_id="air_conditioner",
    state=[26.0],
    valence=85.0,
    score=20
)

res, status = eca.ess.update(
    module_id="air_conditioner",
    db_id=8,
    data=ess
)
Search for ESS with similar states using vector similarity.
​
data
Search
required
The search parameters
​
response
tuple
Returns a tuple of (List[SearchResult] | Error, status_code)
Example: 
from avenieca.api.model import Search

res, status = eca.ess.search(data=Search(
    module_id="air_conditioner",
    state=[24.5],
    limit=5
))

if status == 200:
    for result in res:
        print(f"Score: {result.score}, ESS: {result.ess.state}")

​
upsert(module_id: str, db_id: int)

Upsert an ESS to the Vector Search Engine (VSE) collection.
​
module_id
str
required
The module identifier
​
db_id
int
required
The database ID of the ESS
​
response
tuple
Returns a tuple of (response | Error, status_code)
Example: 
res, status = eca.ess.upsert(module_id="aggregate001", db_id=5)

Build docs developers (and LLMs) love

Get started for freeTalk to us