Ax for C++ API Reference

This generated API reference is emitted by AxIR from compiler-owned metadata. Do not edit it by hand; change the AxIR generator and regenerate packages instead.

Package

Target: cpp
Package: axllm
AxIR contract: 0.1

Signatures

Describe typed Ax inputs and outputs once, then reuse that shape for schemas, prompts, validation, tools, and structured results.

`axllm::s`

Parse an Ax string signature into the target language signature object.

Canonical Ax concept: s
Kind: function
Form: axllm::s(const std::string& signature)
Returns: AxSignature

C++

auto sig = axllm::s("question:string -> answer:string");

`axllm::FieldType`

Build signatures and field types fluently when the target has a fluent helper.

Canonical Ax concept: f
Kind: function
Form: FieldType / Field descriptors
Returns: signature builder or field factory
Important options: input fields, output fields, field descriptions, constraints

`axllm::AxSignature`

Parsed signature with input/output fields, descriptions, and JSON schema helpers.

Canonical Ax concept: AxSignature
Kind: type
Form: axllm::Value signature
Returns: signature object
Important options: inputs, outputs, description

AxGen

Run structured generation with Core-owned prompts, indexed multi-sampling, result selection, tool loops, retries, streaming folds, traces, usage, examples, and field processors.

`axllm::ax`

Create an AxGen program from a string or parsed signature.

Canonical Ax concept: ax
Kind: function
Form: axllm::ax(signature, options)
Returns: AxGen
Important options: functions, examples, demos, sample count, result picker, modelConfig, maxRetries, streaming assertions, field processors

C++

auto qa = axllm::ax("question:string -> answer:string");

`axllm::AxGen`

Structured generation program with indexed multi-sampling, winner selection, forward, streaming, optimization, trace, usage, and tool-call behavior.

Canonical Ax concept: AxGen
Kind: type
Form: axllm::AxGen(signature, options)
Returns: program object
Important options: signature, functions, examples, demos, sample count, result picker, memory, prompt template

AxAI

Call supported providers through the shared provider descriptor registry, scripted transports, routers, and balancers.

`axllm::ai`

Create a provider client from a named deployment profile and options.

Canonical Ax concept: ai
Kind: function
Form: axllm::ai(provider, options)
Returns: AI client/service
Important options: api key or credential provider, model, api URL, headers, transport

C++

auto client = axllm::ai("openai", axllm::object({{"apiKey", std::getenv("OPENAI_API_KEY")}}));

`axllm::get_supported_ai_models`

Return the AxIR-backed provider and model catalog, including dynamic named profiles and portable capability metadata.

Canonical Ax concept: get_supported_ai_models
Kind: function
Form: axllm::get_supported_ai_models(options)
Returns: provider catalog entries
Important options: type filter, thinkingLevels, serviceTiers, isDynamic

C++

auto catalog = axllm::get_supported_ai_models();

`axllm::AxCredentialRequest`

Request metadata passed to a renewable credential callback for every transport attempt.

Canonical Ax concept: AxCredentialRequest
Kind: type
Form: axllm::AxCredentialRequest
Returns: credential request
Important options: profile, operation, method, URL

`axllm::AxCredentialProvider`

Return fresh request headers that override static profile authentication.

Canonical Ax concept: AxCredentialProvider
Kind: interface
Form: axllm::AxCredentialProvider
Returns: header map or credential error
Important options: chat, stream, embeddings, Responses, audio, retries

`axllm::AxStreamHandler`

Incremental, closeable provider event stream. Retry and failover stop once content is delivered.

Canonical Ax concept: AxProviderStream
Kind: type
Form: client.stream_each(request, handler)
Returns: incremental chat events
Important options: next event, terminal error, consumer cancellation, upstream close

C++

client.stream_each(request, [&](const auto& event) { handle(event); return true; });

`axllm::OpenAICompatibleClient`

OpenAI-compatible chat, stream, embedding, audio, and realtime provider boundary.

Canonical Ax concept: OpenAICompatibleClient
Kind: type
Form: axllm::OpenAICompatibleClient(options, transport)
Returns: provider client
Important options: api key, model, base URL, transport

