pulsatrix 1.1.0
Loading...
Searching...
No Matches
pulsatrix::orch Namespace Reference

Classes

struct  AnthropicOptions
 Settings for the Anthropic Messages API. More...
 
struct  ChatRequest
 A request to a provider. More...
 
struct  ChatResponse
 A provider's answer. More...
 
struct  ContentBlock
 One block of a message's content. More...
 
class  HttpError
 A request that got no complete response: the connection, TLS, a timeout or a limit failed. More...
 
struct  HttpHeader
 One request header. A sensitive one (a credential) is redacted by HttpRequest::describe(). More...
 
struct  HttpRequest
 An HTTP request. Redirects are never followed, so a credential only goes to url. More...
 
struct  HttpResponse
 An HTTP response. A status of 400 or 500 is a response, not an error. More...
 
class  HttpTransport
 Sends HTTP requests. One instance may be used by one thread at a time. More...
 
struct  HttpTransportOptions
 How a transport trusts servers. Certificate verification can't be turned off. More...
 
struct  HttpUrl
 An http or https URL split into its parts. More...
 
struct  Message
 One turn of a conversation. More...
 
struct  OpenAiCompatibleOptions
 Settings for an OpenAI-compatible chat-completions server (llama-server, vLLM, Ollama). More...
 
class  Provider
 A model behind an API. More...
 
class  ProviderError
 The provider answered with an error, or failed after its retries. More...
 
struct  RetryPolicy
 When and how long to retry. More...
 
struct  SchemaError
 One way a value fails a schema. More...
 
class  Secret
 Holds a credential, such as an LLM provider's API key. More...
 
struct  SseEvent
 One server-sent event. More...
 
class  SseParser
 Parses a text/event-stream body fed in chunks of any size, as the WHATWG HTML specification defines it. More...
 
struct  StreamCallbacks
 Called as a streamed answer arrives. Either may be empty. More...
 
struct  Tool
 A tool: what the model sees, and the function that runs it. More...
 
struct  ToolCall
 One tool call to run. More...
 
struct  ToolLoopOptions
 Settings for RunToolLoop(). More...
 
struct  ToolLoopResult
 How a tool loop ended. More...
 
struct  ToolOutcome
 What a tool returned. An error is reported to the model, which can try again. More...
 
class  ToolRegistry
 The tools an agent may use. RunToolLoop() takes executor(), and a planned MCP server will serve the same registry, so a tool is defined once. More...
 
struct  ToolSpec
 A tool the model may call. ToolRegistry::specs() makes these from its tools. More...
 
struct  Usage
 Tokens used by one request, or summed over a tool loop. More...
 

Typedefs

using HttpChunkHandler = std::function< bool(std::string_view chunk)>
 Receives a streamed body chunk by chunk. Return false to cancel the request.
 
using ToolExecutor = std::function< ToolOutcome(const ToolCall &)>
 Runs one tool call. ToolRegistry::executor() provides one; any function works.
 
using ToolHandler = std::function< ToolOutcome(const JsonValue &input)>
 Runs a tool on an input that already matches its schema. An exception becomes an error result with the exception's message.
 

Enumerations

enum class  HttpBackend { Httplib , Curl }
 The HTTP libraries a transport can use. More...
 
enum class  StopReason {
  EndTurn , ToolUse , MaxTokens , StopSequence ,
  PauseTurn , Refusal , Other
}
 Why the model stopped. More...
 

Functions

bool HttpBackendAvailable (HttpBackend backend)
 Whether this build has backend.
 
bool HttpsSupported (HttpBackend backend)
 Whether backend can make HTTPS requests in this build.
 
std::unique_ptr< HttpTransport > MakeHttpTransport (HttpBackend backend, HttpTransportOptions options={})
 A transport using backend.
 
std::unique_ptr< HttpTransport > MakeHttpTransport (HttpTransportOptions options={})
 A transport using libcurl if this build has it, which you asked for by turning it on, and cpp-httplib otherwise.
 
HttpUrl ParseHttpUrl (std::string_view url)
 Parses an http:// or https:// URL.
 
void CheckSchema (const JsonValue &schema)
 Checks that schema uses only the supported keywords, each with a valid value.
 
std::vector< SchemaError > ValidateJson (const JsonValue &schema, const JsonValue &value, std::size_t max_errors=16)
 Checks value against schema.
 
std::string StrictModeProblem (const JsonValue &schema)
 Why schema can't be used with Anthropic's strict tool use, or "" if it can.
 
bool JsonEquals (const JsonValue &a, const JsonValue &b)
 JSON equality, as enum, const and uniqueItems use it: numbers by value (1 equals 1.0), objects regardless of member order.
 
bool IsValidToolName (const std::string &name)
 Whether name is a valid tool name (^[a-zA-Z0-9_-]{1,128}$).
 
std::unique_ptr< Provider > MakeAnthropicProvider (AnthropicOptions options, std::shared_ptr< HttpTransport > transport=nullptr)
 The Anthropic provider. transport defaults to MakeHttpTransport().
 
std::unique_ptr< Provider > MakeOpenAiCompatibleProvider (OpenAiCompatibleOptions options, std::shared_ptr< HttpTransport > transport=nullptr)
 The OpenAI-compatible provider. transport defaults to MakeHttpTransport().
 
ToolLoopResult RunToolLoop (Provider &provider, ChatRequest request, const ToolExecutor &execute, const ToolLoopOptions &options={})
 Sends request, runs each tool the model calls with execute, and sends the results back, until the model stops calling tools or options.max_turns requests have been made.
 

Typedef Documentation

◆ HttpChunkHandler

