Skip to main content

​
Overview

This page documents all data models available in the AveniECA Python SDK. All models inherit from the Base class, providing serialization and deserialization capabilities.

​
Base Class

All models inherit from Base, which provides:
  • __dict__ property: Returns a dictionary representation
  • json property: Returns a JSON string representation
  • to_json_file(file) method: Writes the model to a JSON file
  • from_json() class method: Creates an instance from JSON (via JSONWizard)
  • from_dict() class method: Creates an instance from a dictionary (via JSONWizard)

​
Authentication Models

​
AuthLogin

Credentials for authenticating with the AveniECA API.
​
username
str
required
Username for authentication
​
password
str
required
Password for authentication
Example: 
from avenieca.api.model import AuthLogin

auth = AuthLogin(
    username="myuser",
    password="mypassword"
)

​
AuthResponse

Response returned after successful authentication.
​
role
str
required
User role in the system
​
session_id
str
required
Session identifier for authenticated requests
​
user_id
str
required
Unique user identifier
​
username
str
required
Username of the authenticated user

​
Config

Configuration object for API client setup.
​
api_token
str
default:""
API token for authentication
​
username
str
default:""
Username for authentication
​
password
str
default:""
Password for authentication
​
uri
str
default:""
API endpoint URI

​
ESS (Episodic State Store) Models

​
ESSInsert

Model for inserting a new ESS entry.
​
state
List[float]
required
State vector representing the episodic state
​
module_id
str
required
Module identifier for organizing ESS entries
​
valence
float
required
Valence value for this state
​
avg_ess_valence
float
default:"0.0"
Average valence across aggregated states
​
total_ess_score
int
default:"0"
Total score across aggregated states
​
avg_ess_score
int
default:"0"
Average score across aggregated states
​
score
int
default:"0"
Score for this state
​
embedding_input
int
default:"None"
Reference to the embedding input ID
​
aggregate_id
List[int]
default:"[]"
List of aggregated ESS entry IDs
​
aggregate_valence
List[float]
default:"[]"
List of valence values from aggregated entries
​
aggregate_score
List[int]
default:"[]"
List of scores from aggregated entries
​
aggregate_module_id
List[str]
default:"[]"
List of module IDs from aggregated entries
​
aggregate_shape
List[int]
default:"[]"
Shape information for aggregated entries
​
aggregate_context
list
default:"[]"
Context information from aggregated entries
​
aggregate_emb_inp
list
default:"[]"
Embedding input IDs from aggregated entries
​
context
str
default:"None"
Optional context string for this entry
Example: 
from avenieca.api.model import ESSInsert

ess_entry = ESSInsert(
    state=[0.1, 0.2, 0.3, 0.4],
    module_id="perception",
    valence=0.85,
    score=100,
    context="User interaction"
)

​
ESSResponse

Response model for ESS entries retrieved from the database.
​
id
int
required
Unique database identifier for this ESS entry
​
state
List[float]
required
State vector
​
module_id
str
required
Module identifier
​
valence
float
required
Valence value
​
created_at
str
default:"None"
Timestamp when the entry was created
​
updated_at
str
default:"None"
Timestamp when the entry was last updated
​
avg_ess_valence
float
default:"0.0"
Average valence across aggregated states
​
total_ess_score
int
default:"0"
Total score across aggregated states
​
avg_ess_score
int
default:"0"
Average score across aggregated states
​
score
int
default:"0"
Score for this state
​
embedding_input
int
default:"None"
Reference to the embedding input ID
​
aggregate_id
List[int]
default:"[]"
List of aggregated ESS entry IDs
​
aggregate_valence
List[float]
default:"[]"
List of valence values from aggregated entries
​
aggregate_score
List[int]
default:"[]"
List of scores from aggregated entries
​
aggregate_module_id
List[str]
default:"[]"
List of module IDs from aggregated entries
​
aggregate_shape
List[int]
default:"[]"
Shape information for aggregated entries
​
aggregate_context
list
default:"[]"
Context information from aggregated entries
​
aggregate_emb_inp
list
default:"[]"
Embedding input IDs from aggregated entries
​
context
str
default:"None"
Optional context string

​
PrettyESS