`axllm::OpenAIResponsesClient`

OpenAI Responses provider mapping using the same Core-owned request and response contract.

Canonical Ax concept: OpenAIResponsesClient
Kind: type
Form: axllm::OpenAIResponsesClient(options, transport)
Returns: provider client
Important options: api key, model, audio, realtime

`axllm::GoogleGeminiClient`

Gemini provider mapping for chat, streaming, media, tools, embeddings, and usage normalization.

Canonical Ax concept: GoogleGeminiClient
Kind: type
Form: axllm::GoogleGeminiClient(options, transport)
Returns: provider client
Important options: api key, model, embed model

`axllm::AnthropicClient`

Anthropic provider mapping for messages, thinking, cache control, streaming, and usage normalization.

Canonical Ax concept: AnthropicClient
Kind: type
Form: axllm::AnthropicClient(options, transport)
Returns: provider client
Important options: api key, model, thinking, cache control

`axllm::AxUsageContext`

Application attribution merged from service defaults and per-call overrides.

Canonical Ax concept: AxUsageContext
Kind: type
Form: axllm::AxUsageContext
Returns: usage context
Important options: tenant, user, request, run, feature, attributes

`axllm::AxUsageEvent`

Normalized token usage and correlation data for one completed chat or embedding operation.

Canonical Ax concept: AxUsageEvent
Kind: type
Form: axllm::AxUsageEvent
Returns: usage event
Important options: provider, model, tokens, context, correlation IDs, streaming

`axllm::AxUsageObserver`

Best-effort process-wide callback for normalized usage events.

Canonical Ax concept: AxUsageObserver
Kind: interface
Form: axllm::AxUsageObserver
Returns: usage observer
Important options: fail-open delivery, synchronous enqueue

`axllm::set_usage_observer`

Canonical Ax concept: set_usage_observer
Kind: function
Form: axllm::set_usage_observer(observer)
Returns: void
Important options: observer, clear

C++

axllm::set_usage_observer([&](auto event) { events.push_back(event); });

`axllm::AxRuntimeHooks`

Non-serializable rate limiter, tracer, and meter overrides for one service or program execution.

Canonical Ax concept: AxRuntimeHooks
Kind: type
Form: axllm::AxRuntimeHooks
Returns: runtime hooks
Important options: rate limiter, tracer, meter, precedence

C++

axllm::AxRuntimeHooks hooks{limiter, tracer, meter};

`axllm::AxRateLimitInfo`

Provider and model metadata supplied to a request-wrapper rate limiter.

Canonical Ax concept: AxRateLimitInfo
Kind: type
Form: axllm::AxRateLimitInfo
Returns: rate-limit context
Important options: operation, provider, model, streaming, previous usage

`axllm::AxRateLimiter`

Request wrapper that can delay, reject, or execute a chat or embedding request.

Canonical Ax concept: AxRateLimiter
Kind: interface
Form: axllm::AxRateLimiter
Returns: provider result
Important options: next, metadata, errors

`axllm::AxTracer`

Dependency-neutral tracer that creates metadata-only Ax spans.

Canonical Ax concept: AxTracer
Kind: interface
Form: axllm::AxTracer
Returns: span
Important options: start span, parent span, fail-open

`axllm::AxMeter`

Dependency-neutral meter for Ax counters, histograms, and gauges.

Canonical Ax concept: AxMeter
Kind: interface
Form: axllm::AxMeter
Returns: instrument
Important options: counter, histogram, gauge, fail-open

`axllm::AxGlobals`

Process-wide live defaults for runtime hooks and usage observation.

Canonical Ax concept: AxGlobals
Kind: type
Form: axllm::AxGlobals
Returns: global hooks
Important options: rate limiter, tracer, meter, usage observer

`axllm::set_rate_limiter`

Canonical Ax concept: set_rate_limiter
Kind: function
Form: axllm::set_rate_limiter(limiter)
Returns: void
Important options: limiter, clear

C++

axllm::set_rate_limiter(limiter);

`axllm::set_tracer`

