Polyglot

Polyglot Package Cheatsheet

Code-verified API reference for packages/polyglot.

Core Facades

use Cognesy\Polyglot\Inference\Inference;
use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Decision\Decision;

$inference = new Inference();
$embeddings = new Embeddings();
$decision = new Decision();

Native Batch Jobs (Early Access)

use Cognesy\Polyglot\BatchInference\BatchInference;
use Cognesy\Polyglot\BatchInference\Collections\BatchItems;
use Cognesy\Polyglot\BatchInference\Data\BatchItem;
use Cognesy\Polyglot\Inference\Data\InferenceRequest;
use Cognesy\Messages\Messages;

$batches = BatchInference::using('mistral');
$job = $batches->submit(BatchItems::of(
    BatchItem::of('row-1', new InferenceRequest(messages: Messages::fromString('Summarize this.'))),
));
$saved = $job->reference()->toArray();

Persist $saved, reconstruct it with BatchReference::fromArray() in a later process, then call retrieve(), results(), cancel(), or listJobs() explicitly. See docs/batch-inference/overview.md for the asynchronous lifecycle and provider capabilities.

Inference Quick Start

Use a preset for the normal path:

use Cognesy\Polyglot\Inference\Inference;
use Cognesy\Messages\Messages;

$message = Inference::using('openai')
    ->withModel('gpt-4.1-nano')
    ->withMessages(Messages::fromString('Say hello in one sentence.'))
    ->get();

$text = $message->content()->toString();

Get parsed JSON:

use Cognesy\Polyglot\Inference\Data\ResponseFormat;

$data = Inference::using('openai')
    ->withModel('gpt-4.1-nano')
    ->withResponseFormat(ResponseFormat::jsonObject())
    ->withMessages(Messages::fromString('Return JSON with key "ok".'))
    ->asJsonData();

Inference Constructors

use Cognesy\Polyglot\Inference\Config\LLMConfig;
use Cognesy\Polyglot\Inference\Inference;
use Cognesy\Polyglot\Inference\InferenceRuntime;
use Cognesy\Polyglot\Inference\LLMProvider;

$inference = new Inference();
$inference = Inference::using('openai');
$inference = Inference::fromConfig(LLMConfig::fromPreset('openai'));
$inference = Inference::fromProvider(LLMProvider::using('openai'));
$inference = Inference::fromRuntime(
    InferenceRuntime::fromConfig(LLMConfig::fromPreset('openai')),
);
$inference = $inference->withRuntime(
    InferenceRuntime::fromConfig(LLMConfig::fromPreset('openai')),
);

Inference Request Builder Methods

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Config\InferenceRetryPolicy;
use Cognesy\Polyglot\Inference\Data\ResponseFormat;
use Cognesy\Polyglot\Inference\Data\ToolChoice;
use Cognesy\Polyglot\Inference\Data\ToolDefinitions;
use Cognesy\Polyglot\Inference\Enums\ResponseCachePolicy;

$inference = Inference::using('openai')
    ->withMessages($messages)           // Messages
    ->withModel('gpt-4.1-nano')
    ->withMaxTokens(800)
    ->withTools($tools)                 // ToolDefinitions
    ->withToolChoice(ToolChoice::auto())
    ->withResponseFormat($responseFormat) // ResponseFormat
    ->withOptions(['temperature' => 0])
    ->withStreaming(true)
    ->withResponseCachePolicy(ResponseCachePolicy::Memory)
    ->withRetryPolicy(new InferenceRetryPolicy(maxAttempts: 3))
    ->withCachedContext(
        messages: $cachedMessages,       // ?Messages
        tools: $cachedTools,             // ?ToolDefinitions
        toolChoice: ToolChoice::auto(),
        responseFormat: $cachedResponseFormat, // ?ResponseFormat
    );

Single-call variant:

$inference = Inference::using('openai')->with(
    messages: $messages,           // ?Messages
    model: 'gpt-4.1-nano',
    tools: $tools,                 // ?ToolDefinitions
    toolChoice: ToolChoice::auto(),
    responseFormat: $responseFormat, // ?ResponseFormat
    options: ['temperature' => 0],
);

With explicit request:

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Data\InferenceRequest;

$request = new InferenceRequest(
    messages: Messages::fromString('Hello'),
    model: 'gpt-4.1-nano',
);

$pending = Inference::using('openai')
    ->withRequest($request)
    ->create();

Inference Execution Surfaces

$pending = $inference->create();

$message = $inference->get();
$response = $inference->response();
$json = $inference->asJson();
$data = $inference->asJsonData();
$toolJson = $inference->asToolCallJson();
$toolData = $inference->asToolCallJsonData();
$stream = $inference->stream();

$isStreamed = $pending->isStreamed();
$message = $pending->get();
$response = $pending->response();
$json = $pending->asJson();
$data = $pending->asJsonData();
$toolJson = $pending->asToolCallJson();
$toolData = $pending->asToolCallJsonData();
$stream = $pending->stream();

Reasoning, Model Facts, and Pricing

Reasoning is projected from the ordered assistant message:

