Expand usage scenarios in examples docs

Sunrisepeak · Sunrisepeak · commit 4ec165482b72 · 2026-03-10T19:42:23.000+08:00
diff --git a/docs/en/examples.md b/docs/en/examples.md
@@ -152,6 +152,125 @@ int main() {
 }
 ```
 
+## Exception Mode
+
+The library currently reports failures by throwing exceptions. This is the recommended direct style when you want errors to propagate naturally.
+
+```cpp
+import mcpplibs.llmapi;
+import std;
+
+int main() {
+    using namespace mcpplibs::llmapi;
+
+    try {
+        auto client = Client(Config{
+            .apiKey = std::getenv("OPENAI_API_KEY"),
+            .model = "gpt-4o-mini",
+        });
+
+        auto resp = client.chat("Explain RAII in one paragraph.");
+        std::cout << resp.text() << '\n';
+    } catch (const ApiError& e) {
+        std::cerr << "API error: status=" << e.statusCode << " body=" << e.body << '\n';
+        return 2;
+    } catch (const ConnectionError& e) {
+        std::cerr << "Connection error: " << e.what() << '\n';
+        return 3;
+    } catch (const std::exception& e) {
+        std::cerr << "Unexpected error: " << e.what() << '\n';
+        return 4;
+    }
+}
+```
+
+## No-Exception Style At Call Site
+
+If your application prefers not to let exceptions escape, wrap the call and convert the result to `std::optional`, `std::expected`, or your own result type.
+
+```cpp
+import mcpplibs.llmapi;
+import std;
+
+std::optional<std::string> safe_chat(std::string_view prompt) {
+    using namespace mcpplibs::llmapi;
+
+    try {
+        auto client = Client(Config{
+            .apiKey = std::getenv("OPENAI_API_KEY"),
+            .model = "gpt-4o-mini",
+        });
+        return client.chat(prompt).text();
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+```
+
+## Recommended Retry At The Application Layer
+
+Retry policy is currently best implemented by the library user because retryability depends on business semantics.
+
+```cpp
+import mcpplibs.llmapi;
+import std;
+
+std::string chat_with_retry(std::string_view prompt) {
+    using namespace mcpplibs::llmapi;
+
+    for (int attempt = 0; attempt < 3; ++attempt) {
+        try {
+            auto client = Client(Config{
+                .apiKey = std::getenv("OPENAI_API_KEY"),
+                .model = "gpt-4o-mini",
+            });
+            return client.chat(prompt).text();
+        } catch (const ConnectionError&) {
+        } catch (const ApiError& e) {
+            if (e.statusCode != 429 && (e.statusCode < 500 || e.statusCode >= 600)) {
+                throw;
+            }
+        }
+
+        std::this_thread::sleep_for(std::chrono::milliseconds(200 * (1 << attempt)));
+    }
+
+    throw std::runtime_error("retry limit exceeded");
+}
+```
+
+## Parallel Use With Isolated Clients
+
+The recommended concurrency model is one client per task or thread.
+
+```cpp
+import mcpplibs.llmapi;
+import std;
+
+int main() {
+    using namespace mcpplibs::llmapi;
+
+    auto futureA = std::async(std::launch::async, [] {
+        auto client = Client(Config{
+            .apiKey = std::getenv("OPENAI_API_KEY"),
+            .model = "gpt-4o-mini",
+        });
+        return client.chat("Summarize modules.").text();
+    });
+
+    auto futureB = std::async(std::launch::async, [] {
+        auto client = Client(AnthropicConfig{
+            .apiKey = std::getenv("ANTHROPIC_API_KEY"),
+            .model = "claude-sonnet-4-20250514",
+        });
+        return client.chat("Translate 'hello world' to Japanese.").text();
+    });
+
+    std::cout << futureA.get() << '\n';
+    std::cout << futureB.get() << '\n';
+}
+```
+
 ## See Also
 
 - [C++ API Reference](cpp-api.md)
diff --git a/docs/zh-hant/examples.md b/docs/zh-hant/examples.md
@@ -66,3 +66,73 @@ auto embedding = client.embed(
     "text-embedding-3-small"
 );
 ```
+
+## 例外模式
+
+目前函式庫以拋出例外作為失敗回報方式。對於希望讓錯誤自然向上傳遞的呼叫鏈，這是最直接的使用方式。
+
+```cpp
+try {
+    auto resp = client.chat("請用一段話解釋 RAII。");
+    std::cout << resp.text() << '\n';
+} catch (const ApiError& e) {
+    std::cerr << "API error: status=" << e.statusCode << " body=" << e.body << '\n';
+} catch (const ConnectionError& e) {
+    std::cerr << "Connection error: " << e.what() << '\n';
+}
+```
+
+## 無例外模式
+
+如果上層不希望讓例外繼續外拋，可以在呼叫點自行包一層，轉成 `optional`、`expected` 或業務自己的結果型別。
+
+```cpp
+std::optional<std::string> safe_chat(std::string_view prompt) {
+    try {
+        return client.chat(prompt).text();
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+```
+
+## 建議的上層重試
+
+目前更建議由函式庫使用者在上層實作重試，因為是否可重試取決於業務語義。
+
+```cpp
+for (int attempt = 0; attempt < 3; ++attempt) {
+    try {
+        return client.chat(prompt).text();
+    } catch (const ConnectionError&) {
+    } catch (const ApiError& e) {
+        if (e.statusCode != 429 && (e.statusCode < 500 || e.statusCode >= 600)) {
+            throw;
+        }
+    }
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(200 * (1 << attempt)));
+}
+```
+
+## 並發使用
+
+建議模式是「實例隔離、上層並發」，也就是每個任務 / 執行緒各自建立一個 `Client`。
+
+```cpp
+auto futureA = std::async(std::launch::async, [] {
+    auto client = Client(Config{
+        .apiKey = std::getenv("OPENAI_API_KEY"),
+        .model = "gpt-4o-mini",
+    });
+    return client.chat("總結一下 modules。").text();
+});
+
+auto futureB = std::async(std::launch::async, [] {
+    auto client = Client(AnthropicConfig{
+        .apiKey = std::getenv("ANTHROPIC_API_KEY"),
+        .model = "claude-sonnet-4-20250514",
+    });
+    return client.chat("把 hello world 翻譯成日語。").text();
+});
+```
diff --git a/docs/zh/examples.md b/docs/zh/examples.md
@@ -66,3 +66,73 @@ auto embedding = client.embed(
     "text-embedding-3-small"
 );
 ```
+
+## 异常模式
+
+当前库以抛异常作为失败报告方式。对于希望让错误直接上传的调用链，这是最直接的使用方式。
+
+```cpp
+try {
+    auto resp = client.chat("请用一段话解释 RAII。");
+    std::cout << resp.text() << '\n';
+} catch (const ApiError& e) {
+    std::cerr << "API error: status=" << e.statusCode << " body=" << e.body << '\n';
+} catch (const ConnectionError& e) {
+    std::cerr << "Connection error: " << e.what() << '\n';
+}
+```
+
+## 无异常模式
+
+如果你的上层不希望异常继续外抛，可以在调用点自行包一层，转换成 `optional`、`expected` 或业务自己的结果类型。
+
+```cpp
+std::optional<std::string> safe_chat(std::string_view prompt) {
+    try {
+        return client.chat(prompt).text();
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+```
+
+## 推荐的上层重试
+
+当前更推荐由库使用者在上层实现重试，因为是否可重试取决于业务语义。
+
+```cpp
+for (int attempt = 0; attempt < 3; ++attempt) {
+    try {
+        return client.chat(prompt).text();
+    } catch (const ConnectionError&) {
+    } catch (const ApiError& e) {
+        if (e.statusCode != 429 && (e.statusCode < 500 || e.statusCode >= 600)) {
+            throw;
+        }
+    }
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(200 * (1 << attempt)));
+}
+```
+
+## 并发使用
+
+推荐模式是“实例隔离，上层并发”，也就是每个任务 / 线程各自创建一个 `Client`。
+
+```cpp
+auto futureA = std::async(std::launch::async, [] {
+    auto client = Client(Config{
+        .apiKey = std::getenv("OPENAI_API_KEY"),
+        .model = "gpt-4o-mini",
+    });
+    return client.chat("总结一下 modules。").text();
+});
+
+auto futureB = std::async(std::launch::async, [] {
+    auto client = Client(AnthropicConfig{
+        .apiKey = std::getenv("ANTHROPIC_API_KEY"),
+        .model = "claude-sonnet-4-20250514",
+    });
+    return client.chat("把 hello world 翻译成日语。").text();
+});
+```