Canonical Ax concept: set_tracer
Kind: function
Form: axllm::set_tracer(tracer)
Returns: void
Important options: tracer, clear

C++

axllm::set_tracer(tracer);

`axllm::set_meter`

Canonical Ax concept: set_meter
Kind: function
Form: axllm::set_meter(meter)
Returns: void
Important options: meter, clear

C++

axllm::set_meter(meter);

`axllm::AxBalancer`

Retry and route requests across multiple provider services, with opt-in adaptive cost, reliability, and deadline routing.

Canonical Ax concept: AxBalancer
Kind: type
Form: axllm::AxBalancer(services, options)
Returns: AI service
Important options: services, retry policy, capability requirements, adaptive strategy

`axllm::AxBalancerAdaptiveStrategy`

Configure adaptive provider routing without changing the ordered default.

Canonical Ax concept: AxBalancerAdaptiveStrategy
Kind: type
Form: axllm::AxBalancerAdaptiveStrategy
Returns: adaptive strategy
Important options: deadline, bad outcome cost, expected tokens, stable route keys, slice, stats store, routing events

`axllm::AxBalancerStatsStore`

Store shared adaptive decision state with atomic observations.

Canonical Ax concept: AxBalancerStatsStore
Kind: interface
Form: axllm::AxBalancerStatsStore
Returns: stats store
Important options: get, observe

`axllm::AxInMemoryBalancerStatsStore`

Thread-safe in-memory adaptive stats store.

Canonical Ax concept: AxInMemoryBalancerStatsStore
Kind: type
Form: axllm::AxInMemoryBalancerStatsStore
Returns: stats store

`axllm::create_balancer_route_stats`

Create neutral adaptive route statistics.

Canonical Ax concept: create_balancer_route_stats
Kind: function
Form: axllm::create_balancer_route_stats
Returns: route stats

`axllm::update_balancer_route_stats`

Purely reduce one success or failure observation into route statistics.

Canonical Ax concept: update_balancer_route_stats
Kind: function
Form: axllm::update_balancer_route_stats
Returns: route stats
Important options: current stats, observation

`axllm::sample_balancer_route_health`

Sample failure and deadline-miss probability for adaptive exploration.

Canonical Ax concept: sample_balancer_route_health
Kind: function
Form: axllm::sample_balancer_route_health
Returns: sampled health
Important options: route stats, deadline

`axllm::MultiServiceRouter`

Choose a service by capability or model routing policy.

Canonical Ax concept: MultiServiceRouter
Kind: type
Form: axllm::MultiServiceRouter(services)
Returns: AI service
Important options: services, routing

`axllm::ProviderRouter`

Route requests by capability, preserving native media for supporting providers and degrading only when required.

Canonical Ax concept: ProviderRouter
Kind: type
Form: axllm::ProviderRouter(providers, routing, processing)
Returns: AI service
Important options: providers, routing, processing

Agents And RLM

Run AxAgent through the RLM executor loop with stage instructions, validated evidence citations, persistent playbooks, and actor-code execution through an AxCodeRuntime session.

`axllm::agent`

Create an AxAgent from a signature and agent/runtime options.

Canonical Ax concept: agent
Kind: function
Form: axllm::agent(signature, options)
Returns: AxAgent
Important options: name, description, runtime, maxSteps, context fields, discovery, recall, functions, skills, skillsCatalog, memoriesCatalog, relevanceRanking, load observers, used observers, citations, playbook, instruction, instructionAddenda

C++

auto helper = axllm::agent("query:string -> answer:string");

`axllm::AxAgent`

RLM agent with Core-owned envelopes, complete runtime-state export/restore, traces, discovery, recall, loaded skills and memories, usage observers, delegation, validated citations, stage instructions, persistent run-end learning, and verified playbook evolution.

Canonical Ax concept: AxAgent
Kind: type
Form: axllm::AxAgent(signature, options)
Returns: agent program
Important options: executor model, runtime, policy, context, skills, memories, relevance ranking, observers, runtime state, optimizer metadata, citations, playbook

Flow

Compose AxGen, AxAgent, and nested flows into a portable program graph.

`axllm::flow`

