HugeGraph-LLM SDK Quick Start

hugegraph-llm-sdk is a lightweight, standalone Python SDK for programmatically designing schemas, extracting property graphs from unstructured text, validating schemas against HugeGraph rules, and performing iterative model review and bounded repair.

Unlike the full hugegraph-llm application, the SDK is completely headless and does not require HugeGraph Server, Gradio Web UI, FastAPI, or a vector database. Its core runtime depends only on pydantic>=2.14,<3.

Apache License 2.0 · Ask DeepWiki

Requirements and Installation

• Python: >=3.12 (tested and supported on Python 3.12, 3.13, and 3.14).
• Package name: hugegraph-llm-sdk
• Import name: hugegraph_llm_sdk

Install from source or a local wheel

The SDK is currently provided by the hugegraph-ai source tree and has not yet been published to a public package index. Install it from a checkout or a locally built wheel.

1pip install -e /path/to/hugegraph-ai/hugegraph-llm-sdk
2# or
3uv add --editable /path/to/hugegraph-ai/hugegraph-llm-sdk
4
5uv build --no-sources /path/to/hugegraph-ai/hugegraph-llm-sdk --out-dir /tmp/llm-sdk-dist
6pip install /tmp/llm-sdk-dist/hugegraph_llm_sdk-1.8.0-py3-none-any.whl

Provider Extras

Install provider extras from the same checkout:

1pip install -e "/path/to/hugegraph-ai/hugegraph-llm-sdk[openai]"
2pip install -e "/path/to/hugegraph-ai/hugegraph-llm-sdk[ollama]"
3pip install -e "/path/to/hugegraph-ai/hugegraph-llm-sdk[litellm]"
4# uv example: uv add --editable /path/to/hugegraph-ai/hugegraph-llm-sdk --extra openai

Quick Start: Minimal Example

Here is a complete example demonstrating schema design, schema validation, and reviewed graph extraction using a custom model function:

 1from hugegraph_llm_sdk import (
 2    FunctionModel,
 3    design_schema,
 4    validate_schema,
 5    extract_graph,
 6)
 7
 8# 1. Define or wrap your LLM caller
 9model = FunctionModel(generate=lambda prompt: my_agent_model.invoke(prompt).content)
10
11# 2. Design a graph schema from sample texts and target questions
12draft = design_schema(
13    texts=["Alice works for Acme Corp. Bob reports to Alice."],
14    questions=["Which company does each person work for? Who reports to whom?"],
15    model=model,
16)
17
18# Inspect any structural or conceptual issues flagged during design
19if draft.issues:
20    print(f"Schema draft issues: {draft.issues}")
21
22schema = draft.schema
23
24# 3. Validate schema structure against HugeGraph rules
25validation_issues = validate_schema(schema)
26assert not validation_issues, f"Validation failed: {validation_issues}"
27
28# 4. Extract property graph from text
29result = extract_graph(
30    texts="Alice works for Acme Corp as Chief Engineer.",
31    schema=schema,
32    model=model,
33)
34
35# 5. Process chunk outcomes
36print(f"Overall status: {result.status}")  # 'succeeded', 'partial', or 'failed'
37for chunk in result.chunks:
38    if chunk.status == "final":
39        print(f"Extracted graph: {chunk.graph}")
40    else:
41        print(f"Chunk {chunk.index} status: {chunk.status}, reason: {chunk.reason}, issues: {chunk.issues}")

Core API Capabilities

Schema Validation Rules

• validate_schema inspects vertex labels, edge labels, ID strategies (DEFAULT, AUTOMATIC, PRIMARY_KEY, CUSTOMIZE_STRING, CUSTOMIZE_NUMBER, CUSTOMIZE_UUID), and property declarations.
• When propertykeys is omitted, global property definitions are not strictly checked. When a label omits properties, its property set is unconstrained.
• An explicit empty properties: [] indicates that no properties are allowed for that label.
• For edge labels, sort_keys cannot be members of nullable_keys. When frequency is SINGLE or DEFAULT, sort keys are disallowed; MULTIPLE requires non-empty sort keys.

