Skip to content

Developer setup

Logic-Loom is two source trees wired together at runtime:

  • apps/desktop/: the Tauri shell (Rust, src-tauri/) and the Vite + React 19 + TypeScript frontend (src/). pnpm workspace package logic-loom-desktop.
  • services/logic_loom_api/: the logic-loom-api FastAPI sidecar. uv workspace member.

Supporting folders: packaging/ (PyInstaller entrypoint), scripts/ (build and release helpers) and docs/ (this site).

Requirements

  • Python 3.12 (>=3.12,<3.13) and uv
  • Node.js 20 or later and pnpm 11
  • Rust stable, plus the Tauri system dependencies for your OS (see Build from source)

Run it

uv sync                  # core: zsum, Assistant
pnpm install
pnpm logic-loom:dev      # starts the sidecar, Vite and the Tauri shell together

Add extras to unlock the gated modes:

uv sync --extra akms                          # AKMS mode
uv sync --all-packages --all-extras           # every mode

No AKMS or zotero-summarizer source checkout is needed. akms_repo, zsum_repo and logic_loom_root are optional developer overrides; with akms_repo set you also get the legacy in-repo batch plan, Packages/Nodes_Vault, and the /api/nlm and node-promote developer scripts.

Other ways to run parts of the app:

uv run logic-loom-api --port 17321            # sidecar on its own
curl localhost:17321/api/app/health

pnpm fe:dev                                   # Vite without Tauri; set VITE_LOGIC_LOOM_API_BASE
pnpm fe:gen:types                             # regenerate src/api/openapi.ts from a sidecar on :17321

Run in a browser, without WebKitGTK

The desktop shell needs WebKitGTK on Linux, but the app itself is a web frontend talking to the sidecar over HTTP. When a release build will not start, or WebKitGTK cannot be installed, run the two halves yourself and use an ordinary browser. This needs Python 3.12, uv, Node.js 20 or later and pnpm 11, but no Rust and no system libraries.

uv sync --all-packages --all-extras            # or plain `uv sync` for the core modes
pnpm install

# terminal 1: the API
uv run logic-loom-api --port 17321

# terminal 2: the frontend
VITE_LOGIC_LOOM_API_BASE=http://127.0.0.1:17321 pnpm fe:dev

To exercise the token check as the desktop app does, start the API with LOGIC_LOOM_API_TOKEN=<32+ characters> and the frontend with the same value in VITE_LOGIC_LOOM_API_TOKEN.

Then open http://localhost:1420. The sidecar only accepts browser requests from that origin, so keep the frontend on port 1420. Everything works as in the desktop app except the buttons that call into the desktop shell, such as the system folder picker and "Open folder"; type paths into those fields instead.

Tests

uv run pytest services/logic_loom_api/tests -q          # backend
pnpm --filter logic-loom-desktop test                   # frontend (vitest)
pnpm --filter logic-loom-desktop build                  # tsc + vite build

Tests that touch run history need a temporary cache_path; the backend test suite already isolates config, workspace and cache from your real ones.

Docs

This site is built with MkDocs Material from docs/.

uv sync --all-packages --all-extras --group docs
uv run python scripts/gen_docs_reference.py   # regenerate the configuration and API reference pages
uv run mkdocs serve                           # live preview at http://127.0.0.1:8000
uv run mkdocs build --strict                  # what CI runs on every PR

Pull requests that touch the docs build them strictly. Pushing a v* tag to the public repository rebuilds and publishes the site, so the published docs always match the latest release.

Failure Memory lessons

Logic-Loom records its own failure lessons in .failure-memory/, and CI (.github/workflows/failure-memory.yml) runs validate, check and tests/failure_memory on every PR that touches them.

uv sync --extra failure-memory

# Record a lesson (interactive, or --from-json for a prepared lesson)
uv run failure-memory add --interactive \
  --config .failure-memory/config.toml \
  --global-vault ~/.claude/akms/nodes

uv run failure-memory validate --config .failure-memory/config.toml
uv run failure-memory check --config .failure-memory/config.toml \
  --global-vault ~/.claude/akms/nodes

--global-vault is only used to check lesson ids against a global node corpus. Any directory works, including an empty one (mkdir -p ~/.claude/akms/nodes), which is what CI passes.

lessons.json is the source of truth; never append to it with your own code. The route index and node mirrors under .failure-memory/ are generated by compile and committed, and check fails if they do not match the registry. See the akms-failure-memory docs for the lesson format.