cpp: support Ollama-compatible /v1 endpoints

[andrewssobral]

Summary

• preserve OpenAI-compatible /v1 base URLs instead of rewriting them to /api/v1
• skip Lemonade-specific model preload logic for non-Lemonade backends such as Ollama
• add C++ unit coverage and small docs/example wording updates for the new behavior

Problem

GAIA C++ currently normalizes every base URL to /api/v1 and always attempts Lemonade-specific /health and /load model management. That breaks OpenAI-compatible backends like Ollama, where http://localhost:11434/v1 was being rewritten to /v1/api/v1 and model preloading hit unsupported endpoints.

Validation

• rebuilt cpp/build/tests_mock
• ran ./tests_mock --gtest_color=yes successfully (283 tests passed)
• rebuilt the local Ollama-backed consumer example against the updated library

Notes

This change is scoped to the C++ framework, tests, and minimal C++ docs/example wording only.

[itomek]

@claude review this PR, ensure no breaking changes

[github-actions]

Claude finished @itomek's task —— View job

---

PR Review: cpp: support Ollama-compatible /v1 endpoints

• Read changed files and understand the changes
• Review for breaking changes
• Check code quality and patterns
• Verify test coverage
• Provide review feedback

---

Summary

This PR correctly adds support for Ollama and other OpenAI-compatible backends that use /v1 endpoints (instead of Lemonade's /api/v1). The implementation is clean and well-tested.

No Breaking Changes Detected

The changes are backward-compatible:

Behavior	Before	After
URLs without suffix (e.g., http://localhost:8000)	/api/v1 appended	/api/v1 appended (unchanged)
URLs with /api/v1	Preserved	Preserved (unchanged)
URLs with /v1	Rewritten to /v1/api/v1 (broken)	Preserved as-is (fixed)
ensureModelLoaded() for Lemonade endpoints	Calls /health and /load	Unchanged
ensureModelLoaded() for /v1 endpoints	Fails on non-existent /health	Skips gracefully (fixed)

Code Quality

🟢 Good:

• URL normalization logic at cpp/src/lemonade_client.cpp:21-43 is clear and correctly handles edge cases
• Endpoint detection at line 378 correctly identifies non-Lemonade backends
• Debug logging added for observability
• Tests cover all new code paths (6 new test cases)

🟡 Minor observations:

1. Magic number at cpp/src/lemonade_client.cpp:378:

   if (baseUrl_.size() < 7 || baseUrl_.substr(baseUrl_.size() - 7) != "/api/v1")

   Consider using lemonadeSuffix.size() for consistency with normalizeUrl(), though this is minor.

2. Edge case: URLs like http://host/api/v1/ (with trailing slash) would be normalized to http://host/api/v1 by the existing trailing slash stripping, so this is handled correctly.

Test Coverage

The new tests verify:

• /v1 URL preservation in constructors (LegacyConstructorUrlPreservesOpenAiV1)
• /v1 URL preservation in setBaseUrl() (SetBaseUrlNoopWhenOpenAiV1Present, UrlNormalizationPreservesOpenAiV1)
• ensureModelLoaded() skips for OpenAI-compatible endpoints (EnsureModelLoadedSkipsForOpenAiCompatibleV1Endpoints)
• ensureModelLoaded() still fails for offline Lemonade endpoints (EnsureModelLoadedStillFailsForOfflineLemonadeEndpoint)

All 283 tests pass per PR description.

Verdict

Approved - This PR fixes a real bug where Ollama endpoints were being incorrectly rewritten, with no breaking changes to existing Lemonade usage.

---