BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
feat(retrieval): featured input entity into context response
Christianbc8ef1a7a78c
diff --git a/README.md b/README.mdindex 9443651..30201f1 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@<p align="center"><a href="https://discord.gg/VTngQTaeDf"><img src="https://img.shields.io/badge/Discord-Join%20Lumen%20Brain-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"/></a>- <img src="https://img.shields.io/badge/version-2.5.0--dev-blue?style=for-the-badge" alt="Version"/>+ <img src="https://img.shields.io/badge/version-2.6.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>diff --git a/pyproject.toml b/pyproject.tomlindex f443fb6..4ef8dc8 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -1,6 +1,6 @@[project]name = "brainapi2"-version = "2.5.0-dev"+version = "2.6.0-dev"description = "Version 2.x.x of the BrainAPI memory layer."authors = [{name = "Christian",email = "[email protected]"}diff --git a/src/adapters/data.py b/src/adapters/data.pyindex 9748480..efa812d 100644--- a/src/adapters/data.py+++ b/src/adapters/data.py@@ -3,7 +3,7 @@ File: /data.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 12th 2026 8:26:26 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -158,10 +158,10 @@ class DataAdapter:def get_observation_labels(self, brain_id: str = "default") -> list[str]:"""Get all unique observation labels for the specified brain.-+Parameters:brain_id (str): Identifier of the brain to query.-+Returns:list[str]: A list of unique observation label strings for the specified brain."""@@ -226,14 +226,30 @@ class DataAdapter:) -> 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.-+ 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.+ StructuredData: The updated structured data object."""return self.data.update_structured_data(structured_data=structured_data, brain_id=brain_id- )\ No newline at end of file+ )++ def get_last_text_chunks(+ self, brain_id: str = "default", limit: int = 10+ ) -> list[TextChunk]:+ """+ Get the last text chunks from the data client.+ """+ return self.data.get_last_text_chunks(brain_id=brain_id, limit=limit)++ def get_last_structured_data(+ self, brain_id: str = "default", limit: int = 10+ ) -> list[StructuredData]:+ """+ Get the last structured data from the data client.+ """+ return self.data.get_last_structured_data(brain_id=brain_id, limit=limit)diff --git a/src/adapters/interfaces/data.py b/src/adapters/interfaces/data.pyindex d2b261e..615ee01 100644--- a/src/adapters/interfaces/data.py+++ b/src/adapters/interfaces/data.py@@ -3,7 +3,7 @@ File: /data.pyCreated Date: Sunday October 19th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 12th 2026 8:26:26 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -117,14 +117,14 @@ class DataClient(ABC):) -> list[StructuredData]:"""Retrieve structured data entries for a specific brain with optional filtering and pagination.-+Parameters:brain_id (str): Identifier of the brain to query.limit (int): Maximum number of items to return.skip (int): Number of items to skip (offset) for pagination.types (list[str] | None): If provided, restrict results to these structured data types.query_text (str | None): If provided, filter entries that match the text query.-+Returns:list[StructuredData]: List of matching StructuredData objects."""@@ -156,7 +156,7 @@ class DataClient(ABC):) -> list[Observation]:"""Retrieve a filtered, paginated list of observations for a specific brain.-+Parameters:brain_id (str): Identifier of the brain to query.limit (int): Maximum number of observations to return.@@ -164,7 +164,7 @@ class DataClient(ABC):resource_id (str | None): If provided, restrict results to observations for this resource.labels (list[str] | None): If provided, include only observations that have at least one of these labels.query_text (str | None): If provided, include only observations whose text matches this query.-+Returns:observations (list[Observation]): A list of matching Observation objects ordered according to the backend's default sort."""@@ -174,10 +174,10 @@ class DataClient(ABC):def get_observation_labels(self, brain_id: str) -> list[str]:"""Retrieve all unique observation labels for the specified brain.-+Parameters:brain_id (str): Identifier of the brain whose observation labels should be retrieved.-+Returns:list[str]: Unique label strings present in the brain's observations."""@@ -225,10 +225,10 @@ class DataClient(ABC):def get_changelog_types(self, brain_id: str) -> list[str]:"""Return the unique changelog types present for the specified brain.-+Parameters:brain_id (str): Identifier of the brain to query.-+Returns:list[str]: List of unique changelog type names for the brain (order not guaranteed)."""@@ -240,12 +240,28 @@ class DataClient(ABC):) -> StructuredData:"""Update an existing StructuredData record for a specific brain.-+Parameters:structured_data (StructuredData): StructuredData object containing the updated content and identifier of the record to update.brain_id (str): Identifier of the brain that owns the structured data.-+Returns:StructuredData: The stored StructuredData after the update."""- raise NotImplementedError("update_structured_data method not implemented")\ No newline at end of file+ raise NotImplementedError("update_structured_data method not implemented")++ @abstractmethod+ def get_last_text_chunks(self, brain_id: str, limit: int = 10) -> list[TextChunk]:+ """+ Get the last text chunks from the data client.+ """+ raise NotImplementedError("get_last_text_chunks method not implemented")++ @abstractmethod+ def get_last_structured_data(+ self, brain_id: str, limit: int = 10+ ) -> list[StructuredData]:+ """+ Get the last structured data from the data client.+ """+ raise NotImplementedError("get_last_structured_data method not implemented")diff --git a/src/lib/mongo/client.py b/src/lib/mongo/client.pyindex 02cc2e9..f209f8a 100644--- a/src/lib/mongo/client.py+++ b/src/lib/mongo/client.py@@ -3,7 +3,7 @@ File: /client.pyCreated Date: Saturday October 25th 2025Author: Christian Nonis <[email protected]>------Last Modified: Monday January 12th 2026 8:26:26 pm+Last Modified: Thursday January 29th 2026 8:43:59 pmModified By: Christian Nonis <[email protected]>-----"""@@ -402,14 +402,14 @@ class MongoClient(DataClient):) -> StructuredData:"""Update an existing StructuredData record in the specified brain's structured_data collection.-+Parameters:structured_data (StructuredData): The structured data object whose stored record will be updated; its `id` is used to locate the document.brain_id (str): Identifier of the brain (database) containing the structured_data collection to update.-+Returns:StructuredData: The same `structured_data` object that was passed in.-+Notes:The function updates the document matching `structured_data.id` by setting its fields to those from `structured_data`. If no matching document exists, no document is inserted."""@@ -420,5 +420,33 @@ class MongoClient(DataClient):)return structured_data+ def get_last_text_chunks(self, brain_id: str, limit: int = 10) -> list[TextChunk]:+ collection = self.get_collection("text_chunks", database=brain_id)+ results = collection.find().sort("inserted_at", -1).limit(limit)+ return [+ TextChunk(+ id=result["id"],+ text=result["text"],+ metadata=result.get("metadata", None),+ )+ for result in results+ ]++ def get_last_structured_data(+ self, brain_id: str, limit: int = 10+ ) -> list[StructuredData]:+ collection = self.get_collection("structured_data", database=brain_id)+ results = collection.find().sort("inserted_at", -1).limit(limit)+ return [+ StructuredData(+ id=result["id"],+ data=result["data"],+ types=result["types"],+ metadata=result.get("metadata", None),+ inserted_at=result.get("inserted_at", None),+ )+ for result in results+ ]+-_mongo_client = MongoClient()\ No newline at end of file+_mongo_client = MongoClient()diff --git a/src/services/api/constants/requests.py b/src/services/api/constants/requests.pyindex 947d617..704a849 100644--- a/src/services/api/constants/requests.py+++ b/src/services/api/constants/requests.py@@ -283,10 +283,19 @@ class GetContextRequestBody(BaseModel):text: strbrain_id: str = "default"+ historical_limit: int = 10+++class GetContextTriple(BaseModel):+ """Triple for the get context endpoint."""++ identified_entity: str+ triple: Tuple[Node, Predicate, Node, Predicate, Node]class GetContextResponse(BaseModel):"""Response for the get context endpoint."""text_context: str- triples: List[Tuple[Node, Predicate, Node, Predicate, Node]]+ triples: List[GetContextTriple]+ historical_context: List[str] = []diff --git a/src/services/api/controllers/retrieve.py b/src/services/api/controllers/retrieve.pyindex c6dd410..a4d9c8e 100644--- a/src/services/api/controllers/retrieve.py+++ b/src/services/api/controllers/retrieve.py@@ -21,6 +21,7 @@ from src.core.search.relationships import search_relationshipsfrom src.services.api.constants.requests import (GetContextRequestBody,GetContextResponse,+ GetContextTriple,RetrieveRequestResponse,RetrieveNeighborsRequestResponse,RetrievedNeighborNode,@@ -383,10 +384,12 @@ async def get_context(request: GetContextRequestBody) -> GetContextResponse:"""embeddings_map = {}- embeddings_futures = []+ futures = []elements = _entity_extractor.extract_elements(request.text)relationships = []+ historical_context = []+ historical_context_futures = []text_context = ""def _find_vs_nodes(text: str):@@ -402,21 +405,53 @@ async def get_context(request: GetContextRequestBody) -> GetContextResponse:)if len(neighbors) > 0:for n, r, m, r2, b in neighbors:- embeddings_map[text] = (n, r, m, r2, b)- relationships.append((n, r, m, r2, b))+ embeddings_map[text] = (text, n, r, m, r2, b)+ relationships.append((text, n, r, m, r2, b))text_context += ("\n".join(f"{item.name}: {item.description}" for item in (n, r, m, r2, b))+ "\n")- return (n, r, m, r2, b)+ return GetContextTriple(identified_entity=text, triple=(n, r, m, r2, b))return ()- embeddings_futures.append(asyncio.to_thread(_find_vs_nodes, request.text))+ async def _get_historical_context():+ nonlocal historical_context+ _futures = []+ _futures.append(+ asyncio.to_thread(+ data_adapter.get_last_text_chunks,+ brain_id=request.brain_id,+ limit=request.historical_limit,+ )+ )+ _futures.append(+ asyncio.to_thread(+ data_adapter.get_last_structured_data,+ brain_id=request.brain_id,+ limit=request.historical_limit,+ )+ )+ historical_context = await asyncio.gather(*_futures)+ historical_context = [text_chunk.text for text_chunk in historical_context]+ return historical_context++ futures.append(asyncio.to_thread(_find_vs_nodes, request.text))+ historical_context_futures.append(asyncio.to_thread(_get_historical_context))for chunk in elements.tokens:- embeddings_futures.append(asyncio.to_thread(_find_vs_nodes, chunk["text"]))+ futures.append(asyncio.to_thread(_find_vs_nodes, chunk["text"]))- await asyncio.gather(*embeddings_futures)+ await asyncio.gather(*futures)- return GetContextResponse(text_context=text_context, triples=relationships)+ return GetContextResponse(+ text_context=text_context,+ triples=[+ GetContextTriple(+ identified_entity=t[0],+ triple=(t[1], t[2], t[3], t[4], t[5]),+ )+ for t in relationships+ ],+ historical_context=historical_context,+ )