Featured graph consolidation layer (5th agent)

.dockerignore

@@ -117,3 +117,10 @@ deploy/terraform/
 *.tfstate
 *.tfstate.*
 .terraform/
+
+gcp_credentials.json
+READMEP.md
+Untitled-1.excalidraw
+.favorites.json
+.env
+.env*

LICENSE

@@ -1,5 +1,5 @@
 BRAINAPI2 ENGINE LICENSE
-Version 1.0 — © 2025 Lumen Platforms Inc.
+Version 1.0 — © 2026 Lumen Platforms Inc.
 
 This software ("BrainAPI Engine" or "the Software") is provided under a combined
 license consisting of:

Makefile

@@ -35,6 +35,12 @@ stop-neo4j:
 delete-neo4j-volumes:
 	docker compose -f src/lib/neo4j/docker-compose.yaml down -v --remove-orphans
 
+build-neo4j-extension:
+	docker run --rm -v $(PWD)/src/lib/neo4j:/app -w /app maven:3.9-eclipse-temurin-17 mvn compile
+
+package-neo4j-extension:
+	docker run --rm -v $(PWD)/src/lib/neo4j:/app -w /app maven:3.9-eclipse-temurin-17 mvn package -DskipTests
+
 start-mongo:
 	docker compose -f src/lib/mongo/docker-compose.yaml up -d
 
@@ -50,7 +56,7 @@ start-api:
 stop-api:
 	pkill -f uvicorn
 
-DEBUG_ENVS := LANGCHAIN_DEBUG="true" LANGCHAIN_VERBOSE="true" DEBUG="true" ENV="development"
+DEBUG_ENVS := LANGCHAIN_DEBUG="true" LANGCHAIN_VERBOSE="true" DEBUG="true"
 
 start-all:
 	@if [ "$(filter debug,$(MAKECMDGOALS))" = "debug" ] || [ "$$DEBUG" = "true" ]; then \
@@ -60,16 +66,16 @@ start-all:
 		$(MAKE) start-redis DEBUG=true & \
 		$(MAKE) start-neo4j DEBUG=true & \
 		$(MAKE) start-mongo DEBUG=true & \
-		$(MAKE) start-api DEBUG=true & \
-		bash -c "export $(DEBUG_ENVS) && poetry run celery -A src.workers.app worker --loglevel=info --pool=threads --concurrency=10"; \
+		ENV="development" $(MAKE) start-api DEBUG=true & \
+		bash -c "export $(DEBUG_ENVS) ENV="development" && poetry run celery -A src.workers.app worker --loglevel=info --pool=threads --concurrency=10"; \
 	else \
 		$(MAKE) start-milvus & \
 		$(MAKE) start-rabbitmq & \
 		$(MAKE) start-redis & \
 		$(MAKE) start-neo4j & \
 		$(MAKE) start-mongo & \
-		$(MAKE) start-api & \
-		poetry run celery -A src.workers.app worker --loglevel=info --pool=threads --concurrency=10; \
+		ENV="development" $(MAKE) start-api & \
+		ENV="development" poetry run celery -A src.workers.app worker --loglevel=info --pool=threads --concurrency=10; \
 	fi
 
 debug:

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-2.1.4--dev-blue?style=for-the-badge" alt="Version"/>
+  <img src="https://img.shields.io/badge/version-2.3.0--dev-blue?style=for-the-badge" alt="Version"/>
   <img src="https://img.shields.io/badge/python-3.11+-green?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
   <img src="https://img.shields.io/badge/license-AGPLv3%20%2B%20Commons%20Clause-purple?style=for-the-badge" alt="License"/>
 </p>

plugins/readme.txt

