neograph::llm::SchemaProvider Class Reference

LLM provider that adapts to any API via a JSON schema. More...

#include <schema_provider.h>

Inheritance diagram for neograph::llm::SchemaProvider:

Collaboration diagram for neograph::llm::SchemaProvider:

Classes
struct	Config
	Configuration for schema-based provider. More...

Public Member Functions
asio::awaitable< ChatCompletion >	complete_async (const CompletionParams &params) override
	Async completion — single wire path implemented over the owned ConnPool (HTTP keep-alive).
ChatCompletion	complete_stream (const CompletionParams &params, const StreamCallback &on_chunk) override
	Sync completion is inherited from Provider::complete(), which drives complete_async via neograph::async::run_sync.
asio::awaitable< ChatCompletion >	complete_stream_async (const CompletionParams &params, const StreamCallback &on_chunk) override
	Async streaming completion — native override (issue #4).
std::string	get_name () const override
	Get the provider name (from the schema's "name" field).
asio::awaitable< ChatCompletion >	invoke (const CompletionParams &params, StreamCallback on_chunk) override
	v1.0 single-dispatch override (Candidate 6 PR6).
	~SchemaProvider ()
	Destructor — shuts down the background HTTP loop + worker thread held alongside the ConnPool.
Public Member Functions inherited from neograph::Provider
virtual ChatCompletion	complete (const CompletionParams &params)
	Perform a synchronous LLM completion.

Static Public Member Functions
static std::unique_ptr< SchemaProvider >	create (const Config &config)
	Create a schema-based provider instance.

Friends
class	neograph::llm::test_access::SchemaProviderTestAccess

Detailed Description

LLM provider that adapts to any API via a JSON schema.

The schema describes connection details, request/response formats, tool call conventions, and streaming protocols for a given LLM vendor. Built-in schemas: "openai", "claude", "gemini".

auto provider = SchemaProvider::create({
    .schema_path = "claude",          // built-in schema name
    .api_key = "sk-ant-...",
    .default_model = "claude-sonnet-4-20250514"
});

See also

OpenAIProvider for a simpler OpenAI-only provider.

Definition at line 65 of file schema_provider.h.

Constructor & Destructor Documentation

~SchemaProvider()

neograph::llm::SchemaProvider::~SchemaProvider

(

)

Destructor — shuts down the background HTTP loop + worker thread held alongside the ConnPool.

Out-of-line so the ConnPool forward declaration is enough at this header.

Member Function Documentation

complete_async()

asio::awaitable< ChatCompletion > neograph::llm::SchemaProvider::complete_async ( const CompletionParams &  params )

overridevirtual

Async completion — single wire path implemented over the owned ConnPool (HTTP keep-alive).

The schema_mutex_ still serializes the body-build and response-parse phases (yyjson_mut_doc traversal is not thread-safe even for reads), but the network I/O happens off-lock so concurrent fan-out still overlaps.

Reimplemented from neograph::Provider.

complete_stream()

ChatCompletion neograph::llm::SchemaProvider::complete_stream ( const CompletionParams &  params, const StreamCallback &  on_chunk  )

overridevirtual

Sync completion is inherited from Provider::complete(), which drives complete_async via neograph::async::run_sync.

Streaming completion (HTTP/SSE httplib path; WS path dispatched to complete_stream_ws_responses when use_websocket=true and the schema is openai-responses).

Locking contract for on_chunk: the callback is invoked from inside httplib's content callback (HTTP/SSE) or the WebSocket recv loop (WS), in BOTH cases with schema_mutex_ NOT held — the lock is taken only during the per-call body- build + per-call response-parse phases at the start of the request, then released before the network roundtrip begins. Parse state passed through on_chunk (accumulated full_content, tool-call map, etc.) is stack-local to this call and not shared with the schema_mutex_-protected schema templates. Callers can therefore (a) safely call other provider methods from inside on_chunk without deadlocking, and (b) assume tokens emitted by concurrent complete_stream calls on the same provider do not interleave their parse state.

Reimplemented from neograph::Provider.

complete_stream_async()

asio::awaitable< ChatCompletion > neograph::llm::SchemaProvider::complete_stream_async ( const CompletionParams &  params, const StreamCallback &  on_chunk  )

overridevirtual

Async streaming completion — native override (issue #4).

For the WebSocket Responses path (use_websocket=true, openai-responses schema) this co_awaits the existing complete_stream_ws_responses directly — no bridge thread, no nested run_sync, no shared-state race against the awaiter's io_context.

For the HTTP/SSE path (httplib synchronous) it defers to Provider::complete_stream_async's base implementation, which post-#4 spawns a dedicated worker thread for complete_stream and dispatches tokens back onto the awaiter's executor — so the engine's io_context worker stays responsive and the user on_chunk runs single-threaded with the awaiting coroutine.

Reimplemented from neograph::Provider.

create()

static std::unique_ptr< SchemaProvider > neograph::llm::SchemaProvider::create ( const Config &  config )

static

Create a schema-based provider instance.

If schema_path matches a built-in name, the embedded schema is used. Otherwise it is treated as a file path.

Parameters

config

Provider configuration with schema path and API key.

Returns

A unique_ptr to the created provider.

Exceptions

std::runtime_error

If the schema cannot be loaded or parsed.

get_name()

std::string neograph::llm::SchemaProvider::get_name ( ) const

overridevirtual

Get the provider name (from the schema's "name" field).

Returns

Provider identifier string (e.g., "openai", "claude", "gemini").

Implements neograph::Provider.

invoke()

asio::awaitable< ChatCompletion > neograph::llm::SchemaProvider::invoke ( const CompletionParams &  params, StreamCallback  on_chunk  )

overridevirtual

v1.0 single-dispatch override (Candidate 6 PR6).

Anchors the dispatch surface — engine provider->invoke(...) calls land here directly instead of bouncing through the base default that re-forwards to the 4-virtual chain. v0.9 body routes through existing native overrides (no behavioural change); v1.0 will fold complete_async + complete_stream_async bodies into invoke() and delete the legacy methods.

Reimplemented from neograph::Provider.

---

The documentation for this class was generated from the following file:

• include/neograph/llm/schema_provider.h