Implementation:Confident ai Deepeval KeyFileHandler

Overview

KeyFileHandler is the implementation class responsible for persisting and retrieving API keys and configuration values in DeepEval. It manages a hidden .deepeval file in the user's home directory, providing a singleton-based interface for secure key storage and retrieval. The handler explicitly refuses to persist SecretStr-annotated settings to disk, enforcing the credential isolation principle.

API Documentation

Class: KeyFileHandler

Source: deepeval/key_handler.py:L187-283

Import:

from deepeval.key_handler import KeyFileHandler, KeyValues

Pattern: Singleton -- a single instance manages all key file operations.

Methods

Method	Signature	Description
write_key	write_key(key, value)	Persists a key-value pair to the .deepeval hidden file. Refuses to write SecretStr-annotated settings.
fetch_data	fetch_data(key) -> value	Retrieves the stored value for a given key enum from the .deepeval hidden file.

Enum Types

The handler uses typed enums to constrain which keys can be stored and retrieved:

• KeyValues -- General configuration keys (e.g., Confident AI API key, project name)
• ModelKeyValues -- LLM provider API keys (e.g., OpenAI, Azure, Anthropic model keys)
• EmbeddingKeyValues -- Embedding model API keys and configuration

Input / Output

• Inputs: A key enum (from KeyValues, ModelKeyValues, or EmbeddingKeyValues) and a string value.
• Outputs: The value is persisted to the .deepeval hidden file in the user's home directory. On fetch, the stored string value is returned.

Key Features

• SecretStr protection -- The handler refuses to persist any setting annotated with Pydantic's SecretStr type to disk, ensuring that highly sensitive credentials are not written to the local file system in plaintext.
• Singleton pattern -- A single KeyFileHandler instance is shared across the application, preventing race conditions and ensuring consistent state.
• Hidden file storage -- Keys are stored in a .deepeval file, keeping them out of typical directory listings and reducing accidental exposure.

Usage Example

from deepeval.key_handler import KeyFileHandler, KeyValues

handler = KeyFileHandler()

# Write a key
handler.write_key(KeyValues.CONFIDENT_API_KEY, "your-api-key-here")

# Fetch a key
api_key = handler.fetch_data(KeyValues.CONFIDENT_API_KEY)
print(api_key)  # "your-api-key-here"

Relationships

Principle:Confident_ai_Deepeval_API_Key_Management

Related Pages

• Environment:Confident_ai_Deepeval_Python_3_9_Runtime
• Environment:Confident_ai_Deepeval_LLM_Provider_Credentials
• Heuristic:Confident_ai_Deepeval_Secret_Management_Best_Practices
• Heuristic:Confident_ai_Deepeval_Dotenv_Loading_Order

Metadata

DeepEval Tracing Observability LLM_Evaluation 2026-02-14 09:00 GMT