sinapsis-aperturedb 0.1.0__py3-none-any.whl

sinapsis_aperturedb/helpers/aperturedb_env_var_keys.py

@@ -0,0 +1,60 @@
+# -*- coding: utf-8 -*-
+from typing import Any
+
+from pydantic import BaseModel
+from sinapsis_core.utils.env_var_keys import EnvVarEntry, doc_str, return_docs_for_vars
+
+
+class _ApertureDBEnvVars(BaseModel):
+    """Env vars for ApertureDB."""
+
+    APERTUREDB_API_KEY: EnvVarEntry = EnvVarEntry(
+        var_name="APERTUREDB_API_KEY",
+        default_value="",
+        allowed_values=None,
+        description="set api key for ApertureDB",
+    )
+    APERTUREDB_HOST: EnvVarEntry = EnvVarEntry(
+        var_name="APERTUREDB_HOST",
+        default_value="localhost",
+        allowed_values=None,
+        description="set host for ApertureDB",
+    )
+    APERTUREDB_USER: EnvVarEntry = EnvVarEntry(
+        var_name="APERTUREDB_USER",
+        default_value="",
+        allowed_values=None,
+        description="set user for ApertureDB",
+    )
+    APERTUREDB_PASSWORD: EnvVarEntry = EnvVarEntry(
+        var_name="APERTUREDB_PASSWORD",
+        default_value="",
+        allowed_values=None,
+        description="set password for ApertureDB",
+    )
+    APERTUREDB_PORT: EnvVarEntry = EnvVarEntry(
+        var_name="APERTUREDB_PORT",
+        default_value="55555",
+        allowed_values=None,
+        description="set port for ApertureDB",
+    )
+
+
+ApertureDBEnvVars = _ApertureDBEnvVars()
+
+doc_str = return_docs_for_vars(
+    ApertureDBEnvVars,
+    docs=doc_str,
+    string_for_doc="""ApertureDB env vars available: \n""",
+)
+__doc__ = doc_str
+
+
+def __getattr__(name: str) -> Any:
+    if name in ApertureDBEnvVars.model_fields:
+        return ApertureDBEnvVars.model_fields[name].default.value
+
+    raise AttributeError(f"Agent does not have `{name}` env var")
+
+
+_all__ = (*list(ApertureDBEnvVars.model_fields.keys()), "ApertureDBEnvVars")

sinapsis_aperturedb/helpers/query_base_models/add.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+
+from pydantic import Field
+
+from sinapsis_aperturedb.helpers.query_base_models.base import (
+    ConstraintsType,
+    CreateConnectionType,
+    DateType,
+    QueryParameters,
+    ReferenceType,
+)
+
+
+class BaseAddParameters(QueryParameters):
+    """Base class for Add_ commands parameters.
+
+    [optional] _ref: reference to be used within the transaction.
+    [optional] properties: key-value pairs associated with objects (Entity, Image, Video, Descriptor, etc) and connections.
+    [optional] if_not_found: When using if_not_found, an Add* command (AddEntity, etc) will become a "conditional add"
+        the object will be inserted into the database if and only if there is no other element of the same type that
+        fulfills the specified constraints
+    [optional] connect
+    """
+
+    ref: ReferenceType | None = Field(alias="_ref", default=None)
+    properties: dict[str, int | float | str | bool | DateType] | None = None
+    if_not_found: ConstraintsType | None = None
+    connect: CreateConnectionType | None = None
+
+
+class AddEntityParameters(BaseAddParameters):
+    """AddEntity class: name of entity class."""
+
+    class_: str = Field(alias="class")

sinapsis_aperturedb/helpers/query_base_models/base.py

