Download the PHP package aisdk/core without Composer

aisdk/core

Framework-agnostic PHP AI SDK core: contracts, fluent API, value objects, streaming, tools, structured output, and PSR integration.

Installation

Basic Usage

Default models allow terse call sites:

For long-running workers, concurrent applications, or dependency-injected code, use an instance runtime so configuration is not stored in static process state:

The static Generate and provider entry points remain convenient for scripts and request-scoped applications; the instance API is the safer choice when one PHP process serves multiple independent workloads.

Structured Output

Tools

Class-based tools:

Streaming

Stream hooks:

Image Generation

Generate multiple images or use portable image options:

Speech Generation

The portable speech surface supports input(), voice(), format(), and provider-specific options:

Embeddings

Generate one vector or a batch of vectors through the same text-only API:

dimensions() is the only portable embedding option. Provider-specific fields such as retrieval task type or truncation can be sent with providerOptions() using the provider package's documented field names.

Transcription

The portable transcription surface accepts typed audio content. Language hints, diarization, timestamp detail, and other provider-specific controls remain available through providerOptions().

Video Generation

Video providers expose asynchronous jobs through one portable API. run() waits for completion; job() starts the operation and returns its job descriptor.

Live Voice, Transcription, and Translation

AiSdk\Live is part of core. Provider packages prepare their endpoint, authentication, messages, and normalized events; the application supplies a transport that implements core's two small transport contracts.

The session API is transport-independent:

Use separate builders so an operation only exposes portable fields that apply to it:

providerOptions('provider-name', [...]) remains the escape hatch for provider-only session fields. Proxy, TLS, timeout, buffer, and frame-limit configuration belongs to the transport instead.

Ready-made transports

The optional aisdk/transport package supplies WebSocket and bidirectional HTTP/2 implementations:

Transport::auto() chooses from the endpoint prepared by the provider. Use Transport::webSocket() or Transport::http2() when the application should explicitly restrict the network protocol.

Core without aisdk/transport

Core has no Amp or WebSocket dependency. Install any networking library and implement AiSdk\Live\Contracts\TransportInterface plus TransportConnectionInterface. A complete Amp implementation is included in examples/AppWebSocketTransport.php:

Provider adapters only exchange TransportFrame::text() and TransportFrame::binary() with the transport. A custom transport must not interpret provider event names.

events() waits for incoming network data. For continuous, full-duplex audio, run the microphone sender and event consumer concurrently using the async runtime chosen by your application. Core itself does not expose Amp, Revolt, or another event-loop type; the ready-made transport README includes an Amp example.

Tools and normalized events

Voice tools use the same core Tool objects as text generation. A registered tool with a handler is executed automatically. The ToolCallEvent is still emitted for observability, followed by an automatic ToolResultEvent. Unknown or handler-less tools remain manual:

Portable events cover audio and text deltas, append-only transcript deltas, replaceable transcript updates, completed transcripts, speech boundaries, interruptions, tool calls and results, usage, response completion, errors, and closure. Unknown provider messages are preserved as ProviderEvent rather than discarded.

WebRTC and provider-hosted calls

WebRTC and SIP are connection topologies, not PHP media transports. A browser uses its native RTCPeerConnection; PHP creates a short-lived client secret or exchanges an SDP offer through the provider adapter:

For an incoming provider-hosted call, first verify the webhook with the provider package, then control the call through core:

That control connection is sometimes called a sideband connection: the provider continues carrying WebRTC or SIP media, while the backend attaches a WebSocket to the same call ID to update the session, observe events, and handle tools. Providers expose lifecycle methods only where their official protocol supports them.

Model IDs and Capabilities

Model IDs are opaque provider values. Packages do not ship model inventories, so new, private, routed, deployed, and locally installed models can be used without waiting for an SDK release:

Provider::model() is the only public provider model selector. The operation resolves that opaque reference to its internal text, image, speech, transcription, embedding, video, or Live adapter when the request executes.

Adapter capabilities are internal implementation details. Before sending a request, the SDK verifies that the selected provider adapter can serialize the requested features. The provider remains the authority on whether the exact model accepts those features. Models never need to be registered with the SDK.

Providers whose available models depend on the current account, region, or local runtime may implement AvailableModelsProviderInterface and, where supported, ModelInspectionProviderInterface. Provider packages should query an authoritative runtime endpoint instead of presenting a bundled list as live availability. For example, Ollama exposes Ollama::availableModels() for its local registry and Ollama::inspectModel() for informational model details.

Supported Capabilities

• Text generation (Generate::text())
• Streaming text generation (->stream())
• Image generation (Generate::image())
• Speech generation (Generate::speech())
• Text embeddings (Generate::embedding())
• Audio transcription (Generate::transcription())
• Video generation and asynchronous jobs (Generate::video(), Generate::videoJob())
• Live voice, transcription, and translation (Live::voice(), Live::transcribe(), Live::translate())
• Tool calling (->tool(...))
• Structured output (->output(...))
• Provider options passthrough (->providerOptions(...))
• Normalized provider errors

Testing

Core ships with fakes and assertions for deterministic testing:

Embedding tests can use AiSdk\Testing\Fakes\FakeEmbeddingModel in the same way. Transcription tests can use AiSdk\Testing\Fakes\FakeTranscriptionModel.

Documentation

• PHP AI SDK documentation
• Core documentation

Community

• Contributing
• Support
• For private security reports, email [email protected].