PR: Harden Ollama Provider Config Parsing, Add Robust Logging & Diagnostics

[DJJones66]

PR: Harden Ollama Provider Config Parsing, Add Robust Logging & Diagnostics

Summary

This PR fixes brittle JSON parsing for Ollama provider settings, adds structured logging and clearer errors across the provider/registry/endpoint layers, and ships diagnostic scripts to investigate encryption/JSON issues in settings_instances.value. The net effect is safer initialization, clearer failures, easier debugging, and zero changes to external API contracts.

---

Problem / Motivation

• Encrypted / malformed settings for ollama_servers_settings could fail to parse (e.g., double-encoded JSON, undeciphered ciphertext), causing provider initialization and chat requests to break without actionable logs.
• Minimal observability: provider/server selection + HTTP calls lacked breadcrumbs; failures (404 model missing, connect errors) were hard to triage.
• Operational friction: teams needed tooling to confirm whether data was encrypted, double-encoded, or corrupted and whether the ENCRYPTION_MASTER_KEY was present/valid.

---

What’s Changed

1) Provider: backend/app/ai_providers/ollama.py

• Add initialization logs with server URL resolution and defaults.

• Add request logs for chat calls (non-secret metadata only).

• Centralize endpoint construction (api_url) and debug-log outgoing URL.

• Add granular error handling:

  • httpx.ConnectError → clear “server not reachable” message.
  • httpx.HTTPStatusError 404 → “model not found” with server details.
  • Other HTTP errors → status + response text surfaced to the client.

• Keep return schema unchanged (choices[0].message.content, finish_reason, etc.).

2) Registry: backend/app/ai_providers/registry.py

• Add trace logs for provider instance cache hits/misses and instance creation.

3) API Endpoint Helper: backend/app/api/v1/endpoints/ai_providers.py

• Add request context prints/logs (provider/settings/server/model/user/stream flags).
• Replace ad-hoc JSON parsing with robust utilities (below).
• Enforce Ollama settings validation; if invalid/missing, provide a clear 404 with a list of available servers or a “no servers configured” message.
• Fallback to a minimal default structure only when appropriate.

4) Utilities: New backend/app/utils/json_parsing.py

• safe_encrypted_json_parse(...): multi-strategy parser that handles:

  • direct JSON, double-encoded JSON, cleaned JSON, nested JSON,
  • detection of encrypted-looking values and helpful errors pointing to ENCRYPTION_MASTER_KEY,
  • structured, encryption-aware error surfaces (with context).

• validate_ollama_settings_format(...): verifies expected servers[] schema.

• create_default_ollama_settings(): minimal safe default ({"servers": []}).

5) Diagnostics / Tooling (New)

• backend/scripts/inspect_settings_encryption.py

  • Async DB inspector that lists tables, dumps settings, analyzes value formats (encrypted/json/double-encoded), runs encryption service checks, and generates a JSON report.

• backend/scripts/run_inspection.py

  • Simple runner to execute the inspection end-to-end.

• backend/scripts/test_ollama_fix.py

  • Unit-style harness to simulate edge cases (double-encoded, encrypted-looking strings, malformed JSON) and validate that parsing/validation behaves as expected.

• Two example saved reports under backend/scripts/*.json from local runs.

---

User-Visible Behavior

• When an Ollama server is missing or mis-IDed, clients now receive:

  • 404 with readable guidance and list of available servers (if any), or
  • 404 with “No Ollama servers are configured” if none exist.

• When the server is down or unreachable:

  • Response includes server URL and server name to speed triage.

• When model is unknown:

  • 404 with explicit “model not found on server” message.

No API shapes changed; only messages are clearer.

---

Configuration & Ops Notes

• Ensure ENCRYPTION_MASTER_KEY is set in the backend environment if settings encryption is enabled.
  Example (dev):

  export ENCRYPTION_MASTER_KEY='a-long-random-secret'

---

Backward Compatibility

• ✅ No schema changes.
• ✅ No API contract changes.
• ✅ Existing settings continue to work; malformed/legacy values now produce actionable errors instead of opaque failures.

---

Security Considerations

• Logs avoid secrets (no API keys printed).
• Utilities surface when encryption keys are missing/misconfigured without exposing key content.
• Scripts are diagnostic; they read DB state and produce reports for operators.

---

Performance Impact

• Negligible. Added logging is lightweight; no hot-path loops added. HTTP behavior unchanged aside from error handling.

---

TL;DR: This PR makes Ollama setup far more resilient and debuggable. If something’s off—wrong key, malformed JSON, missing server, unknown model—you’ll get a precise, actionable message and the tools to fix it quickly.