hof-engine 0.1.0__tar.gz

hof_engine-0.1.0/.dockerignore

@@ -0,0 +1,7 @@
+hof/ui/admin/node_modules
+__pycache__
+*.pyc
+.git
+.ruff_cache
+.mypy_cache
+.pytest_cache

hof_engine-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff (lint)
+        run: ruff check hof/ tests/
+
+      - name: Run ruff (format check)
+        run: ruff format --check hof/ tests/
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: |
+          pytest tests/ \
+            -m "not integration" \
+            --cov=hof \
+            --cov-report=term-missing \
+            --cov-report=xml \
+            -v
+
+      - name: Upload coverage report
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

hof_engine-0.1.0/.github/workflows/publish-testpypi.yml

@@ -0,0 +1,41 @@
+name: Publish to TestPyPI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build & Publish (TestPyPI)
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install hatch
+        run: pip install hatch twine
+
+      - name: Build package (compiles admin UI via hatch_build.py)
+        run: hatch build
+
+      - name: Check distribution metadata
+        run: twine check dist/*
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

hof_engine-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install hatch
+        run: pip install hatch twine
+
+      - name: Set version from release tag
+        if: github.event_name == 'release' || startsWith(github.ref, 'refs/tags/')
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          echo "Publishing version: $VERSION"
+          sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
+
+      - name: Build package (compiles admin UI via hatch_build.py)
+        run: hatch build
+
+      - name: Check distribution metadata
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hof_engine-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment variables / secrets
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.cursor/
+
+# Node
+node_modules/
+hof/ui/admin/dist/
+hof-react/dist/
+
+# Hof generated (per-project)
+migrations/
+_hof_entry.tsx
+ui/index.html
+ui/package.json
+ui/vite.config.ts
+ui/tsconfig.json
+ui/node_modules/
+ui/dist/
+
+# OS
+.DS_Store
+Thumbs.db

hof_engine-0.1.0/.hof/components-manifest.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "updated_at": "2026-03-10T17:14:40Z",
+  "artifacts": [
+    {
+      "engine_version": "0.1.0",
+      "artifact_url": "https://github.com/jhoetter/hof-engine/releases/download/components-0.1/hof-components.tar.gz",
+      "sha256": "1af4bf05df285815a6ca35af3a9a4eba0473325c451e9265547e51996994c24f",
+      "published_at": "2026-03-10T17:14:40Z"
+    }
+  ]
+}

hof_engine-0.1.0/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md — hof-engine
+
+## What this repo is
+
+hof-engine is the **core framework** for building full-stack Python + React applications. It is distributed as a pip package (`pip install hof-engine`) and provides:
+
+- **Tables** — 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
+- **Cron** — scheduled tasks via Celery Beat
+- **Admin UI** — React dashboard (flow viewer, table browser, pending actions)
+- **CLI** — `hof` command for dev server, migrations, scaffolding, module management
+- **LLM integration** — `@prompt()` decorator with structured outputs via llm-markdown
+- **React hooks** — `@hof-engine/react` npm package (`hof-react/` directory)
+
+## What does NOT belong here
+
+- **Customer-specific business logic** — belongs in the customer repo
+- **Reusable modules** (tables, flows, functions, UI for specific use cases like lead enrichment, billing) — belongs in **hof-components**
+- **Deployment, server provisioning, DNS, infrastructure** — belongs in **hof-os**
+- **Design tokens, brand colors, Tailwind themes** — belongs in **design-system-\<customer\>** repos (managed by hof-os)
+- **Application examples** — belong in **hof-components** (as modules or in `docs/examples/`)
+
+## Ecosystem
+
+This repo is part of the bithof platform (hof-os, hof-engine, hof-components, design-system-\<customer\>, customer-\<name\>). For the full ecosystem map, repo boundaries, and ownership rules, see:
+
+```
+~/repos/hof-os/docs/ecosystem.md
+```
+
+## Repo Structure
+
+```
+hof-engine/
+├── hof/                    # Main Python package (this ships in the pip wheel)
+│   ├── api/                # FastAPI server, routes, auth
+│   ├── cli/                # CLI commands (dev, db, flow, fn, table, cron, new, add)
+│   ├── core/               # Registry, discovery
+│   ├── db/                 # SQLAlchemy engine, migrations
+│   ├── flows/              # Flow execution engine
+│   ├── llm/                # LLM decorators and integration
+│   └── ui/
+│       ├── admin/          # Admin React UI (pre-built to dist/ for pip wheel)
+│       └── vite.py         # ViteManager for user React components
+├── hof-react/              # @hof-engine/react npm package (hooks for customer UIs)
+├── docs/                   # Framework reference documentation
+│   ├── guide/              # Getting started
+│   └── reference/          # Tables, functions, flows, UI, CLI, config, LLM
+├── tests/                  # pytest test suite
+├── hatch_build.py          # Hatch hook: compiles admin UI before wheel build
+├── pyproject.toml          # Package config, dependencies, build settings
+└── .github/workflows/      # CI + PyPI publish
+```
+
+## Rules for AI agents
+
+1. **Framework only.** Every change here should benefit ALL customer projects, not just one. If it's specific to a use case, it belongs in hof-components.
+
+2. **The pip wheel must be self-contained.** The admin UI ships as pre-built static assets (`hof/ui/admin/dist/`). Never add runtime dependencies on Node.js, hof-components, or hof-os.
+
+3. **The `hof add` CLI fetches from hof-components.** If you're adding a new module, add it to hof-components, not here. The `hof/cli/commands/add.py` command handles the copy.
+
+4. **`hof-react/` is a separate npm package.** It has its own `package.json`, `tsconfig.json`, and build step (`tsup`). Changes to React hooks go here, not in `hof/ui/admin/`.
+
+5. **Docs in this repo are framework reference only.** Application examples and tutorials belong in hof-components (`docs/examples/`).

hof_engine-0.1.0/Dockerfile

@@ -0,0 +1,52 @@
+# Multi-stage Dockerfile for hof-engine applications
+# Stage 1: Python dependencies
+FROM python:3.11-slim AS python-deps
+
+WORKDIR /app
+
+# Install system dependencies required by psycopg2 and other packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml ./
+RUN pip install --upgrade pip && pip install -e ".[dev]"
+
+# Stage 2: Node.js for building the admin UI and user UI
+FROM node:20-slim AS node-builder
+
+WORKDIR /app/hof/ui/admin
+COPY hof/ui/admin/package*.json ./
+RUN npm ci --silent
+
+COPY hof/ui/admin/ ./
+RUN npm run build
+
+# Stage 3: Final runtime image
+FROM python:3.11-slim AS runtime
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy installed Python packages from deps stage
+COPY --from=python-deps /usr/local/lib/python3.11 /usr/local/lib/python3.11
+COPY --from=python-deps /usr/local/bin /usr/local/bin
+
+# Copy application source
+COPY hof/ ./hof/
+COPY pyproject.toml ./
+
+# Copy built admin UI
+COPY --from=node-builder /app/hof/ui/admin/dist ./hof/ui/admin/dist
+
+# Create a non-root user
+RUN useradd --create-home --shell /bin/bash hof
+USER hof
+
+EXPOSE 8001
+
+CMD ["uvicorn", "hof.api.server:create_app", "--factory", "--host", "0.0.0.0", "--port", "8001"]

hof_engine-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: hof-engine
+Version: 0.1.0
+Summary: Full-stack Python + React framework for building applications with workflows, tables, UIs, and LLM integration.
+Project-URL: Homepage, https://github.com/jhoetter/hof-engine
+Project-URL: Documentation, https://github.com/jhoetter/hof-engine/tree/main/docs
+Project-URL: Repository, https://github.com/jhoetter/hof-engine
+Author: Johannes Hoetter
+License-Expression: MIT
+Keywords: framework,full-stack,llm,react,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.14.0
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: celery[redis]>=5.4.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: llm-markdown[openai]>=0.3.0
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: redis>=5.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
+Requires-Dist: typer>=0.15.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: websockets>=14.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# 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
+
+## Quick Start
+
+```bash
+pip install hof-engine
+hof new project my-app
+cd my-app
+```
+
+Define a table:
+
+```python
+# 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:
+
+```python
+# functions/greet.py
+from hof import function
+
+@function
+def greet(name: str) -> dict:
+    return {"message": f"Hello, {name}!"}
+```
+
+Define a flow:
+
+```python
+# 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:
+
+```bash
+hof db migrate
+hof dev
+```
+
+## Requirements
+
+- Python 3.11+
+- Node.js 18+ (for React UI)
+- PostgreSQL
+- Redis
+
+## Documentation
+
+See the [docs/](docs/) directory:
+
+- [Getting Started](docs/guide/getting-started.md)
+- [Tables Reference](docs/reference/tables.md)
+- [Functions Reference](docs/reference/functions.md)
+- [Flows Reference](docs/reference/flows.md)
+- [UI Reference](docs/reference/ui.md)
+- [LLM Reference](docs/reference/llm.md)
+- [CLI Reference](docs/reference/cli.md)
+- [Configuration](docs/reference/config.md)
+
+## Ecosystem
+
+hof-engine is part of the bithof platform:
+
+| Repo | Role |
+|---|---|
+| **hof-engine** (this repo) | Core framework (pip package) |
+| [hof-components](https://github.com/jhoetter/hof-components) | Reusable modules and templates, copied via `hof add` |
+| [hof-os](https://github.com/jhoetter/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](https://github.com/jhoetter/customer-acme-test) | Example customer project |
+
+For application examples, see [hof-components/docs/examples/](https://github.com/jhoetter/hof-components/tree/main/docs/examples).
+
+## 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:
+
+1. Go to [PyPI Trusted Publishers](https://pypi.org/manage/account/publishing/).
+2. Add a publisher with:
+   - PyPI project name: `hof-engine`
+   - Owner/repo: your GitHub repo for this project
+   - Workflow: `publish.yml` (filename only)
+   - Environment: `pypi`
+3. In GitHub, create an environment named `pypi` (recommended to require manual approval).
+
+Optional setup for TestPyPI:
+
+1. Go to [TestPyPI Trusted Publishers](https://test.pypi.org/manage/account/publishing/).
+2. 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`
+3. In GitHub, create an environment named `testpypi`.
+
+Release flow:
+
+1. Bump/update code as needed and push to default branch.
+2. Create and push a git tag like `v0.1.1` (`git tag v0.1.1 && git push origin v0.1.1`).
+3. The workflow builds and uploads the package to PyPI under your account/project ownership.
+4. 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`.

hof_engine-0.1.0/README.md

@@ -0,0 +1,150 @@
+# 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
+
+## Quick Start
+
+```bash
+pip install hof-engine
+hof new project my-app
+cd my-app
+```
+
+Define a table:
+
+```python
+# 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:
+
+```python
+# functions/greet.py
+from hof import function
+
+@function
+def greet(name: str) -> dict:
+    return {"message": f"Hello, {name}!"}
+```
+
+Define a flow:
+
+```python
+# 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:
+
+```bash
+hof db migrate
+hof dev
+```
+
+## Requirements
+
+- Python 3.11+
+- Node.js 18+ (for React UI)
+- PostgreSQL
+- Redis
+
+## Documentation
+
+See the [docs/](docs/) directory:
+
+- [Getting Started](docs/guide/getting-started.md)
+- [Tables Reference](docs/reference/tables.md)
+- [Functions Reference](docs/reference/functions.md)
+- [Flows Reference](docs/reference/flows.md)
+- [UI Reference](docs/reference/ui.md)
+- [LLM Reference](docs/reference/llm.md)
+- [CLI Reference](docs/reference/cli.md)
+- [Configuration](docs/reference/config.md)
+
+## Ecosystem
+
+hof-engine is part of the bithof platform:
+
+| Repo | Role |
+|---|---|
+| **hof-engine** (this repo) | Core framework (pip package) |
+| [hof-components](https://github.com/jhoetter/hof-components) | Reusable modules and templates, copied via `hof add` |
+| [hof-os](https://github.com/jhoetter/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](https://github.com/jhoetter/customer-acme-test) | Example customer project |
+
+For application examples, see [hof-components/docs/examples/](https://github.com/jhoetter/hof-components/tree/main/docs/examples).
+
+## 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:
+
+1. Go to [PyPI Trusted Publishers](https://pypi.org/manage/account/publishing/).
+2. Add a publisher with:
+   - PyPI project name: `hof-engine`
+   - Owner/repo: your GitHub repo for this project
+   - Workflow: `publish.yml` (filename only)
+   - Environment: `pypi`
+3. In GitHub, create an environment named `pypi` (recommended to require manual approval).
+
+Optional setup for TestPyPI:
+
+1. Go to [TestPyPI Trusted Publishers](https://test.pypi.org/manage/account/publishing/).
+2. 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`
+3. In GitHub, create an environment named `testpypi`.
+
+Release flow:
+
+1. Bump/update code as needed and push to default branch.
+2. Create and push a git tag like `v0.1.1` (`git tag v0.1.1 && git push origin v0.1.1`).
+3. The workflow builds and uploads the package to PyPI under your account/project ownership.
+4. 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`.