Make llm.get_key() a public documented API for plugins to use

[simonw]

The llm.get_key() method is currently undocumented and confusing to use:

>> import llm
>> llm.get_key("hi")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: get_key() missing 1 required positional argument: 'key_alias'
>> help(llm.get_key)

>> llm.get_key(key_alias="hi")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: get_key() missing 1 required positional argument: 'explicit_key'
>> help(llm.get_key)

>> llm.get_key(None, key_alias="hi")
>> llm.get_key(None, key_alias="openai")
'sk-proj...

Originally posted by @simonw in #1093

[simonw]

llm/llm/__init__.py

Lines 335 to 359 in 5a8d717

	def get_key(
	explicit_key: Optional[str], key_alias: str, env_var: Optional[str] = None
	) -> Optional[str]:
	"""
	Return an API key based on a hierarchy of potential sources.
	:param provided_key: A key provided by the user. This may be the key, or an alias of a key in keys.json.
	:param key_alias: The alias used to retrieve the key from the keys.json file.
	:param env_var: Name of the environment variable to check for the key.
	"""
	stored_keys = load_keys()
	# If user specified an alias, use the key stored for that alias
	if explicit_key in stored_keys:
	return stored_keys[explicit_key]
	if explicit_key:
	# User specified a key that's not an alias, use that
	return explicit_key
	# Stored key over-rides environment variables over-ride the default key
	if key_alias in stored_keys:
	return stored_keys[key_alias]
	# Finally try environment variable
	if env_var and os.environ.get(env_var):
	return os.environ[env_var]
	# Couldn't find it
	return None

[simonw]

I think I rename the existing function to resolve_key(explicit_key, key_alias, env_var) and have get_key(key_alias, env_var) as a nicer user-facing function.

[simonw]

Rats, 89 search results for /llm\.get_key/ and they mostly look like other people who depend on the existing behavior.

https://github.com/search?q=%2Fllm%5C.get_key%2F&type=code

[simonw]

I'm going to add new named keyword-only arguments and document those.

key = llm.get_key(alias="github", env="GITHUB_TOKEN", explicit="explicit key here")

The docs can mention that positional arguments are accepted for backwards-compatibility but I recommend the new keyword arguments instead.

[simonw]

New docs:

llm.get_key()

This method can be used to look up secrets that users have stored using the {ref}llm keys set <help-keys-set> command. If your plugin needs to access an API key this can be a convenient way to do so.

Use the alias="name" option to retrieve the key set with that alias:

github_key = llm.get_key(alias="github")

You can also add env="ENV_VAR" to fall back to looking in that environment variable if the key has not been configured:

github_key = llm.get_key(alias="github", env="GITHUB_TOKEN")

In some cases you may allow users to provide a key as input, where they could input either the key itself or specify an alias to lookup in keys.json. Use the input= parameter for that:

github_key = llm.get_key(input=input_from_user, alias="github", env="GITHUB_TOKEN")

An previous version of function used positional arguments in a confusing order. These are still supported but the new keyword arguments are recommended as a better way to use llm.get_key() going forward.