fix(adapters): make the declared LLMClient interface sufficient to run

[ptimizeroracle]

Follow-up to #230. Fixing that bug made with_custom_llm_client() reach the pipeline — and revealed that a client implementing the declared interface still could not complete a single row.

Two undeclared requirements

LLMClient declares three abstract methods. Two more were required, and neither was stated:

start() / stop() — the invocation stage calls them unconditionally, through a # type: ignore[attr-defined]. That comment is the code admitting the attribute is not on the interface. A client without them died at the first row:

AttributeError: 'MyCustomLLMClient' object has no attribute 'start'

ainvoke() — the default executor is async, so this is what a run actually calls, not invoke(). Without it every row was skipped and the run reported "Check the model name, credentials, and provider" — a provider problem, for a missing method.

Neither the ABC nor mypy could say so. You found out at runtime, with a misleading message.

Fix

Defaults on the base class: start/stop no-op, and the async methods delegate to their sync counterparts. Implement what is abstract and it runs.

Delegating serialises requests — the sync call blocks the event loop — so the docstring says to override ainvoke() with a real async client for concurrency. Correct by default, fast when you need it.

The example had never run

examples/13_custom_client.py failed at instantiation on the missing structured_invoke, so the #230 injection bug was not even reachable through it. Nothing executes examples in CI, so it sat broken.

before → TypeError: Can't instantiate abstract class MyCustomLLMClient
after  → Processed: 3 rows   Total cost: $0.000126

Documentation

docs/guides/custom-clients.md — the API had no documentation at all. Its only public presence was that example, so the single discoverable path to the feature demonstrated something that could not work.

The guide covers the interface, the async method that actually runs, optional lifecycle hooks, what you get for free (batching, concurrency, retries, cost tracking, checkpointing), the shared-instance guarantee from #230, and a stub-for-tests recipe. Added to SUMMARY.md so it appears in GitBook nav.

Test

test_client_with_only_abstract_methods_runs — a client implementing exactly the three abstract methods runs a pipeline end to end. It fails when either default is removed.

That is the contract worth pinning: the interface says what it needs, and needing it is enough.

Full suite: 1165 passing, mypy clean.

ai assistance: i directed this work with help from claude code.