Merge branch 'trunk' into add/architecture-definition

Author: felixarntz

docs/GLOSSARY.md

@@ -3,13 +3,17 @@
 This glossary defines common terms relevant for the PHP AI Client and related projects.
 
 * **Agent**: An autonomous system that can perceive its environment, make decisions, and take actions to achieve specific goals, often leveraging AI models.
-* **AI Capability**: A single string that denotes an AI feature, such as text generation or image generation.
-* **AI Option**: A parameter that can be passed to a model, such as temperature or output MIME type.
+* **Candidate Count**: The number of different response options an LLM generates internally.
+* **Capability**: A specific skill, function, or type of task that an AI model can perform, e.g. text generation or image generation.
+* **Extender API**: The API used by developers that want to enable the use of additional _Providers_ or _Models_.
 * **Generative AI**: Overaching term describing AI models that generate content as requested in a prompt.
+* **Implementer API**: The API used by people that want to _implement_ AI features in their own software/products.
 * **MCP**: The "Model Context Protocol", a proposed standard for connecting AI assistants to the systems where data lives.
 * **Message**: A single message, either a user prompt, a model response, or a system prompt—optionally containing of multiple message parts.
 * **Message part**: A part of a message, such as a piece of text, a URL, a file, or a function call.
 * **Modality**: The type or format of input provided to, or output received from, an AI model. Examples include text, image, audio, and video.
 * **Model**: A specific AI model that supports arbitrary AI features and modalities. Examples include content generation, classification, embedding.
+* **Option**: AI configuration and output options for a model, e.g. temperature or output schema.
 * **Prompt**: The input that a generative AI model uses to generate content—often text, but it can also be of other modalities.
 * **Provider**: An entity (company, organization, or platform) that offers access to one or more AI models or services via an API (e.g., Anthropic, Google, OpenAI, a locally hosted service).
+* **Provider Registry**: Manages the available AI _Providers_ and _Models_. Provides a mechanism to find models that match criteria for a given AI interaction.

docs/REQUIREMENTS.md

@@ -2,6 +2,18 @@
 
 This document outlines the functional requirements for the PHP AI Client, as well as the bigger picture for how it can eventually be used. The concrete technical architecture is defined and outlined in a separate document, based on these requirements.
 
+## Target Audiences
+
+There are two primary developer audiences this client is intended for. This is important to understand as it significantly influences the thinking and complexity around the APIs introduced in this library.a
+
+### Extenders
+
+Extenders are the folks that will be adding providers, models, and otherwise extending the functionality of the client itself. These are highly technical people who likely have a stronger understanding of how models and model APIs work. Given their capabilities, these APIs will be more technical and formal in nature, using things such as interfaces, traits, and so forth, relying on a knowledge of inheritence and composition.
+
+### Implementers
+
+Implementors are the folks that will be utilizing the client to take advantage of AI features. These developers know their own codebase well, but their technical and model knowledge varies. It is important not to rely on this knowledge for them to get significant value from the client. The APIs for these people will be simpler, straightforward, readable, and composable, so they can interact with the model with only what they need to know in mind.
+
 ## Objective
 
 Enable calling any generative AI implementation using a uniform API in various programming languages.