Create an AxFlow program graph or compile the portable Mermaid shorthand.

Canonical Ax concept: flow
Kind: function
Form: axllm::flow(options) / axllm::flow(mermaid, bindings)
Returns: AxFlow
Important options: nodes, execute mappers, conditions, cache, returns, Mermaid roundtrip

C++

auto wf = axllm::flow();

`axllm::AxFlow`

Workflow graph with Core-owned planning, cache keys, state merge, child aggregation, optimization, and returns projection.

Canonical Ax concept: AxFlow
Kind: type
Form: axllm::AxFlow(optionsOrMermaid, bindings)
Returns: flow program
Important options: steps, state, parallel groups, returns

Tools

Expose host functions to AxGen and AxAgent with typed argument and return schemas.

`axllm::Tool`

Build a typed function tool. Rust uses tool because fn is reserved.

Canonical Ax concept: fn
Kind: function
Form: axllm::Tool(name, description, parameters, handler)
Returns: tool builder or Tool
Important options: name, description, args, returns, handler

C++

axllm::Tool search("search", "Search docs", axllm::object({}), handler);

`axllm::Tool`

Callable tool descriptor with JSON-schema-compatible parameters and a host handler.

Canonical Ax concept: Tool
Kind: type
Form: axllm::Tool
Returns: tool descriptor
Important options: parameters, returns, handler

MCP

Use MCP clients and transports while keeping JSON-RPC lifecycle, tools, prompts, resources, OAuth, cancellation, and SSRF checks aligned.

`axllm::AxMCPClient`

MCP client that lists tools/prompts/resources and converts MCP tools to Ax functions.

Canonical Ax concept: AxMCPClient
Kind: type
Form: axllm::AxMCPClient(transport, options)
Returns: MCP client
Important options: transport, client info, roots, tool overrides

C++

axllm::AxMCPClient client(transport);

`axllm::AxMCPStreamableHTTPTransport`

Streamable HTTP transport with session headers, OAuth options, and SSRF protection.

Canonical Ax concept: AxMCPStreamableHTTPTransport
Kind: type
Form: axllm::AxMCPStreamableHTTPTransport(endpoint, options)
Returns: MCP transport
Important options: endpoint, headers, OAuth, SSRF protection

`axllm::AxMCPStdioTransport`

Stdio transport with JSON-RPC framing for local MCP servers.

Canonical Ax concept: AxMCPStdioTransport
Kind: type
Form: axllm::AxMCPStdioTransport(command, options)
Returns: MCP transport
Important options: command, args, env

Runtime Profiles

Run RLM actor code through the portable AxCodeRuntime and optional target-specific runtime profiles.

`axllm::ProcessCodeRuntime`

Process/JSONL runtime adapter for actor-code sessions and runtime protocol tests.

Canonical Ax concept: ProcessCodeRuntime
Kind: type
Form: axllm::RuntimeProtocolClient(transport)
Returns: AxCodeRuntime
Important options: command, env, cwd, timeout

C++

auto runtime = axllm::RuntimeProtocolClient(transport);

`axllm::RuntimeCapabilities`

Runtime capability envelope visible to the agent runtime policy.

Canonical Ax concept: RuntimeCapabilities
Kind: type
Form: axllm::RuntimeCapabilities
Returns: capability record
Important options: language, snapshot, patch, abort, usage instructions

`axllm::RuntimeEnvelope`

Actor primitive envelope for final, clarification, discovery, recall, used, guidance, and runtime results.

Canonical Ax concept: RuntimeEnvelope
Kind: type
Form: axllm::RuntimeEnvelope
Returns: runtime envelope
Important options: type, args, result, error

`javascript-quickjs`

Optional runtime profile for javascript actor code.

Canonical Ax concept: runtime-profile:javascript-quickjs
Kind: runtime-profile
Form: tools/axir verify --targets cpp --runtime-profiles javascript-quickjs
Returns: AxCodeRuntime-compatible actor execution profile
Important options: actor language: javascript, support mode: embedded, dependency mode: optional-build, feature gate: AX_BUILD_QUICKJS_PROFILE, environment gate: AXIR_QUICKJS_CFLAGS, environment gate: AXIR_QUICKJS_LDFLAGS

