dcosnet
/
ai-lsc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ai-lsc/QA-PASS-REPORT.md

11 KiB
Raw Permalink Blame History

AI-LSC MoE QA Pass — Final Report

Source: ai-lsc-main(1).tar.gz Date: 2026-08-31 Pass scope: Surgical cleanup (one more pass after v3.1 critique + v3.2 taxonomy migration). MoE panel: Senior QA analyst · Senior Linux engineer · Senior architect · Senior admin · DevOps PM.

1. Standards referenced

Standard Application
PEP 868 / PEP 8 Type annotations, line length ≤100, import ordering.
POSIX sh / bash set -euo pipefail, no bashisms in sourced contexts.
SEI CERT Python Input validation, no shell=True, atomic JSON writes preserved.
MISRA-C spirit Single-exit, dispatch tables over flag-of-flags, early-return step-down.
Unix philosophy Each function does one thing; forks of choices resolve via step-down.

2. Wording sweep — "restored / brought back / related logic" eliminated

All instances rewritten as decisive statements. Source files touched:

File Line(s) Change
src/ai_lsc/registry/layers/routing.py docstring "Restored layer (v3.1.1b)" → "L5 (Intelligent API Routers & Proxies) holds …"; added source-of-truth note.
TODO.md 6 "restored in full from the v3.1.1b routing tarball" → "the canonical 1.3 k-line implementation now lives in-tree".
scripts/apply_10layer_taxonomy.py (now retired) 201, 668, 757 "restored from the routing tarball" → "canonical 124-category cascade"; "the restored Routing layer" → "the L5 Routing layer".
CHANGES.md 224, 254, 269, 321 "Restored in full from the v3.1.1b routing tarball" → "canonical 1.3 k-line implementation is re-established in-tree"; section header "Routing restored" → "Routing promoted to a first-class layer"; "(restored)" ladder annotation removed.
whatremains.txt 9 "the restored installer cmds" → "the canonical installer cmds".
docs/ADR-003-workspace-tab.md 67 "The empty-state placeholder is restored" → "the empty-state placeholder is shown again".

Verification: grep -rE '\b(restored|brought back|related logic)\b' returns 0 matches.

3. Author metadata

File Field Value
pyproject.toml authors, maintainers Jeremy Anderson <info@dcos.net>
README.md header Author + email + https://dcos.net link
README.md clone URL https://github.com/dcos-net/ai-lsc.git
LICENSE header AUTHOR + COPYRIGHT + HOMEPAGE = dcos.net

4. Code patterns — nested ifs → arrays/dispatch tables

4.1 src/ai_lsc/manifest/support.py — build_system_context

Replaced 6 cascaded if field: blocks with a single _FIELDS tuple + comprehension:

_FIELDS: tuple[tuple[str, str], ...] = (
    ("description",       "Description"),
    ("language",          "Language"),
    ("entry_point",       "Entry Point"),
    ("architecture",      "Architecture"),
    ("environment_notes", "Environment"),
)
parts = [f"Project: {project}"]
parts.extend(
    f"{label}: {manifest.get(key)}"
    for key, label in _FIELDS
    if manifest.get(key)
)

Added a "Source-of-truth boundary" docstring noting the manifest is a derived view; the registry layer files remain authoritative.

4.2 src/ai_lsc/manifest/support.py — resolve_context_files

Replaced outer-for + inner-for + if with a single list comprehension (one pass over patterns → files → filter).

4.3 src/ai_lsc/ui/pages/chatbot_console.py — _build_payload_history (M-40 / L-09)

Replaced the 3-way nested ternary parts[0] + "\n\n" + parts[1] if len(parts) == 2 else (parts[0] if parts else "") with the flat "\n\n".join(parts). Behavior preserved (empty parts → empty string).

4.4 src/ai_lsc/ui/pages/chatbot_console.py — HTML bubble builder (M-22)

Extracted _render_bubble(msg) helper. Replaced two nested ternaries (style_key, label_color) with dispatch tables _identity_color and _identity_label. The main loop is now a one-liner:

html += "".join(_render_bubble(m) for m in self.chat_messages)

5. Unix philosophy — step-down (early return) refactors

5.1 bootstrap.sh — base-dir detection (lines 70-100)

The 4-level nested if/elif/else (root → prompt → sudo/alt-base/error) was inverted to a step-down if/elif/else where each branch resolves one situation and exits the block. Removed one nesting level.

5.2 src/ai_lsc/runtime/installer.py — install_git / install_git_node

Both methods had a 3-way fork (pull / re-clone-on-failure / clone-non-git-dir / fresh-clone) with duplicated shutil.move + makedirs + git clone code across branches. Extracted:

  • _backup_existing(dest) -> str — single-purpose backup helper.
  • _clone_fresh(pkg, dest) -> None — single-purpose clone helper.

Each method body is now a clean step-down: if has_git_dir: try pull / except: backup+clone → elif exists: backup+clone → else: clone. Behavior identical; ~30 lines of duplication removed.

5.3 src/ai_lsc/registry/openengineer/importer.py — directory scan

The two for md_file in sorted(...) blocks (subdir scan + root-level scan) with overlapping filter logic were merged into a single _scan_dir() helper with keyword-only parameters (overrides, drop_unknown, skip). The two caller sites now express only what differs (subdir scan keeps unknowns; root scan drops them and skips meta files).

6. Docs vs source — source-of-truth boundary

The manifest module (src/ai_lsc/manifest/support.py) and the routing layer file (src/ai_lsc/registry/layers/routing.py) now both carry explicit "source of truth" docstrings:

