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 packagelogic-loom-desktop.services/logic_loom_api/: thelogic-loom-apiFastAPI 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:
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.