$reasoning = $response->message()->reasoningContent();

foreach ($stream->deltas() as $delta) {
    echo $delta->messageChunks->reasoningDelta();
}

Read model facts using one exact (driver, wire model) key. An absent key returns unknown facts; the catalog does not infer from the model name:

use Cognesy\Polyglot\Inference\Models\ModelCatalog;

$profile = ModelCatalog::discover()->find('qwen', 'qwen3.8-max');
$profile->limits->contextWindow;
$profile->capabilities->tools;
$profile->capabilities->reasoning;

The catalog is not used by ordinary inference unless it is passed explicitly to InferenceRuntime. Reuse one discovered catalog at the application composition root when local capability policy or metadata is needed. Known semantic fallback is off by default; direct PHP config uses allowLossyFallback: true, while Laravel and Symfony connection config uses allow_lossy_fallback: true. Every accepted adjustment is observable on the effective request and InferenceRequested event.

Pricing is caller-owned and is not stored in model catalog records:

use Cognesy\Polyglot\Inference\Data\InferencePricing;
use Cognesy\Polyglot\Inference\Pricing\FlatRateCostCalculator;

$cost = (new FlatRateCostCalculator())->calculate(
    usage: $response->usage(),
    // Illustrative USD rates per 1M tokens; supply your current sourced rates.
    pricing: new InferencePricing(
        inputPerMToken: 0.20,
        outputPerMToken: 0.80,
    ),
);

Streaming (InferenceStream)

$stream = $inference
    ->withStreaming(true)
    ->create()
    ->stream();

foreach ($stream->deltas() as $delta) {
    // PartialInferenceDelta
}

$mapped = $stream->map(fn($delta) => $delta->messageChunks->textDelta());
$filtered = $stream->filter(fn($delta) => $delta->messageChunks->textDelta() !== '');
$total = $stream->reduce(
    fn($carry, $delta) => $carry + strlen($delta->messageChunks->textDelta()),
    0,
);

$allDeltas = $stream->all();
$final = $stream->final(); // ?InferenceResponse

$stream->onDelta(function ($delta): void {
    // callback for each visible delta
});

$lastDelta = $stream->lastDelta();
$usage = $stream->usage();
$execution = $stream->execution();

Inference Runtime / Provider Setup

use Cognesy\Polyglot\Inference\Config\LLMConfig;
use Cognesy\Polyglot\Inference\InferenceRuntime;
use Cognesy\Polyglot\Inference\LLMProvider;

$runtime = InferenceRuntime::fromConfig(LLMConfig::fromPreset('openai'));
$runtime = InferenceRuntime::fromProvider(LLMProvider::using('openai'));

$provider = LLMProvider::using('openai')
    ->withConfigOverrides(['model' => 'gpt-4.1-nano'])
    ->withModel('gpt-4.1-mini');

Driver registry helpers:

use Cognesy\Polyglot\Inference\Creation\InferenceDriverRegistry;

$drivers = InferenceDriverRegistry::default()
    ->withDriver('custom', $driverFactory);

$runtime = InferenceRuntime::fromConfig(
    LLMConfig::fromArray([
        'driver' => 'custom',
        'apiUrl' => 'https://example.test',
        'endpoint' => '/v1/chat',
        'model' => 'custom-model',
    ]),
    drivers: $drivers,
);

Embeddings Quick Start

use Cognesy\Polyglot\Embeddings\Embeddings;

$vectors = Embeddings::using('openai')
    ->withModel('text-embedding-3-small')
    ->withInputs(['hello world'])
    ->vectors();

Embeddings Constructors and Builder Methods

use Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig;
use Cognesy\Polyglot\Embeddings\Config\EmbeddingsRetryPolicy;
use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Embeddings\EmbeddingsProvider;
use Cognesy\Polyglot\Embeddings\EmbeddingsRuntime;

$embeddings = new Embeddings();
$embeddings = Embeddings::using('openai');
$embeddings = Embeddings::fromConfig(EmbeddingsConfig::fromPreset('openai'));
$embeddings = Embeddings::fromProvider(
    EmbeddingsProvider::fromEmbeddingsConfig(EmbeddingsConfig::fromPreset('openai')),
);
$embeddings = Embeddings::fromRuntime(
    EmbeddingsRuntime::fromConfig(EmbeddingsConfig::fromPreset('openai')),
);

$embeddings = $embeddings
    ->withInputs(['a', 'b'])
    ->withModel('text-embedding-3-small')
    ->withOptions(['dimensions' => 512])
    ->withRetryPolicy(new EmbeddingsRetryPolicy(maxAttempts: 3));

Single-call variant:

$embeddings = Embeddings::using('openai')->with(
    input: ['hello'],
    options: ['dimensions' => 512],
    model: 'text-embedding-3-small',
);

With explicit request:

use Cognesy\Polyglot\Embeddings\Data\EmbeddingsRequest;

$request = new EmbeddingsRequest(
    input: ['hello'],
    model: 'text-embedding-3-small',
);

$pending = Embeddings::using('openai')
    ->withRequest($request)
    ->create();

