Python API Overview - HeavenBase

A broad API can still have one front door; the fire exits just need labels.

1. Motivation

Importing every provider class, Registry helper, query fragment, and interface compiler into first-user code makes the package look harder than the application. Hiding all advanced seams creates the opposite problem: integrations depend on private modules. HeavenBase keeps a broad lazy root facade while recommending one small first-read surface. Application examples start with import heavenbase as hb; advanced authors move into owning packages only when their task requires that boundary.

2. Start with the Primary Surface

Area	Primary API	Purpose
Workspace	`hb.HeavenBase`, `hb.WorkspaceManifest`, `hb.Context`	Durable or detached application boundaries
Schema	`hb.Entity`, `hb.field`, logical types	Typed Entity classes and JSON-compatible schema
Placement	`hb.InlineColumn`, `hb.SideTable`, `hb.VectorIndex`, `hb.SparseGramIndex`, `hb.GraphEdge`	Field-level storage intent
Query	`hb.Query`, `hb.QuerySpec`, `hb.Aggregate`	Immutable query values and aggregation
Result	`hb.ResultFrame`	Detached transport result with explicit exports
Metadata	`hb.Catalog`, `hb.MetaSchema`, `hb.capabilities`	Object, structure, and registered choice inspection
LLM	`hb.LLM`, `hb.LLMSession`, `hb.Prompt`	Preset-driven generation and prompt rows
Tools	`hb.Capsule`, `hb.Tool`, `hb.Toolkit`	Callable capture, composition, persistence, and MCP

import heavenbase as hb


class Item(hb.Entity):
    name = hb.field(hb.ShortText)
    score = hb.field(hb.Float)


ws = hb.HeavenBase("api-demo", preset="debug")
ws.register(Item)
ws.upsert(Item, {"name": "Alpha", "score": 0.9})

rows = ws.query(Item).where(Item.score >= 0.5).execute().rows()

This flow is the default mental model: define, open, register, write, query, and choose a result export.

3. Use the Correct Workspace Entry Point

ws = hb.HeavenBase("shop", preset="debug")
same = hb.HeavenBase.load("shop")
ws.activate()
active = hb.HeavenBase.load()

Call	Absence behavior	Registration	Activation
`hb.HeavenBase(id, ...)`	Creates an absent id	Durable unless `detached=True`	Never implicit
`hb.HeavenBase.load(id)`	Raises `KeyError`	Existing only	No change
`hb.HeavenBase.load()`	Uses active, then configured default	Existing only	No change
`hb.HeavenBase(..., detached=True)`	Constructs caller-owned facade	None	Forbidden

Explicit preset= or backends= values assert the durable construction. Conflicts raise FileExistsError. release() removes the live facade while preserving Backend data; drop() destroys owned physical data.

4. Keep Schema and Row Lifecycles Separate

ws.register(Item)
item_id = ws.upsert(Item, {"name": "Beta", "score": 0.7})
ws.set(item_id, {"score": 0.8}, entity=Item)
item = ws.get(item_id, entity=Item)

Registration establishes the canonical class, placement, physical schema, and MetaSchema projection. Ordinary row operations require that class to exist and never register schema as a side effect. Root dynamic Extension Entity exports such as hb.Agent resolve through hb.DEFAULT_CONTEXT. Cross-Context code should use the canonical class from the target workspace instead of treating Python class identity as durable.

5. Treat Queries and Frames as Values

base = ws.query(Item).where(Item.score >= 0.5)
names = base.select("name")
total = base.count().execute().scalar()

print(names.execute().rows())
print(total)

Every fluent transform returns a new hb.Query; there is no mutable builder, copy, or fork API. execute() recomputes and returns a newly detached hb.ResultFrame. Use an explicit result exit:

rows() for JSON-like row dictionaries
scalar() for one-cell terminal results
to_pandas(), to_pyarrow(), to_numpy(), to_pydantic(), or to_daft() for typed consumers
ids and column(...) for focused inspection

Use query.explain() to inspect selected Backends, strategies, handlers, native/fallback mode, and unsupported reasons before relying on provider behavior.

6. Use Context-Bound Agent and LLM APIs

llm = hb.LLM(preset="mock", context=ws.context)
print(llm.chat("Reply with hb-ok"))

toolkit = ws.to_mcp(profile="agent")
print(toolkit.list_tools())

Pass the owning Context when isolation matters. Workspace MCP profiles scope tools, entities, Skills, and serializers; full is an administrative profile, not the default for untrusted agents. Concrete Toolkit persistence is workspace-owned. Toolkit.register, load, list, describe, and delete accept ws=; omission uses existing-only hb.HeavenBase.load() and never creates a hidden Toolkit store.

7. Use Advanced APIs from Their Owners

Boundary	Public owner
Registry kernel	`heavenbase.utils.registry`
Module install, inspect, resolve, lifecycle	`heavenbase.modules` and `context.modules()`
Placement values and profiles	`heavenbase.placement`
Frames, fragments, handlers, row operations	`heavenbase.execution`
Backend providers and types	`heavenbase.backends`
SQL dialect and database behavior	`heavenbase.database`
LLM gateways, specs, sessions, caches	`heavenbase.llm`
Extension-author facades	`hb.ext`
Parser-neutral CLI contracts	`heavenbase.cli`

Use hb.ext for Registry-backed backend, handler, strategy, operation, profile, serializer, and Extension authorship. Keep normal application onboarding on the root facade.

8. Avoid Retired Compatibility Paths

The 0.1.2.1 architecture has no compatibility packages at:

heavenbase.registry
heavenbase.storage
heavenbase.handlers
heavenbase.frame
heavenbase.discovery

Use heavenbase.utils.registry, heavenbase.placement, heavenbase.execution, and heavenbase.capabilities instead. SQL resources live under heavenbase.database.resources.sql; Toolkit prompts live under heavenbase.toolkit.prompts.

9. Read the API Contract Conservatively

Public root exports are lazy where implementation imports are heavy.
Registered tags describe semantic claims; they do not prove executable support.
Independent Backends do not form a distributed transaction.
Workspace manifests export construction, requested Extension roots, and schema, not row data.
Installed executable modules and Capsules are trusted code boundaries.
Provider-specific native behavior should be verified with explain() and focused tests.

Summary

Primary APIs own application workflows; advanced APIs expose narrow engine seams.
Context and workspace arguments preserve runtime authority.
Retired compatibility packages are not extension points.

Further Exploration

Related resources:

Workspace - Learn construction and lifecycle
Entities - Define public schema
Query - Compose and explain immutable queries
Extensions - Use the advanced Registry-backed seams
MCP Toolkit - Persist and serve tools
CLI Reference - Use the command-line adapter

​1. Motivation

​2. Start with the Primary Surface

​3. Use the Correct Workspace Entry Point

​4. Keep Schema and Row Lifecycles Separate

​5. Treat Queries and Frames as Values

​6. Use Context-Bound Agent and LLM APIs

​7. Use Advanced APIs from Their Owners

​8. Avoid Retired Compatibility Paths

​9. Read the API Contract Conservatively

​Summary

​Further Exploration

1. Motivation

2. Start with the Primary Surface

3. Use the Correct Workspace Entry Point

4. Keep Schema and Row Lifecycles Separate

5. Treat Queries and Frames as Values

6. Use Context-Bound Agent and LLM APIs

7. Use Advanced APIs from Their Owners

8. Avoid Retired Compatibility Paths

9. Read the API Contract Conservatively

Summary

Further Exploration