fixenv-cli 0.2.0

AI-powered Python environment doctor — diagnose, research, resolve.

FixEnv — AI-Powered Python Environment Doctor

A production-grade CLI that diagnoses Python/Conda environment errors, researches fixes against current docs, and proposes safe shell commands — always behind a mandatory Human-in-the-Loop (HITL) approval gate. Works with any OpenAI-compatible LLM endpoint, ships a Textual TUI, an undo system, a plugin API, dependency auditing, environment diffing, and more.

$ fixenv diagnose "ModuleNotFoundError: No module named 'nltk'"
① Diagnostic → ② Research → ③ Resolution → ⛔ HITL approve → ✓ execute

Highlights

• 3-agent pipeline — Diagnostic → Research → Resolution, with validated Pydantic JSON handoffs (inspectable, loggable, cacheable).
• Grounded in your actual project — reads the real pin/constraint for the affected package straight from pyproject.toml / requirements.txt when relevant, instead of letting the model guess at what's installed vs. pinned.
• Honest execution — a fix is only ever reported as successful if every command's exit code was 0 and the Resolution agent's own post_fix_verification commands actually pass when run for real — not just displayed. A failed step is reported as failed, every time.
• Any OpenAI-compatible provider — OpenAI, Groq, OpenRouter, aicredits-style gateways, local vLLM / LM Studio / Ollama. Per-model fallback chain, with automatic retry on transient errors and on malformed model output.
• HITL safety gate — never runs a command without explicit y; dangerous commands get an extra confirmation. A live PyPI check flags any version pin in the plan that doesn't actually exist before you approve it.
• Undo — fixenv undo reverses what a session executed, through the same gate.
• Textual TUI — fixenv tui: health dashboard, sessions, stats, cache.
• Fingerprint + fuzzy cache — same error never costs two API calls.
• Dependency audit — fixenv audit (CVEs via real version comparison, unpinned deps) with --fix auto-pin and optional Tavily/SerpAPI-backed research.
• Env diff & doctor — compare environments; proactive health scan with a score.
• Plugins — add commands and health checks via entry points.
• Scriptable — --json on every reporting command; structured logging; CI-friendly.

Install

pip install -e ".[all]"     # everything (TUI + dev tooling)
# or minimal:
pip install -e .            # core CLI
pip install -e ".[tui]"     # core + Textual TUI
fixenv --help

Configure the LLM provider

FixEnv speaks the OpenAI Chat Completions API, so it works with any compatible endpoint. Run the wizard:

fixenv config init

…or set it directly. For an aicredits / OpenAI-compatible gateway:

fixenv config set llm.provider openai_compatible
fixenv config set llm.base_url https://your-gateway/v1
fixenv config set llm.model your-model-id
export FIXENV_LLM_API_KEY=sk-...        # or FIXENV_LLM_BASE_URL, OPENAI_API_KEY
fixenv providers test                    # ping the endpoint, show latency
fixenv providers models                  # list available models

For Groq (default): export GROQ_API_KEY=gsk_...

Config lives in ~/.fixenv/config.toml; secrets only ever come from env vars (the wizard writes them to ~/.fixenv/.env, which is loaded automatically — never committed, never stored in config.toml). Enable --research for a grounded fix by setting a research provider and key in the wizard, or directly:

fixenv config set research.provider tavily   # or: serpapi
export TAVILY_API_KEY=tvly-...               # or SERPAPI_KEY

A project may override llm / research / output via a .fixenv.toml file. Switch between setups with profiles:

fixenv config save-profile work
fixenv config use personal

Commands

Command	What it does
fixenv diagnose <err>	Full pipeline; --dry-run, --research, --interactive, --json
fixenv undo [id]	Reverse the commands a session executed
fixenv replay <id>	Re-run a saved fix (skip diagnosis)
fixenv doctor	Proactive health scan with a 0–100 score; --json, --fix
fixenv explain <code>	Plain-English explanation + bug/risk flags
fixenv ask [q]	Conversational follow-up grounded in your last session
fixenv audit [path]	Dependency CVE / pinning audit; --deep, --fix, --json
fixenv diff <a> <b>	Compare two environments (conda envs, venvs, freeze files)
fixenv export <id>	Render a session as Markdown / HTML / JSON
fixenv stats	Analytics dashboard over saved sessions
fixenv watch <log>	Tail a log file and auto-diagnose new tracebacks
fixenv tui	Full-screen interactive dashboard
fixenv providers	list / test / models for the configured endpoint
fixenv plugins	List discovered plugins
fixenv completion	Shell tab-completion instructions
fixenv cache · sessions · config	Manage cache, sessions, configuration

Examples:

fixenv diagnose --file traceback.txt --interactive
cat error.log | fixenv diagnose -
fixenv diagnose "..." --json | jq .status        # CI
fixenv audit requirements.txt --fix              # pin unpinned deps (with backup)
fixenv diff base ml-env                           # two conda envs
fixenv export abc123 --format html -o report.html
fixenv --debug doctor                             # verbose logging → ~/.fixenv/fixenv.log

Architecture

User error ─▶ Diagnostic agent ─▶ Research agent ─▶ Resolution agent ─▶ HITL gate ─▶ execute ─▶ verify
              (read-only env       (provider + web      (exact shell        (y/n/copy)   (live    (real exit
               snapshot + git)      research + real       commands + risk)                output)  codes +
                                     dependency pins)                                              post_fix_
                                                                                                     verification)
                    │
     providers.py ──┘  any OpenAI-compatible endpoint, fallback chain,
                        retries on transient errors AND malformed model output

• providers.py — LLM abstraction (LLMProvider, build_provider, fallback chain, JSON mode).
• agents.py / models.py — the three agents and their Pydantic contracts.
• orchestrator.py — pipeline, HITL gate, executor + verification, caching, undo recording.
• tools.py / envmanagers.py — read-only environment inspection (conda, venv, poetry, uv, pipenv, pyenv).
• audit.py — dependency file parsing/scanning; also backs find_dependency_pin(), which grounds the Research agent in the project's real pyproject.toml/requirements.txt constraints.
• cache.py — fingerprint + opt-in fuzzy cache. rollback.py — undo. report.py — exports.
• tui/ — Textual dashboard. plugins.py — entry-point discovery.

Safety model

• The HITL gate (safety.require_approval, default on) is sacred — no command runs without y. Dangerous commands (rm -rf, mkfs, …) require a second confirm.
• A live PyPI check (safety.check_pypi_versions, default on) flags any pip install pkg==X.Y.Z in the plan whose exact version doesn't exist on PyPI — before you approve it.
• tools.py performs read-only inspection only — no installs, no mutations.
• Every executed command records a revert_command so fixenv undo can reverse it.
• Success is never assumed: every command's real exit code is checked, and post_fix_verification is executed and checked too — a session is only marked completed if everything genuinely passed.

Plugins

Register external commands or health checks via entry points:

[project.entry-points."fixenv.plugins"]
myext = "my_pkg.fixenv_ext:register"        # register(app: typer.Typer) -> None

[project.entry-points."fixenv.health_checks"]
gpu = "my_pkg.checks:check_gpu"             # check(report) -> None

Development

make dev          # install with all extras
make check        # ruff + mypy + pytest
make tui          # launch the TUI

CI runs ruff, mypy, and pytest (150+ tests) across Python 3.10–3.13 on Linux and Windows — ruff and mypy are both hard gates (a lint or type error fails the build).

License

MIT