LuxForge Foundry

Foundry is the shared Python foundation for LuxForge applications.

It provides reusable capabilities that would otherwise be reimplemented across projects — logging, file handling, database utilities, terminal components, shared helpers, and other common application infrastructure.

The package is distributed publicly as luxforge while exposing the foundry Python namespace.

Documentation: see docs/ — how to use Foundry, how to use @luxforge/framework, and the LuxFilm demo app both are proven against.

Installation

Install the latest public release from PyPI:

pip install luxforge

Install the supported PostgreSQL and database-lifecycle facilities with:

pip install "luxforge[postgres]"

Then import only the capabilities you need:

from foundry.logger import logger

For local Foundry development:

git clone <repository-url>
cd Foundry
pip install -e .

What Foundry Provides

Foundry is intended to be a collection of independently reusable capabilities rather than a framework that applications must adopt wholesale.

Current areas include:

• Logging — shared structured logging through foundry.logger
• Files — common file reading, writing, and discovery utilities
• PostgreSQL — connections, transactions, COPY, introspection, managers, durable SQL resources, dependency ordering, managed imports, checksums, validation, and guarded lifecycle operations
• Colours — shared colour and terminal presentation utilities
• Menu — reusable terminal menu and input handling
• Utilities — common helpers used across LuxForge software

Applications can use a single Foundry capability without needing to initialise or depend on the rest of the library.

For example:

from foundry.logger import logger

logger.info("Application started")

Package Structure

Foundry uses a standard src-based Python package layout:

src/
└── foundry/
    ├── colours/
    ├── files/
    ├── logger/
    ├── menu/
    ├── postgres/
    │   └── lifecycle/
    └── utils/

See docs/builtin/foundry/postgres.md for the supported PostgreSQL API and complete lifecycle model.

The public import namespace is deliberately kept separate from the distribution name:

PyPI distribution:  luxforge
Python namespace:    foundry

This means consumers install:

pip install luxforge

and use:

from foundry.logger import logger

Development

Run the Foundry health check:

pwsh .\tooling\build\check.ps1

A successful check reports:

BUILD STATUS: GREEN

Build the package with:

pwsh .\tooling\build\build.ps1

The build process produces both a wheel and source distribution under dist/.

Release builds are verified by installing the generated wheel into a clean environment and testing the public Foundry imports before publication.

Running LuxFilm with Docker

LuxFilm (packages/framework/demo) — Foundry's own @luxforge/framework proving ground — can run as two containers: the Foundry Runtime API and the built frontend, served by nginx.

docker compose -f docker/compose.yaml build
docker compose -f docker/compose.yaml up -d
docker compose -f docker/compose.yaml down

• Frontend: http://localhost:8080
• API: http://localhost:8420 (/foundry/*)

Environment variables (set in docker/compose.yaml, or override via docker compose -f docker/compose.yaml run -e ... / a .env file compose picks up automatically):

• FOUNDRY_RUNTIME_HOST / FOUNDRY_RUNTIME_PORT — what the API binds to inside its container. Defaults to 0.0.0.0:8420; a container needs this bind (unlike a bare-metal dev machine) since the port mapping, not the app's own bind address, is what controls real exposure.
• FOUNDRY_ALLOWED_ORIGINS — CORS origins the API accepts, since the browser calls it directly from the frontend's own origin (a different port). Defaults to http://localhost:8080.
• VITE_API_URL — a frontend build argument (docker/compose.yaml's frontend.build.args), baked into the static output at build time. Where the browser reaches the API; defaults to http://localhost:8420.

If you change host ports in docker/compose.yaml, update FOUNDRY_ALLOWED_ORIGINS and VITE_API_URL to match — otherwise the frontend and API can't talk to each other.

This is local/demo tooling, not a production deployment topology — see foundry.runtime's own docs for why Foundry Runtime is normally mounted into a host application rather than run as its own public service.

Releases

Foundry has a guided release process:

pwsh .\tooling\release.ps1

The release tooling validates the repository, version, package, tests, Git state, built artifacts, and installed wheel before creating and publishing a release.

Releases are distributed to:

• PyPI — public distribution as luxforge
• Azure Artifacts — LuxForge package feed

Public installation therefore requires no LuxForge-specific package configuration:

pip install luxforge

Direction

Foundry exists to make common LuxForge capabilities something that is built once, tested once, and reused everywhere.

As shared functionality matures, it belongs in Foundry rather than being independently recreated inside each application.