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

Inspecting graphs (remote mode)

These commands talk to a Graphora API server and need --mode remote.

# Show the evidence and decisions behind a node or edge
graphora explain tx_abc123 --node-id n_alice
graphora explain tx_abc123 --edge-id e_works_at --json > evidence.json

# Compare two transforms — added / removed / changed
graphora diff tx-old tx-new
graphora diff tx-old tx-new --json | jq '.summary'
graphora diff tx-old tx-new -n 5      # tighter detail tables

Scenarios (named graph snapshots)

A scenario is a named point-in-time snapshot of a transform's extracted graph — useful for branching what-if comparisons before publishing.

# Create a snapshot
graphora scenario create -t tx-abc -n baseline
graphora scenario create -t tx-abc -n "merge-alice-alicia" -d "what-if ER"

# List / show / delete
graphora scenario list
graphora scenario show sc-abc123
graphora scenario delete sc-abc123 --yes    # --yes for non-interactive use

Regression testing against a golden corpus

# Informational run — exit 0 regardless of F1
graphora test golden/

# Gate CI on nodes.f1 and edges.f1 >= 0.6
graphora test golden/ --min-f1 0.6

# Capture the full per-doc report
graphora test golden/ -o report.json

Each subdirectory of the corpus must contain document.txt, ontology.yaml, and expected.json. Exit codes: 0 all green, 1 at least one below threshold, 2 configuration / corpus problem.

MCP integration

Wire Graphora's MCP server into an agent client's config:

# Workspace-relative install (cursor / vscode / codex / claude-code)
graphora install cursor

# User-global install
graphora install claude-desktop

# Preview without writing
graphora install cursor --dry-run

Supported clients: claude-code, claude-desktop, codex, cursor, vscode. Existing mcpServers entries are preserved unless you pass --force.

Modes

The CLI supports two modes:

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.

Community

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

Security

Please report security vulnerabilities to support@graphora.io

See SECURITY.md for details.

Made with ❤️ by Arivan Labs