Skip to main content

​
What are Aggregates?

Aggregates in AveniECA combine multiple ESS (Experience-State-Score) records from different modules into a single composite state vector. This allows you to represent complex multi-dimensional states as a unified entity for prediction and analysis. An aggregate ESS contains:
  • A concatenated state vector from all component ESS
  • Metadata about each component (module_id, valence, score, etc.)
  • Computed aggregate statistics (averages, totals)

​
Aggregate Fields in ESSInsert

When creating an aggregate, you’ll use these special fields in the ESSInsert model: 
from avenieca.api.model import ESSInsert

aggregate = ESSInsert(
    module_id="aggregate001",
    state=[],                      # Concatenated state vectors
    valence=10.0,                  # Total aggregate valence
    score=0,                       # Aggregate score
    avg_ess_valence=0.0,          # Average valence across all ESS
    total_ess_score=0,            # Sum of all component scores
    avg_ess_score=0,              # Average score across all ESS
    aggregate_id=[],              # DB IDs of component ESS
    aggregate_valence=[],         # Valence values of each component
    aggregate_score=[],           # Score values of each component
    aggregate_module_id=[],       # Module IDs of each component
    aggregate_shape=[],           # Length of each component state vector
    aggregate_context=[],         # Context from each component
    aggregate_emb_inp=[],         # Embedding inputs from each component
    context=None,
)

​
Key Fields Explained

​
state
List[float]
Concatenated state vectors from all component ESS in order
​
aggregate_id
List[int]
Database IDs of the component ESS records
​
aggregate_module_id
List[str]
Module IDs corresponding to each component ESS
​
aggregate_shape
List[int]
Length of each component’s state vector, used to reconstruct individual states
​
avg_ess_valence
float
Average valence calculated from all component ESS
​
total_ess_score
int
Sum of all component ESS scores

​
Creating Aggregates from Multiple ESS

Here’s a complete example showing how to create an aggregate from multiple ESS records: 
import os
from avenieca.api.model import Config, ESSInsert, ESSResponse
from avenieca.api.eca import ECA
from typing import List

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

# Helper function to create aggregates
def create_aggregate_from_ess(array_ess: List[ESSResponse], aggregate_insert: ESSInsert):
    total_ess_score = 0
    total_ess_valence = 0.0
    for ess in array_ess:
        aggregate_insert.state.extend(ess.state)
        aggregate_insert.aggregate_module_id.append(ess.module_id)
        aggregate_insert.aggregate_id.append(ess.id)
        aggregate_insert.aggregate_context.append(ess.context)
        aggregate_insert.aggregate_valence.append(ess.valence)
        aggregate_insert.aggregate_score.append(ess.score)
        aggregate_insert.aggregate_emb_inp.append(ess.embedding_input)
        aggregate_insert.aggregate_shape.append(len(ess.state))
        total_ess_score += ess.score
        total_ess_valence += ess.valence
    aggregate_insert.total_ess_score = total_ess_score
    aggregate_insert.avg_ess_score = int(total_ess_score / len(array_ess))
    aggregate_insert.avg_ess_valence = total_ess_valence / len(array_ess)
    aggregate_insert.valence = total_ess_valence
    return aggregate_insert

# Create component ESS responses (these would typically come from the API)
ess_air_conditioner = ESSResponse(
    id=5,
    created_at='',
    updated_at='',
    state=[25.0],
    module_id='air_conditioner',
    valence=90.0,
    score=18,
    embedding_input=None,
    context=None
)

ess_temperature = ESSResponse(
    id=2,
    created_at='',
    updated_at='',
    module_id="temperature",
    state=[28.0],
    valence=-90,
    score=1,
    context=None,
    embedding_input=None
)

ess_occupancy = ESSResponse(
    id=7,
    created_at='',
    updated_at='',
    state=[10.0],
    module_id='occupancy',
    valence=-90.0,
    score=6,
    embedding_input=None,
    context=None
)

ess_purifier = ESSResponse(
    id=3,
    created_at='',
    updated_at='',
    state=[2.0],
    module_id='purifier',
    valence=90.0,
    score=28,
    embedding_input=None,
    context=None
)

ess_air_quality_index = ESSResponse(
    id=6,
    created_at='',
    updated_at='',
    state=[70.0],
    module_id='air_quality_index',
    valence=-90.0,
    score=2,
    embedding_input=None,
    context=None
)

# Initialize empty aggregate
aggregate_insert = ESSInsert(
    module_id="aggregate001",
    state=[],
    valence=10.0,
    avg_ess_valence=0.0,
    score=0,
    total_ess_score=0,
    avg_ess_score=0,
    aggregate_id=[],
    aggregate_valence=[],
    aggregate_score=[],
    aggregate_module_id=[],
    aggregate_shape=[],
    aggregate_context=[],
    aggregate_emb_inp=[],
    context=None,
)

# Create the aggregate
agg_in = create_aggregate_from_ess(
    [
        ess_air_conditioner,
        ess_air_quality_index,
        ess_occupancy,
        ess_purifier,
        ess_temperature
    ],
    aggregate_insert
)

# Save to database
res, status = eca.ess.create(data=agg_in)
if status == 201:
    print(f"Aggregate created: {res.id}")
    print(f"Combined state: {res.state}")
    print(f"Average valence: {res.avg_ess_valence}")

​
Aggregate Validation and Errors

The AveniECA API validates aggregates during creation and update. If validation fails, you’ll receive an AggregateError response: 
from avenieca.api.model import AggregateError

res, status = eca.ess.create(data=agg_in)

if isinstance(res, AggregateError):
    # Handle validation errors
    if res.field_length_errors:
        print("Field length mismatches:", res.field_length_errors)
    
    if res.invalid_ess_db_ids:
        print("Invalid ESS IDs:", res.invalid_ess_db_ids)
    
    if res.ess_mismatch:
        print("ESS data mismatch:", res.ess_mismatch)
    
    if res.incorrect_avg_ess_score:
        print("Average score error:", res.incorrect_avg_ess_score)
    
    if res.incorrect_avg_ess_valence:
        print("Average valence error:", res.incorrect_avg_ess_valence)

​
Common Validation Errors

All aggregate arrays (aggregate_id, aggregate_valence, aggregate_score, etc.) must have the same length. Each index represents one component ESS.
The ESS IDs in aggregate_id must reference existing ESS records in the database.
The data in aggregate fields must match the actual ESS records referenced by aggregate_id.
The avg_ess_score, avg_ess_valence, and total_ess_score must be calculated correctly from component values.

​
Retrieving Aggregates

You can query which aggregates contain a specific ESS: 
# Find all aggregates containing a specific ESS
res, status = eca.ess.get_all_aggregates(
    module_id="temperature",
    aggregate_module_id="aggregate001",
    ess_id=2
)

if status == 200:
    for aggregate in res:
        print(f"Aggregate {aggregate.id} contains temperature ESS")

​
Next Steps

Predictions

Use aggregates with Cortex for multi-dimensional predictions

Best Practices

Learn production patterns for aggregate design

Build docs developers (and LLMs) love

Get started for freeTalk to us