Blinkin Legacy Docs Docs
Porting · porting/2026-05-05-zweistein-python-services-local-probe.md Docs Home

Zweistein Python Services Local Probe

Date: 2026-05-05

Objective

Start the local rebuild of the imported Zweistein Python services:

  • python_server/query_engine: FastAPI query engine for chat, agentic apps, tools, RAG, media routing, and model orchestration.
  • python_server/ingestion_worker: Redis worker for document/media ingestion and indexing.

This slice verifies metadata, local Python selection, placeholder env coverage, partial Query Engine install, and the current blocker.

What Was Added

  • legacy-src/zweistein/python_server/query_engine/README.md
  • legacy-src/zweistein/python_server/ingestion_worker/README.md

The Poetry metadata referenced README.md, but the files were missing in the imported snapshot.

  • configs/local/zweistein-query-engine.env.example Complete local placeholder values for Query Engine required settings.
  • configs/local/zweistein-ingestion-worker.env.example Complete local placeholder values for Ingestion Worker required settings.
  • scripts/zweistein-python-local.mjs Small helper for Poetry checks, Python 3.12 environment selection, dry-run install plans, disk readiness checks, guarded install commands, import probes, Docker Torch probes, and Docker build attempts.
  • scripts/hetzner-python-gate.mjs Server-side follow-up helper for the same Python blocker on native Linux/amd64.
  • package.json scripts:
    • zweistein-python:check
    • zweistein-python:disk
    • zweistein-query:env
    • zweistein-query:install:plan
    • zweistein-query:install
    • zweistein-query:import
    • zweistein-query:main-import
    • zweistein-query:docker-torch-probe
    • zweistein-query:docker-build
    • zweistein-ingestion:env
    • zweistein-ingestion:install:plan
    • zweistein-ingestion:install
    • zweistein-ingestion:import
    • zweistein-ingestion:docker-build

Sensitive Data Cleanup

During Python inspection, API-key-like defaults were found in the imported local Query Engine settings. A JWT-like Studio API fixture was also found during the expanded scan.

The local copy now uses placeholders instead. The foundation verifier now fails if it sees common hardcoded secret patterns such as private keys, JWT-like tokens, NVIDIA API keys, Google API keys, AWS keys, GitHub tokens, Stripe webhook secrets, or Stripe live/test secrets.

Local Commands

Check Poetry metadata for both services:

npm run zweistein-python:check

Check whether the current machine has enough disk for local Python installs/builds:

npm run zweistein-python:disk

Select Python 3.12 for Query Engine:

npm run zweistein-query:env

Preview the Query Engine install without writing packages:

npm run zweistein-query:install:plan

Attempt Query Engine dependency install:

npm run zweistein-query:install

Run the lightweight Query Engine import probe:

npm run zweistein-query:import

Run the Query Engine FastAPI app import probe:

npm run zweistein-query:main-import

Check the Hetzner-like Linux/amd64 Torch wheel without doing a full image build:

npm run zweistein-query:docker-torch-probe

Attempt the legacy Query Engine Dockerfile path:

npm run zweistein-query:docker-build

Select Python 3.12 for Ingestion Worker:

npm run zweistein-ingestion:env

Preview the Ingestion Worker install without writing packages:

npm run zweistein-ingestion:install:plan

Verification Evidence

  • poetry check initially failed for both Python services because README.md was missing.
  • After adding local placeholder READMEs, npm run zweistein-python:check passed for both services with Poetry 2 metadata warnings only.
  • npm run zweistein-query:env selected /opt/homebrew/bin/python3.12.
  • Raw POETRY_VIRTUALENVS_IN_PROJECT=true poetry install --no-root --no-interaction --no-ansi for Query Engine created a local .venv and installed many dependencies.
  • Query Engine install stopped with torch (2.10.0+cpu) because Poetry could not find a compatible wheel for this local macOS/Python 3.12 environment from the configured pytorch-cpu source.
  • npm run zweistein-query:import succeeded for the partial environment and printed:
