v0.13.0: Forced tool choice (toolChoice)

Add the provider-agnostic toolChoice chat option and the PapiAI\Core\ToolChoice validator. Callers pass "auto", "none", "required", or ["name" => ""]; the validator normalises it against the declared tools and throws before any HTTP call on an unknown value or an unenforceable choice (never silently drops). The chat options bag is now a reusable @psalm-type ChatOptions on ProviderInterface for providers to import. Providers map the option to their native mechanism from v0.13.0 onward. See #24 for the parked interface-segregation follow-up.

v0.12.0

Changes since 0.11:

Backward-compatible OCP/DIP hardening of papi-core. No public method is removed; the change is safe for existing consumers.

Neutral Usage value object

• New Usage (inputTokens, outputTokens, totalTokens, raw), implementing ArrayAccess over the legacy keys so $response->usage['input_tokens'] keeps working.
• Response and EmbeddingResponse store a Usage and accept Usage|array (array path deprecated).
• Bug fix: the token getters (getInputTokens() etc.) now read the normalised Usage, so they return correct counts for OpenAI-family providers and Cohere (previously 0).

Neutral tool flow

• Removed toAnthropic()/toOpenAI() from ToolInterface; kept them @deprecated on the concrete Tool.
• Agent now emits a neutral tool definition (name, description, parameters); each provider formats it to its own wire shape.

Provider-owned response mapping

• Response::fromAnthropic() and ToolCall::fromAnthropic() are @deprecated; Anthropic mapping now lives in the anthropic package. Response::fromOpenAI() stays as the shared OpenAI-compatible adapter.

v0.11.0

Changes since 0.10:

• Add LLMTokenOptimisationProxyInterface + OptimisationResult.

v0.10.0

Changes since v0.9.1:
VideoProviderInterface + VideoResponse; fix empty-model fallback.

v0.9.1

Changes since v0.9:

• Add PHPDoc to all classes and public methods

v0.9

Changes in this release

• AgentBuilder — fluent builder API: Agent::build()->provider($p)->model($m)->tools([...])->middleware([...])->create()
• Exception hierarchy:
  • PapiException — base exception for all PapiAI errors
  • ProviderException — provider errors with status code and response body
  • RateLimitException — rate limit errors with optional retry-after
  • AuthenticationException — authentication failures
• CostEstimate — value object for estimating API call costs from token usage and model pricing
• 183 tests, 0 psalm errors

v0.8

Changes in this release

• Middleware pipeline — MiddlewareInterface contract with process(AgentRequest, callable $next): Response
• Agent refactored to run requests through a configurable middleware pipeline (backwards-compatible)
• AgentRequest value object representing a request flowing through middleware
• QueueInterface contract with AgentJob and JobStatus for async agent execution
• Built-in middleware:
  • LoggingMiddleware — PSR-3 compatible logging (psr/log suggested, not required)
  • CacheMiddleware — PSR-16 compatible response caching (psr/simple-cache suggested, not required)
  • RateLimitMiddleware — in-memory token bucket rate limiter, zero dependencies
  • RetryMiddleware — configurable retry with exponential backoff, zero dependencies
• 167 tests, 81.6% coverage

v0.7

Changes in this release

• Add TextToSpeechProviderInterface contract for TTS providers
• Add TranscriptionProviderInterface contract for STT providers
• Add ConversationStoreInterface with FileConversationStore implementation for conversation persistence
• Add AudioResponse and TranscriptionResponse value objects
• Add toArray() / fromArray() serialization to Conversation and Message
• 140 tests, 83.5% coverage

v0.6

Changes in this release:

• EmbeddingProviderInterface — new contract for generating text embeddings via embed(string|array $input, array $options): EmbeddingResponse
• EmbeddingResponse — value object for embedding results with first(), dimensions(), count(), and usage tracking
• VectorStoreInterface — new contract for vector storage with upsert(), query(), delete(), flush(), and count()
• InMemoryVectorStore — pure PHP implementation with cosine similarity search and metadata filtering, zero dependencies
• FailoverProvider — wraps multiple providers with automatic failover on failure, configurable retry exception types, and getLastUsedProvider() tracking
• SearchResult — value object for vector query results with id, score, metadata, and content
• Development tooling — PHP CS Fixer (PSR-12), Psalm level 4 static analysis, CI workflow for PHP 8.2–8.5, pre-commit hooks, 75% minimum test coverage
• Bug fixes — removed unused variables in Agent, added toAnthropic()/toOpenAI() to ToolInterface, fixed redundant null check in Schema, adding missing imports in AgentInterface

v0.5

Changes in this release:

• Add ImageProviderInterface for image generation capability discovery
• Add Message and StreamChunk imports to ProviderInterface
• Fix issue in composer lock