Skip to content

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.

feat(retrieval): featured input entity into context response

Christianbc8ef1a7a78c
diff --git a/README.md b/README.md
index 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.toml
index 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.py
index 9748480..efa812d 100644
--- a/src/adapters/data.py
+++ b/src/adapters/data.py
@@ -3,7 +3,7 @@ File: /data.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Monday January 12th 2026 8:26:26 pm
+Last Modified: Thursday January 29th 2026 8:43:59 pm
Modified 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.py
index d2b261e..615ee01 100644
--- a/src/adapters/interfaces/data.py
+++ b/src/adapters/interfaces/data.py
@@ -3,7 +3,7 @@ File: /data.py
Created Date: Sunday October 19th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Monday January 12th 2026 8:26:26 pm
+Last Modified: Thursday January 29th 2026 8:43:59 pm
Modified 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.py
index 02cc2e9..f209f8a 100644
--- a/src/lib/mongo/client.py
+++ b/src/lib/mongo/client.py
@@ -3,7 +3,7 @@ File: /client.py
Created Date: Saturday October 25th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Monday January 12th 2026 8:26:26 pm
+Last Modified: Thursday January 29th 2026 8:43:59 pm
Modified 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.py
index 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: str
brain_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.py
index 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_relationships
from 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,
+ )