Model Adapters

The SDK includes standard model adapters under hugegraph_llm_sdk.providers:

1from hugegraph_llm_sdk.providers.openai import OpenAIClient
2
3model = OpenAIClient(
4    api_key="your-api-key",
5    api_base="https://api.openai.com/v1",
6    model_name="gpt-4o-mini",
7)

• FunctionModel: Wraps any custom function generate(prompt: str) -> str or async agenerate(prompt: str) -> str.
• OpenAIClient: Adapter for OpenAI and OpenAI-compatible endpoints (supports close() and await aclose()).
• OllamaClient: Adapter for local Ollama instances.
• LiteLLMClient: Adapter using LiteLLM connection routing.
• ThreadedModel: Wraps a synchronous model so calls execute inside worker threads during async execution without blocking the event loop.

Review and Bounded Repair

By default, extraction executes an iterative review and bounded repair loop:

1extract -> validate -> review
2              ^           |
3              |           +-- pass  -> final
4              |           +-- block -> blocked
5              +-- repair <- fix

Review options are configured via ExtractionOptions:

 1from hugegraph_llm_sdk import ExtractionOptions, extract_graph
 2
 3options = ExtractionOptions(
 4    max_reviews=2,  # Maximum review attempts per chunk (0–5, default: 2)
 5    max_fixes=1,    # Maximum repair attempts per chunk (0–3, default: 1)
 6    max_workers=1,  # Worker concurrency (1–8, default: 1)
 7)
 8
 9result = extract_graph(
10    texts="Bob manages Charlie at Beta Corp.",
11    schema=schema,
12    model=model,
13    options=options,
14)

Chunk and Result Statuses

• Chunk status:
  • final: Graph passed structural validation and model review. Only final chunks are merged into result.graph.
  • candidate: Validation passed, but review budget was exhausted or review could not conclude.
  • blocked: Graph could not pass validation within the repair budget or was explicitly rejected by review.
  • failed: An exception or unrecoverable error occurred during execution.
• Aggregate status:
  • succeeded: All chunks achieved final status.
  • partial: At least one chunk is final, but one or more chunks failed or remain candidate/blocked.
  • failed: No chunk reached final status.

Concurrency and Async Processing

When setting max_workers > 1, you must pass a stateless model_factory callable instead of a single model instance. This ensures thread-safety and isolated model state per worker:

 1from hugegraph_llm_sdk import ExtractionOptions, extract_graph
 2from hugegraph_llm_sdk.providers.openai import OpenAIClient
 3
 4chunks = [
 5    "Alice joined Acme Corp in 2022.",
 6    "Bob joined Beta LLC in 2023.",
 7    "Charlie works with Alice at Acme Corp.",
 8]
 9
10result = extract_graph(
11    texts=chunks,
12    schema=schema,
13    model_factory=lambda: OpenAIClient(api_key="your-api-key", model_name="gpt-4o-mini"),
14    options=ExtractionOptions(max_workers=3),
15)
16
17print(f"Total vertices: {len(result.graph.get('vertices', []))}")
18print(f"Total edges: {len(result.graph.get('edges', []))}")

The SDK automatically manages the lifecycle of models created by model_factory, disposing of them when each worker batch finishes.

Relationship with HugeGraph-LLM

hugegraph-llm-sdk and hugegraph-llm reside in the same repository under separate modules:

1hugegraph-ai/
2├── hugegraph-llm-sdk/      # Standalone headless Python SDK (pydantic-only baseline)
3├── hugegraph-llm/          # Full application layer (FastAPI, Gradio UI, GraphRAG, vector DB)
4├── hugegraph-python-client/# Low-level HugeGraph Server client (pyhugegraph)
5└── hugegraph-mcp/          # Model Context Protocol server

• hugegraph-llm-sdk: Embeddable library for Python pipelines, LLM agent toolchains, and data transformation scripts requiring schema design and graph extraction.
• hugegraph-llm: Production application service providing Web UI, REST endpoints (POST /graph/extract, POST /rag), vector index persistence, and automated ingestion into HugeGraph Server.