ISPrefDiag

Diagnostic CLI for MicroStrategy / Strategy Intelligence Server (CastorServer / MSTRSvr) memory and performance incidents.

Status

v0.1.1 (Beta). All three subcommands (analyze, validate, tui) are functional; cross-platform CI gates the parser layer on Ubuntu, macOS, and Windows.

Install

Build a wheel and install it as an isolated tool:

uv build

uv tool install ./dist/ispref-*.whl

uv downloads a compatible Python 3.11+ automatically if your system Python is older. Verify with:

ispref --version
ispref --help

Alternative: pipx

pipx install ./dist/ispref-*.whl

pipx does not auto-download Python; your system Python must already be >= 3.11.

Editable install (development only)

uv tool install -e .

Use this if you are hacking on ISPrefDiag itself.

Quickstart

After installing, run the three commands below against the in-repo fixture pair to confirm everything works end-to-end:

ispref --help
ispref validate tests/fixtures/phase3/working_set_exceeds_governor/DSSErrors.log \
                tests/fixtures/phase3/working_set_exceeds_governor/DSSPerformanceMonitor.csv
ispref analyze tests/fixtures/phase3/working_set_exceeds_governor/DSSErrors.log \
               tests/fixtures/phase3/working_set_exceeds_governor/DSSPerformanceMonitor.csv \
               --out report.md

The validate command exits non-zero if the log and CSV do not share an overlapping time window (strict -- no fuzzy match fallback). The analyze command produces a Markdown report with inventory, terminating event, memory composition, and at least one cited finding.

Subcommands

• analyze -- Run full diagnostic pipeline on a log + CSV pair; emit a Markdown report with cited findings. Default backend: NullBackend (no LLM). Pass --llm anthropic or --llm ollama to add an LLM-augmented narrative section.
• validate -- Confirm a log + CSV pair share an overlapping time window (tz-aware UTC). Use this to sanity-check artifact pairs before analyze.
• tui -- Launch the Textual TUI for interactive review (3 screens: F1 MCM events, F2 Counters, F3 Findings). Forces --llm none (no LLM in TUI mode).

Development

uv sync --group dev
uv run pytest
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

Configuration

ISPrefDiag reads configuration with the following precedence (highest wins):

1. CLI flags (--llm none|anthropic|ollama)
2. Environment variables (ISPREF_LLM__MODE=..., ANTHROPIC_API_KEY=...)
3. Project pyproject.toml [tool.ispref] (API keys are rejected here -- env vars only)
4. User ~/.config/ispref/config.toml (run ispref --init-config to write a template)
5. Built-in defaults (LLM mode = none)

Troubleshooting

ispref not on PATH after install

If which ispref fails after uv tool install, ensure ~/.local/bin is on your PATH. Run uv tool update-shell to add it automatically.

pipx install fails with "Python 3.11 required"

pipx uses your system Python; it does not auto-download newer versions. Install Python 3.11+ first (e.g. uv python install 3.11 && uv python pin 3.11) or use the uv tool install path above.

uv tool install hangs or fails with proxy / network errors

uv tries to download a compatible Python on first install. Behind a corporate proxy that blocks python-build-standalone artifacts, pass --python /path/to/python3.12 to skip the download, or set UV_NO_MANAGED_PYTHON=1.

--llm anthropic prompts for egress confirmation

The first run with --llm anthropic in a session requires explicit confirmation that ISPrefDiag may make outbound HTTPS calls to api.anthropic.com. Pass --yes to bypass (CI scripts) or set ISPREF_LLM_CONFIRM_EGRESS=yes in your environment.

License

See LICENSE.