Skip to main content
PackageRegistry is an in-memory catalog for b01t algorithm packages. You publish a compiled program as a PackageMeta entry, then retrieve it by name or tag, resolve its dependencies in topological order, and save or load the entire registry to a JSON file. A global DEFAULT_REGISTRY instance is available for convenience. 
from b01t import PackageMeta, PackageRegistry, DEFAULT_REGISTRY

​
PackageMeta

PackageMeta is a dataclass that describes a published algorithm package. 
from b01t import PackageMeta
from b01t import Effect

meta = PackageMeta(
    name="grover-oracle",
    effect="coherent",
    safe=True,
    tags=["search", "oracle"],
    docs="Grover phase oracle for 3-bit target.",
    inputs=[("ctrl", 3), ("tgt", 1)],
    version="1.0.0",
    depends_on=["hadamard-layer"],
)
​
name
str
required
Unique name for this package. Used as the registry key.
​
effect
str
required
Effect string: "coherent" or "adaptive". Matches Effect.value.
​
safe
bool
required
Whether the program carries Certification.SAFE or is_safe = True.
​
tags
list[str]
Free-form tags for discovery. Default: [].
​
docs
str
Human-readable description of the algorithm. Default: "".
​
inputs
list[tuple[str, int]]
Register specifications as (name, size) tuples, in order. Default: [].
​
version
str
Semantic version string. Default: "0.1.0".
​
depends_on
list[str]
Names of other packages this package depends on. Used for topological resolution. Default: [].
​
ir
IRProgram | None
Attached broad IR program, if any. Not persisted in JSON (save stores its text dump; load does not restore it). Default: None.
​
exact_program
ExactProgram | None
Attached exact program. Persisted to JSON using exact-oracle-v1 format when save is called. Restored on load. Default: None.

​
PackageRegistry

​
publish

registry.publish(meta: PackageMeta) -> None
Adds or replaces the package entry for meta.name.
​
meta
PackageMeta
required
The package metadata to store. If a package with the same name already exists, it is overwritten.

​
get

registry.get(name: str) -> Optional[PackageMeta]
Retrieves the package with the given name, or None if not found.
​
name
str
required
The exact package name to look up.

​
find_by_tag

registry.find_by_tag(tag: str) -> list[PackageMeta]
Returns all packages whose tags list includes tag.
​
tag
str
required
The tag to search for.

​
all

registry.all() -> list[PackageMeta]
Returns all published packages as a list. Order is insertion order.

​
save

registry.save(path: str | Path) -> None
Serializes the registry to a JSON file at path. Each entry includes all scalar fields. If a package has an exact_program, it is serialized using exact-oracle-v1 format. Broad IRProgram objects are saved as their text dump but are not restored on load.
​
path
str | Path
required
File path to write. The file is created or overwritten.

​
load

registry.load(path: str | Path) -> None
Deserializes packages from a JSON file previously written by save and merges them into this registry.
​
path
str | Path
required
File path to read.

​
resolve

registry.resolve(name: str) -> list[PackageMeta]
Returns the transitive dependencies of name in topological order (dependencies first, then name itself). Raises DSLValidationError if a circular dependency is detected or a required package is missing.
​
name
str
required
The package name to resolve.
order = registry.resolve("my-algorithm")
for pkg in order:
    print(pkg.name)
# prints dependencies in load order, then "my-algorithm"

​
dependency_graph_dot

registry.dependency_graph_dot() -> str
Returns a string in DOT format describing the dependency graph of all published packages. You can pipe this to Graphviz to visualise the graph. 
dot = registry.dependency_graph_dot()
print(dot)
# digraph packages {
#   rankdir=BT;
#   "grover" [label="grover\n[coherent]"];
#   "grover" -> "oracle";
#   ...
# }

​
DEFAULT_REGISTRY

DEFAULT_REGISTRY is a module-level PackageRegistry instance. Use it to publish packages without managing your own registry object. 
from b01t import DEFAULT_REGISTRY, PackageMeta

DEFAULT_REGISTRY.publish(PackageMeta(
    name="my-oracle",
    effect="coherent",
    safe=True,
))

pkg = DEFAULT_REGISTRY.get("my-oracle")

​
Full example

from b01t import (
    coherent, QReg, h, cx,
    PackageMeta, PackageRegistry,
    exact_program_to_dict,
)

@coherent
def bell(a: QReg, b: QReg) -> None:
    h(a[0])
    cx(a[0], b[0])

prog = bell.build_exact(("a", 1), ("b", 1))

registry = PackageRegistry()
registry.publish(PackageMeta(
    name="bell-pair",
    effect="coherent",
    safe=True,
    tags=["entanglement", "two-qubit"],
    docs="Prepares a Bell state from |00⟩.",
    inputs=[("a", 1), ("b", 1)],
    version="1.0.0",
    exact_program=prog,
))

# Save to disk
registry.save("registry.json")

# Load into a fresh registry
fresh = PackageRegistry()
fresh.load("registry.json")

loaded = fresh.get("bell-pair")
print(loaded.exact_program.certification)  # Certification.SAFE