hof-engine

Full-stack Python + React framework for building applications with workflows, database tables, UIs, and LLM integration -- all defined as code.

Features

Tables: Define database schemas as Python classes with auto-generated CRUD APIs
Functions: Backend operations exposed as API endpoints and CLI commands
Flows: Workflow DAGs with parallel execution, LLM nodes, and human-in-the-loop
UIs: Native React components with hot reload via Vite
Cron Jobs: Scheduled tasks with Celery Beat
CLI: Full CLI access to all features
Admin Dashboard: Visual flow viewer, table browser, execution history, and logs
LLM Integration: First-class support via llm-markdown with structured outputs
Self-Contained Docs: Bundle Markdown documentation with your app, served and rendered in the admin UI

Quick Start

pip install hof-engine
hof new project my-app
cd my-app

Define a table:

# tables/task.py
from hof import Table, Column, types

class Task(Table):
    title = Column(types.String, required=True)
    done = Column(types.Boolean, default=False)

Define a function:

# functions/greet.py
from hof import function

@function
def greet(name: str) -> dict:
    return {"message": f"Hello, {name}!"}

Define a flow:

# flows/onboarding.py
from hof import Flow

onboarding = Flow("onboarding")

@onboarding.node
def create_task(user_name: str) -> dict:
    return {"task": f"Welcome {user_name}"}

@onboarding.node(depends_on=[create_task])
def notify(task: str) -> dict:
    return {"notified": True}

Run:

hof db migrate
hof dev

hof fn output: By default, hof fn <name> prints human-friendly tables (for list-like results such as { "rows", "total" }) or a key/value layout for plain dicts. Use --format json when you need machine-readable JSON for scripts or pipes. The -j / --json flag supplies input to the function only, not the output format.

Self-Contained Docs

Every hof application can ship its own documentation. Place Markdown files in a docs/ directory at the project root and they are automatically served at /api/docs and rendered in the admin UI at /docs.

my-app/
  docs/
    index.md          # Overview
    data-model.md     # Table schemas
    api.md            # Function reference

Use optional YAML frontmatter to control titles, section grouping, and sort order:

---
title: Data Model
section: Reference
order: 1
---

No configuration needed — docs_dir defaults to "docs". Set docs_dir="" in hof.config.py to disable. See the Configuration reference for full details.

Requirements

Python 3.11+
Node.js 18+ (for React UI)
PostgreSQL
Redis

Documentation

See the docs/ directory:

Ecosystem

hof-engine is part of the bithof platform:

Repo	Role
hof-engine (this repo)	Core framework (pip package)
hof-components	Reusable modules and templates, copied via `hof add`
hof-os	Agency operations: deployment, provisioning, billing, design system generation
design-system-<customer>	Per-customer design tokens + Tailwind theme (git submodule in project repos)
customer-acme-test	Example customer project

For application examples, see hof-components/docs/examples/.

Contributing (PR hygiene)

Prefer squashing noisy WIP commits (duplicate messages, one-line “fix” iterations) on a feature branch before merging to main, so history stays readable.
When syncing the components artifact (hof/components-manifest.json and related generated output), batch updates into fewer commits instead of many back-to-back chore: update components artifact pushes.

License

MIT

Releasing to PyPI

This repository is configured for Trusted Publishing via GitHub Actions:

.github/workflows/publish.yml for PyPI
.github/workflows/publish-testpypi.yml for TestPyPI
The repository can stay private.
No PYPI_TOKEN secret is required.
Publishing to PyPI happens when a GitHub Release is published (or manually via workflow dispatch).
Publishing to TestPyPI is manual via workflow dispatch.

One-time setup in your PyPI account:

Go to PyPI Trusted Publishers.
Add a publisher with:
- PyPI project name: hof-engine
- Owner/repo: your GitHub repo for this project
- Workflow: publish.yml (filename only)
- Environment: pypi
In GitHub, create an environment named pypi (recommended to require manual approval).

Optional setup for TestPyPI:

Go to TestPyPI Trusted Publishers.
Add a publisher with:
- TestPyPI project name: hof-engine
- Owner/repo: your GitHub repo for this project
- Workflow: publish-testpypi.yml (filename only)
- Environment: testpypi
In GitHub, create an environment named testpypi.

Release flow:

Bump/update code as needed and push to default branch.
Create and push a git tag like v0.1.1 (git tag v0.1.1 && git push origin v0.1.1).
The workflow builds and uploads the package to PyPI under your account/project ownership.
Optional: also publish a GitHub Release for changelog/visibility.

Manual publish options:

Publish to PyPI now (no release): run the Publish to PyPI workflow via GitHub Actions Run workflow.
Publish to TestPyPI: run the Publish to TestPyPI workflow via GitHub Actions Run workflow.

Metadata

Release files for hof-engine 0.1.119

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hof-engine 0.1.119
File	Size	Uploaded
hof_engine-0.1.119.tar.gz	596.9 kB	May 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hof-engine 0.1.119
File	Interpreter	ABI	Platform	Reset
hof_engine-0.1.119-py3-none-any.whl 587.2 kB May 2, 2026	Python 3	none	any	Details

Total release size: 1.2 MB

Release files / hof_engine-0.1.119.tar.gz

Download URL	hof_engine-0.1.119.tar.gz
Size	596.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`52df58e533afc5e18905430bfbb504a10befcb2414765d9c92a55635e39efbce`
BLAKE2b-256 checksum How to use checksums	`8cb3bd70d68c567e82a1de6e02687c0258abda9553738ce9b7cd0e9ab74826bd`
Upload date	May 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jhoetter/hof-engine
Publishing commit: github.com/jhoetter/hof-engine/tree/5afc076151c458596088ac1455ab5e959f311532

Workflow

Publishing configuration: github.com/jhoetter/hof-engine/blob/5afc076151c458596088ac1455ab5e959f311532/.github/workflows/auto-release.yml
Publishing logs: github.com/jhoetter/hof-engine/actions/runs/25263381077/attempts/1

Artifact

Subject: hof_engine-0.1.119.tar.gz
SHA-256 checksum: 52df58e533afc5e18905430bfbb504a10befcb2414765d9c92a55635e39efbce Verifying attestations

Release files / hof_engine-0.1.119-py3-none-any.whl

Download URL	hof_engine-0.1.119-py3-none-any.whl
Size	587.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8a3cda14758ca44831b0e219a7e71ed585151b4d364d0436876e29424f748a8c`
BLAKE2b-256 checksum How to use checksums	`5bcbcdbc6f58cd785d95ea634d38fcf21dc9ae00f20ed5bc0c4d2938922f18d2`
Upload date	May 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/jhoetter/hof-engine
Publishing commit: github.com/jhoetter/hof-engine/tree/5afc076151c458596088ac1455ab5e959f311532

Workflow

Publishing configuration: github.com/jhoetter/hof-engine/blob/5afc076151c458596088ac1455ab5e959f311532/.github/workflows/auto-release.yml
Publishing logs: github.com/jhoetter/hof-engine/actions/runs/25263381077/attempts/1

Artifact

Subject: hof_engine-0.1.119-py3-none-any.whl
SHA-256 checksum: 8a3cda14758ca44831b0e219a7e71ed585151b4d364d0436876e29424f748a8c Verifying attestations