@@ -0,0 +1,165 @@
+# -*- coding: utf-8 -*-
+from typing import Annotated, Any, Literal, Tuple
+
+from pydantic import BaseModel, Field
+
+
+class ConnectionParams(BaseModel):
+    """Model to store connection parameters to ApertureDB server."""
+
+    host: str | None = None
+    user: str | None = None
+    port: int | None = None
+    password: str | None = None
+    key: str | None = None
+    use_ssl: bool | None = None
+
+    def get_connection_params(self) -> dict[str, Any]:
+        """Get connection parameters as a dictionary, excluding None and unset values."""
+        conn_params = self.model_dump(exclude_none=True, exclude_unset=True)
+        return conn_params
+
+
+class QueryParameters(BaseModel):
+    """Base class for query parameters."""
+
+    def get_parameters(self) -> dict[str, Any]:
+        """Format parameters as a dictionary. Excludes any not set."""
+        dumped_model = self.model_dump(mode="json", by_alias=True, exclude_unset=True, exclude_none=True)
+        return self.remove_empty_dicts(dumped_model)
+
+    @staticmethod
+    def remove_empty_dicts(data: dict) -> dict:
+        """Remove empty dictionaries and lists from the input dictionary.
+
+        Parameters
+        ----------
+        data (dict): Dictionary to filter.
+
+        Returns:
+        -------
+        dict: Dictionary with None values and empty dicts/lists removed.
+        """
+        return {k: v for k, v in data.items() if v is not None and (not isinstance(v, (dict, list)) or len(v) > 0)}
+
+
+class Query(BaseModel):
+    """Query base model."""
+
+    command: str
+    parameters: QueryParameters
+    blobs: list[bytes] | None = None
+
+    def prepare_query(self) -> Tuple[dict[str, Any], list[bytes]]:
+        """Format the query as a dictionary required by ApertureDB.
+
+        A query is composed of:
+            a string representing a JSON array of one or more commands, and
+            [optional] an "array of blobs".
+
+        """
+        query = {self.command: self.parameters.get_parameters()}
+        if self.blobs:
+            return query, self.blobs
+        return query, []
+
+
+class Response(BaseModel):
+    """Base model to store ApertureDB responses.
+
+    The JSON response is an array of objects where each member gives information about how a particular command executed.
+
+    status: Indicates execution status (e.g., 0 for success).
+    returned: Indicates the number of entities, connections, or blobs returned. If the user requests only aggregated values (e.g., sum, average) or uses _ref without requesting any properties, "returned" will be 0.
+    entities/connections [Optional]: Included only when the user explicitly requests property values.
+    blobs_start[Optional]: Included only if blobs=true was set in the query. Indicates the 0-based index in the return vector where blob data for this command begins.
+    _blob_index[Optional]: Included in each entity only if blobs=true. Indicates the blob's position relative to the full return vector.
+
+    """
+
+    status: int
+    info: str | None = None
+    returned: int | None = None
+    entities: list[dict[str, Any]] | dict[str, Any] | None = None
+    connections: list[dict[str, Any]] | dict[str, Any] | None = None
+    blobs_start: int | None = None
+    command: str | None = Field(exclude=True, default=None)
+
+    def format_response_dict(self) -> dict[str, Any]:
+        """Format the response as a dictionary.
+
+        If a command is set, returns a dictionary with the command as the key.
+        Otherwise, returns the response dictionary directly.
+
+        Returns:
+        -------
+        dict[str, Any]: Formatted response dictionary.
+        """
+        response_dict = self.model_dump(mode="json", exclude_unset=True)
+        if self.command is not None:
+            return {self.command: response_dict}
+        return response_dict
+
+
+# ------------Parameter types
+ReferenceType = Annotated[int, Field(ge=1, le=100000)]
+ConstraintsType = list[Any] | dict[str, Any] | None
+ImageFormatType = Literal["jpg", "png"]
+EngineType = Literal["Flat", "IVF", "HNSW"]
+MetricType = Literal["L2", "IP", "CS"]
+
+
+class ConnectionRef(BaseModel):
+    ref: ReferenceType | None = None
+    connection_class: str | None = None
+    constraints: ConstraintsType = None
+
+
+class IsConnectedTo(BaseModel):
+    ref: ReferenceType | None = None
+    connection_class: str | None = None
+    constraints: ConstraintsType | None = None
+    any: list[ConnectionRef] | None = None
+    in_: list[ConnectionRef] | None = Field(alias="in", default=None)
+    out: list[ConnectionRef] | None = None
+
+
+class ResultsType(BaseModel):
+    list_: list[str] | None = Field(alias="list", default=None)
+    all_properties: bool | None = None
+    count: bool | None = None
+    sum: str | list[str] | None = None
+    average: str | list[str] | None = None
+    min: str | list[str] | None = None
+    max: str | list[str] | None = None
+    group: list[str] | None = None
+
+
+class BatchType(BaseModel):
+    batches: int | None = None
+    batch_size: int | None = None
+    batch_id: int | None = None
+
+
+class DateType(BaseModel):
+    """datetime (ISO 8601 representation)."""
+
+    date: str = Field(alias="_date")
+
+
+class CreateConnectionType(BaseModel):
+    """ref: Reference to other objects within the transaction.
+
+    [optional] class: Name of the class that is used to describe the relationship between the objects.
+    [optional] direction: [in, out]. Default is "out. "in" indicates that the relationship actually ends at the object
+                (object) in the Add*.
+    """
+
+    ref: ReferenceType
+    class_: str | None = Field(alias="class", default=None)
+    direction: Literal["in", "out"] | None = None
+
+
+class GetSchemaParameters(QueryParameters):
+    ref: ReferenceType | None = None
+    type: Literal["entities", "connections", "both"] | None = None

