Metadata-Version: 2.4
Name: fixenv-cli
Version: 0.2.0
Summary: AI-powered Python environment doctor — diagnose, research, resolve.
Author: Shivang0101
License: MIT
Project-URL: Homepage, https://github.com/Shivang0101/fixEnv
Project-URL: Repository, https://github.com/Shivang0101/fixEnv
Project-URL: Issues, https://github.com/Shivang0101/fixEnv/issues
Project-URL: Changelog, https://github.com/Shivang0101/fixEnv/blob/main/CHANGELOG.md
Keywords: developer-tools,ai,cli,python,environment,debugging
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.40.0
Requires-Dist: groq>=0.9.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Requires-Dist: toml>=0.10.2
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: packaging>=23.0
Provides-Extra: tui
Requires-Dist: textual>=0.70.0; extra == "tui"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-toml>=0.10; extra == "dev"
Provides-Extra: all
Requires-Dist: fixenv-cli[dev,tui]; extra == "all"
Dynamic: license-file

# 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

```bash
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:

```bash
fixenv config init
```

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

```bash
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:

```bash
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**:

```bash
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:

```bash
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:

```toml
[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

```bash
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