3.12.12
0.111.1
  • poetry run python -c "import torch" failed with ModuleNotFoundError, confirming the Torch dependency is not installed.
  • npm run zweistein-query:main-import reached the legacy FastAPI app import path and then failed at llama_index.postprocessor.colbert_rerank, which imports torch. This confirms the next local startup blocker is the missing Torch dependency, not missing env placeholders.
  • npm run zweistein-ingestion:env created the local Ingestion Worker Python 3.12 environment.
  • npm run zweistein-python:disk reports the current Mac has about 1.9 GiB free at the project path, below the 8 GiB local Poetry install guard and the 20 GiB local Docker build guard.
  • npm run zweistein-query:install:plan reports only one remaining Query Engine install operation in the current local venv: torch (2.10.0+cpu).
  • npm run zweistein-ingestion:import currently fails at the first import because redis is not installed in the Ingestion Worker venv.
  • npm run zweistein-ingestion:install:plan reports 307 installs, including redis, opencv-python, spider-rs, torch (2.5.1), and openai-whisper.
  • npm run zweistein-ingestion:install is now guarded and refuses to run on this Mac while free disk is below 8 GiB. It prints a short no-stacktrace message and points to the install-plan commands or Hetzner/native Linux.
  • npm run legacy:verify now reports potential hardcoded secrets: 0.
  • docker run --rm --platform linux/amd64 python:3.11-slim python -m pip install --dry-run --index-url https://download.pytorch.org/whl/cpu 'torch==2.10.0+cpu' passed. The Linux container resolved torch-2.10.0+cpu-cp311-cp311-manylinux_2_28_x86_64.whl and ended with Would install ... torch-2.10.0+cpu ....
  • docker build --platform linux/amd64 -f legacy-src/zweistein/python_server/query_engine/devops/docker/Dockerfile -t legacy-blinkin-query-engine:local legacy-src/zweistein/python_server/query_engine started the real legacy Query Engine Dockerfile path. It installed Debian build tooling, Rust, Poetry 1.8.3, the first locked dependency set, and reached torch (2.6.0+cpu), transformers, weaviate-client, crewai, presidio, spider-rs, and other service dependencies before becoming effectively idle while building the native spider-rs wheel under Docker Desktop amd64 emulation. The build container was stopped deliberately and the generated intermediate container/image were removed.

Current Blocker

The Query Engine lock resolves torch to a CPU wheel from the explicit pytorch-cpu source. That source did not provide a compatible wheel for this Mac/Python 3.12 setup.

The Linux/amd64 Docker probe confirms that the required CPU Torch wheel is available for a Hetzner-like Linux target. The remaining blocker is no longer Torch availability on Linux; it is that a full old Query Engine image build is too heavy and unreliable under Docker Desktop amd64 emulation on this Mac.

For the Hetzner path, the next decision should be one of:

  • verify the full Query Engine Docker build on a native Linux amd64 machine or Hetzner staging box with npm run hetzner:python:build:query;
  • verify the Ingestion Worker Docker build on the same target with npm run hetzner:python:build:ingestion;
  • run npm run hetzner:python:imports, npm run hetzner:python:up, and npm run hetzner:python:health before continuing the full stack;
  • pin a macOS-compatible local development Torch source/version separately from production;
  • split heavyweight ML dependencies behind optional groups so lightweight API/import checks can run without Torch;
  • regenerate the lockfile for the target Hetzner architecture after choosing the runtime image.

Not Yet Done

  • Query Engine does not fully install locally on macOS yet.
  • Query Engine Docker build has not completed on this Mac under amd64 emulation.
  • Query Engine FastAPI app was not started.
  • Ingestion Worker dependencies were not installed. The dry-run install plan requires 307 packages and should run on Hetzner/native Linux or a local machine with much more free disk.
  • Ingestion Worker Docker build was not attempted yet.
  • Redis worker processing was not exercised.
  • Weaviate/vector storage was not exercised.
  • Document/media ingestion, OCR, transcription, RAG, and agentic tool routes were not tested.
  • The final Docker/Hetzner Python runtime shape is not decided yet.