Document isolated-client concurrency model

Author: Sunrisepeak

docs/en/advanced.md

@@ -57,6 +57,35 @@ auto resp = task.get();
 std::cout << resp.text() << '\n';
 ```
 
+## Concurrency Model
+
+Use instance isolation for concurrency:
+
+- `Client` is stateful and not thread-safe
+- `tinyhttps::HttpClient` is also not thread-safe
+- create one `Client` per task or per thread
+- do not share a single `Client` across concurrent callers
+
+This works well for calling multiple providers in parallel because each client owns its own provider, conversation, and transport state.
+
+```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("summarize this");
+});
+
+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 this");
+});
+```
+
 ## Tool Calling Loop
 
 The provider surfaces requested tools via `ChatResponse::tool_calls()`. You then append a tool result and continue the conversation.

docs/en/cpp-api.md

@@ -160,6 +160,12 @@ const P& provider() const
 P& provider()
 ```
 
+### Thread-Safety
+
+- `Client<P>` is stateful and not thread-safe
+- use one client per task or thread
+- do not share one client across concurrent callers
+
 ## Provider Config Types
 
 ```cpp

docs/zh-hant/advanced.md

@@ -22,6 +22,17 @@ auto task = client.chat_async("簡要解釋 coroutine。");
 auto resp = task.get();
 ```
 
+## 並發模型
+
+建議使用「實例隔離、上層並發」的方式：
+
+- `Client` 是有狀態物件，不保證執行緒安全
+- `tinyhttps::HttpClient` 也不保證執行緒安全
+- 每個任務或執行緒各自建立一個 `Client`
+- 不要把同一個 `Client` 共享給多個並發呼叫方
+
+這種方式天然適合多模型 / 多 provider 並發呼叫，因為每個實例都持有獨立的 provider、對話與傳輸狀態。
+
 ## 工具呼叫流程
 
 ```cpp

docs/zh/advanced.md

@@ -22,6 +22,17 @@ auto task = client.chat_async("简要解释 coroutine。");
 auto resp = task.get();
 ```
 
+## 并发模型
+
+推荐使用“实例隔离，上层并发”的方式：
+
+- `Client` 是有状态对象，不保证线程安全
+- `tinyhttps::HttpClient` 也不保证线程安全
+- 每个任务或线程单独创建一个 `Client`
+- 不要把同一个 `Client` 共享给多个并发调用方
+
+这种方式天然适合多个模型 / 多个 provider 并发调用，因为每个实例都持有独立的 provider、会话和传输状态。
+
 ## 工具调用循环
 
 ```cpp

src/client.cppm

@@ -17,6 +17,8 @@ private:
     ChatParams defaultParams_;
 
 public:
+    // Thread-safety: Client instances are intentionally stateful and not synchronized.
+    // Use one Client per task/thread and avoid sharing a Client across threads.
     explicit Client(P provider) : provider_(std::move(provider)) {}
     explicit Client(openai::Config config)
         requires std::same_as<P, openai::OpenAI>

src/tinyhttps/http.cppm

@@ -219,6 +219,8 @@ static bool iequals(std::string_view a, std::string_view b) {
 
 export class HttpClient {
 public:
+    // Thread-safety: HttpClient owns a mutable connection pool and is not synchronized.
+    // Keep each instance isolated to a single caller/task unless you add external locking.
     explicit HttpClient(HttpClientConfig config = {})
         : config_(std::move(config)) {}
 

tests/llmapi/test_client.cpp

@@ -7,9 +7,15 @@ import std;
 using namespace mcpplibs::llmapi;
 
 struct FullMockProvider {
+    std::string prefix { "reply to: " };
+    int delayMs { 0 };
+
     std::string_view name() const { return "full_mock"; }
 
     ChatResponse chat(const std::vector<Message>& msgs, const ChatParams&) {
+        if (delayMs > 0) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(delayMs));
+        }
         std::string lastContent;
         if (!msgs.empty()) {
             auto& c = msgs.back().content;
@@ -18,7 +24,7 @@ struct FullMockProvider {
             }
         }
         return ChatResponse {
-            .content = { TextContent { "reply to: " + lastContent } },
+            .content = { TextContent { prefix + lastContent } },
             .stopReason = StopReason::EndOfTurn,
             .usage = { .inputTokens = 10, .outputTokens = 5, .totalTokens = 15 },
         };
@@ -96,6 +102,40 @@ int main() {
     assert(client2.conversation().size() == 2);
     std::filesystem::remove("/tmp/test_client_conv.json");
 
+    // Test 8: isolated clients can be used concurrently without sharing conversation state
+    auto futureA = std::async(std::launch::async, [] {
+        auto isolatedClient = Client(FullMockProvider{
+            .prefix = "openai-like: ",
+            .delayMs = 10,
+        });
+        isolatedClient.system("provider a");
+        auto resp = isolatedClient.chat("hello from a");
+        return std::pair{
+            resp.text(),
+            isolatedClient.conversation().size(),
+        };
+    });
+
+    auto futureB = std::async(std::launch::async, [] {
+        auto isolatedClient = Client(FullMockProvider{
+            .prefix = "anthropic-like: ",
+            .delayMs = 10,
+        });
+        isolatedClient.system("provider b");
+        auto resp = isolatedClient.chat("hello from b");
+        return std::pair{
+            resp.text(),
+            isolatedClient.conversation().size(),
+        };
+    });
+
+    auto [textA, sizeA] = futureA.get();
+    auto [textB, sizeB] = futureB.get();
+    assert(textA == "openai-like: hello from a");
+    assert(textB == "anthropic-like: hello from b");
+    assert(sizeA == 3);
+    assert(sizeB == 3);
+
     println("test_client: ALL PASSED");
     return 0;
 }