AncestryLLM

AncestryLLM is a local-first toolset for people researching family history. It helps you work with RootsMagic and GEDCOM data using predictable local tools, with optional AI assistance only when you choose it.

The implemented product surfaces in 0.6.0 are the command-line interface (CLI), an interactive prompt, and a deliberately small desktop control shell. Your research remains yours: use fictional data while learning, and never put real family-tree files, reports, or credentials in this repository.

What you can do today

• Use the CLI for one task at a time, or open the interactive prompt for a local session.
• Work with genealogy research workflows that preserve RootsMagic inputs and handle GEDCOM data carefully.
• Install the released desktop control shell, which provides Home, Diagnostics, Settings, and capability onboarding.

The supported 0.6.0 desktop core is not a desktop genealogy application. It provides Home, Diagnostics, Settings, and capability onboarding. The installed shell also packages separately labeled provider and consent configuration, Tasks and Chat source-level surfaces; those surfaces remain unsupported until their named target-matched gates pass. They add no supported desktop genealogy or domain routes, file workflows, task admission, provider requests, cloud account use, or updater flow. Desktop genealogy workflows are not available yet; use the CLI or interactive prompt for supported genealogy work.

The 0.6.0 source includes a narrow desktop settings and credential management foundation. It can update five reviewed non-secret settings and can set, delete, or report only the presence of allowlisted credentials through the OS keyring. It cannot read credential values, select consent on your behalf, make a provider call, or run a genealogy workflow. This development surface is outside the supported packaged shell until its target-matched verification gates pass.

The 0.6.0 source also includes separate Local Providers, Cloud Providers, and Consent & Privacy settings. Saving a provider profile requires an explicit endpoint test and an optimistic-revision match. Creating consent requires a complete preview of the provider, profile, model, purpose, data classes, retention, warnings, and optional budget; living-person and remote-retention choices receive explicit warnings. A stored key alone cannot enable a provider, and this configuration surface does not execute provider requests.

The 0.6.0 source includes a Tasks destination for backend-owned work. It reloads sanitized snapshots, follows bounded monotonic events, distinguishes cancelling, pending-safe-point, cancelled, and terminal outcomes, and displays only safe artifact metadata. The renderer stores no job state and receives no path or artifact authority. This surface admits no work and adds no provider or genealogy operation.

The 0.6.0 source includes an internal asynchronous adapter for already authorized provider streams. Consent and capability checks complete before its provider worker starts; a bounded queue, per-chunk byte limit, absolute deadline, and cooperative cancellation constrain the stream. Success, failure, timeout, and cancellation each produce one privacy-minimal audit outcome. This is source-level groundwork only: it adds no Electron bridge, chat UI, public streaming transport, or network path for provider=none.

The 0.6.0 source includes a bounded transient-chat path and a Chat destination to the desktop source. Each short-lived conversation binds an exact stored provider profile, model, purpose, data class, and compatible current consent; message content remains process-memory-only. Electron Main owns the authenticated stream and native external-link confirmation. The renderer accepts only ordered, validated events, renders model Markdown through a closed element allowlist with raw HTML, images, embeds, and executable actions disabled, and copies plain text only. This remains outside the supported packaged shell until the target-matched packaged and adversarial gates pass.

The 0.6.0 desktop source recommends Local Desktop on first run and keeps Connect Remote and Host Remote visible but unavailable. Before it enables settings or credential changes, the shell checks a sanitized schema-v1 startup report for configuration, SQLCipher, keyring, and workspace readiness. If a required component is blocked, the application stays open in read-only Diagnostics and gives stable recovery guidance; it does not repair configuration, initialize a database, replace a key, or fall back to plaintext. The packaged sidecar reads credentials only from the OS keyring. The documented environment fallback remains limited to explicit CLI and headless use.

The 0.6.0 source also includes the deployment-profile control plane. Local Desktop is the preselected, recommended mode. The CLI can inspect, preview, diagnose, and explicitly recover the versioned profile without discovering a mode from the network, environment, Docker, or ambient services. Connect to Remote and Host Remote Server remain advanced, unavailable runtime choices until their separate enrollment, host-bootstrap, and release gates pass; selecting a profile never starts a listener or moves genealogy data.

