Metadata-Version: 2.5
Name: hindsight-pg0-configurable
Version: 0.1.0
Summary: Configurable native PostgreSQL and pgvector launcher for Hindsight on Windows
Author: Dark Light
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: licenses/PostgreSQL.txt
License-File: licenses/Theseus.txt
License-File: licenses/pgvector.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database :: Database Engines/Servers
Requires-Python: >=3.11
Requires-Dist: filelock<4,>=3.20.1
Requires-Dist: python-dotenv<2,>=1.2.1
Provides-Extra: full
Requires-Dist: hindsight-api<2,>=1.0.0; extra == 'full'
Provides-Extra: slim
Requires-Dist: hindsight-api-slim<2,>=1.0.0; extra == 'slim'
Description-Content-Type: text/markdown

# 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:

```powershell
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:

```powershell
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.

```powershell
$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.

```powershell
$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:

```powershell
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.

```powershell
python -m hindsight_pg0_configurable status
python -m hindsight_pg0_configurable start
python -m hindsight_pg0_configurable stop
```

| Variable | Default / meaning |
| --- | --- |
| `HINDSIGHT_PG_INSTALLATION_DIR` | Required absolute native installation root |
| `HINDSIGHT_PG_STATE_DIR` | `%LOCALAPPDATA%\HindsightPg0` on Windows |
| `HINDSIGHT_PG_NAME` | `hindsight`; dedicated instance subdirectory |
| `HINDSIGHT_PG_PORT` | `55439`; explicit port, no automatic switching |
| `HINDSIGHT_PG_USERNAME` | `hindsight`; initial cluster owner |
| `HINDSIGHT_PG_DATABASE` | `hindsight` |
| `HINDSIGHT_PG_PASSWORD` | Optional initial password; otherwise generated |

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

```sh
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](https://hindsight.vectorize.io/developer/configuration),
[pg0 0.15.2 versions](https://github.com/vectorize-io/pg0/blob/v0.15.2/versions.env),
[PostgreSQL pg_ctl](https://www.postgresql.org/docs/current/app-pg-ctl.html).
