Game‑Troubleshooting Agent

Diagnose Linux game crashes locally using a lightweight Python agent, a small set of diagnostic tools, and any LLM that exposes a local HTTP endpoint (Ollama, LM Studio, etc.).

---

Highlights

• Purely offline workflow—no cloud API keys.
• Modular architecture (lda_agent package) with dedicated modules for tools, prompt construction, LLM clients, orchestration, and persistence.
• Supports tool-calling style interactions so the LLM can request additional diagnostics before answering.
• Caches solved issues in a lightweight SQLite DB for future retrieval.

---

Prerequisites

Dependency	Notes
Python 3.10+	venv strongly recommended
pip 21+	for installing dependencies
Ollama or LM Studio	provides the LLM endpoint
journalctl, lspci, nvidia-smi	optional but unlock richer diagnostics

---

Getting Started

1. Clone & create a virtual environment

git clone https://github.com/<your-username>/game-troubleshooter.git
cd game-troubleshooter
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install --upgrade pip

2. Install Python requirements

pip install -r requirements.txt

Installed packages:

• python-dotenv – loads .env config automatically.
• requests – talks to the local LLM API.
• rich – nicer CLI output.
• psutil – gathers system stats for the diagnostic tools.

3. Configure the LLM endpoint

Create an optional .env file in the project root:

LLM_MODEL=phi-2
LOCAL_API_URL=http://127.0.0.1:11434/api/generate  # Ollama default
# LM Studio example:
# LOCAL_API_URL=http://127.0.0.1:1234/v1/chat/completions
MAX_AGENT_ROUNDS=3
LLM_REQUEST_TIMEOUT=180  # seconds to wait for the local LLM
LLM_TEMPERATURE=0.1      # lower values -> more deterministic replies

The agent auto-detects the backend from the URL and formats the payload accordingly.

4. Run the agent

Interactive shell:

python agent.py

One-off query:

python agent.py "Why does Proton crash on launch?"

The CLI prints each round, shows the LLM response, executes tool calls when requested, and stores final answers in solutions.db.

---

Desktop GUI (PySide6)

Prefer a windowed experience? Launch the PySide6 front-end:

python desktop_app.py

Features:

• Backend selector (LM Studio, Ollama, or custom URL) plus model override.
• Rich log pane that mirrors tool calls and LLM decisions.
• Separate answer panel with copy-friendly text.

Only requirement beyond the base CLI is PySide6, already listed in requirements.txt. Start your local LLM first (LM Studio “Local Server” or ollama serve), then run the GUI and trigger diagnoses with the “Run Diagnosis” button.

---

Project Layout

lda_agent/
├── cli.py           # CLI entry point + argument parsing
├── config.py        # Environment / .env loading
├── llm.py           # Local LLM client (Ollama or OpenAI-compatible)
├── orchestrator.py  # Agent loop + tool execution
├── persistence.py   # SQLite knowledge base
├── gui_app.py       # PySide6 desktop UI
└── tools.py         # Tool registry and implementations
agent.py             # Convenience runner (python agent.py)
desktop_app.py       # Launches the PySide6 GUI
requirements.txt
README.md

Each module is designed to be testable and replaceable. For example, add new tools by extending build_registry() in lda_agent/tools.py, or plug in a different backend by adjusting LLMClient.

---

Extending the Agent

• Add tools – implement a function that returns a dict ({\"ok\": bool, ...}), wrap it in a Tool, and register it in build_registry().
• Change prompt style – edit lda_agent/prompt.py.
• Swap LLM backends – point LOCAL_API_URL to any OpenAI-compatible endpoint or custom server; the prompt + orchestration logic stay unchanged.
• Persist more metadata – extend the fixes schema in lda_agent/persistence.py.

---

Troubleshooting

• LLM returns non-JSON when tool-calling: ensure the selected model supports instruction following; smaller models may need higher MAX_AGENT_ROUNDS.
• Permission errors for journalctl: run the CLI with sudo, or adjust the tools to use --user logs only.
• Timeouts: confirm that the local LLM server is running and reachable on the configured LOCAL_API_URL.

---

License

MIT – feel free to adapt for your own desktop support workflows.

• Tool Execution – When the LLM decides more data is needed, it returns a JSON payload like:

{
  "action": "read_log",
  "arguments": {"path": "/home/user/.steam/steam/logs/launch.log"}
}

The orchestrator executes that function and feeds its output back into the next prompt.

• Local LLM – Ollama’s /api/generate or LM Studio’s /v1/chat/completions endpoint is called with the constructed prompt. No external network traffic occurs.

---

6️⃣ Extending / Customising

Feature	How to add
New diagnostic tool	Add a function in tools.py, register it in TOOLS = { ... }. Make sure it returns a JSON‑serialisable dict.
GPU vendor detection	Parse /usr/share/hwdata/pci.ids or use lspci -nnk.
Automatic fix scripts	Wrap tool calls in shell scripts (bash install_nvidia.sh). Use subprocess.run() with check=True.
GUI front‑end	Replace the CLI loop with a simple Flask/HTMX web app or PyQt5 window. The core logic stays unchanged.
Persisted knowledge base	Add a SQLite table (solutions.db) that caches query→answer pairs. Check it before hitting the LLM.
Multi‑language support	Include --lang en flag; pass the language to the prompt.

---

7️⃣ FAQ & Troubleshooting

Issue	Fix
Ollama is not found	Make sure /usr/local/bin/ollama (or wherever you installed it) is in $PATH.
Local API URL returns 502	Ensure the Ollama / LM Studio server is running and listening on the port specified. Try curl http://127.0.0.1:11434/api/tags to confirm.
LLM never finishes or hangs	The default timeout for the HTTP request is 60 s; you can raise it in agent.py.
Tool fails with “permission denied”	Run the script as a user that has read access to /var/log, Steam logs, etc. For root‑only commands (e.g., installing drivers) add an explicit sudo call or ask for password via getpass.
Model size is too big for my GPU	Switch to a smaller model (phi-2) in the .env file.

---

8️⃣ License

MIT – Feel free to copy, modify, and distribute.
If you use this project commercially, just give credit where it’s due.