Issue #348 adds a user-visible macOS arm64 local-runtime manager to the 0.6.0 source on top of that host-only control foundation. After explicit review and confirmation it can acquire exact checksum-pinned Colima/Lima, Docker CLI, Compose, and Buildx artifacts into an app-owned profile and context, then start, stop, repair, or remove that substrate. Docker Desktop remains optional and compatible; AncestryLLM neither selects nor changes its context. Docker authority never enters the renderer, preload bridge, sidecar, or managed containers. This work does not start an AncestryLLM application container, activate a deployment profile, mount genealogy data, or weaken the network-free provider=none contract. See the published deployment operations guide for the trust boundary, recovery procedure, and residual risk.

Issue #349 adds a minimal, production-shaped OCI and Compose verification topology for one probe-only gateway and an optional dormant worker. The images are built and exercised natively on Linux amd64 and arm64 in CI, expose no host ports, run non-root with read-only roots and bounded resources, and contain no genealogy or provider route. A read-only named-volume attachment is a policy placeholder only: storage initialization, schema migration, secret delivery, and profile activation remain blocked until their separate #350 and #351 controls pass. The topology is release evidence, not a supported deployment runbook or application-container availability claim.

Start here

Choose the path that matches how you want to use AncestryLLM.

Use the CLI or interactive prompt

You will need Python 3.12 through 3.14 and a working OS credential store.

1. Install AncestryLLM as an isolated command with either uv or pipx:

   uv tool install ancestryllm
   # or
   pipx install ancestryllm
   ancestry --version
   

   If you are already working in an activated virtual environment, ordinary pip remains supported:

   python -m pip install ancestryllm
   

   For optional AI assistance, use uv tool install 'ancestryllm[all-llm]', pipx install 'ancestryllm[all-llm]', or the corresponding ordinary pip command in place of the base install. Installing an extra still does not select a provider or authorize a cloud call.

2. Run ancestry --help to see available commands, or run ancestry to open the interactive prompt.

On a minimal or headless system, first follow the setup diagnostics. They cover a supported credential backend and the headless/CI environment-injection fallback for ephemeral test secrets. Run ancestry --json database diagnose before opening an encrypted workspace.

Work from source

A source checkout requires a system-supplied Python 3.12 through 3.14. The checked-in .python-version selects 3.12 by default; repository uv policy never downloads Python. After authenticating as described in the verified uv bootstrap guide, run:

make setup
make test

make setup verifies exactly uv 0.12.1 and synchronizes all application extras and dependency groups from uv.lock. Do not create a separate pip-managed development environment or install uv from PATH.

Use the desktop control shell

Desktop installation does not require Python or pipx. Download the target-matched full installer and SHA256SUMS from the same immutable official release. Verify the checksum and declared binarySigningMode, then install, relaunch, and confirm healthy Diagnostics. If startup is degraded, keep the shell in its read-only state and follow the component-specific recovery shown in Diagnostics before retrying once or relaunching. Read the desktop installation and verification procedure before downloading.

For examples and a complete command reference, read the CLI guide. For help using the interactive prompt, read the REPL guide.

Privacy and provider choices

AncestryLLM works locally by default. Provider none is network-free even if environment keys or provider software are present. A cloud call requires explicit provider selection and your consent; installed packages and environment keys never choose a remote provider for you.

Credentials belong in your OS keyring. Keep real genealogy records, exports, backups, logs, prompts, and secrets out of the repository. Learn the details in the privacy and consent guide and the provider guide.

Learn more

• Understand the released desktop shell and its limits.
• Check GEDCOM compatibility and interoperability limits.
• Learn how AncestryLLM protects file imports.
• Read the documentation site for guides and reference material.
• Contribute to AncestryLLM if you are working on the project itself.
• Maintain locked dependency environments when changing application extras or repository tool groups. Source checkouts use make setup; the former dev extra is no longer an installation path.