feat: add agent-helper CLI commands for schema introspection and type discovery

[johnnygreco]

Summary

Adds two agent-helper CLI command groups — inspect and list — that expose Data Designer's configuration API as structured, agent-consumable output. These commands let AI agents programmatically discover configuration types, schemas, builder methods, and valid values without reading source files.

data-designer inspect — detailed schemas and signatures

• inspect column <type> — schema for a column config type
• inspect sampler <type> — schema for a sampler params type
• inspect validator <type> — schema for a validator params type
• inspect processor <type> — schema for a processor config type
• inspect sampler-constraints — constraint schemas for sampler columns
• inspect config-builder — DataDesignerConfigBuilder method signatures and docstrings

data-designer list — available types and values

• list columns — column type names and config classes
• list samplers — sampler type names and params classes
• list validators — validator type names and params classes
• list processors — processor type names and config classes
• list model-aliases — configured model aliases and backing models
• list persona-datasets — Nemotron-Persona datasets and install status

Supporting infrastructure

• Introspection service layer (cli/services/introspection/) — discovery, Pydantic model inspection, method signature extraction, and dual-format output (text + JSON)
• Controller layer — IntrospectionController and ListController orchestrate discovery, inspection, formatting, and output
• Field descriptions added to config models (column_configs.py, models.py, sampler_params.py, etc.) for self-documenting schema output

Tests

Comprehensive test suite across discovery, inspection, formatting, controllers, commands, and end-to-end usage scenarios.

Attention areas

• config/column_configs.py — Field description additions across all column config types; verify descriptions are accurate
• cli/services/introspection/discovery.py — Uses live module inspection to discover types; changes to config module exports could affect discovery
• cli/controllers/introspection_controller.py — Shared _show_typed_items pattern; new type categories should follow this pattern

[greptile-apps]

Greptile Summary

This PR adds comprehensive agent-helper CLI commands (inspect and list) that expose Data Designer's configuration API as structured output for AI agents. The implementation includes a well-designed introspection service layer with discovery, inspection, formatting, and controller components. Field descriptions were added to all config models for self-documenting schemas.

Key Changes:

• Added inspect commands for detailed schemas (column types, samplers, validators, processors, config builder methods)
• Added list commands for available types and values (model aliases, persona datasets)
• Implemented introspection service layer with runtime discovery using discriminator pattern matching
• Added comprehensive field descriptions across all config models
• Integrated commands with lazy loading for performance
• Extensive test coverage (540+ new test lines)

Issue Found:

• ListController._print_type_table line 131: separator width calculation missing header length consideration

Confidence Score: 4/5

• PR is safe to merge with one minor formatting fix needed
• score reflects excellent implementation quality, comprehensive testing, and consistent field descriptions across config models; minor deduction for separator width bug in list_controller.py line 131 that affects table formatting
• packages/data-designer/src/data_designer/cli/controllers/list_controller.py requires fix for separator width calculation on line 131

Important Files Changed

Filename	Overview
packages/data-designer/src/data_designer/cli/controllers/list_controller.py	New controller for listing configuration types; contains separator width bug on line 131
packages/data-designer/src/data_designer/cli/services/introspection/discovery.py	Well-implemented discovery service using runtime introspection and discriminator pattern matching
packages/data-designer/src/data_designer/cli/services/introspection/pydantic_inspector.py	Comprehensive Pydantic model inspection with recursive schema rendering; handles edge cases well
packages/data-designer/src/data_designer/cli/controllers/introspection_controller.py	Clean orchestration layer for introspection commands with consistent patterns
packages/data-designer-config/src/data_designer/config/column_configs.py	Field descriptions added to all column config types; descriptions are accurate and helpful
packages/data-designer-config/src/data_designer/config/models.py	Comprehensive field descriptions added to model config types; consistent and clear

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    CLI[CLI Command: data-designer inspect/list]
    
    CLI --> |inspect column| IC[IntrospectionController]
    CLI --> |list columns| LC[ListController]
    
    IC --> |discover types| DS[Discovery Service]
    LC --> |discover types| DS
    
    DS --> |scan dd namespace| DISC[discover_column_configs<br/>discover_sampler_types<br/>discover_validator_types<br/>discover_processor_configs]
    
    DISC --> |extract discriminators| LAZY[_LAZY_IMPORTS<br/>model_fields<br/>Literal annotations]
    
    IC --> |inspect model| PI[PydanticInspector]
    IC --> |inspect methods| MI[MethodInspector]
    
    PI --> |format schema| FMT[Formatters]
    MI --> |format signatures| FMT
    LC --> |format table| FMT
    
    FMT --> OUT[Console Output<br/>Text or JSON]
    
    style CLI fill:#e1f5ff
    style DS fill:#fff4e1
    style PI fill:#f0e1ff
    style MI fill:#f0e1ff
    style FMT fill:#e1ffe1
    style OUT fill:#ffe1e1

