mirror of
https://github.com/nesquena/hermes-webui.git
synced 2026-05-27 20:20:20 +00:00
nesquena-hermes
29878259ca
Closes #1695. @Patrick-81 reported the bare "AIAgent not available -- check that hermes-agent is on sys.path" error on a symlinked install (~/Programmes/hermes-agent linked to ~/hermes-agent). The maintainer's response — three diagnostic commands plus `pip install -e .` in the agent dir — fixed it for them. This PR captures both halves of that learning so the next user with the same shape doesn't have to file a new issue: 1. **Error message diagnostic block.** New helper `_aiagent_import_error_detail()` in api/streaming.py builds a multi-line diagnostic when the import fails, including: - the running Python interpreter - HERMES_WEBUI_AGENT_DIR (set value, or "(not set)") - sys.path entries that mention hermes/agent (or "no entries mention..." — itself a strong diagnostic signal) - the most-common fix (`pip install -e .` in the agent dir) - a pointer to docs/troubleshooting.md The original error message string is preserved as the FIRST line so existing log scrapers and docs-search keep matching. Helper is kept as a separate function so it stays out of the hot path until we actually need to raise — building it on every successful import would be wasted work. 2. **New docs/troubleshooting.md.** Symptom → Why → Diagnostic commands → Fix → When-to-file-a-bug template, with one entry to start: the "AIAgent not available" flow Patrick-81 walked through. Future recurring failure modes follow the same template. Required a one-line addition to .gitignore — docs/* is gitignored with an allowlist, and the new file needed `!docs/troubleshooting.md` to be tracked. 3. **README link.** docs/troubleshooting.md added to the `## Docs` section so users know where to look first. 13 regression tests in tests/test_1695_aiagent_import_error_detail.py: 9 for the helper output shape (preserves original message line, includes running python, shows HERMES_WEBUI_AGENT_DIR set/unset both ways, includes pip-install-e hint, points at troubleshooting doc, lists relevant sys.path entries when present, says "no entries..." when absent, output is multi-line) plus 4 for the docs-presence regression (file exists, has the AIAgent section, includes pip install -e ., describes the diagnostic chain with readlink + agent/__init__.py verification). 190 streaming/aiagent tests pass after the change. ast.parse on api/streaming.py clean. CI failure on prior push was due to the docs/* gitignore swallowing the new troubleshooting.md file silently — this commit adds the allowlist entry so the file is tracked.
53 lines
975 B
Plaintext
53 lines
975 B
Plaintext
# Python cache
|
|
__pycache__/
|
|
*.pyc
|
|
*.pyo
|
|
*.pyd
|
|
|
|
# Backup and temporary files
|
|
*.bak
|
|
*.swp
|
|
*.swo
|
|
|
|
# Archive directory (pre-git backups, kept on disk but not tracked)
|
|
archive/
|
|
|
|
# Local environment and secrets (but keep the example templates)
|
|
.env
|
|
.env.*
|
|
!.env.example
|
|
!.env.docker.example
|
|
.claude/
|
|
CLAUDE.md
|
|
AGENTS.md
|
|
.cursorrules
|
|
.windsurfrules
|
|
.aider*
|
|
copilot-instructions.md
|
|
|
|
# Generated screenshots and transient artifacts
|
|
screenshot-*.png
|
|
full-UI.png
|
|
|
|
# Version file written by Docker/CI build — generated, never committed
|
|
api/_version.py
|
|
|
|
# OS files
|
|
.DS_Store
|
|
Thumbs.db
|
|
|
|
# Local reference clones — never committed (except tracked design/UI-UX reference pages)
|
|
docs/*
|
|
!docs/ui-ux/
|
|
!docs/ui-ux/**
|
|
!docs/docker.md
|
|
!docs/supervisor.md
|
|
!docs/troubleshooting.md
|
|
|
|
# Local-only PR review harness: rendering drivers, sample bank, fixtures.
|
|
# Used by Claude during deep reviews; never shared in the repo.
|
|
.local-review/
|
|
graphify-out/
|
|
.graphify_cached.json
|
|
.graphify_uncached.txt
|