`python-pyodide`

Optional runtime profile for python actor code.

Canonical Ax concept: runtime-profile:python-pyodide
Kind: runtime-profile
Form: tools/axir verify --targets cpp --runtime-profiles python-pyodide
Returns: AxCodeRuntime-compatible actor execution profile
Important options: actor language: python, support mode: process-adapter, dependency mode: optional-env, environment gate: AXIR_PYODIDE_RUNTIME_SERVER, environment gate: AXIR_PYODIDE_RESOLVE

Optimizers

Optimize Ax programs through BootstrapFewShot -> GEPA composition and evolve program or agent playbooks through grounded, budgeted, rollback-safe learning.

`axllm::optimize`

Convenience optimizer helper that composes AxBootstrapFewShot before AxGEPA and returns an artifact without applying final component changes.

Canonical Ax concept: optimize
Kind: function
Form: axllm::optimize(program, student, examples, options, teacher)
Returns: optimized artifact
Important options: student/client, teacher/reflection client, metric budget, bootstrap

C++

auto artifact = axllm::optimize(qa, client, train, axllm::object({}), &reflection);

`axllm::playbook`

Bind an ACE-backed playbook to a program; agents also expose an agent-bound playbook handle.

Canonical Ax concept: playbook
Kind: function
Form: axllm::playbook(program, student, options)
Returns: AxPlaybook
Important options: student/client, teacher, seed snapshot, online updates, verification budget

C++

auto pb = axllm::playbook(program, client);

`axllm::AxPlaybook`

Persistent playbook with render/update/snapshot operations and agent-bound verified evolve over train/validation task sets.

Canonical Ax concept: AxPlaybook
Kind: type
Form: axllm::AxPlaybook / agent.playbook(...)
Returns: playbook handle
Important options: verify, minHeldInGain, epsilon, runsPerTask, maxMetricCalls, maxProposals

`axllm::AxBootstrapFewShot`

Few-shot demonstration optimizer that selects successful evaluator rollouts before prompt/component evolution.

Canonical Ax concept: AxBootstrapFewShot
Kind: type
Form: axllm::AxBootstrapFewShot(options)
Returns: optimizer engine
Important options: quality threshold, max demos, max rounds, batch size

C++

axllm::AxBootstrapFewShot bootstrap(axllm::object({{"qualityThreshold", 0.7}}));

`axllm::AxGEPA`

Generated GEPA optimizer engine with Core-owned reflection, Pareto, bootstrap, and selector-state behavior.

Canonical Ax concept: AxGEPA
Kind: type
Form: axllm::AxGEPA(reflection, options)
Returns: optimizer engine
Important options: reflection client, budget, metric, candidate count

C++

axllm::AxGEPA engine(reflection_client);

`axllm::OptimizerEngine`

Optimizer boundary consumed by AxGen, AxAgent, and AxFlow optimization helpers.

Canonical Ax concept: OptimizerEngine
Kind: interface
Form: axllm::OptimizerEngine::optimize(request, evaluator)
Returns: optimized artifact
Important options: request, evaluator

`axllm::OptimizerEvaluator`

Evaluator callback boundary used by generated optimizers.

Canonical Ax concept: OptimizerEvaluator
Kind: interface
Form: axllm::OptimizerEvaluator::evaluate(request)
Returns: score/evidence result
Important options: dataset rows, candidate map, evidence

Errors And Values

Handle target-native errors and dynamic values at Ax host boundaries.

`axllm::AxError`

Target-native error envelope for validation, provider, runtime, MCP, and optimizer failures.

Canonical Ax concept: AxError
Kind: type
Form: axllm::AxError with target-native error handling
Returns: error
Important options: category, message, status, code, retryable

`axllm::Value`

Dynamic JSON-like value boundary used by generated package APIs, tools, providers, MCP, and runtime sessions.

Canonical Ax concept: Value
Kind: type
Form: axllm::Value
Returns: dynamic value
Important options: string, number, boolean, object, array, null