Examples¶

Complete, runnable examples demonstrating HyperBinder's capabilities.

Where to Start¶

Example	Best For	Concepts Covered
Unified Intelligence	Unique capabilities	Fuzzy-to-exact traversal, cross-encoding joins, multi-hop chains
Fictional Universes	First-time users	Nested molecules, cross-domain analogies, typed entities
E-Commerce Platform	Practical applications	Multi-collection, hierarchies, recommendations
Enterprise Knowledge	Production patterns	6 collection types, HDC queries, knowledge graphs
Intersections Tutorial	Understanding joins	Step-by-step cross-collection mechanics, cross-encoding links
Fuzzy-to-Exact Bridge	Search + CRUD	Catalog/RelationalTable separation, safe mutations

Unified Intelligence Demo¶

The power showcase. See what makes HyperBinder unique: seamless traversal across semantic and exact data in a single query chain.

# Traditional approach: 200+ lines across 3+ systems
# HyperBinder approach: ~10 lines, one system

results = (
    hb.query("employees")
    .search("machine learning expert")     # SEMANTIC: fuzzy bio search
    .filter(department="Engineering")      # EXACT: department filter
    .join("expertise")                     # CROSS-ENCODING: ID → topic
    .join("projects")                      # SEMANTIC: topic → focus area
    .join("budgets")                       # EXACT: project_id match
)

# Traversed: Fuzzy → Exact → Cross-Encoding → Semantic → Exact
# All in one declarative query!

View full example →

Fictional Universes¶

The fun introduction. Model characters from Marvel, DC, Star Wars, Lord of the Rings, and Harry Potter using nested molecule composition.

# Characters as typed entities: (Universe, Name)
schema = Triple(
    subject=Pair(
        left=Field("universe", encoding=Encoding.EXACT),
        right=Field("name", encoding=Encoding.SEMANTIC),
    ),
    predicate=Field("relation", encoding=Encoding.EXACT),
    object=Pair(...)
)

# Cross-universe analogy: Luke:Yoda :: Harry:?
results = hb.analogy("Luke Skywalker", "Yoda", "Harry Potter", ...)
# → Dumbledore (wise mentor archetype)

View full example →

E-Commerce Platform¶

The practical example. Build a complete e-commerce knowledge system with products, categories, purchases, and recommendations.

# Four interconnected collections
product_schema = Document(content_field="description", ...)
category_schema = Hierarchy(node_field="category", parent_field="parent")
purchase_schema = Document(content_field="product_id", ...)
recommendation_schema = Network(source_field="source", target_field="target")

# Cross-collection query: Products in "Computers" and subcategories
descendants = categories.query(schema).descendants(node="Computers")
for cat in descendants:
    products = products.query(schema).filter(where=[("category", "==", cat)])

View full example →

Enterprise Knowledge Management¶

The comprehensive example. Model an entire enterprise with employees, organization hierarchy, expertise graphs, projects, documents, and collaboration networks.

# Six compound types working together
employees = Catalog(columns={...})
organization = Hierarchy(node_field="department", ...)
expertise = KnowledgeGraph(entity_field="subject", ...)
projects = Catalog(columns={...})
documents = Document(content_field="content", ...)
collaboration = Network(source_field="source", ...)

# HDC-specific: Analogical reasoning
# "Alice is our ML expert in Data Science. Who plays a similar role in Platform?"
results = hb.analogy("Alice Zhang", "Data Science", "Platform", ...)

View full example →

Intersections Tutorial¶

The mechanics deep-dive. Understand exactly how cross-collection joins work, step by step. Includes cross-encoding joins using flexible mode.

# Strict mode: same-encoding fields
hb.intersect("employees.employee_id", "expertise.subject")

# Flexible mode: cross-encoding fields (EXACT ↔ SEMANTIC)
ix = hb.intersect_flexible("employees.employee_id", "expertise.topic")
hb.populate_links(ix, links_df, "emp_id", "topic")

# Join works for both modes
for result in hb.query("employees").search("...").join("expertise"):
    if result.is_matched:
        print(f"{result.source['name']} → {result.target['skill']}")

View full example →

Fuzzy-to-Exact Bridge¶

The pattern for combining search and CRUD. Learn how to bridge semantic discovery with deterministic mutations using Catalog and RelationalTable together.

# Dual-schema architecture
search_schema = Catalog(fields={...})        # Optimized for search
crud_schema = RelationalTable(columns={...}) # Optimized for CRUD

# Bridge pattern: fuzzy discovery → exact mutations
candidates = hb.query("users_search", search_schema).search("ML expert")
for r in candidates:
    if r.data["department"] == "Engineering":  # Exact filter
        pk = r.data["user_id"]
        hb.update("users", where={"user_id": pk}, set={...}, schema=crud_schema)

View full example →

Running the Examples¶

Examples can run in either client mode (with server) or local mode (embedded):

Client Mode (with server)¶

# Install the SDK
pip install hybi

# Start the server (see server documentation)
hyperbinder serve

# Run an example
python examples/compose/fictional_universe_demo.py

Local Mode (embedded, no Docker)¶

# Install SDK with local support
pip install hybi hre

# Examples will detect local mode if server is unavailable
# Or modify examples to use: hb = HyperBinder(local=True)
python examples/compose/fictional_universe_demo.py

The examples are also available in the SDK repository under examples/compose/.