graphora 0.4.3

Python client for the Graphora API

Graphora Python Client

Official Python client and CLI 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

• CLI Tool: Extract knowledge graphs from the command line
• Complete API Coverage: Access all Graphora API endpoints
• Type Safety: Fully typed with Pydantic models
• Dual Mode: Run locally (embedded) or via remote API
• Async Support: Efficient handling of long-running operations
• Minimal Dependencies: Lightweight with few external dependencies

Installation

# Basic client library
pip install graphora

# With CLI support
pip install graphora[cli]

Quick Start

CLI (Fastest - 3 commands)

# 1. Install
pip install graphora[cli]

# 2. Configure (downloads graphora-api automatically)
graphora config init --api-key "your-gemini-api-key"

# 3. Extract!
graphora extract document.pdf -o graph.json

That's it! The CLI automatically downloads and manages graphora-api for you.

Python Client

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,
)

CLI Usage

The Graphora CLI provides a convenient way to extract knowledge graphs from documents.

Configuration

Config is stored in ~/.graphora/config.yaml:

# Interactive setup
graphora config init

# Set individual values
graphora config set llm.api_key "your-gemini-api-key"
graphora config set defaults.mode embedded  # or 'remote'

# View configuration
graphora config show

# Check status
graphora status

Extraction

# Extract with auto-inferred schema
graphora extract document.pdf -o graph.json

# Extract multiple files
graphora extract doc1.pdf doc2.pdf docs/ -o combined.json

# Use custom schema
graphora extract document.pdf --schema ontology.yaml -o graph.json

# Output as Cypher statements
graphora extract document.pdf -f cypher -o import.cypher

# Verbose output
graphora extract document.pdf -o graph.json -v

Schema Management

# Infer schema from documents
graphora schema infer document.pdf -o ontology.yaml

# Validate a schema file
graphora schema validate ontology.yaml

Modes

The CLI supports two modes:

Mode	Description	Requirements
embedded	Runs extraction locally (default)	Gemini API key only
remote	Uses hosted Graphora API	API URL + auth token

Embedded mode (recommended) runs the full extraction pipeline locally:

# Auto-downloads graphora-api, just need your API key
graphora config init --api-key "your-gemini-key"

Remote mode uses the hosted Graphora API:

graphora config init --mode remote \
  --api-url "https://api.graphora.io" \
  --auth-token "your-token"

Updating

# Update graphora-api to latest version
graphora update

# Install specific version
graphora update --version v1.2.0

Advanced: Custom API Path

For local development, you can point to your own graphora-api clone:

graphora config set embedded.api_path /path/to/my/graphora-api

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