The manifest file itself is an optional convenience; if absent, callers fall back to defaults — the registry layer files in ai_lsc.registry.layers remain the authoritative source for tool definitions.

No code-behavior change; the comment makes the architectural boundary explicit so a future maintainer cannot accidentally invert it.

7. Verification

Check Result
AST-parse 100 Python files 0 failures
bash -n on bootstrap.sh + run.sh 0 failures
Refactored modules import cleanly OK
build_system_context smoke test OK (dispatch table produces identical output)
resolve_context_files smoke test OK (returns same file list)
Wording sweep grep 0 matches for `restored

8. Out-of-scope (preserved per user policy)

  • curl|sh installers (Ollama, Grafana Alloy, Meilisearch) — C-05 policy (see whatremains.txt).
  • Layer-file filesystem backfill (L-18) — mechanical, ~10 min/layer.
  • defaults.py 3700-line split (L-14) — conflicts with layer-file decomposition.
  • Pre-existing unused imports JCL_FILE_NAME (support.py) and Path (installer.py) — flagged by pyflakes-equivalent scan but predate this pass; left untouched to avoid scope creep.

9. Tarball

Packaged as ai-lsc-moe-qa-pass.tar.gz in /home/z/my-project/download/. Contains the full project tree post-cleanup.

10. Post-pass cleanup (follow-up)

After the initial MoE QA pass was packaged, two follow-up changes were applied:

10.1 Retirement of one-shot migration scripts

The following five scripts were one-shot migrations that had already been applied to the registry/layer files. Per the project-manager perspective on the MoE panel ("don't leave dead code sitting around"), they have been removed from the tree:

  • apply_taxonomy_migration.py (root) — v3.2 superseded by apply_10layer_taxonomy.py.
  • scripts/apply_10layer_taxonomy.py — taxonomy re-org, applied.
  • scripts/backfill_layer_flags.py — H-15 flag backfill, applied.
  • scripts/backfill_tool_licenses.py — license field backfill, applied.
  • scripts/backfill_default_licenses.py — license default backfill, applied.

The empty scripts/ directory was also removed. All historical references in CHANGES.md, TODO.md, and QA-PASS-REPORT.md were patched so no doc points at a missing file.

10.2 Open WebUI launcher fix

open-webui serve dropped the --data-dir CLI option in a recent release; the registry's three open-webui launcher commands all used it and were failing at startup with:

No such option '--data-dir'.

The data directory is now set via the WEBUI_DATA_DIR environment variable, which is the supported mechanism in current open-webui. The hermes_webui launcher also dropped the invalid --env OLLAMA_BASE_URL=... trailer (open-webui reads OLLAMA_BASE_URL from the process environment directly, not via a CLI flag). Three sites patched:

  • src/ai_lsc/registry/layers/user_interfaces.py — openwebui launcher.
  • src/ai_lsc/registry/layers/user_interfaces.py — hermes_webui launcher.
  • src/ai_lsc/registry/defaults.py — openwebui launcher.

Each launcher now reads (e.g. for the canonical openwebui):

WEBUI_DATA_DIR={workspaces_root}/openwebui open-webui serve --port {port}

For hermes_webui the env-prefix also carries OLLAMA_BASE_URL:

WEBUI_DATA_DIR={workspaces_root}/hermes-webui OLLAMA_BASE_URL=http://localhost:17051 open-webui serve --port {port}

The ai-lsc runtime resolves env-prefix shells via shlex.split() on the launcher cmd, so the env-assignment form is parsed correctly.

11. Open WebUI Python-3.13 audioop fix (follow-up #2)

After the launcher fix landed, open-webui started successfully but crashed at import time inside the uv-managed tool env:

ModuleNotFoundError: No module named 'audioop'
…
ModuleNotFoundError: No module named 'pyaudioop'

Root cause: Python 3.13 removed the audioop stdlib module (PEP 594). pydub (an open-webui dep) imports audioop and falls back to pyaudioop on ImportError; neither was present in the uv-managed open-webui env at ~/.local/share/uv/tools/open-webui/.

Fix

uv tool install supports --with <extra> for additional dependencies. The pkg field in the registry now carries that flag, and install_uv was hardened to shlex-split pkg so the flag passes through verbatim:

  • src/ai_lsc/runtime/installer.py install_uv — shlex-splits pkg; validates only the first token as the package name; passes remaining tokens as additional argv to uv tool install. Falls back to pipx using just the first token.
  • src/ai_lsc/runtime/installer.py _detect_installation / _binary_name / _detect_version — all now take only the first shlex token of pkg when looking up the binary on PATH or building version-detection commands. (Without this, preflight would look for a binary literally named open-webui --with audioop-lts.)
  • src/ai_lsc/registry/layers/user_interfaces.py — both openwebui and hermes_webui installer.pkg changed from "open-webui" to "open-webui --with audioop-lts". Inline comment explains the Python-3.13 / PEP-594 rationale.
  • src/ai_lsc/registry/defaults.py — openwebui entry updated to match.

Verification

  • 95 Python files AST-parse cleanly.
  • Registry loads 187 tools; validate_registry() reports 0 errors.
  • shlex.split("open-webui --with audioop-lts") yields the expected argv: ["open-webui", "--with", "audioop-lts"].
  • _binary_name("open-webui --with audioop-lts", "uv") resolves to "open_webui" (the actual on-PATH binary name).

Operator workaround for existing installs

If open-webui was installed before this fix landed, the audioop-lts backport can be added in place:

~/.local/share/uv/tools/open-webui/bin/python -m pip install audioop-lts

Or reinstall via the new pkg spec:

uv tool install --force "open-webui --with audioop-lts"