sinapsis_aperturedb/helpers/query_base_models/delete.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+
+
+from sinapsis_aperturedb.helpers.query_base_models.base import (
+    ConstraintsType,
+    QueryParameters,
+    ReferenceType,
+)
+
+
+class BaseDeleteParameters(QueryParameters):
+    """Base parameters for Delete_ commands.
+
+    [optional] ref: Reference to other entity objects within the transaction.
+    [optional] constraints
+    """
+
+    ref: ReferenceType | None = None
+    constraints: ConstraintsType | None = None
+
+
+class DeleteEntityParameters(BaseDeleteParameters):
+    """Parameters for DeleteEntity command.
+
+    [optional] with_class: Specifies the entity class.
+    """
+
+    with_class: str | None = None
+
+
+class DeleteDescriptorSetParameters(BaseDeleteParameters):
+    """Parameters for DeleteDescriptorSet command.
+
+    [optional] background: Differs deletion of the set and associated descriptions as a background task.
+        Defaults to false.
+    """
+
+    set: str

sinapsis_aperturedb/helpers/query_base_models/find.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+from pydantic import Field
+
+from sinapsis_aperturedb.helpers.query_base_models.base import (
+    BatchType,
+    ConstraintsType,
+    IsConnectedTo,
+    QueryParameters,
+    ReferenceType,
+    ResultsType,
+)
+
+
+class BaseFindParameters(QueryParameters):
+    """Base parameters for Find_ commands.
+
+    [optional] _ref: Reference to be used within the transaction.
+    [optional] unique: Indicates whether a single object is expected to satisfy the constraints.
+    [optional] constraints: used to specify search/filter criteria over the properties defined for objects
+    [optional] is_connected_to: specifies one or more connection-based constraints that must be satisfied in a Find* command
+    [optional] group_by_source: specifies in a Find* command the result is a set of objects connected to the referenced
+                Find* command by connections as defined by the is_connected_to parameter
+    [optional] results: Defines the information returned in the JSON response as a result of a Find* command
+    [optional] batch: specify a query that can be used by multiple workers to retrieve a portion of the results
+    [optional] sort: specifies how the results will be sorted on the response, and which properties will be used for sorting
+    [optional] limit: specifies the maximum number of elements that will be returned.
+    [optional] offset: specifies the number of results that will be skipped
+    [optional] uniqueids: indicates whether unique ids will be returned as part of the response (Default: false).
+
+
+    """
+
+    ref: ReferenceType | None = Field(alias="_ref", default=None)
+    unique: bool | None = None
+    constraints: ConstraintsType | None = Field(default=None)
+    is_connected_to: IsConnectedTo = Field(default_factory=dict)
+    group_by_source: bool | None = None
+    results: ResultsType = Field(default_factory=dict)
+    batch: BatchType = Field(default_factory=dict)
+    sort: str | dict[str, str] | list[dict[str, str]] | None = None
+    limit: int | None = None
+    offset: int | None = None
+    uniqueids: bool | None = None
+
+
+class FindEntityParameters(BaseFindParameters):
+    """Parameters for FindEntity command.
+
+    [optional] with_class: Name of entity class.
+    """
+
+    with_class: str | None = None

sinapsis_aperturedb/helpers/query_base_models/update.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+from sinapsis_aperturedb.helpers.query_base_models.base import (
+    ConstraintsType,
+    DateType,
+    QueryParameters,
+    RectangleType,
+    ReferenceType,
+)
+
+
+class BaseUpdateParameters(QueryParameters):
+    """Base parameters for Update_ commands.
+
+    [optional] ref: Reference to other entities within the transaction.
+    [optional] constraints: used to specify search/filter criteria over the properties defined for objects
+    [optional] properties: key-value pairs associated with objects (Entity, Image, Video, Descriptor, etc) and connections.
+    [optional] remove_props: list of property keys that will be removed as part of an Update* command.
+    """
+
+    ref: ReferenceType | None = None
+    constraints: ConstraintsType | None = None
+    properties: dict[str, int | float | str | bool | DateType] | None = None
+    remove_props: list[str] | None = None
+
+
+class UpdateEntityParameters(BaseUpdateParameters):
+    """Parameters for UpdateEntity command.
+
+    [optional] with_class: name of entity class.
+    """
+
+    with_class: str | None = None
+
+
+class UpdateBoundingBoxParameters(BaseUpdateParameters):
+    """Parameters for UpdateBoundingBox command.
+
+    [optional] rectangle
+    [optional] label
+    """
+
+    rectangle: RectangleType | None = None
+    label: str | None = None
+
+
+class UpdatePolygonParameters(BaseUpdateParameters):
+    """Parameters for UpdatePolygon command.
+
+    [optional] polygons
+    [optional] label
+    """
+
+    polygons: list[list[list[int | float]]] | None = None
+    label: str | None = None
+
+
+class UpdateDescriptorSetParameters(BaseUpdateParameters):
+    """Parameters for UpdateDescriptorSet command.
+
+    [optional] with_name: name of the set.
+    """
+
+    with_name: str | None = None
+
+
+class UpdateDescriptorParameters(BaseUpdateParameters):
+    """Parameters for UpdateDescriptor command.
+
+    [optional] with_name: name of the set.
+    """
+
+    label: str | None = None

