How to Use the Text Parameter Type in Hypster for String Configuration

Use hp.text(default, name="param_name") to define string values in Hypster configurations, which validates inputs through the TextValidator and requires a mandatory name argument for self-documenting parameter paths.

The text parameter type in Hypster provides a type-safe way to handle string configuration values in the gilad-rubin/hypster library. Unlike standard Python strings, hp.text() creates a SingleValueSpec that enforces validation rules and integrates with Hypster's nested configuration contexts.

Understanding the Text Parameter Architecture

Hypster routes all parameter type calls through a dynamic attribute system. When you call hp.text(), the Hypster.__getattr__ method in src/hypster/hp.py (lines 99-106) maps the string "text" to the private _text method.

The _text method (lines 87-97 in src/hypster/hp.py) constructs a SingleValueSpec instance using TextValidator. Unlike numeric validators, TextValidator disables strict mode because strings lack bounded ranges. The method then invokes _execute_single to register the specification in the current configuration context.

During instantiation, src/hypster/hp_calls.py (lines 89-101) validates supplied values against the TextValidator, ensuring only string types are accepted.

Basic Syntax and Usage

The hp.text() function requires two arguments: a default string value and a mandatory name parameter that becomes the key in the final configuration dictionary.

from hypster import hp

# Define a text parameter with explicit naming

model_name = hp.text("gpt-4", name="model_name")
system_prompt = hp.text("You are a helpful assistant.", name="system_prompt")

print(model_name)      # → "gpt-4"

print(system_prompt)   # → "You are a helpful assistant."

The name argument enables fully-qualified parameter paths, which proves essential when nesting configurations or integrating with Hyperparameter Optimization (HPO) frameworks.

Validation and Type Safety

According to the source code in src/hypster/hp_calls.py, the TextValidator performs runtime type checking to guarantee that configured values remain strings. This catches type mismatches early in the configuration lifecycle.

The validation logic distinguishes text from numeric types (hp.int, hp.float) by omitting range constraints. While numeric validators enforce minimum and maximum bounds, TextValidator only verifies the Python str type, accepting any string length or content.

Common Usage Patterns

Nesting Parameters in Function Contexts

Hypster tracks the call stack to scope parameter names within nested functions, preventing naming collisions across different configuration contexts.

from hypster import hp

def generate_prompt():
    prefix = hp.text("Task:", name="prompt_prefix")
    suffix = hp.text("Complete the above.", name="prompt_suffix")
    return {"prefix": prefix, "suffix": suffix}

config = generate_prompt()
print(config)

# {'prompt_prefix': 'Task:', 'prompt_suffix': 'Complete the above.'}

Handling Missing Name Errors

Omitting the name parameter triggers an informative RuntimeError with the full call path, simplifying debugging.

from hypster import hp

# This raises RuntimeError: text parameter requires a `name`

model_name = hp.text("gpt-4")

Combining with Multi-Text Parameters

Use hp.text() alongside hp.multi_text() for configurations requiring both single strings and string collections.

from hypster import hp

# Single string value

api_endpoint = hp.text("https://api.openai.com", name="api_endpoint")

# List of string values

stop_sequences = hp.multi_text(["###", "END"], name="stop_sequences")

Both calls return plain Python values (str and List[str]) compatible with standard library functions and third-party APIs.

Summary

• hp.text() creates a SingleValueSpec using TextValidator to enforce string typing
• The name parameter is mandatory and defines the configuration dictionary key (implemented in src/hypster/hp.py)
• Type validation occurs in src/hypster/hp_calls.py, ensuring only string values are accepted
• Nested contexts support reusable parameter names through call-stack tracking
• The API follows the uniform pattern shared with hp.int(), hp.float(), and hp.bool()

Frequently Asked Questions

What happens if I pass a non-string default value to hp.text()?

The TextValidator in src/hypster/hp_calls.py validates the default value immediately during the configuration definition phase. Supplying a non-string default raises a validation error before runtime execution, preventing type mismatches from propagating to downstream code.

Why does hp.text() require a name parameter while standard Python variables don't?

The name parameter enables Hypster to construct fully-qualified parameter paths for nested configurations and HPO integration. According to the documentation in docs/in-depth/hp-call-types/text-and-multi-text.md, this requirement makes configurations self-documenting and allows the same parameter name to exist in different lexical scopes without collision.

Can I use hp.text() for multiline strings or empty strings?

Yes. The TextValidator accepts any valid Python string, including empty strings "", multiline strings using triple quotes, and Unicode content. The validator only checks the type (string), not the content length or character constraints, unlike numeric parameters that enforce bounds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}