Formatted ESS response with additional display fields.
​
id
int
required
Unique database identifier
​
state
List[str]
required
State vector as strings for display
​
aggregate_id
List[int]
required
List of aggregated ESS entry IDs
​
aggregate_valence
List[float]
required
List of valence values from aggregated entries
​
aggregate_score
List[int]
required
List of scores from aggregated entries
​
aggregate_module_id
List[str]
required
List of module IDs from aggregated entries
​
aggregate_shape
List[int]
required
Shape information for aggregated entries
​
module_id
str
required
Module identifier
​
valence
float
required
Valence value
​
avg_ess_valence
float
required
Average valence across aggregated states
​
total_ess_score
int
required
Total score across aggregated states
​
avg_ess_score
int
required
Average score across aggregated states
​
created_at
str
required
Creation timestamp
​
updated_at
str
required
Last update timestamp
​
score
int
default:"0"
Score for this state
​
embedding_input
int
default:"None"
Reference to the embedding input ID
​
aggregate_context
list
default:"[]"
Context information from aggregated entries
​
aggregate_emb_inp
list
default:"[]"
Embedding input IDs from aggregated entries
​
context
str
default:"None"
Optional context string
​
state_float
float
default:"None"
Numeric representation of state
​
state_str
str
default:"None"
String representation of state

​
AggregateError

Error model for validation issues when aggregating ESS entries.
​
ess_from_aggregate
str
default:""
Error message for ESS aggregation issues
​
field_length_errors
list
default:"[]"
List of field length validation errors
​
module_id_position
list
default:"[]"
List of module ID position errors
​
verifying_ess_exists
list
default:"[]"
List of ESS existence verification errors
​
ess_mismatch
list
default:"[]"
List of ESS mismatch errors
​
invalid_ess_db_ids
list
default:"[]"
List of invalid ESS database IDs
​
invalid_module_ids
list
default:"[]"
List of invalid module IDs
​
incorrect_avg_ess_score
str
default:""
Error message for incorrect average ESS score
​
incorrect_avg_ess_valence
str
default:""
Error message for incorrect average ESS valence
​
incorrect_valence
str
default:""
Error message for incorrect valence
​
incorrect_total_ess_sore
str
default:""
Error message for incorrect total ESS score

​
Sequence Models

​
SequenceInsert

Model for inserting a new sequence entry.
​
module_id
str
required
Module identifier for the sequence
​
instance_id
int
required
Instance identifier within the module
​
status
str
default:"n"
Status of the sequence (e.g., ‘n’ for new)
​
context
str
default:"None"
Optional context for the sequence
Example: 
from avenieca.api.model import SequenceInsert

sequence = SequenceInsert(
    module_id="perception",
    instance_id=42,
    status="active",
    context="User session 123"
)

​
SequenceResponse

Response model for sequence entries.
​
id
int
required
Unique database identifier
​
module_id
str
required
Module identifier
​
instance_id
int
required
Instance identifier
​
status
str
required
Current status of the sequence
​
created_at
str
required
Creation timestamp
​
updated_at
str
required
Last update timestamp
​
context
str
default:"None"
Optional context

​
NextStateRequest

Request model for predicting next states in a sequence.
​
module_id
str
required
Module identifier to search within
​
range
int
default:"2"
Range parameter for state prediction
​
recall
int
default:"2"
Number of previous states to recall
​
n
int
default:"1"
Number of next states to predict
​
status
str
default:"None"
Filter by sequence status
​
current_state
int
default:"None"
Current state ID
​
previous_state
list
default:"None"
List of previous state IDs
​
store_response
bool
default:"False"
Whether to store the response
​
store_sequence
bool
default:"False"
Whether to store the sequence
Example: 
from avenieca.api.model import NextStateRequest

request = NextStateRequest(
    module_id="perception",
    range=3,
    recall=5,
    n=2,
    current_state=100,
    store_response=True
)

​
NextStateResponse

Response containing current and predicted next states.
​
current_state
List[Twin]
required
List of Twin objects representing the current state
​
next_state
List[Twins]
required
List of Twins objects representing predicted next states

​
NextStateResponseRaw

Raw response with float state vectors instead of string representations.
​
current_state
List[TwinRaw]
required
List of TwinRaw objects for current state
​
next_state
List[TwinsRaw]
required
List of TwinsRaw objects for predicted next states

​
Twin Models

