Folder Management

Organize and isolate data into logical folder groups in Morphik

Overview

Folders in Morphik provide a way to organize documents into logical groups. This is particularly useful for multi-project environments where you want to maintain separation between different contexts. Documents within a folder are isolated from those in other folders, allowing for clean organization and data separation.

ℹ️ All folder APIs accept folder UUIDs, names, or canonical paths (e.g., "/projects/alpha/specs"). Folder objects expose full_path, parent_id, depth, and child_count; documents expose folder_path to mirror server responses.

Creating and Accessing Folders

Sync

from morphik import Morphik

db = Morphik()

# Create a new folder
folder = db.create_folder("marketing_docs")

# Create a nested folder (parents created automatically)
nested = db.create_folder(full_path="/projects/alpha/specs")

# Access an existing folder by name/path or UUID
folder = db.get_folder("/projects/alpha")
folder_by_id = db.get_folder(folder.id)

Async

from morphik import AsyncMorphik

async with AsyncMorphik() as db:
    # Create a new folder
    folder = await db.create_folder("marketing_docs")

    nested = await db.create_folder(full_path="/projects/alpha/specs")
    
    # Access an existing folder by name/path or UUID
    folder = await db.get_folder("/projects/alpha")
    folder_by_id = await db.get_folder(folder.id)

Operations Within a Folder

Once you have a folder object, all operations performed on it are scoped to that folder. Documents created, retrieved, or manipulated will be contained within this folder’s scope.

Sync

# Get a folder
folder = db.get_folder("marketing_docs")

# Ingest a document into this folder
doc = folder.ingest_text("New marketing strategy for Q3", 
                       filename="strategy_q3.txt",
                       metadata={"department": "marketing", "quarter": "Q3"})

# Retrieve documents only from this folder
marketing_docs = folder.list_documents()

# Search documents only within this folder
results = folder.retrieve_chunks("marketing strategy")

# Query within the folder context
response = folder.query("What is our Q3 marketing strategy?")

Async

# Get a folder
folder = db.get_folder("marketing_docs")

# Ingest a document into this folder
doc = await folder.ingest_text("New marketing strategy for Q3", 
                             filename="strategy_q3.txt",
                             metadata={"department": "marketing", "quarter": "Q3"})

# Retrieve documents only from this folder
marketing_docs = await folder.list_documents()

# Search documents only within this folder
results = await folder.retrieve_chunks("marketing strategy")

# Query within the folder context
response = await folder.query("What is our Q3 marketing strategy?")

Nested Folders and Scope Depth

Folders can be nested arbitrarily. Use canonical paths (leading slash optional) to address them, and include descendant folders in retrieval/listing by setting folder_depth:

folder = db.create_folder(full_path="/projects/alpha/specs")

# Query across /projects/alpha and all children
chunks = db.retrieve_chunks(
    query="design notes",
    folder_name="/projects/alpha",
    folder_depth=-1,  # -1: all descendants, 0/None: exact only, n>0: include up to n levels
)

Folder-scoped helpers inherit the path automatically, so folder.retrieve_chunks(..., folder_depth=-1) will include its children.

Expanding Scope with Additional Folders

Folder-scoped retrieval/list/query helpers accept additional_folders to include extra folders in the same request:

folder = db.get_folder("/projects/alpha")

# Search across /projects/alpha plus shared archives
results = folder.retrieve_chunks(
    "design notes",
    additional_folders=["/shared", "/archive"],
)

Folder Methods

All the core document operations available on the main Morphik client are also available on folder objects, but they are automatically scoped to the specific folder:

• ingest_text - Ingest text content into this folder
• ingest_file - Ingest a file into this folder
• ingest_files - Ingest multiple files into this folder
• ingest_directory - Ingest all files from a directory into this folder
• retrieve_chunks - Retrieve chunks matching a query from this folder (supports reverse image search)
• retrieve_docs - Retrieve documents matching a query from this folder
• query - Generate a completion using context from this folder (supports llm_config parameter for custom LLM configuration)
• list_documents - List all documents in this folder
• batch_get_documents - Get multiple documents by their IDs from this folder
• batch_get_chunks - Get specific chunks by source from this folder
• get_info - Fetch the latest folder metadata from the API
• get_summary - Fetch the latest folder summary
• upsert_summary - Create or update the folder summary
• delete_document_by_filename - Delete a document by filename from this folder