sinapsis_aperturedb/helpers/tags.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+from enum import Enum
+
+
+class Tags(Enum):
+    DATABASE = "database"
+    JSON = "json"

sinapsis_aperturedb/templates/__init__.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+import importlib
+from typing import Callable, cast
+
+_root_lib_path = "sinapsis_aperturedb.templates"
+
+_template_lookup: dict = {
+    "ApertureDBGetStatus": f"{_root_lib_path}.aperturedb_client_base",
+    "ApertureDBFindEntities": f"{_root_lib_path}.aperturedb_find_in_table",
+    "ApertureDBAddEntitiesFromCSV": f"{_root_lib_path}.aperturedb_add_to_table",
+    "ApertureDBGetSchema": f"{_root_lib_path}.aperturedb_database_info",
+}
+
+
+def __getattr__(name: str) -> Callable:
+    if name in _template_lookup:
+        module = importlib.import_module(_template_lookup[name])
+        return cast(Callable, getattr(module, name))
+    raise AttributeError(f"template `{name}` not found in {_root_lib_path}")
+
+
+__all__ = list(_template_lookup.keys())

sinapsis_aperturedb/templates/aperturedb_add_to_table.py

@@ -0,0 +1,72 @@
+# -*- coding: utf-8 -*-
+import pandas as pd
+from pydantic.dataclasses import dataclass
+from sinapsis_core.data_containers.data_packet import DataContainer
+
+from sinapsis_aperturedb.helpers.query_base_models.add import (
+    AddEntityParameters,
+)
+from sinapsis_aperturedb.helpers.query_base_models.base import (
+    Query,
+)
+from sinapsis_aperturedb.templates.aperturedb_client_base import (
+    ApertureDBClientQuery,
+    ApertureDBClientQueryAttributes,
+)
+
+
+@dataclass
+class ApertureDBAddEntitiesFromCSVKeys:
+    records: str = "records"
+    class_: str = "class"
+    properties: str = "properties"
+
+
+class ApertureDBAddEntitiesFromCSV(ApertureDBClientQuery):
+    """Template to add Entities from a CSV file.
+
+    This template receives a CSV as a pandas dataframe within the DataContainer, then
+    creates queries to add Entities from the CSV with one of the columns' names to be used as
+    the Entity class name.
+    """
+
+    COMMAND = "AddEntity"
+
+    class ApertureDBAddEntitiesFromCSVAttributes(ApertureDBClientQueryAttributes):
+        """Attributes for ApertureDBAddEntity template.
+
+        class_column: name of the column which will be used as class name. Case sensitive
+        """
+
+        class_column: str
+        generic_key: str
+
+    AttributesBaseModel = ApertureDBAddEntitiesFromCSVAttributes
+
+    def execute(self, container: DataContainer) -> DataContainer:
+        """Gets CSV data from the pandas dataframe and creates an AddEntity query for each row.
+
+        Args:
+            container (DataContainer): The container holding the input data packets.
+
+        Returns:
+            DataContainer: The updated container with responses
+        """
+        csv_dataframe: pd.DataFrame = self._get_generic_data(container)
+
+        if not isinstance(csv_dataframe, pd.DataFrame):
+            self.logger.warning("Received CSV data must be a pandas dataframe object. Returning input datacontainer.")
+            return container
+
+        queries = []
+        for record in csv_dataframe.to_dict(ApertureDBAddEntitiesFromCSVKeys.records):
+            entity = {}
+            class_value = record.pop(self.attributes.class_column)
+            entity[ApertureDBAddEntitiesFromCSVKeys.class_] = class_value
+            entity[ApertureDBAddEntitiesFromCSVKeys.properties] = record
+            parameters = AddEntityParameters(**entity)
+            query_base_model = Query(command=self.COMMAND, parameters=parameters)
+            queries.append(query_base_model.prepare_query()[0])
+
+        self.process_query_list(queries, container)
+        return container