Documentation

Learn how to build AI applications with HyperX, the hypergraph database for multi-hop reasoning and agentic RAG.

Quick Start

1. Install the SDK

Terminal
pip install hyperxdb

Requires Python 3.10+

2. Get your API key

Sign up at hyperxdb.dev to get your API key, or set the HYPERX_API_KEY environment variable.

3. Create your first entities

Python
from hyperx import HyperX

# Initialize client
db = HyperX(api_key="hx_sk_...")

# Create entities
ml = db.entities.create(
    name="Machine Learning",
    entity_type="concept",
    attributes={"description": "Learning from data"}
)
data = db.entities.create(name="Data", entity_type="concept")

# Create a hyperedge connecting them
edge = db.hyperedges.create(
    description="ML requires Data",
    members=[
        {"entity_id": ml.id, "role": "subject"},
        {"entity_id": data.id, "role": "requirement"},
    ]
)

Core Concepts

Entities

Nodes in your knowledge graph representing concepts, objects, or information. Each has a name, type, and optional attributes and vector embedding.

Hyperedges

Connect any number of entities with semantic roles. Unlike traditional edges, hyperedges can model complex N-ary relationships like "Team A built Product B using Technology C".

Multi-Hop Paths

Traverse relationships across multiple hops to discover indirect connections. Configure max depth and filter by roles at each hop.

Agentic RAG

HyperX v0.6.0 introduces purpose-built tools for AI agents with quality signals that enable self-correction and multi-step reasoning.

Python
from hyperx import HyperX
from hyperx.agents import create_tools

client = HyperX(api_key="hx_sk_...")

# Create tools with access level
tools = create_tools(client, level="explore")

# Execute a tool
result = tools.execute("hyperx_search", query="React hooks")

# Check quality signals for self-correction
if result.quality.should_retrieve_more:
    print(result.quality.suggested_refinements)

Agent Tools

8 tools organized into 3 access levels:

SearchTool

Hybrid search across entities and hyperedges

PathsTool

Find multi-hop paths between entities

LookupTool

Retrieve entities or hyperedges by ID

ExplorerTool

Explore neighbors within N hops

ExplainTool

Get explanations for relationships

RelationshipsTool

List all relationships for an entity

EntityCrudTool

Create, update, delete entities

HyperedgeCrudTool

Create, update, delete hyperedges

Quality Signals

Every tool response includes quality signals to guide agent behavior:

Python
result = tools.execute("hyperx_search", query="...")

# Quality signals
result.quality.confidence        # 0.0-1.0 reliability score
result.quality.coverage          # Dict of entity type coverage
result.quality.diversity         # 0.0-1.0 result diversity
result.quality.should_retrieve_more  # Boolean trigger
result.quality.suggested_refinements # List of query suggestions

LangChain Integration

Python
from hyperx.agents import HyperXToolkit

# Create toolkit for LangGraph
toolkit = HyperXToolkit(client=db, level="explore")
tools = toolkit.get_tools()

# Use with LangGraph agent
from langgraph.prebuilt import create_react_agent
agent = create_react_agent(llm, tools)

LlamaIndex Integration

Python
from hyperx.agents import HyperXToolSpec

# Create tool spec
spec = HyperXToolSpec(client=db, level="explore")
tools = spec.to_tool_list()

# Use with LlamaIndex agent
from llama_index.core.agent import ReActAgent
agent = ReActAgent.from_tools(tools, llm=llm)

API Reference

Authentication

Include your API key in the Authorization header:

Authorization: Bearer hx_sk_your_api_key

Entities

POST /entities Create entity
GET /entities/:id Get entity
PUT /entities/:id Update entity
DELETE /entities/:id Delete entity

Hyperedges

POST /hyperedges Create hyperedge
GET /hyperedges/:id Get hyperedge
PUT /hyperedges/:id Update hyperedge
DELETE /hyperedges/:id Delete hyperedge
POST /search Hybrid search
POST /search/vector Vector similarity search

Paths

POST /paths/find Find paths between entities
POST /paths/explore Explore neighbors

Support

Need help? We're here for you: