Getting Started

Prerequisites

• Rust stable
• just — cargo install just

Clone and Build

git clone https://github.com/Hologram-Technologies/hologram
cd hologram
just ci   # fmt check + clippy + full test suite

Install

There is no umbrella crate. Add the individual crates you need to Cargo.toml:

[dependencies]
hologram-compiler = { git = "https://github.com/Hologram-Technologies/hologram" }
hologram-exec     = { git = "https://github.com/Hologram-Technologies/hologram" }
hologram-backend  = { git = "https://github.com/Hologram-Technologies/hologram" }

Enable source frontend features when you want to parse Hologram graph functions embedded in host-language files:

[dependencies]
hologram-compiler = {
  git = "https://github.com/Hologram-Technologies/hologram",
  features = ["frontend-python", "frontend-typescript", "frontend-rust"],
}

Run the Pipeline Example

crates/hologram-cli/examples/pipeline.rs runs the end-to-end flow: it parses a graph, compiles it to a .holo archive, executes it on the CPU backend, and mints + composes UOR-ADDR κ-labels.

cargo run -p hologram-cli --example pipeline

Compile and Execute

Compile a graph to a .holo archive and execute it synchronously against the CPU backend:

use hologram_backend::CpuBackend;
use hologram_compiler::{source, BackendKind, Compiler};
use hologram_exec::{BufferArena, InferenceSession, InputBuffer};
use prism::vocabulary::WittLevel;

// Parse native Hologram source into a Graph and compile it.
let graph = source::parse("input x\nop relu x as=y\noutput y\n").unwrap();
let compiled = Compiler::new(graph, BackendKind::Cpu, WittLevel::new(32))
    .compile()
    .unwrap();

// Load the archive and execute against the CPU backend.
let mut session =
    InferenceSession::load(&compiled.archive, CpuBackend::<BufferArena>::new()).unwrap();
let zeros = vec![0u8; 4096];
let inputs: Vec<InputBuffer> =
    (0..session.input_count()).map(|_| InputBuffer { bytes: &zeros }).collect();
let outputs = session.execute(&inputs).unwrap();

Graphs can also be built programmatically with Graph::new() plus add_node / add_input / add_output.

Using the CLI

hologram-cli builds the hologram binary:

# compile native Hologram source (or an empty graph) to a .holo archive
hologram compile --source graph.txt --output model.holo --backend cpu --witt-level 32

# inspect an archive's section table
hologram inspect --archive model.holo

# execute against zero-byte inputs; prints each output port's byte length
hologram execute --archive model.holo

# micro-bench: run an archive N times, report wall-clock per iteration
hologram bench --archive model.holo --iterations 100

By default compile folds the constant-only cone into the archive (warm start); pass --no-warm to emit the labels-only lattice instead.

Source Frontends

Native Hologram source is always available. Python, TypeScript, and Rust frontends are feature-gated and parse the host language AST without executing host-language code. They extract restricted Hologram builder functions from larger application files, ignore unrelated functions, and lower every supported language through the same SourceProgram -> Graph -> Compiler path.

The CLI detects source language from .txt, .py, .ts, .tsx, and .rs extensions. Use --source-language <lang> only for unusual extensions or an explicit override. If a file contains one inferred graph function, --graph can be omitted. If it contains multiple graph functions, use --graph <name>.

SDK Source Helpers

Python and TypeScript SDKs can compile native Hologram .txt source through the same FFI boundary used by the CLI:

import hologram as hg

archive = hg.compile_source_file("graph.txt")

import { compileSourceFile, createNativeBinding } from "@hologram/native";

const archive = await compileSourceFile("graph.txt", createNativeBinding());

Compile Python Source

Enable the frontend-python feature to compile restricted Hologram builder functions embedded in ordinary Python files. The compiler parses the Python AST; it does not execute Python code.

def ordinary_app_code():
    return 42

def encoder(h):
    x = h.input("x", dtype="f32", shape=[2, 3])
    y = h.ops.relu(x, shape=[2, 3])
    h.output("y", y)

cargo run -p hologram-cli --features frontend-python -- compile \
  --source graph.py \
  --graph encoder \
  --output model.holo

If the file contains exactly one inferred graph function, --graph can be omitted. Use --source-language python when the file does not have a .py extension.

Compile TypeScript Source

Enable the frontend-typescript feature to compile restricted Hologram builder functions embedded in ordinary TypeScript files. The compiler parses the TypeScript AST; it does not execute TypeScript code.

function ordinaryAppCode() {
    return 42;
}

export function encoder(h: HologramBuilder) {
    const x = h.input("x", { dtype: "f32", shape: [2, 3] });
    const y = h.ops.relu(x, { shape: [2, 3] });
    h.output("y", y);
}

cargo run -p hologram-cli --features frontend-typescript -- compile \
  --source graph.ts \
  --graph encoder \
  --output model.holo

If the file contains exactly one inferred graph function, --graph can be omitted. Use --source-language typescript when the file does not have a .ts or .tsx extension.

Compile Rust Source

Enable the frontend-rust feature to compile restricted Hologram builder functions embedded in ordinary Rust files. The compiler parses the Rust AST with syn; it does not compile or execute Rust code.

fn ordinary_app_code() -> i32 {
    42
}

pub fn encoder(h: &mut HologramBuilder) {
    let x = h.input("x", dtype("f32"), shape([2, 3]));
    let y = h.ops().relu(x, shape([2, 3]));
    h.output("y", y);
}

cargo run -p hologram-cli --features frontend-rust -- compile \
  --source graph.rs \
  --graph encoder \
  --output model.holo

If the file contains exactly one inferred graph function, --graph can be omitted. Use --source-language rust when the file does not have a .rs extension.

Run Benchmarks

just bench
# or a single suite:
cargo bench -p hologram-bench --bench lut_activation

Criterion HTML reports: target/criterion/report/index.html

WASM Build

just wasm
# builds the no_std library stack for wasm32-unknown-unknown

Project Layout

crates/
  hologram-host/       # platform/host bounds
  hologram-types/      # shared types: dtype tags, memory tiers
  hologram-ops/        # UOR-native op taxonomy + semantics + backward rules
  hologram-graph/      # tensor graph IR, desugaring, elision, scheduling
  hologram-compiler/   # graph → .holo (lowering, fusion, planning)
  hologram-archive/    # .holo format, UOR-ADDR κ-labels, BLAKE3 footer
  hologram-backend/    # kernel backends (CPU SIMD + LUT; optional wgpu/Metal)
  hologram-exec/       # content-addressed executor, buffer pool, warm-start
  hologram-ffi/        # C ABI bindings
  hologram-cli/        # compile / execute / inspect / bench subcommands
  hologram-bench/      # criterion benchmarks

Next Steps

• Architecture — content-addressed execution, LUT materialization, fusion, and the .holo format
• Configuration — Cargo features, backend selection, and Witt level