Merge branch 'main' into 00bad53466

Author: Adityav369

scripts/sanity_test.sh

@@ -7,13 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2025-02-09
+
 ### Added
-- `retrieve_chunks`: New `output_format` parameter (`"base64"` | `"url"`). When set to `"url"`, image chunks are returned as presigned URLs in `content` and `download_url` is populated. Default remains `"base64"` for backward compatibility.
-- `retrieve_chunks`: `padding` parameter surfaced consistently in SDK convenience methods (folder/user scopes) to fetch neighboring page chunks for ColPali.
-- `batch_get_chunks`: `output_format` parameter mirrors retrieval APIs so batch lookups can request presigned URLs for image chunks.
+- Nested folders: folder models now expose `full_path`, `parent_id`, `depth`, and `child_count`; documents/graphs expose `folder_path`; folder helpers send canonical paths and `create_folder` accepts nested `full_path`.
+- Folder scope depth controls: `folder_depth` is available on retrieve/query/list/search helpers (including grouped retrieval) and graph accessors to optionally include descendant folders.
+- Retrieval options: `retrieve_chunks` and `retrieve_chunks_grouped` expose `output_format` (`"base64"` | `"url"` | `"text"`) and `padding` everywhere; `batch_get_chunks` mirrors `output_format`.
 
 ### Changed
-- Image handling in SDK parsing: When `output_format="url"`, `FinalChunkResult.content` is a string URL for image chunks; when `"base64"`, the SDK attempts to decode to `PIL.Image` (unchanged behavior).
+- Image parsing: when `output_format="url"`, `FinalChunkResult.content` remains a URL string; when `"base64"`, the SDK attempts to decode to `PIL.Image` (unchanged behavior).
+- Folder scoping now prefers canonical paths across folder/user scoped clients and graph/document helpers.
 
 ### Notes
 - Server now hot-swaps base64/data-URI image chunks into binary storage when necessary and returns a presigned URL. In local dev, URLs may be `file://...` paths; in S3-backed deployments, HTTPS presigned URLs.

sdks/python/CHANGELOG.md

@@ -77,6 +77,19 @@ response = db.query(
 print(response.completion)
 ```
 
+### Nested Folders & Folder Depth
+
+```python
+# Create a nested folder (parents are auto-created server-side)
+folder = db.create_folder(full_path="/projects/alpha/specs", description="Specs folder")
+
+# Scope queries to a path and include descendants with folder_depth=-1
+chunks = folder.retrieve_chunks(query="design notes", folder_depth=-1)
+docs = db.list_documents(folder_name="/projects/alpha", folder_depth=-1)
+```
+
+`Folder.full_path` is exposed on folder objects, and `Document.folder_path` / `Graph.folder_path` mirror server responses for tracing scope.
+
 ### Asynchronous Usage
 
 ```python

sdks/python/README.md

@@ -13,4 +13,4 @@
     "DocumentQueryResponse",
 ]
 
-__version__ = "1.0.5"
+__version__ = "1.1.1"

sdks/python/morphik/__init__.py

@@ -295,6 +295,7 @@ def _prepare_query_request(
         include_paths: bool,
         prompt_overrides: Optional[Union[QueryPromptOverrides, Dict[str, Any]]],
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         use_reranking: Optional[bool] = None,  # Add missing parameter
         chat_id: Optional[str] = None,
@@ -323,6 +324,8 @@ def _prepare_query_request(
         }
         if folder_name:
             payload["folder_name"] = folder_name
+        if folder_depth is not None:
+            payload["folder_depth"] = folder_depth
         if end_user_id:
             payload["end_user_id"] = end_user_id
         if chat_id:
@@ -356,6 +359,7 @@ def _prepare_retrieve_chunks_request(
         min_score: float,
         use_colpali: bool,
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         padding: int = 0,
         output_format: Optional[str] = None,
@@ -387,6 +391,8 @@ def _prepare_retrieve_chunks_request(
             request["query"] = query
         if folder_name:
             request["folder_name"] = folder_name
+        if folder_depth is not None:
+            request["folder_depth"] = folder_depth
         if end_user_id:
             request["end_user_id"] = end_user_id
         if padding > 0:
@@ -403,6 +409,7 @@ def _prepare_retrieve_docs_request(
         min_score: float,
         use_colpali: bool,
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         use_reranking: Optional[bool] = None,  # Add missing parameter
     ) -> Dict[str, Any]:
@@ -417,6 +424,8 @@ def _prepare_retrieve_docs_request(
         }
         if folder_name:
             request["folder_name"] = folder_name
+        if folder_depth is not None:
+            request["folder_depth"] = folder_depth
         if end_user_id:
             request["end_user_id"] = end_user_id
         return request
@@ -427,6 +436,7 @@ def _prepare_list_documents_request(
         limit: int,
         filters: Optional[Dict[str, Any]],
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         include_total_count: bool,
         include_status_counts: bool,
@@ -439,6 +449,8 @@ def _prepare_list_documents_request(
         params = {}
         if folder_name:
             params["folder_name"] = folder_name
+        if folder_depth is not None:
+            params["folder_depth"] = folder_depth
         if end_user_id:
             params["end_user_id"] = end_user_id
 

sdks/python/morphik/_internal.py

@@ -153,6 +153,7 @@ def _scoped_retrieve_chunks(
         min_score: float,
         use_colpali: bool,
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         padding: int,
         output_format: Optional[str] = None,
@@ -165,6 +166,7 @@ def _scoped_retrieve_chunks(
             min_score,
             use_colpali,
             folder_name,
+            folder_depth,
             end_user_id,
             padding,
             output_format,
@@ -187,6 +189,7 @@ def _scoped_retrieve_docs(
         min_score: float,
         use_colpali: bool,
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         use_reranking: Optional[bool],
     ) -> List[Any]:
@@ -197,6 +200,7 @@ def _scoped_retrieve_docs(
             min_score,
             use_colpali,
             folder_name,
+            folder_depth,
             end_user_id,
             use_reranking,
         )
@@ -223,6 +227,7 @@ def _scoped_query(
         include_paths: bool,
         prompt_overrides: Optional[Dict[str, Any]],
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         use_reranking: Optional[bool],
         chat_id: Optional[str],
@@ -243,6 +248,7 @@ def _scoped_query(
             include_paths,
             prompt_overrides,
             folder_name,
+            folder_depth,
             end_user_id,
             use_reranking,
             chat_id,
@@ -275,6 +281,7 @@ def _scoped_list_documents(
         limit: int,
         filters: Optional[Dict[str, Any]],
         folder_name: Optional[Union[str, List[str]]],
+        folder_depth: Optional[int],
         end_user_id: Optional[str],
         include_total_count: bool,
         include_status_counts: bool,
@@ -288,6 +295,7 @@ def _scoped_list_documents(
             limit,
             filters,
             folder_name,
+            folder_depth,
             end_user_id,
             include_total_count,
             include_status_counts,