Loading

_{Last reviewed commit: 83ccb30}

[greptile-apps]

_{37 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{32 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{32 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

_{32 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Module prefix regex only strips one level
The regex r"data_designer\.config\.\w+\." only strips a single submodule segment. For types from deeper nested paths like data_designer.config.utils.code_lang.CodeLang, this produces code_lang.CodeLang instead of CodeLang.

Consider using a greedy pattern that strips the full dotted path:

Suggested change

	type_str = re.sub(r"data_designer\.config\.\w+\.", "", type_str)
	type_str = re.sub(r"data_designer\.config\.(?:\w+\.)+", "", type_str)

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/src/data_designer/cli/services/introspection/pydantic_inspector.py
Line: 146:146

Comment:
**Module prefix regex only strips one level**
The regex `r"data_designer\.config\.\w+\."` only strips a single submodule segment. For types from deeper nested paths like `data_designer.config.utils.code_lang.CodeLang`, this produces `code_lang.CodeLang` instead of `CodeLang`.

Consider using a greedy pattern that strips the full dotted path:

```suggestion
    type_str = re.sub(r"data_designer\.config\.(?:\w+\.)+", "", type_str)
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Missing enum_name in docstring Args
The enum_name parameter is declared in the signature but not documented in the Args section. This function uses enum_name as a critical fallback lookup mechanism (line 112), so documenting it helps future contributors understand the two-phase discovery strategy.

Suggested change

	"""Discover params classes keyed by their literal discriminator value.
	Args:
	params_class_suffix: Class-name suffix to select params classes.
	discriminator_field: Field name that stores the literal discriminator.
	Returns:
	Dict mapping discriminator values to params classes.
	"""Discover params classes keyed by their literal discriminator value.
	Args:
	params_class_suffix: Class-name suffix to select params classes.
	discriminator_field: Field name that stores the literal discriminator.
	enum_name: Name of the enum class on ``dd`` used as a fallback to
	match params classes by normalized name when no literal
	discriminator is present.
	Returns:
	Dict mapping discriminator values to params classes.
	"""

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/src/data_designer/cli/services/introspection/discovery.py
Line: 82:89

Comment:
**Missing `enum_name` in docstring Args**
The `enum_name` parameter is declared in the signature but not documented in the Args section. This function uses `enum_name` as a critical fallback lookup mechanism (line 112), so documenting it helps future contributors understand the two-phase discovery strategy.

```suggestion
    """Discover params classes keyed by their literal discriminator value.

    Args:
        params_class_suffix: Class-name suffix to select params classes.
        discriminator_field: Field name that stores the literal discriminator.
        enum_name: Name of the enum class on ``dd`` used as a fallback to
            match params classes by normalized name when no literal
            discriminator is present.

    Returns:
        Dict mapping discriminator values to params classes.
    """
```

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

_{36 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Unreachable guard condition
_default_to_json handles all input types (None, Enum, bool, int, float, str, list, dict, fallback repr()) and never returns _UNDEFINED. This means default_json is not _UNDEFINED is always True after line 242, making the guard on line 243 dead code. It's harmless but worth simplifying for clarity.

Suggested change

	if default_json is not _UNDEFINED:
	default_display = repr(default_json)
	default_json = _default_to_json(field_info.default)
	default_display = repr(default_json)

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/src/data_designer/cli/services/introspection/pydantic_inspector.py
Line: 243:244

Comment:
**Unreachable guard condition**
`_default_to_json` handles all input types (None, Enum, bool, int, float, str, list, dict, fallback `repr()`) and never returns `_UNDEFINED`. This means `default_json is not _UNDEFINED` is always `True` after line 242, making the guard on line 243 dead code. It's harmless but worth simplifying for clarity.

```suggestion
                    default_json = _default_to_json(field_info.default)
                    default_display = repr(default_json)
```

How can I resolve this? If you propose a fix, please make it concise.

[nabinchha]

is it worth warning here or somewhere else about providing fstrings here that could mess up the jinja template? I've found that cursor likes to auto convert this to f""

[nabinchha]

is 'code', 'local_callable', or 'remote' necessary since it's already strongly typed? Same comment for other similar chanages.

[nabinchha]

is introspection needed when the agent can crawl to data designer installed source code and discover all of these themselves?

[andreatgretel]

+1, would like to understand a bit better the motivation. I think the new documentation (field descriptions etc.) is very helpful, but the agent can get it "for free" right, do we need the whole CLI introspection layer?

[johnnygreco]

I don't think reading source code or fetching docs is "free". This is designed to be much more targeted, concise context for the agent right when they need it. This is like going above and beyond for AX – similar to how you can ask what's the point of adding display_sampler_record when the user can just write a quick display function – it's for UX.

[greptile-apps]

_{37 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Separator width ignores column header
The separator width for the second column is computed from the max class name length but doesn't account for the col2 header length. If all class names are shorter than the header string (e.g., "config_class" is 12 chars), the separator underline will be shorter than the header text. This is inconsistent with list_model_aliases at lines 76-78 which correctly uses max(len(header), max(len(data))) for all columns.

Suggested change

	typer.echo(f"{'-' * max_width} {'-' * max(len(items[t].__name__) for t in sorted_types)}")
	typer.echo(f"{'-' * max_width} {'-' * max(len(col2), max(len(items[t].__name__) for t in sorted_types))}")

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/src/data_designer/cli/controllers/list_controller.py
Line: 131:131

Comment:
**Separator width ignores column header**
The separator width for the second column is computed from the max class name length but doesn't account for the `col2` header length. If all class names are shorter than the header string (e.g., `"config_class"` is 12 chars), the separator underline will be shorter than the header text. This is inconsistent with `list_model_aliases` at lines 76-78 which correctly uses `max(len(header), max(len(data)))` for all columns.

```suggestion
        typer.echo(f"{'-' * max_width}  {'-' * max(len(col2), max(len(items[t].__name__) for t in sorted_types))}")
```

How can I resolve this? If you propose a fix, please make it concise.

[nabinchha]

should there be a list on model providers. same question for mcp configs....

[johnnygreco]

We can certainly add that. I was thinking to keep it simple, we hold off on mcp, and assume the user has set up their model providers – so the model alias is the only think the agent needs to choose. WDYT?

[greptile-apps]

_{37 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Separator width for col2 doesn't account for header length. When all class names are shorter than the header text (e.g., "config_class" is 12 chars), the separator underline will be too short.

Suggested change

	typer.echo(f"{'-' * max_width} {'-' * max(len(items[t].__name__) for t in sorted_types)}")
	typer.echo(f"{'-' * max_width} {'-' * max(len(col2), max(len(items[t].__name__) for t in sorted_types))}")

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/src/data_designer/cli/controllers/list_controller.py
Line: 131

Comment:
Separator width for `col2` doesn't account for header length. When all class names are shorter than the header text (e.g., `"config_class"` is 12 chars), the separator underline will be too short.

```suggestion
        typer.echo(f"{'-' * max_width}  {'-' * max(len(col2), max(len(items[t].__name__) for t in sorted_types))}")
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

separator width for col2 doesn't include header length in calculation

when all class names are shorter than col2 header text, separator will be too short. compare with lines 76-78 which correctly use max(len(header), max(len(data))) pattern

Suggested change

	typer.echo(f"{'-' * max_width} {'-' * max(len(items[t].__name__) for t in sorted_types)}")
	typer.echo(f"{'-' * max_width} {'-' * max(len(col2), max(len(items[t].__name__) for t in sorted_types))}")

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/data-designer/src/data_designer/cli/controllers/list_controller.py
Line: 131

Comment:
separator width for `col2` doesn't include header length in calculation

when all class names are shorter than `col2` header text, separator will be too short. compare with lines 76-78 which correctly use `max(len(header), max(len(data)))` pattern

```suggestion
        typer.echo(f"{'-' * max_width}  {'-' * max(len(col2), max(len(items[t].__name__) for t in sorted_types))}")
```

How can I resolve this? If you propose a fix, please make it concise.