using pulsatrix::orch::HttpChunkHandler = typedef std::function<bool(std::string_view chunk)>

Receives a streamed body chunk by chunk. Return false to cancel the request.

◆ ToolExecutor

using pulsatrix::orch::ToolExecutor = typedef std::function<ToolOutcome(const ToolCall&)>

Runs one tool call. ToolRegistry::executor() provides one; any function works.

Note
An exception is caught and sent to the model as an error result with its message.

◆ ToolHandler

using pulsatrix::orch::ToolHandler = typedef std::function<ToolOutcome(const JsonValue& input)>

Runs a tool on an input that already matches its schema. An exception becomes an error result with the exception's message.

Enumeration Type Documentation

◆ HttpBackend

enum class pulsatrix::orch::HttpBackend
strong

The HTTP libraries a transport can use.

Enumerator
Httplib 

cpp-httplib, always built; HTTPS when the build found OpenSSL

Curl 

libcurl, with PULSATRIX_ORCHESTRATOR_CURL; its own TLS (Schannel on Windows)

◆ StopReason

enum class pulsatrix::orch::StopReason
strong

Why the model stopped.

Enumerator
EndTurn 

it finished its answer

ToolUse 

it called tools and waits for their results

MaxTokens 

it reached max_tokens

StopSequence 

it produced a stop sequence

PauseTurn 

the provider paused a long turn; send the conversation back to continue

Refusal 

it declined

Other 

a reason this version doesn't know; see ChatResponse::stop_reason_text

Function Documentation

◆ CheckSchema()

void pulsatrix::orch::CheckSchema ( const JsonValue &  schema)

Checks that schema uses only the supported keywords, each with a valid value.

Exceptions
std::invalid_argumentnaming the first problem and where it is in the schema.

◆ HttpBackendAvailable()

bool pulsatrix::orch::HttpBackendAvailable ( HttpBackend  backend)

Whether this build has backend.

◆ HttpsSupported()

bool pulsatrix::orch::HttpsSupported ( HttpBackend  backend)

Whether backend can make HTTPS requests in this build.

◆ IsValidToolName()

bool pulsatrix::orch::IsValidToolName ( const std::string &  name)

Whether name is a valid tool name (^[a-zA-Z0-9_-]{1,128}$).

◆ JsonEquals()

bool pulsatrix::orch::JsonEquals ( const JsonValue &  a,
const JsonValue &  b 
)

JSON equality, as enum, const and uniqueItems use it: numbers by value (1 equals 1.0), objects regardless of member order.

◆ MakeAnthropicProvider()

std::unique_ptr< Provider > pulsatrix::orch::MakeAnthropicProvider ( AnthropicOptions  options,
std::shared_ptr< HttpTransport >  transport = nullptr 
)

The Anthropic provider. transport defaults to MakeHttpTransport().

◆ MakeHttpTransport() [1/2]

std::unique_ptr< HttpTransport > pulsatrix::orch::MakeHttpTransport ( HttpBackend  backend,
HttpTransportOptions  options = {} 
)

A transport using backend.

Exceptions
std::invalid_argumentif this build doesn't have backend.

◆ MakeHttpTransport() [2/2]

std::unique_ptr< HttpTransport > pulsatrix::orch::MakeHttpTransport ( HttpTransportOptions  options = {})

A transport using libcurl if this build has it, which you asked for by turning it on, and cpp-httplib otherwise.

◆ MakeOpenAiCompatibleProvider()

std::unique_ptr< Provider > pulsatrix::orch::MakeOpenAiCompatibleProvider ( OpenAiCompatibleOptions  options,
std::shared_ptr< HttpTransport >  transport = nullptr 
)

The OpenAI-compatible provider. transport defaults to MakeHttpTransport().

◆ ParseHttpUrl()

HttpUrl pulsatrix::orch::ParseHttpUrl ( std::string_view  url)

Parses an http:// or https:// URL.

Exceptions
HttpError(InvalidRequest) for another scheme, user info (user@host), a fragment, an empty host, a bad port, or whitespace or control characters.

◆ RunToolLoop()

ToolLoopResult pulsatrix::orch::RunToolLoop ( Provider &  provider,
ChatRequest  request,
const ToolExecutor &  execute,
const ToolLoopOptions &  options = {} 
)

Sends request, runs each tool the model calls with execute, and sends the results back, until the model stops calling tools or options.max_turns requests have been made.

Note
The results of one answer's calls go back together, first in the next user message and in the order of the calls, as the Anthropic API requires. A PauseTurn answer is sent back as it is, to let the model continue.
Exceptions
ProviderErroror HttpError as Provider::chat() does.

◆ StrictModeProblem()

std::string pulsatrix::orch::StrictModeProblem ( const JsonValue &  schema)

Why schema can't be used with Anthropic's strict tool use, or "" if it can.

Note
Strict mode needs "additionalProperties": false on every object, and doesn't support numeric, string-length or most array constraints, oneOf, not, or enum values that are arrays or objects. Its limits across a whole request (20 strict tools, 24 optional parameters, 16 union-typed parameters) aren't checked here.
Exceptions
std::invalid_argumentif schema doesn't pass CheckSchema().

◆ ValidateJson()

std::vector< SchemaError > pulsatrix::orch::ValidateJson ( const JsonValue &  schema,
const JsonValue &  value,
std::size_t  max_errors = 16 
)

Checks value against schema.

Returns
The ways it fails, at most max_errors of them; empty if it matches. A failed anyOf, oneOf or not is one error, without the reasons inside it.
Note
Error messages never quote the value, which came from a model and may be large.
Exceptions
std::invalid_argumentif schema doesn't pass CheckSchema().