Session

The AgentSession is the top-level owner of agent state—HyperBinder client, collection metadata, intersection metadata, and the tool registry.

graph TB
    Session["AgentSession"]
    Session --> HB["hb<br/>HyperBinder client"]
    Session --> Collections["collections<br/>Dict[str, CollectionMeta]"]
    Session --> Intersections["intersections<br/>List[IntersectionMeta]"]
    Session --> Registry["tool_registry<br/>ToolRegistry"]
    Collections --> Meta["CollectionMeta<br/>schema, fields, stats"]
    Intersections --> IX["IntersectionMeta<br/>source, target, relation"]

Quick Start

from hybi import HyperBinder
from hybi.agent import AgentSession

hb = HyperBinder()

# Create a new session (auto-registers all built-in tools)
session = AgentSession.create(hb)

# Register a collection after a create_collection tool runs
session.register_collection(
    name="drugs",
    schema=compound_obj,
    schema_type="catalog",
    row_count=0,
    field_names=["name", "mechanism", "indication"],
)

# Save session metadata for later
session.save("session.json")

Restoring a Session

# Restore from saved metadata (reattaches to HyperBinder storage)
session = AgentSession.restore(hb, "session.json")

# Collection data persists in HyperBinder—save/restore only
# tracks which collections and intersections belong to this session

Schema on restore

Restored sessions have schema=None on CollectionMeta objects. The schema_type and field_names are preserved, which is sufficient for query dispatch.

---

AgentSession

hybi.agent.session.AgentSession

Top-level agent session for agent.

Owns the HyperBinder client, collection metadata, intersection metadata, and tool registry. No WorldState, no ToposAgent.

hb = hb instance-attribute

session_id = session_id instance-attribute

collections = collections instance-attribute

intersections = intersections instance-attribute

tool_registry = tool_registry instance-attribute

create(hb, *, session_id=None, tools=None, procedural_memory=False) classmethod

Create a new agent session.

Parameters:

Name	Type	Description	Default
hb	Any	HyperBinder backend (LocalHyperBinder or RemoteHyperBinder). Required -- the session calls hb.ingest(), hb.search(), etc.	required
session_id	Optional[str]	Optional session identifier. Generated if not provided.	None
tools	Optional[List[ToolDefinition]]	Additional tools beyond built-ins.	None
procedural_memory	bool	When True, enable procedural memory to capture error→success code patterns from execute_code calls.	False

Returns:

Type	Description
AgentSession	A fully initialized AgentSession.

restore(hb, path, *, tools=None) classmethod

Restore a session from a saved JSON file.

Reattaches to HyperBinder storage. Collection schemas are reconstructed from saved schema_type + field_stats via _build_compound(). Falls back to schema=None if reconstruction fails.

Parameters:

Name	Type	Description	Default
hb	Any	HyperBinder backend (required).	required
path	str	Path to the session JSON file.	required
tools	Optional[List[ToolDefinition]]	Additional tools beyond built-ins.	None

Returns:

Type	Description
AgentSession	AgentSession with restored metadata.

register_collection(name, schema, schema_type, row_count=0, field_names=None, description='', field_descriptions=None)

Register a collection in the session metadata.

warmup()

Single-pass scan to populate field_stats with cardinality and top_values.

For each collection: 1. Ensure field_stats exist (derive from compound if available, else create minimal entries from field_names). 2. For each key field (is_key=True): aggregate once to populate cardinality and top_values. 3. For non-key EXACT fields: check cardinality ratio and promote to key if low cardinality (< 30% of row_count). 4. Cache the rendered schema summary.

register_warmup_hook(hook)

Register a hook to run at the end of warmup().

Extensions (e.g. runtime) use this to inject optional warmup steps without creating a hard dependency from core → extension.

save(path)

Save session metadata to a JSON file.

Collection data persists in HyperBinder storage. This just remembers which collections and intersections belong to this conversation.

---

CollectionMeta

Metadata for a registered collection.

from hybi.agent import CollectionMeta

meta = CollectionMeta(
    name="drugs",
    schema=compound_obj,
    schema_type="catalog",
    row_count=150,
    field_names=["name", "mechanism", "indication"],
    field_stats={},          # FieldStats per field (populated by warmup)
    slot_map={},             # root_slot -> column_name mapping
    key_fields=[],           # fields marked as keys (exact-encoded)
    description="",          # human-readable description
    field_descriptions=None, # per-field descriptions
)

hybi.agent.session.CollectionMeta dataclass

Metadata for a registered collection.

---

IntersectionMeta

Metadata for a declared cross-collection link.

from hybi.agent import IntersectionMeta

ix = IntersectionMeta(
    source="drugs.name",
    target="trials.drug_name",
    relation="identity",
)

hybi.agent.session.IntersectionMeta dataclass

Metadata for a declared intersection.