folders.mdx

title	Folder Management
description	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 either the folder’s UUID or its name. Use whichever identifier you already have—Morphik resolves it automatically.

Creating and Accessing Folders

```python from morphik import Morphik

db = Morphik()

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

# Access an existing folder by name or UUID
folder = db.get_folder("marketing_docs")
folder_by_id = db.get_folder(folder.id)
```

```python from morphik import AsyncMorphik

async with AsyncMorphik() as db:
    # Create a new folder
    folder = db.create_folder("marketing_docs")
    
    # Access an existing folder by name or UUID
    folder = await db.get_folder("marketing_docs")
    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.

```python # 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?")
```

```python # 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?")
```

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
• create_graph - Create a knowledge graph from documents in this folder
• update_graph - Update a knowledge graph with new documents from this folder
• 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 name or UUID.

```python from morphik import Morphik

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

document_id = "doc_123"

# Add an existing document to the folder (name or UUID works)
db.add_document_to_folder(folder.id, document_id)
db.add_document_to_folder("marketing_docs", 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)
```

```python 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("marketing_docs", 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:

```python 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)
```

```python 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:

```python 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?")

# Create project-specific knowledge graphs
project_a.create_graph("project_a_graph")
project_b.create_graph("project_b_graph")
```

```python 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?")
    
    # Create project-specific knowledge graphs
    await project_a.create_graph("project_a_graph")
    await project_b.create_graph("project_b_graph")
```

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:

```python # 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")
```

```python # 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.