hindsight-pg0-configurable

Run Hindsight with PostgreSQL and pgvector in an explicitly configured native installation directory. Database data, credentials, locks and logs live in a separate writable state directory. Intended for native Windows x86-64 setups where application-control policy prohibits executing PostgreSQL from a user profile. No Docker, service registration, symbolic links or runtime downloads.

Initial alpha release. The Python launcher and Windows archive layout are checked on macOS; execution of these binaries under Windows and any corporate policy is not yet validated. This package does not grant execution rights. The selected executable directory and its EXE/DLL files must be permitted by IT.

This is an independent launcher, not an official Hindsight or pg0 release. It does not replace the pg0 Python module or satisfy a dependency named pg0-embedded. It uses Hindsight's supported HINDSIGHT_API_DATABASE_URL setting, so an installed original pg0 package can coexist without being used by this launcher. Launch through this package, rather than hindsight-api.

Install through PyPI or your Artifactory PyPI proxy

Use Python 3.11 or newer and the same Python environment for all commands:

python -m pip install "hindsight-pg0-configurable[full]==0.1.0"

For a slim Hindsight installation, use [slim] instead of [full]; configure your embedding and reranking providers as required by Hindsight. If Hindsight is already installed in this environment, the base package is sufficient:

python -m pip install hindsight-pg0-configurable==0.1.0

The optional extras accept Hindsight 1.x. Actual availability of Hindsight's transitive dependencies depends on your Artifactory mirror and Python version. The launcher does not configure or download LLMs or embedding models.

Prepare PostgreSQL once

Replace the example executable path with the directory approved by your IT. The installation root will contain bin, lib, and share. Preparation needs write access to the destination's parent directory; a destination may be absent or empty. A populated directory is never overwritten. An IT operator may prepare the directory and subsequently grant normal users read/execute access.

$env:HINDSIGHT_PG_INSTALLATION_DIR = 'C:\Program Files\Firma\Hindsight\PostgreSQL-18.1'
python -m hindsight_pg0_configurable prepare

The wheel and source distribution already contain PostgreSQL 18.1.0 and pgvector 0.8.5 Windows archives, the same versions used by pg0-embedded 0.15.2. Preparation checks their pinned SHA-256 digests and copies real files into the requested location. It does not execute the archives' contents. Runtime startup only reads this native installation and does not unpack or update it.

Alternatively provision a compatible PostgreSQL installation with pgvector through IT and point the launcher at its installation root; prepare is then unnecessary. prepare bundles Windows x86-64 only. An explicitly supplied native installation also permits development checks on other operating systems.

Configure and run Hindsight

Set these variables in every new terminal or persist them in your approved launcher configuration. No registry changes are made by this package.

$env:HINDSIGHT_PG_INSTALLATION_DIR = 'C:\Program Files\Firma\Hindsight\PostgreSQL-18.1'
$env:HINDSIGHT_PG_STATE_DIR = "$env:LOCALAPPDATA\Firma\HindsightPg0"

# Add your normal HINDSIGHT_API_LLM_* / embeddings / reranker configuration.
python -m hindsight_pg0_configurable run

Pass ordinary Hindsight foreground options after --, for example:

python -m hindsight_pg0_configurable run -- --host 127.0.0.1 --port 8888

The launcher initializes a dedicated cluster on first start, binds PostgreSQL to 127.0.0.1:55439, creates the database and enables pgvector, and supplies Hindsight's database URL. SCRAM authentication uses a generated password. Hindsight still requires your normal provider settings. The original hindsight-api command does not automatically adopt this configuration.

Provider settings in a discovered .env are loaded first. The launcher then sets its own database URL and disables further dotenv reloads for the process and its workers. Existing read-replica and migration URL overrides are cleared for this dedicated local cluster. A stale .env therefore cannot switch it back to the original embedded pg0 or another database.

The cluster started by run stops when foreground Hindsight exits normally. A cluster already running before run is borrowed and remains running. --daemon is unsupported. An abrupt process kill can leave PostgreSQL running; use status and stop to manage this dedicated instance.

python -m hindsight_pg0_configurable status
python -m hindsight_pg0_configurable start
python -m hindsight_pg0_configurable stop

The state directory stores the password in <name>\manager.json and must remain private to the user. POSIX state files use mode 0600; Windows uses the directory's inherited ACLs. Public status output excludes passwords and URLs. This package never deletes clusters or imports existing pg0 data. A nonempty unmanaged data directory is refused. Existing instance settings must remain unchanged across restarts; choose another instance name for a separate setup.

For a new PostgreSQL or pgvector release, prepare a new installation directory and plan any required database migration separately. Upgrading this Python package alone does not modify installed native files or existing databases.

Build and release

python scripts/fetch_bundles.py
uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build
uv run twine check dist/*

scripts/fetch_bundles.py downloads only the pinned upstream release archives, verifies their hashes and adds them to the distribution data directory. The archives are not versioned in Git. Both wheel and sdist must contain them; inspect built distributions before publication. Publishing uses a PyPI API token from the environment, never from this repository.

Sources: Hindsight configuration, pg0 0.15.2 versions, PostgreSQL pg_ctl.