Execution shortcuts:

$response = $embeddings->get();
$vectors = $embeddings->vectors();
$first = $embeddings->first();

$pending = $embeddings->create();
$request = $pending->request();
$response = $pending->get();

Embeddings Runtime / Provider Setup

use Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig;
use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Embeddings\EmbeddingsProvider;
use Cognesy\Polyglot\Embeddings\EmbeddingsRuntime;

$runtime = EmbeddingsRuntime::fromConfig(EmbeddingsConfig::fromPreset('openai'));
$runtime = EmbeddingsRuntime::fromProvider(
    EmbeddingsProvider::fromEmbeddingsConfig(EmbeddingsConfig::fromPreset('openai')),
);

$provider = EmbeddingsProvider::new()
    ->withConfig(EmbeddingsConfig::fromPreset('openai'))
    ->withConfigOverrides(['model' => 'text-embedding-3-small']);

Decision Quick Start

use Cognesy\Polyglot\Decision\Collections\ChoiceOptions;
use Cognesy\Polyglot\Decision\Collections\Questions;
use Cognesy\Polyglot\Decision\Collections\ScoreLevels;
use Cognesy\Polyglot\Decision\Data\ChoiceOption;
use Cognesy\Polyglot\Decision\Decision;
use Cognesy\Polyglot\Decision\Questions\Choice;
use Cognesy\Polyglot\Decision\Questions\Noul;
use Cognesy\Polyglot\Decision\Questions\Score;

$questions = Questions::of(
    new Noul('billing', 'Is this about billing?'),
    new Choice(
        id: 'tone',
        options: ChoiceOptions::of(
            new ChoiceOption('calm'),
            new ChoiceOption('frustrated'),
        ),
        instructions: 'What is the tone?',
    ),
    new Score(
        id: 'urgency',
        levels: ScoreLevels::of('low', 'medium', 'high'),
        instructions: 'How urgent is this?',
    ),
);

$answers = Decision::using('typesafe')
    ->with(input: 'Charged twice; please help today.', questions: $questions)
    ->get();

$probability = $answers->noul('billing')->probability();
$tone = $answers->choice('tone')->value();
$urgency = $answers->score('urgency')->value();

Decision Runtime and Pending Result

use Cognesy\Polyglot\Decision\Config\DecisionConfig;
use Cognesy\Polyglot\Decision\Config\DecisionRetryPolicy;
use Cognesy\Polyglot\Decision\Data\DecisionRequest;
use Cognesy\Polyglot\Decision\DecisionRuntime;

$runtime = DecisionRuntime::fromConfig(DecisionConfig::fromPreset('typesafe'));
$pending = $runtime->create(new DecisionRequest(
    input: 'Charged twice; please help today.',
    questions: $questions,
    retryPolicy: new DecisionRetryPolicy(maxAttempts: 3),
));

$request = $pending->request();
$executionId = $pending->executionId();
$answers = $pending->get();
$response = $pending->response(); // memoized after get()

Decision defaults to one attempt and has no streaming API. Lifecycle telemetry uses sdm.decision and sdm.decision.attempt. See docs/decision/overview.md for serialization, structured content, dynamic options, retry ownership, and live testing.

Bundled Decision presets are explicit:

Preset	Semantics
typesafe	Native Choice, Noul, and Score
classifier-dev	Native Choice; projected Noul and Score
clef, clef-flash	Native Choice, Noul, and Score on Cloudflare Workers AI
fastino	Native Choice, Noul, and Score via fastino/GLiDE; set a 300 s timeout
jeff	Native primitives; Score requires JEFF_TEMPERATURE=1
laya	Native primitives plus typed modelActionProbability signals
perplexity	Native Choice, Noul, and Score via pplx-decider-v1-27b

Provider compatibility does not imply equal quality or calibration. Run the fixed example corpus with php examples/B06_Decisions/ProviderEvaluation/evaluate.php <preset>, then replace it with independently labeled application cases.

Testing

Deterministic test seams:

• Tests\Support\FakeInferenceDriver
  • queue sync InferenceResponse fixtures or streaming PartialInferenceDelta batches
  • best for most inference runtime tests that do not need HTTP or adapter coverage
• Tests\Support\FakeEmbeddingsDriver
  • queue EmbeddingsResponse fixtures and record handled requests
  • best for most embeddings runtime and memoization tests
• MockHttpDriver
  • use when transport and provider adapter behavior still matter
  • best for golden tests, request assertions, and provider-specific error-path coverage
• POLYGLOT_TYPESAFE_LIVE=1
  • opts into the bounded TypeSafe integration smoke
• POLYGLOT_CLASSIFIER_DEV_LIVE=1, POLYGLOT_CLEF_LIVE=1, POLYGLOT_FASTINO_LIVE=1, POLYGLOT_JEFF_LIVE=1, POLYGLOT_LAYA_LIVE=1, and POLYGLOT_PERPLEXITY_LIVE=1
  • opt into the corresponding bounded provider smoke
• ordinary test runs remain offline and do not require credentials, Python, model weights, or special hardware