Installation¶

The package declares CPython 3.10 or newer. CI is configured to exercise Linux on Python 3.10 through 3.14 and Windows and macOS on Python 3.12. The core package contains the CLI, chunking algorithms, local SQLite index, embedding cache, offline hash provider, migration workflow, and benchmark fixtures.

Install from PyPI¶

Create a virtual environment for application use:

python -m venv .venv

Activate it on Linux or macOS:

source .venv/bin/activate

Activate it in PowerShell:

.venv\Scripts\Activate.ps1

Install Steadlith:

python -m pip install --upgrade pip
python -m pip install steadlith

Confirm both entry points:

steadlith --version
python -m steadlith --version

For a CLI-only machine, pipx can keep Steadlith isolated:

pipx install steadlith

Optional embedding providers¶

The default hash provider is included in the core package and makes no network requests. Install only the provider integration you need.

OpenAI:

python -m pip install "steadlith[openai]"

Sentence Transformers:

python -m pip install "steadlith[sentence-transformers]"

Both optional providers require --allow-network on commands that may contact an API or download a model. The confirmation applies to one command invocation. It is not stored in the project configuration.

Install from a source checkout¶

Use an editable install when contributing:

git clone https://github.com/satwiksps/steadlith.git
cd steadlith
python -m venv .venv

Activate the environment with the platform command shown above, then install:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

The repository main branch can be newer than the latest release. Use a tagged release when reproducibility matters.

Upgrade¶

Inspect the changelog and compatibility policy, then upgrade in the same environment:

python -m pip install --upgrade steadlith
steadlith --version
steadlith plan
steadlith verify

plan is read-only and reveals any identity or source-scope change before the index is modified.

When upgrading from 0.3, the first plan can report metadata-only move operations because 1.0 stores project-relative document paths instead of absolute paths. These operations do not require new embeddings; review the plan, then apply it with steadlith index to commit the portable metadata.

Users of Cairn 0.2 should follow Adopt a 0.2 project instead of renaming state files by hand.

Uninstall¶

Remove an environment installation with:

python -m pip uninstall steadlith

For pipx:

pipx uninstall steadlith

Package removal does not delete project data. With the default configuration, steadlith.toml, steadlith.toml.migration.json, and .steadlith/ can contain configuration, resolved paths, index data, cached embeddings, the manifest mirror, and migration records. If the migration journal exists, run steadlith migrate --recover before uninstalling or deleting data. Retain any required backup, then remove only the default files or the custom state paths and sidecars named by the configuration.

Troubleshooting installation¶

steadlith is not recognized

Run python -m steadlith --version. If that works, the environment’s script directory is not on PATH, or the virtual environment is not active.

No module named steadlith

Check python -m pip --version and python --version. They must refer to the same environment used for installation.

Optional provider import error

Install the matching extra. Provider SDKs are deliberately absent from the core installation.

SQLite error during startup

Confirm the state directory is writable and that the cache and index are different files. Paths must remain below the configuration directory.