​
Twin

Represents a state twin with string representation.
​
aggregate_id
int
required
Aggregate identifier
​
ess_id
int
required
ESS entry identifier
​
module_id
str
required
Module identifier
​
state
str
required
State representation as string

​
TwinRaw

Represents a state twin with raw float vector.
​
state
List[float]
required
State vector as list of floats
​
aggregate_id
int
required
Aggregate identifier
​
ess_id
int
required
ESS entry identifier
​
module_id
str
required
Module identifier

​
Twins

Collection of Twin objects.
​
list
List[Twin]
required
List of Twin objects

​
TwinsRaw

Collection of TwinRaw objects.
​
list
List[TwinRaw]
required
List of TwinRaw objects

​
Document Models

​
DocumentInsert

Model for inserting a new document.
​
doc_id
str
required
Unique document identifier
​
text
str
required
Document text content
​
embed
bool
default:"False"
Whether to generate embeddings for this document
Example: 
from avenieca.api.model import DocumentInsert

doc = DocumentInsert(
    doc_id="doc_001",
    text="This is the document content.",
    embed=True
)

​
DocumentResponse

Response model for document entries.
​
id
int
required
Unique database identifier
​
doc_id
str
required
Document identifier
​
text
str
required
Document text content
​
status
str
required
Processing status of the document
​
created_at
str
required
Creation timestamp
​
updated_at
str
required
Last update timestamp

​
Embedding Models

​
EmbeddingInputInsert

Model for inserting embedding input.
​
module_id
str
required
Module identifier
​
input
str
required
Input text to be embedded
​
hash
str
required
Hash of the input for deduplication
Example: 
import hashlib
from avenieca.api.model import EmbeddingInputInsert

input_text = "Sample input"
input_hash = hashlib.sha256(input_text.encode()).hexdigest()

emb_input = EmbeddingInputInsert(
    module_id="perception",
    input=input_text,
    hash=input_hash
)

​
EmbeddingInputResponse

Response model for embedding input entries.
​
id
int
required
Unique database identifier
​
module_id
str
required
Module identifier
​
input
str
required
Input text
​
hash
str
required
Hash of the input
​
created_at
str
required
Creation timestamp
​
updated_at
str
required
Last update timestamp

​
EmbeddingInputHash

Model for querying by embedding input hash.
​
hash
str
required
Hash of the embedding input

​
Search Models

Model for performing similarity search in ESS.
​
module_id
str
required
Module identifier to search within
​
state
List[float]
required
Query state vector for similarity search
​
limit
int
default:"1"
Maximum number of results to return
Example: 
from avenieca.api.model import Search

search_query = Search(
    module_id="perception",
    state=[0.1, 0.2, 0.3, 0.4],
    limit=10
)

​
SearchResult

Single search result with similarity score.
​
score
float
required
Similarity score for this result
​
ess
ESSResponse
required
The matching ESS entry

​
Retrieval Models

​
RetrievalRequest

Request model for retrieval-augmented generation.
​
query
str
required
Query string for retrieval
Example: 
from avenieca.api.model import RetrievalRequest

request = RetrievalRequest(
    query="What is the meaning of life?"
)

​
RetrievalResponse

Response from retrieval-augmented generation.
​
response
str
required
Generated response text

​
ECA (Event-Condition-Action) Models

​
ECAResponse

Response model for ECA rule entries.
​
percept_ess_ids
List[int]
required
List of ESS IDs associated with percepts
​
response_ess_ids
List[int]
required
List of ESS IDs associated with responses
​
percept_names
List[str]
required
Names of percept states
​
response_names
List[str]
required
Names of response states
​
name
str
required
Name of the ECA rule
​
id
int
required
Unique database identifier
​
percept
int
required
Percept identifier
​
response
int
required
Response identifier
​
twin_module_id
str
required
Module identifier for twin states
​
status
str
required
Status of the ECA rule
​
created_at
str
required
Creation timestamp
​
updated_at
str
required
Last update timestamp

​
Error Models

​
Error

General error response model.
​
errors
List[str]
required
List of error messages
Example: 
from avenieca.api.model import Error

error_response = Error(
    errors=["Invalid module_id", "State vector dimension mismatch"]
)

Build docs developers (and LLMs) love

Get started for freeTalk to us