Transformation Examples

Examples of transforming documents with Graphora

Transformation Examples

This page provides practical examples of transforming documents using the Graphora client library.

Basic Document Transformation

The following example demonstrates how to transform a set of documents using a registered ontology:

import os
from graphora import GraphoraClient

client = GraphoraClient(
    auth_token=os.environ["GRAPHORA_AUTH_TOKEN"],
)

# Use a previously registered ontology
ontology_id = "ont_123456789"

# Prepare a list of document files to transform
document_paths = [
    "document1.pdf",
    "document2.docx",
    "document3.txt"
]

# Transform the documents
response = client.transform(ontology_id, document_paths)
print(f"Transformation started with ID: {response.id}")

# Check the status of the transformation
status = client.get_transform_status(response.id)
print(f"Transformation status: {status.status}")
print(f"Progress: {status.progress:.2%}")

Transforming Documents with Metadata

You can also provide metadata for each document to enrich the transformation process:

import os
from graphora import GraphoraClient, DocumentMetadata, DocumentType

client = GraphoraClient(
    auth_token=os.environ["GRAPHORA_AUTH_TOKEN"],
)

# Use a previously registered ontology
ontology_id = "ont_123456789"

# Prepare document paths and metadata
document_paths = [
    "document1.pdf",
    "document2.docx"
]

metadata = [
    DocumentMetadata(
        source="Annual Report 2024",
        document_type=DocumentType.PDF,
        tags=["finance", "annual", "report"],
        custom_metadata={
            "department": "Finance",
            "confidentiality": "Internal"
        }
    ),
    DocumentMetadata(
        source="Product Specifications",
        document_type=DocumentType.DOCX,
        tags=["product", "specifications", "technical"],
        custom_metadata={
            "department": "Engineering",
            "product_id": "PRD-2024-001"
        }
    )
]

# Transform the documents with metadata
response = client.transform(ontology_id, document_paths, metadata=metadata)
print(f"Transformation started with ID: {response.id}")

Monitoring Transformation Progress

For long-running transformations, you can monitor the progress:

import os
import time
from graphora import GraphoraClient, TransformRunStatus

client = GraphoraClient(
    auth_token=os.environ["GRAPHORA_AUTH_TOKEN"],
)

# Start a transformation (assuming you have already set up the ontology and documents)
transform_response = client.transform(ontology_id, document_paths)
transform_id = transform_response.id

# Monitor the transformation progress
completed = False
while not completed:
    status = client.get_transform_status(transform_id)
    print(
        f"{status.current_stage} | {status.overall_status} | "
        f"{status.percentage_complete:.1f}%"
    )

    if status.overall_status in (
        TransformRunStatus.COMPLETED,
        TransformRunStatus.FAILED,
    ):
        completed = True
        if status.overall_status == TransformRunStatus.COMPLETED:
            print("Transformation completed successfully!")
        else:
            failure = status.error_summary.error_message if status.error_summary else "Unknown error"
            print(f"Transformation failed: {failure}")
    else:
        # Wait for 5 seconds before checking again
        time.sleep(5)

# If transformation was successful, you can proceed to merging
if status.status == "COMPLETED":
    print("Ready to merge the transformed data into a graph")

Using the Wait Helper Method

You can also use the built-in wait method for convenience:

import os
from graphora import GraphoraClient

client = GraphoraClient(
    auth_token=os.environ["GRAPHORA_AUTH_TOKEN"],
)

# Start a transformation
transform_response = client.transform(ontology_id, document_paths)
transform_id = transform_response.id

# Wait for completion (with timeout)
try:
    final_status = client.wait_for_transform(transform_id, timeout=300)  # 5 minutes
    print(f"Transformation completed with status: {final_status.overall_status}")
except Exception as e:
    print(f"Transformation failed or timed out: {e}")

Handling Different Document Types

Graphora supports various document types. Here’s how to transform a mix of document types:

import os
from graphora import GraphoraClient

client = GraphoraClient(
    auth_token=os.environ["GRAPHORA_AUTH_TOKEN"],
)

# Use a previously registered ontology
ontology_id = "ont_123456789"

# Prepare a list of different document types
documents = [
    "text_document.txt",      # Plain text
    "word_document.docx",     # Microsoft Word
    "pdf_document.pdf",       # PDF
    "data.csv",               # CSV
    "config.json",            # JSON
    "schema.yaml"             # YAML
]

# Transform the documents
response = client.transform(ontology_id, documents)
print(f"Transformation started with ID: {response.id}")

These examples demonstrate the basic operations for transforming documents with the Graphora client library. For more detailed information about transformation concepts and options, see the Transformation Concepts page.