graphora 0.4.1

Python client for the Graphora API

Graphora Python Client

Official Python client for the Graphora API

A Python client for interacting with the Graphora API. This library provides a simple and intuitive interface for working with Graphora's graph-based data processing capabilities. Graphora is a Text to Knowledge Graphs platform that helps you transform unstructured text into powerful knowledge graphs.

Features

• Complete API Coverage: Access all Graphora API endpoints
• Type Safety: Fully typed with Pydantic models
• User Context: All API calls are automatically scoped to the specified user
• Async Support: Efficient handling of long-running operations
• Minimal Dependencies: Lightweight with few external dependencies
• Comprehensive Documentation: Detailed guides and API references

Installation

pip install graphora

Quick Start

import os
from graphora import GraphoraClient

# Initialize client with a Clerk-issued bearer token. The base URL defaults to
# GRAPHORA_API_URL (or https://api.graphora.io if unset), so you can omit it
# for most cases.
client = GraphoraClient(
    auth_token=os.environ["GRAPHORA_AUTH_TOKEN"],
)

# Upload an ontology
with open("ontology.yaml", "r") as f:
    ontology_yaml = f.read()

ontology = client.register_ontology(ontology_yaml)

# Upload documents and wait for processing
transform = client.transform(
    ontology_id=ontology.id,
    files=["document1.pdf", "document2.txt"],
)
final_status = client.wait_for_transform(transform.id)
print("Transform status:", final_status.overall_status)

# Inspect the resulting graph
graph = client.get_transformed_graph(transform_id=transform.id)
print(
    f"Nodes: {graph.total_nodes or len(graph.nodes)} | "
    f"Edges: {graph.total_edges or len(graph.edges)}"
)

# Start merging the processed data
merge = client.start_merge(
    session_id=ontology.id,
    transform_id=transform.id,
)

Environment Variables

The following environment variables can be used to configure the client:

• GRAPHORA_AUTH_TOKEN: Clerk-issued bearer token (preferred)
• GRAPHORA_API_KEY: Legacy API key support (deprecated; replaced by bearer tokens)
• GRAPHORA_USER_ID: Optional user ID for client-side bookkeeping
• GRAPHORA_API_URL: Custom API URL (optional). Defaults to https://api.graphora.io if unset.

Core API Methods

Ontology Management

• register_ontology(ontology_yaml) - Register and validate an ontology
• get_ontology(ontology_id) - Retrieve an ontology by ID

Document Processing

• transform(ontology_id, files, metadata=None) - Upload documents for processing
• get_transform_status(transform_id) - Check transformation status
• wait_for_transform(transform_id) - Wait for transformation to complete
• cleanup_transform(transform_id) - Clean up transformation data

Graph Operations

• get_transformed_graph(transform_id) - Retrieve graph data
• update_transform_graph(transform_id, changes) - Save graph modifications

Merge Operations

• start_merge(session_id, transform_id) - Start merging processed data
• get_merge_status(merge_id) - Check merge status
• get_conflicts(merge_id) - Get conflicts requiring resolution
• resolve_conflict(merge_id, conflict_id, ...) - Resolve specific conflicts
• get_merge_statistics(merge_id) - Get merge statistics
• get_merged_graph(merge_id, transform_id) - Retrieve merged graph

Documentation

For detailed documentation, see the docs directory or visit our official documentation website.

Examples

Check out the examples directory for sample code demonstrating various use cases:

• manage_ontology.py - Ontology creation and management
• upload_and_transform.py - Document upload and transformation
• modify_graph.py - Graph data manipulation
• merge_graph_data.py - Merging and conflict resolution

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Before Contributing

1. Read the Code of Conduct
2. Sign the Contributor License Agreement
3. Check out good first issues

Documentation

• Contributing Guide - How to contribute
• Security Policy - How to report security issues
• Support - How to get help
• Trademark Policy - Trademark usage guidelines
• Examples - Code examples

Related Repositories

• Frontend: graphora/graphora-fe
• Backend API: graphora/graphora-api

License

This project is licensed under the MIT License.

See LICENSE for full terms.

Note: While this client library is MIT licensed, the Graphora backend services are AGPL v3 licensed. For commercial use of the backend, contact [e-mail]

Community

• GitHub Discussions: Ask questions, share ideas
• Discord: Coming soon
• Twitter: Coming soon

Security

Please report security vulnerabilities to [e-mail]

See SECURITY.md for details.

---

Made with ❤️ by Arivan Labs