@@ -0,0 +1,5 @@
+Plugins can be used to extend the functionality of the BrainAPI.
+
+To add a plugin, add the plugin into the plugins directory and make sure the `brainapi.config.yaml` file is placed into the root of the `plugins` directory.
+
+If you are using a remote plugin add the `<plugin_name>.config.yaml` file directly into the `plugins` directory.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brainapi2"
-version = "2.1.4-dev"
+version = "2.3.0-dev"
 description = "Version 2.x.x of the BrainAPI memory layer."
 authors = [
     {name = "Christian",email = "alch.infoemail@gmail.com"}

src/adapters/data.py

@@ -3,8 +3,8 @@
 Created Date: Sunday October 19th 2025
 Author: Christian Nonis <alch.infoemail@gmail.com>
 -----
-Last Modified: Saturday December 13th 2025
-Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@gmail.com>
+Last Modified: Monday January 12th 2026 8:26:26 pm
+Modified By: Christian Nonis <alch.infoemail@gmail.com>
 -----
 """
 
@@ -157,62 +157,83 @@ def get_observations_list(
 
     def get_observation_labels(self, brain_id: str = "default") -> list[str]:
         """
-        Retrieve all unique observation labels for the specified brain.
+        Get all unique observation labels for the specified brain.
 
         Parameters:
-            brain_id (str): Identifier of the brain to query labels from.
+            brain_id (str): Identifier of the brain to query.
 
         Returns:
-            list[str]: All unique labels present in observations for the specified brain.
+            list[str]: A list of unique observation label strings for the specified brain.
         """
         return self.data.get_observation_labels(brain_id=brain_id)
-
-    def get_changelog_by_id(
-        self, id: str, brain_id: str = "default"
-    ) -> KGChanges:
+
+    def get_changelog_by_id(self, id: str, brain_id: str = "default") -> KGChanges:
         """
         Retrieve a changelog entry by its identifier.
-        
+
         Parameters:
             id (str): Identifier of the changelog entry to retrieve.
             brain_id (str): Brain namespace key to query; defaults to "default".
-        
+
         Returns:
             KGChanges: The changelog entry matching the given `id`.
         """
         return self.data.get_changelog_by_id(id=id, brain_id=brain_id)
 
     def get_changelogs_list(
-        self, 
-        brain_id: str = "default", 
-        limit: int = 10, 
-        skip: int = 0, 
+        self,
+        brain_id: str = "default",
+        limit: int = 10,
+        skip: int = 0,
         types: list[str] = None,
-        query_text: str = None
+        query_text: str = None,
     ) -> list[KGChanges]:
         """
         Retrieve a paginated list of knowledge-graph changelogs for a brain.
-        
+
         Parameters:
             brain_id (str): Identifier of the brain to query.
             limit (int): Maximum number of changelogs to return.
             skip (int): Number of changelogs to skip (offset).
             types (list[str] | None): If provided, restrict results to these changelog types.
             query_text (str | None): If provided, filter changelogs by matching text.
-        
+
         Returns:
             list[KGChanges]: Changelogs matching the filters and pagination parameters.
         """
-        return self.data.get_changelogs_list(brain_id=brain_id, limit=limit, skip=skip, types=types, query_text=query_text)
+        return self.data.get_changelogs_list(
+            brain_id=brain_id,
+            limit=limit,
+            skip=skip,
+            types=types,
+            query_text=query_text,
+        )
 
     def get_changelog_types(self, brain_id: str = "default") -> list[str]:
         """
         Retrieve distinct changelog types for a brain.
-        
+
         Parameters:
             brain_id (str): Identifier of the brain to query; defaults to "default".
-        
+
         Returns:
             list[str]: List of changelog type names.
         """
         return self.data.get_changelog_types(brain_id=brain_id)
+
+    def update_structured_data(
+        self, structured_data: StructuredData, brain_id: str = "default"
+    ) -> StructuredData:
+        """
+        Update an existing structured data entry.
+
+        Parameters:
+        	structured_data (StructuredData): The structured data object with updated information.
+        	brain_id (str): Identifier of the brain context for the update.
+
+        Returns:
+        	StructuredData: The updated structured data object.
+        """
+        return self.data.update_structured_data(
+            structured_data=structured_data, brain_id=brain_id
+        )

src/adapters/embeddings.py

@@ -3,14 +3,21 @@
 Created Date: Sunday October 19th 2025
 Author: Christian Nonis <alch.infoemail@gmail.com>
 -----
-Last Modified: Sunday October 19th 2025 9:00:59 am
-Modified By: the developer formerly known as Christian Nonis at <alch.infoemail@gmail.com>
+Last Modified: Thursday January 29th 2026 8:43:59 pm
+Modified By: Christian Nonis <alch.infoemail@gmail.com>
 -----
 """
 
 import uuid
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_exponential,
+    retry_if_exception_type,
+)
 from src.adapters.interfaces.embeddings import EmbeddingsClient, VectorStoreClient
 from src.constants.embeddings import Vector
