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): retrieve text chunks

Christianea4205f52519
diff --git a/src/adapters/data.py b/src/adapters/data.py
index efa812d..ef9d5ae 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: Thursday January 29th 2026 8:43:59 pm
+Last Modified: Thursday February 19th 2026 7:45:12 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -59,6 +59,20 @@ class DataAdapter:
ids=ids, with_observations=with_observations, brain_id=brain_id
)
+ def get_text_chunks(
+ self,
+ brain_id: str = "default",
+ limit: int = 10,
+ skip: int = 0,
+ query_text: str = None,
+ ) -> Tuple[List[TextChunk], int]:
+ """
+ Get text chunks with pagination and a query text.
+ """
+ return self.data.get_text_chunks(
+ brain_id=brain_id, limit=limit, skip=skip, query_text=query_text
+ )
+
def save_structured_data(
self, structured_data: StructuredData, brain_id: str = "default"
) -> StructuredData:
@@ -110,7 +124,7 @@ class DataAdapter:
skip: int = 0,
types: list[str] = None,
query_text: str = None,
- ) -> list[StructuredData]:
+ ) -> Tuple[list[StructuredData], int]:
"""
Get a list of structured data.
"""
diff --git a/src/adapters/interfaces/data.py b/src/adapters/interfaces/data.py
index 615ee01..e0db157 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: Thursday January 29th 2026 8:43:59 pm
+Last Modified: Thursday February 19th 2026 7:45:12 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -62,6 +62,15 @@ class DataClient(ABC):
"""
raise NotImplementedError("get_by_ids method not implemented")
+ @abstractmethod
+ def get_text_chunks(
+ self, brain_id: str, limit: int = 10, skip: int = 0, query_text: str = None
+ ) -> Tuple[List[TextChunk], int]:
+ """
+ Get text chunks with pagination and a query text.
+ """
+ raise NotImplementedError("get_text_chunks method not implemented")
+
@abstractmethod
def save_structured_data(
self, structured_data: StructuredData, brain_id: str
@@ -114,7 +123,7 @@ class DataClient(ABC):
skip: int = 0,
types: list[str] = None,
query_text: str = None,
- ) -> list[StructuredData]:
+ ) -> Tuple[list[StructuredData], int]:
"""
Retrieve structured data entries for a specific brain with optional filtering and pagination.
@@ -126,7 +135,7 @@ class DataClient(ABC):
query_text (str | None): If provided, filter entries that match the text query.
Returns:
- list[StructuredData]: List of matching StructuredData objects.
+ Tuple[list[StructuredData], int]: Tuple containing the list of matching StructuredData objects and the total count of matching objects.
"""
raise NotImplementedError("get_structured_data_list method not implemented")
diff --git a/src/lib/mongo/client.py b/src/lib/mongo/client.py
index f209f8a..413cac5 100644
--- a/src/lib/mongo/client.py
+++ b/src/lib/mongo/client.py
@@ -3,12 +3,12 @@ File: /client.py
Created Date: Saturday October 25th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Thursday January 29th 2026 8:43:59 pm
+Last Modified: Thursday February 19th 2026 7:45:12 pm
Modified By: Christian Nonis <[email protected]>
-----
"""
-from typing import List
+from typing import List, Tuple
from pymongo import MongoClient as PyMongoClient
from pymongo.database import Database
from pymongo.collection import Collection
@@ -188,7 +188,7 @@ class MongoClient(DataClient):
skip: int = 0,
types: list[str] = None,
query_text: str = None,
- ) -> list[StructuredData]:
+ ) -> Tuple[list[StructuredData], int]:
collection = self.get_collection("structured_data", database=brain_id)
query = {}
if types:
@@ -202,16 +202,39 @@ class MongoClient(DataClient):
]
results = collection.find(query).skip(skip).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
- ]
+ total = collection.count_documents(query)
+ 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
+ ],
+ total,
+ )
+
+ def get_text_chunks(
+ self, brain_id: str, limit: int = 10, skip: int = 0, query_text: str = None
+ ) -> Tuple[List[TextChunk], int]:
+ collection = self.get_collection("structured_data", database=brain_id)
+ query = {}
+
+ if query_text:
+ query["$or"] = [
+ {"text": {"$regex": query_text, "$options": "i"}},
+ {"metadata": {"$regex": query_text, "$options": "i"}},
+ ]
+
+ results = collection.find(query).skip(skip).limit(limit)
+ total = collection.count_documents(query)
+ return (
+ [TextChunk(**result) for result in results],
+ total,
+ )
def get_structured_data_types(self, brain_id: str) -> list[str]:
collection = self.get_collection("structured_data", database=brain_id)
diff --git a/src/services/api/controllers/structured_data.py b/src/services/api/controllers/structured_data.py
index 5c65913..def90f0 100644
--- a/src/services/api/controllers/structured_data.py
+++ b/src/services/api/controllers/structured_data.py
@@ -3,8 +3,8 @@ File: /structured_data.py
Created Date: Saturday December 6th 2025
Author: Christian Nonis <[email protected]>
-----
-Last Modified: Saturday December 13th 2025
-Modified By: the developer formerly known as Christian Nonis at <[email protected]>
+Last Modified: Sunday December 21st 2025 11:57:01 am
+Modified By: Christian Nonis <[email protected]>
-----
"""
@@ -14,24 +14,24 @@ from fastapi import HTTPException
from starlette.responses import JSONResponse
from src.services.data.main import data_adapter
-async def get_structured_data_by_id(
- id: str, brain_id: str = "default"
-):
+
+async def get_structured_data_by_id(id: str, brain_id: str = "default"):
"""
Get structured data by ID.
"""
+
def _get_data():
data = data_adapter.get_structured_data_by_id(id, brain_id)
if not data:
raise HTTPException(status_code=404, detail="Structured data not found")
return data
-
+
result = await asyncio.to_thread(_get_data)
-
+
return JSONResponse(
content={
"message": "Structured data retrieved successfully",
- "data": result.model_dump(mode="json")
+ "data": result.model_dump(mode="json"),
}
)
@@ -46,34 +46,54 @@ async def get_structured_data_list(
"""
Get a list of structured data.
"""
+
def _get_list():
- return data_adapter.get_structured_data_list(brain_id, limit, skip, types, query_text)
-
- results = await asyncio.to_thread(_get_list)
-
+ return data_adapter.get_structured_data_list(
+ brain_id, limit, skip, types, query_text
+ )
+
+ results, total = await asyncio.to_thread(_get_list)
+
return JSONResponse(
content={
"message": "Structured data list retrieved successfully",
"data": [r.model_dump(mode="json") for r in results],
- "count": len(results)
+ "count": len(results),
+ "total": total,
}
)
+
async def get_structured_data_types(
brain_id: str = "default",
):
"""
Get all unique types from structured data.
"""
+
def _get_types():
return data_adapter.get_structured_data_types(brain_id)
-
+
results = await asyncio.to_thread(_get_types)
-
+
return JSONResponse(
content={
"message": "Structured data types retrieved successfully",
"types": results,
- "count": len(results)
+ "count": len(results),
}
- )
\ No newline at end of file
+ )
+
+
+async def get_text_chunks(
+ brain_id: str = "default",
+ limit: int = 10,
+ skip: int = 0,
+ query_text: Optional[str] = None,
+):
+ """
+ Get text chunks by a query text.
+ """
+ return await asyncio.to_thread(
+ data_adapter.get_text_chunks, brain_id, limit, skip, query_text
+ )
diff --git a/src/services/api/routes/retrieve.py b/src/services/api/routes/retrieve.py
index 4ce5052..3f2e91d 100644
--- a/src/services/api/routes/retrieve.py
+++ b/src/services/api/routes/retrieve.py
@@ -10,6 +10,7 @@ Modified By: Christian Nonis <[email protected]>
from typing import List, Literal, Optional
from fastapi import APIRouter, Body, Query
+from fastapi.responses import JSONResponse
from src.services.api.constants.requests import (
GetContextRequestBody,
GetContextResponse,
@@ -33,6 +34,7 @@ from src.services.api.controllers.structured_data import (
get_structured_data_by_id as get_structured_data_by_id_controller,
get_structured_data_list as get_structured_data_list_controller,
get_structured_data_types as get_structured_data_types_controller,
+ get_text_chunks as get_text_chunks_controller,
)
from src.services.api.controllers.observations import (
get_observation_by_id as get_observation_by_id_controller,
@@ -258,6 +260,27 @@ async def get_structured_data_list(
)
+@retrieve_router.get(path="/text-chunks")
+async def get_text_chunks(
+ brain_id: str = "default",
+ limit: int = 10,
+ skip: int = 0,
+ query_text: Optional[str] = None,
+):
+ """
+ Get text chunks by a query text.
+ """
+ results, total = await get_text_chunks_controller(brain_id, limit, skip, query_text)
+
+ return JSONResponse(
+ content={
+ "message": "Text chunks retrieved successfully",
+ "data": results,
+ "total": total,
+ }
+ )
+
+
@retrieve_router.get(path="/observations/labels")
async def get_observation_labels(
brain_id: str = "default",