Model Providers Factory
Relevant source files
The following files were used as context for generating this wiki page:
The Model Providers Factory is a central architectural component in TDD Guard responsible for instantiating the appropriate Large Language Model (LLM) client based on the application's configuration. It abstracts the complexity of client creation, allowing the system to switch between different interaction methods—such as direct API calls, CLI-based execution, or SDK integration—without modifying the validation logic.
Sources: CLAUDE.md:50-58, src/providers/ModelClientProvider.test.ts:10-40
Architecture and Components
The factory pattern is implemented via the ModelClientProvider, which serves as the primary entry point for obtaining a ModelClient. This system relies on a strictly typed contract to ensure all instantiated clients provide a consistent interface for the TDD validator.
The ModelClient Interface
All clients generated by the factory must implement the IModelClient interface. This interface mandates a single asynchronous method: ask(prompt: string): Promise<string>. This abstraction allows the validator to remain agnostic of whether it is communicating with a local CLI or a remote cloud service.
Sources: src/validation/validator.test.ts:16-20, src/validation/models/AnthropicApi.test.ts:24-26
ModelClientProvider
The ModelClientProvider uses the Config object to determine which implementation of the ModelClient to instantiate. It supports three primary client types:
- ClaudeCli: Interacts with the Claude CLI environment.
- AnthropicApi: Communicates directly with the Anthropic REST API.
- ClaudeAgentSdk: Utilizes the official Anthropic Agent SDK.
Sources: src/providers/ModelClientProvider.test.ts:15-40, CLAUDE.md:50-58
Client Selection Logic
The selection process is driven by the validationClient setting within the Config class. If no specific configuration is provided, the system defaults to the sdk client.
This diagram illustrates the decision flow within the ModelClientProvider based on configuration settings.
Sources: src/config/Config.ts:15-20, src/providers/ModelClientProvider.test.ts:10-40
Configuration and Parameters
The factory leverages centralized configuration to pass necessary credentials and environmental flags to the resulting clients.
Configuration Mapping
The factory ensures that specific configuration properties reach the correct clients. For instance, the anthropicApiKey is passed to the AnthropicApi client, while useSystemClaude is routed to the ClaudeCli client.
| Client Type | Configuration Dependency | Purpose |
|---|---|---|
api | anthropicApiKey | Required for authentication with Anthropic services. |
cli | useSystemClaude | Determines if the system-installed Claude binary should be used. |
| All | modelVersion | Specifies which Claude model to target (e.g., claude-3-5-sonnet-20241022). |
Sources: src/providers/ModelClientProvider.test.ts:42-65, src/config/Config.ts:80-95, src/validation/models/AnthropicApi.test.ts:31-35
Default Settings
The factory uses constants defined in the configuration layer to ensure stability when environmental variables are missing.
| Constant | Default Value |
|---|---|
DEFAULT_MODEL_VERSION | claude-sonnet-4-0 |
DEFAULT_CLIENT | sdk |
Sources: src/config/Config.ts:11-12
Data Flow
When the TDD Guard hook is triggered, the factory is invoked to prepare the AI validation layer.
This sequence shows how the Model Providers Factory fits into the validation lifecycle, providing a client to the validator.
Sources: src/validation/validator.test.ts:180-205, src/providers/ModelClientProvider.test.ts:25-30
Implementation Details
The ModelClientProvider implementation is designed for testability and dependency injection. It allows the injection of a Config instance, enabling different environments (production vs. test) to utilize different model providers.
Model Versioning
The factory ensures that the modelVersion configured in the system is passed through to the underlying API or SDK calls. In the case of AnthropicApi, this is used to populate the model field in the message creation request.
Sources: src/validation/models/AnthropicApi.test.ts:40-42, src/config/Config.ts:100-105
Error Handling in the Factory
If a client creation fails—for example, due to a missing API key for the api provider—the factory behavior is governed by the underlying class constructors. The validator is designed to catch errors during the ask phase of the resulting client, blocking operations if the model client becomes unresponsive or fails to initialize properly.
Sources: src/validation/validator.test.ts:155-170, src/validation/models/AnthropicApi.test.ts:70-75
Conclusion
The Model Providers Factory provides a robust abstraction layer that enables TDD Guard to support various Claude interaction methods. By decoupling the client instantiation from the TDD logic, the project maintains high flexibility and eases the integration of future model providers or experimental SDKs.