fix(config): treat an empty providers list as no secret providers

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.

[nadeem4]

The bug

The shipped configs/secrets.yaml ships with every provider example commented out:

version: 1providers:
# Example: Azure Key Vault# - id: azure-prod...

YAML parses that as {'version': 1, 'providers': None}. SecretsFileConfig.providers
was List[SecretProviderConfig] — required, no default — so validation failed and
ConfigManager.load_secrets raised:

ValueError: Secret Configuration Invalid: 1 validation error for SecretsFileConfig
providers
Input should be a valid list [type=list_type, input_value=None, input_type=NoneType]
For further information visit https://errors.pydantic.dev/2.13/v/list_type

NL2SQLContext.__init__ calls load_secrets, so the default non-demo path was
broken for anyone using the file as shipped — including a fresh
pip install nl2sql-engine. It stayed invisible in demo mode only because
.env.demo points SECRETS_CONFIG at configs/secrets.demo.yaml, which does not
exist, and a missing file short-circuits to [].

Surfaced by the repaired nl2sql doctor, which reported the error instead of
crashing on it.

Which shapes failed

secrets.yaml shape	before	after
all-commented (the shipped file)	FAILS: providers Input should be a valid list	OK -> []
empty file	FAILS: Input should be a valid dictionary ... input_value=[]	OK -> []
no providers: key at all	FAILS: providers Field required	OK -> []
providers: []	OK	OK -> []

Only the explicit empty list worked. All four are shapes a user legitimately
produces, and all four now load as "no secret providers configured".

The fix

Two defects, both real:

1. configs/secrets.py — providers now defaults to an empty list, plus a
   field_validator(..., mode="before") coercing None to []. In pydantic v2 a
   missing key and an explicit None are different cases: the default covers only
   the missing key, so the validator is what handles a providers: key left empty
   by commenting its entries out.
2. configs/manager.py — yaml.safe_load(content) or [] produced a list
   for an empty file, which then failed model_validate with a confusing "should
   be a valid dictionary". The envelope is a mapping, so the fallback is now {}.

configs/secrets.yaml itself is deliberately left alone. Commenting out every
example is a legitimate thing for a user to do, and the loader has to tolerate it;
adding providers: [] to the shipped file would paper over the defect for that one
file and leave every user-edited copy broken.

Sibling loaders in manager.py were checked for the same fallback/model mismatch:
load_datasources, load_llm and load_sample_questions all use or {} against
mapping-shaped envelopes, and load_policies uses json.loads with no fallback.
None has the mismatch, and their remaining required fields (datasources,
default) are genuinely required — an empty datasources or LLM config is a
misconfiguration worth an error. Left as-is.

Tests

packages/nl2sql/tests/unit/test_config_manager_secrets_empty.py covers all four
shapes, that a real multi-provider config still parses, and — the regression that
actually shipped — that the repo's own configs/secrets.yaml loads without raising.
Written first; 4 of 6 failed against main with the ValidationError above.

Unit suite 247 passed, 1 skipped, 47 deselected (241 + 6 new), key-free
integration 28 passed, 267 deselected; both run twice under pytest-randomly.