Molecules vs Compounds¶

Both molecules and compounds define schemas, but they serve different purposes. You can think of these elements as the "building blocks" for composing your knowledge layer.

HyperBinder comes with several prebuilt molecules and compounds for common use cases, and we plan to add more in future releases.

Quick Comparison¶

Aspect	Molecules	Compounds
What they are	Core building blocks	Convenience wrappers
Flexibility	Full control over slots	Pre-configured defaults
When to use	Custom structures	Common patterns
Examples	Pair, Triple, Bundle	KnowledgeGraph, Catalog

Molecules: Full Control¶

Molecules give you complete control over structure:

from hybi.compose import Triple, Field, Encoding

# You define every slot
schema = Triple(
    subject=Field("entity", encoding=Encoding.SEMANTIC),
    predicate=Field("relation", encoding=Encoding.EXACT),
    object=Field("target", encoding=Encoding.SEMANTIC, weight=1.5),
)

Use molecules when:

You need custom field names
You want specific encoding per field
You're nesting structures
You need fine-grained control

Available Molecules¶

Molecule	Slots	Best For
Pair	`left`, `right`	Key-value, edges
Triple	`subject`, `predicate`, `object`	Knowledge graphs
Bundle	User-defined	Tabular data
Sequence	`item`	Ordered data
Tree	`child`, `parent`	Hierarchies
Graph	`source`, `edge`, `target`	Networks

Compounds: Quick Setup¶

Compounds are pre-configured molecules for common domains:

from hybi.compose import KnowledgeGraph

# Sensible defaults, less code
schema = KnowledgeGraph(
    entity_field="entity",
    relation_field="relation",
)

Use compounds when:

Your data fits a common pattern
You want sensible defaults
You're prototyping quickly
You don't need custom encodings

Available Compounds¶

Compound	Based On	Default Fields
KnowledgeGraph	Triple	entity, relation, target
Catalog	Bundle	User-specified
TimeSeries	Sequence	timestamp, value
Hierarchy	Tree	node, parent
Document	Bundle	content, metadata
Network	Graph	source, target, edge

Side-by-Side Examples¶

Knowledge Graph¶

Using Triple (Molecule)Using KnowledgeGraph (Compound)

from hybi.compose import Triple, Field, Encoding

schema = Triple(
    subject=Field("person", encoding=Encoding.SEMANTIC),
    predicate=Field("relation", encoding=Encoding.EXACT),
    object=Field("organization", encoding=Encoding.SEMANTIC),
)

from hybi.compose import KnowledgeGraph

schema = KnowledgeGraph(
    entity_field="person",
    relation_field="relation",
    # Uses SEMANTIC for entities, EXACT for relations by default
)

Tabular Data¶

Using Bundle (Molecule)Using Catalog (Compound)

from hybi.compose import Bundle, Field, Encoding

schema = Bundle(
    fields={
        "name": Field(encoding=Encoding.SEMANTIC, weight=1.5),
        "category": Field(encoding=Encoding.EXACT),
        "price": Field(encoding=Encoding.NUMERIC, similar_within=50),
    }
)

from hybi.compose import Catalog, Field, Encoding

schema = Catalog(
    columns={
        "name": Field(encoding=Encoding.SEMANTIC, weight=1.5),
        "category": Field(encoding=Encoding.EXACT),
        "price": Field(encoding=Encoding.NUMERIC, similar_within=50),
    }
)

Organizational Hierarchy¶

Using Tree (Molecule)Using Hierarchy (Compound)

from hybi.compose import Tree, Field

schema = Tree(
    child=Field("employee"),
    parent=Field("manager"),
)

from hybi.compose import Hierarchy

schema = Hierarchy(
    node_field="employee",
    parent_field="manager",
)

When Compounds Aren't Enough¶

Use molecules directly when you need:

Custom Encodings Per Slot¶

# Compounds use defaults; molecules let you customize each slot
Triple(
    subject=Field("entity", encoding=Encoding.SEMANTIC),
    predicate=Field("type", encoding=Encoding.EXACT),  # Exact match for types
    object=Field("value", encoding=Encoding.NUMERIC),  # Numeric for values
)

Nested Structures¶

# Compounds don't support nesting; molecules do
Triple(
    subject=Pair(
        left=Field("entity_type", encoding=Encoding.EXACT),
        right=Field("entity_name"),
    ),
    predicate=Field("relation"),
    object=Field("target"),
)

Field Weights¶

# Fine-grained relevance control
Bundle(
    fields={
        "title": Field(encoding=Encoding.SEMANTIC, weight=2.0),  # 2x importance
        "description": Field(encoding=Encoding.SEMANTIC, weight=1.0),
        "category": Field(encoding=Encoding.EXACT, weight=0.5),  # Half weight
    }
)

Decision Guide¶

flowchart LR
    Q1{Custom encodings?} -->|Yes| M[Molecule]
    Q1 -->|No| Q2{Common pattern?}
    Q2 -->|No| M
    Q2 -->|Yes| C[Compound]

If your data is...	Use
Knowledge facts (entity-relation-entity)	`KnowledgeGraph`
Time-ordered events	`TimeSeries`
Parent-child relationships	`Hierarchy`
Node-edge networks	`Network`
Documents with metadata	`Document`
Generic tabular	`Catalog`

Summary¶

Start with compounds for common patterns
Switch to molecules when you need more control
Compounds expand to molecules internally - same capabilities once defined
Both produce schema-aware queries with the same ComposeQuery interface