Quickstart

Get Purple8 Hyper Graph running and execute your first hybrid query in under 5 minutes.

Prerequisites

• Python 3.12 or later
• pip

1. Install

pip install purple8-hyper-graph

The base installation includes GraphEngine, BrickCoreStorage (Purple8 Cortex), BrickWAL, CortexAutoConfig, HNSW vector search, BM25 full-text search, Cypher query engine, Journey Engine, REST API, and the 125-tool MCP server out of the box.

Optional extras

# Optional LLM provider SDKs (LiteLLM is already included in core)
pip install "purple8-hyper-graph[openai,anthropic,google,vertex,bedrock]"

# Optional cloud KMS backends (HashiCorp Vault, AWS KMS, GCP Cloud KMS, Azure Key Vault)
pip install "purple8-hyper-graph[kms-full]"

# Optional AEC / BIM vertical (IFC file parsing + scipy sparse Laplacian)
pip install "purple8-hyper-graph[aec]"

2. Create a graph and add data

from purple8_graph import GraphEngine
import numpy as np

# Open (or create) a Cortex-backed database with hardware-bounded RSS
engine = GraphEngine("./my_graph", auto_config=True)

# Add some nodes — any labels, any properties
engine.add_node("doc1", labels=["Document"], properties={
    "title": "Attention is all you need",
    "year": 2017,
    "region": "Global",
})
engine.add_node("doc2", labels=["Document"], properties={
    "title": "BERT: Pre-training of Deep Bidirectional Transformers",
    "year": 2018,
    "region": "Global",
})
engine.add_node("vaswani", labels=["Person"], properties={"name": "Ashish Vaswani"})
engine.add_node("devlin",  labels=["Person"], properties={"name": "Jacob Devlin"})
engine.add_node("ml",      labels=["Topic"],  properties={"name": "Machine Learning"})

# Add relationships
engine.add_edge("doc1", "vaswani", "AUTHORED_BY")
engine.add_edge("doc2", "devlin",  "AUTHORED_BY")
engine.add_edge("doc1", "ml",      "BELONGS_TO")
engine.add_edge("doc2", "ml",      "BELONGS_TO")

3. Add vector embeddings

For real usage, use your embedding model of choice. For this quickstart, random vectors stand in:

# In production, replace with: openai.embeddings.create(...) or sentence_transformers.encode(...)
DIMS = 384
engine.add_node("doc1", labels=["Document"], properties={
    "title": "Attention is all you need",
    "year": 2017,
    "region": "Global",
}, embedding=np.random.rand(DIMS).tolist())
engine.add_node("doc2", labels=["Document"], properties={
    "title": "BERT: Pre-training of Deep Bidirectional Transformers",
    "year": 2018,
    "region": "Global",
}, embedding=np.random.rand(DIMS).tolist())

4. Run a hybrid query

from purple8_graph.query_language import QueryLanguage

# Simulate a query embedding
query_vec = np.random.rand(DIMS).tolist()

# Vector search + graph traversal — one Cypher statement
ql = QueryLanguage(engine)
results = ql.execute("""
    CALL db.vector.search('Document', $vec, 10) YIELD node, score
    WHERE score > 0.5
    MATCH (node)-[:AUTHORED_BY]->(author:Person)
    MATCH (node)-[:BELONGS_TO]->(topic:Topic)
    RETURN node.title, author.name, topic.name, score
    ORDER BY score DESC
""", {"vec": query_vec})

for row in results:
    print(f"{row['node.title']}  (score={row['score']:.4f})")
    print(f"  Author: {row['author.name']}  Topic: {row['topic.name']}")

5. Query without vectors

Cypher also works without vector search — standard graph queries:

# Find all documents from a specific author
results = ql.execute("""
    MATCH (p:Person {name: 'Ashish Vaswani'})<-[:AUTHORED_BY]-(doc:Document)
    RETURN doc.title, doc.year
    ORDER BY doc.year
""")

# Multi-hop — find co-authors (people who share a topic)
results = ql.execute("""
    MATCH (p1:Person)<-[:AUTHORED_BY]-(doc:Document)-[:BELONGS_TO]->(t:Topic)
    MATCH (doc2:Document)-[:BELONGS_TO]->(t)<-[:BELONGS_TO]-(doc3:Document)
    MATCH (doc3)-[:AUTHORED_BY]->(p2:Person)
    WHERE p1 <> p2
    RETURN p1.name, p2.name, t.name
    LIMIT 10
""")

6. Start the REST API & MCP server (optional)

You don't need a server for embedded usage (GraphEngine runs in-process with 0.33 ms vector query P99 at 100K nodes). When you want to expose the REST API, LCNC operational console, and MCP SSE endpoint (/mcp/sse):

# Local Python server defaults to port 8100 (Docker Compose defaults to port 8000)
P8G_DATA_PATH=./my_graph P8G_API_KEY=devkey P8G_PORT=8100 python -m purple8_graph.secure_server

The server starts at http://localhost:8100 (interactive OpenAPI docs at http://localhost:8100/docs, MCP SSE endpoint at http://localhost:8100/mcp/sse exposing 125 tools across 16 namespaces such as graph.query, graph.hybrid_search, rag.hybrid_query, and journey.define).

# Create an auth token
curl -s -X POST http://localhost:8100/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"Purple8Admin!"}' \
  | jq .access_token

# Execute a Cypher query via REST
curl -s -X POST http://localhost:8100/query \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "MATCH (n:Document) RETURN n.title LIMIT 5"}'

What's next?

• Docker Quickstart — run the Developer or Red Hat UBI9 / OpenShift container on port 8000
• Your first full example — a complete knowledge graph with real embeddings
• Hybrid Search guide — deep dive into the vector + BM25 + graph query model
• MCP Integration — connect Claude, Cursor, or custom agents to 125 dot-namespaced tools
• Schema & Data Model — understand schemaless vs. strict mode
• REST API reference — complete endpoint documentation