+from src.lib.embeddings.client import EmbeddingError
 
 
 class EmbeddingsAdapter:
@@ -23,19 +30,49 @@ def add_client(self, client: EmbeddingsClient) -> None:
         """
         self.embeddings = client
 
+    @retry(
+        stop=stop_after_attempt(5),
+        wait=wait_exponential(multiplier=1, min=2, max=30),
+        retry=retry_if_exception_type(EmbeddingError),
+    )
+    def _embed_text_with_retry(self, text: str) -> list[float]:
+        return self.embeddings.embed_text(text)
+
+    @retry(
+        stop=stop_after_attempt(5),
+        wait=wait_exponential(multiplier=1, min=2, max=30),
+        retry=retry_if_exception_type(EmbeddingError),
+    )
+    def _embed_texts_with_retry(self, texts: list[str]) -> list[list[float]]:
+        return self.embeddings.embed_texts(texts)
+
     def embed_text(self, text: str) -> Vector:
         """
         Embed a text and return a vector.
         """
-        from src.lib.embeddings.client import EmbeddingError
-
         try:
-            embeddings = self.embeddings.embed_text(text)
+            embeddings = self._embed_text_with_retry(text)
             return Vector(id=str(uuid.uuid4()), embeddings=embeddings, metadata={})
         except EmbeddingError as e:
             print(f"Embedding failed in adapter, returning empty vector: {e}")
             return Vector(id=str(uuid.uuid4()), embeddings=[], metadata={})
 
+    def embed_texts(self, texts: list[str]) -> list[Vector]:
+        """
+        Embed a list of texts and return a list of vectors.
+        """
+        try:
+            embeddings_list = self._embed_texts_with_retry(texts)
+            return [
+                Vector(id=str(uuid.uuid4()), embeddings=embeddings, metadata={})
+                for embeddings in embeddings_list
+            ]
+        except EmbeddingError as e:
+            print(f"Embedding failed in adapter, returning empty vectors: {e}")
+            return [
+                Vector(id=str(uuid.uuid4()), embeddings=[], metadata={}) for _ in texts
+            ]
+
 
 class VectorStoreAdapter:
     def __init__(self):
@@ -83,14 +120,34 @@ def search_similar_by_ids(
         store: str,
         min_similarity: float,
         limit: int = 10,
-    ) -> list[Vector]:
+    ) -> dict[str, list[Vector]]:
         """
-        Search similar vectors by their IDs.
+        Finds vectors similar to the provided vector IDs within a specified store and brain.
+
+        Parameters:
+            vector_ids (list[str]): IDs of the source vectors to find similarities for.
+            brain_id (str): Identifier of the brain/namespace to search within.
+            store (str): Name of the vector store to query.
+            min_similarity (float): Minimum similarity threshold for returned vectors (inclusive).
+            limit (int): Maximum number of similar vectors to return per source ID.
+
+        Returns:
+            dict[str, list[Vector]]: Mapping from each source vector ID to a list of similar Vectors.
+            Each list contains at most `limit` items, includes only vectors with similarity >= `min_similarity`,
+            and is ordered by descending similarity.
         """
         return self.vector_store.search_similar_by_ids(
             vector_ids, brain_id, store, min_similarity, limit
         )
 
+    def remove_vectors(
+        self, ids: list[str], store: str, brain_id: str = "default"
+    ) -> None:
+        """
+        Remove vectors from the vector store.
+        """
+        return self.vector_store.remove_vectors(ids, store, brain_id)
+
 
 _embeddings_adapter = EmbeddingsAdapter()
 _vector_store_adapter = VectorStoreAdapter()