Managing Existing Documents and Folders

You can move previously ingested documents into a folder, remove them, or delete the entire folder. The SDK methods accept a folder UUID, name, or canonical path.

Sync

from morphik import Morphik

db = Morphik()
folder = db.get_folder("marketing_docs")

document_id = "doc_123"

# Add an existing document to the folder (name/path or UUID works)
db.add_document_to_folder(folder.id, document_id)
db.add_document_to_folder("/projects/alpha/specs", document_id)

# Remove the document from the folder
db.remove_document_from_folder("marketing_docs", document_id)

# Delete the folder (also removes its documents)
db.delete_folder(folder.id)

Async

from morphik import AsyncMorphik

async with AsyncMorphik() as db:
    folder = await db.get_folder("marketing_docs")
    document_id = "doc_123"

    await db.add_document_to_folder(folder.id, document_id)
    await db.add_document_to_folder("/projects/alpha/specs", document_id)

    await db.remove_document_from_folder("marketing_docs", document_id)

    await db.delete_folder(folder.id)

Using Custom LLM Configuration with Folders

You can pass a custom LLM configuration when querying within a folder:

Sync

from morphik import Morphik

db = Morphik()
folder = db.get_folder("research")

# Use a specific model for this query
response = folder.query(
    "Summarize the latest findings",
    llm_config={
        "model": "claude-3-opus-20240229",
        "temperature": 0.5
    }
)

print(response.completion)

Async

from morphik import AsyncMorphik

async with AsyncMorphik() as db:
    folder = db.get_folder("research")
    
    # Use a specific model for this query
    response = await folder.query(
        "Summarize the latest findings",
        llm_config={
            "model": "claude-3-opus-20240229",
            "temperature": 0.5
        }
    )
    
    print(response.completion)

Example: Project Document Management

A common use case for folders is separating different projects. Here’s an example of how to organize project documentation:

Sync

from morphik import Morphik
from pathlib import Path

db = Morphik()

# Create folders for different projects
project_a = db.create_folder("project_a")
project_b = db.create_folder("project_b")

# Ingest project documentation into respective folders
project_a.ingest_directory(Path("/path/to/project_a_docs"), 
                          recursive=True, 
                          metadata={"project": "Project A"})

project_b.ingest_directory(Path("/path/to/project_b_docs"), 
                          recursive=True, 
                          metadata={"project": "Project B"})

# Query is scoped to just Project A documents
project_a_response = project_a.query("What are the key milestones for this project?")

# Query is scoped to just Project B documents
project_b_response = project_b.query("What are the technical requirements?")

Async

from morphik import AsyncMorphik
from pathlib import Path

async with AsyncMorphik() as db:
    # Create folders for different projects
    project_a = db.create_folder("project_a")
    project_b = db.create_folder("project_b")
    
    # Ingest project documentation into respective folders
    await project_a.ingest_directory(Path("/path/to/project_a_docs"), 
                                  recursive=True, 
                                  metadata={"project": "Project A"})
    
    await project_b.ingest_directory(Path("/path/to/project_b_docs"), 
                                  recursive=True, 
                                  metadata={"project": "Project B"})
    
    # Query is scoped to just Project A documents
    project_a_response = await project_a.query("What are the key milestones for this project?")
    
    # Query is scoped to just Project B documents
    project_b_response = await project_b.query("What are the technical requirements?")
    

Accessing a Folder’s User Scope

You can further scope operations within a folder to a specific user by using the signin method on the folder object:

Sync

# Get a folder
project_folder = db.get_folder("project_x")

# Create a user scope within this folder
user_in_project = project_folder.signin("user_123")

# This document is accessible only to user_123 within project_x
doc = user_in_project.ingest_text("User-specific project notes")

Async

# Get a folder
project_folder = db.get_folder("project_x")

# Create a user scope within this folder
user_in_project = project_folder.signin("user_123")

# This document is accessible only to user_123 within project_x
doc = await user_in_project.ingest_text("User-specific project notes")

See User Management for more details on working with user scopes.